SuperCache.Storage.MatchSpec (SuperCache v1.4.0)

Copy Markdown View Source

Compiled match specifications for ETS queries.

This module provides helper functions to create and compile match specs for common ETS query patterns. Compiled match specs can be reused across multiple queries for better performance.

Why use match specs?

Example

# Instead of:
:ets.match(table, {:"$1", :"$2"})

# Use:
spec = MatchSpec.match([{:"$1", :"$2"}], [:"$1", :"$2"])
:ets.select(table, spec)

Summary

Types

match_spec()

Functions

all_records()

Create a match spec to get all records.

compile(spec)

Compile a match spec for repeated use.

delete_match(pattern)

Create a match spec for deletion.

match(pattern, bindings)

Create a match spec for :ets.match/2 style queries.

match_object(pattern)

Create a match spec for :ets.match_object/2 style queries.

select(table, spec)

Run a match spec against a table.

select_delete(table, spec)

Run a match spec for deletion.

with_guard(pattern, guards, body)

Create a match spec with a guard condition.

Types

match_spec()

@type match_spec() :: [{tuple(), [tuple()], [tuple()]}]

Functions

all_records()

@spec all_records() :: match_spec()

Create a match spec to get all records.

Note: :"$_" is only valid in the body of a match spec, not in the pattern. A generic "match all" select spec that works for any tuple arity does not exist — the pattern must match the stored tuple structure exactly.

Prefer :ets.tab2list/1 when you need all records from a table, or use match_object/1 with an explicit pattern like {:"$1", :"$2"}.

compile(spec)

@spec compile(match_spec()) :: :ets.comp_match_spec() | match_spec()

Compile a match spec for repeated use.

Compiled match specs are more efficient when the same query is executed multiple times.

Note: In Erlang/Elixir, :ets.select/2 can accept either:

Example

spec = MatchSpec.match({:"$1", :_}, [:"$1"])
compiled = MatchSpec.compile(spec)

# Later, use with :ets.select(table, compiled)

delete_match(pattern)

@spec delete_match(tuple() | atom()) :: match_spec()

Create a match spec for deletion.

Returns a match spec that, when used with :ets.select_delete/2, deletes matching records.

Parameters

  • pattern: The match pattern with :"$1", :"$2", etc.

Example

# Delete all records with :expired status
spec = MatchSpec.delete_match({:"$1", :"$2", :expired})
:ets.select_delete(table, spec)

match(pattern, bindings)

@spec match(tuple() | atom(), [term()]) :: match_spec()

Create a match spec for :ets.match/2 style queries.

Returns a match spec that, when used with :ets.select/2, returns a list of binding lists (like :ets.match/2).

Parameters

  • pattern: The match pattern with :"$1", :"$2", etc.
  • bindings: List of bindings to return (e.g., [:"$1", :"$2"])

Example

# Match all records and return the first two fields
spec = MatchSpec.match({:"$1", :"$2", :_}, [:"$1", :"$2"])
:ets.select(table, spec)

match_object(pattern)

@spec match_object(tuple() | atom()) :: match_spec()

Create a match spec for :ets.match_object/2 style queries.

Returns a match spec that, when used with :ets.select/2, returns full matching tuples (like :ets.match_object/2).

Parameters

  • pattern: The match pattern with :"$1", :"$2", etc.

Example

# Match all records with :admin as third element
spec = MatchSpec.match_object({:"$1", :"$2", :admin})
:ets.select(table, spec)

select(table, spec)

@spec select(atom() | :ets.tid(), :ets.comp_match_spec() | match_spec()) :: [term()]

Run a match spec against a table.

Accepts either a compiled match spec or a regular match spec list.

select_delete(table, spec)

@spec select_delete(atom() | :ets.tid(), :ets.comp_match_spec() | match_spec()) ::
  non_neg_integer()

Run a match spec for deletion.

Accepts either a compiled match spec or a regular match spec list.

with_guard(pattern, guards, body)

@spec with_guard(tuple() | atom(), [tuple()], [term()]) :: match_spec()

Create a match spec with a guard condition.

Parameters

  • pattern: The match pattern
  • guards: List of guard conditions (tuples)
  • body: List of expressions to return

Example

# Match records where the second element is > 100
spec = MatchSpec.with_guard(
  {:"$1", :"$2"},
  [{:>, :"$2", 100}],
  [:"$_"]
)