Matching

Compile a pattern once, then match it against subjects. All match functions accept a Matcher or a raw expression (compiled via compile_pattern); constraints takes cross-variable Constraints and maxsteps bounds engine work.

Compilation

MatchMaker.compile_pattern — Function
compile_pattern(
    expr::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal};
    vars
) -> Matcher

Compile expr into a Matcher. vars maps pattern variables (inner Syms or marker terms) to VarSpec variants (slotspec/segmentspec); unlisted variables get the unconstrained spec for their kind.

source

First match

Base.match — Function
match(
    m::Matcher,
    s::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal};
    constraints,
    maxsteps
) -> Union{Nothing, MarkersMap}

The first match of pattern m (a Matcher or a raw expression, compiled via compile_pattern) against subject s, as a MarkersMap or nothing. constraints is a collection of Constraints.

source

Enumerating matches

MatchMaker.matches — Function
matches(
    m::Matcher,
    s::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal};
    constraints,
    maxsteps
) -> MatchIterator

Lazy iterator of all matches of m against s; each item is a MarkersMap. maxsteps bounds total search steps — the iterator ends when the budget is exhausted (a truncated result set).

source
MatchMaker.boundmatches — Function
boundmatches(
    m::Matcher,
    s::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal};
    constraints,
    maxsteps
) -> BoundMatchIterator

Lazy iterator of all matches of m against s like matches, but each item is a BoundMatch: a persistent snapshot of the index-only binding state that reconstructs segment terms on access. Far cheaper per result than materializing a MarkersMap — use it when collecting many results, or when the consumer reads only a few bound values per match.

source
MatchMaker.boundmatchall — Function
boundmatchall(m, s; kwargs...) -> Vector{BoundMatch}

collect(boundmatches(m, s)) — all matches as a Vector{BoundMatch}. The cheap matchall for enumeration-heavy workloads (~10× faster on segment-heavy cases); materialize individual results to get the same MarkersMaps matchall returns.

source
Base.eachmatch — Function
eachmatch(
    f,
    m::Matcher,
    s::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal};
    constraints,
    maxsteps
)

Call f(::SubstitutionView) on each successive match of m against s; stop when f returns false. The zero-allocation hot path (§5.6): the view is only valid inside f — copy with materialize to keep results.

source

Occurrence search — match sites inside a subject

MatchMaker.boundmatches_at — Function
boundmatches_at(
    m::Matcher,
    s::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal};
    constraints,
    maxsteps
) -> BoundMatchAtIterator

Lazy (BoundMatch, t) pairs for each match of m at each node of s — occurrence search in the boundmatches idiom. Sites deduplicated by ===-identity; postorder (bottom-up) traversal.

source
MatchMaker.BoundMatchAtIterator — Type
BoundMatchAtIterator

Lazy iterator over match sites — yields (BoundMatch, t) pairs: a frozen binding snapshot and the matched subterm, one per (pattern-match, node) in postorder. materialize(bm) a pair's first element for a MarkersMap.

The subject is interned once into the engine's shared IR, so a structurally shared subterm is one node and yields one hit — sites are deduplicated by ===-identity, not by syntactic position (REWRITING.md milestone 4).

source

Cross-variable constraints

MatchMaker.Constraint — Type
Constraint(fn, vars)

A cross-variable constraint (DESIGN.md §4.9): fn is called with a Vector{BasicSymbolic{SymReal}} of bound values in vars order and must return Bool. Fires as soon as every variable in vars is bound. vars elements are variable Syms or marker terms.

source

Instantiation

MatchMaker.instantiate — Function
instantiate(
    template::SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal},
    subst
) -> SymbolicUtils.BasicSymbolicImpl.var"typeof(BasicSymbolicImpl)"{SymReal}

Rebuild template, replacing marker terms with their bound values from subst (a MarkersMap or any dict keyed on variable syms/marker terms). slot/optional vars substitute their bound expression; segment vars splice arguments(bound) into the parent's argument list (a Const segment binding contributes zero arguments); a head marker (slot(f)(…)) substitutes the raw bound operation.

Extended help

Iterates the template's IRStructure in postorder building out[i] — no recursion. For templates without segment or head markers, SymbolicUtils.IRSubstituter gives the same result; instantiate is required for splicing and head substitution.

source