lib/match-recursive.x

Optional reference matcher.

Primary API

Functions

match_recursive_search

List match_recursive_search(List input, Var pattern)

Returns every recursively matching node and its named bindings. Traversal visits car, then cdr, then the node. Each hit is prepended, so the returned order reverses that visitation. The result, its records, and star-capture Lists are canonical and follow their owning List pool’s lifetime, possibly an ancestor of the current pool. Each record maps <*> to the matched node. Explicit nil nodes are visited, but a proper List’s implicit terminal cdr is not. Returns nil when the pattern is malformed or no node matches.

Raises: <alloc-fail> or <size-limit> while searching or binding.

Source: lib/match-recursive.x:406

match_recursive_search_replace

List match_recursive_search_replace(List input, Var pattern, Var template)

Replaces every recursively matching node and returns the resulting List. Traversal rewrites car, then cdr, then matches the node. The result is canonical; constructed cells follow their owning List pool’s lifetime, possibly an ancestor of the current pool. Explicit nil nodes are visited, but a proper List’s implicit terminal cdr is not.

Raises: <alloc-fail> or <size-limit> while searching or replacing.

Source: lib/match-recursive.x:434

match_recursive_try_capture

int match_recursive_try_capture( MatchCaptureLayout layout, Var input, MatchCaptureBuffer *captures)

Matches input against layout with the recursive reference engine. Returns 1 and publishes positional captures on success. A null or malformed layout, an invalid or undersized buffer, and a mismatch return 0 without changing the caller-owned buffer or value array. On success, present identifies the written slots; the call does not retain the layout or the capture buffer. Star-capture Lists are canonical and follow their owning List pool’s lifetime, possibly an ancestor of the current pool.

Raises: <alloc-fail> or <size-limit> while materializing captures.

Source: lib/match-recursive.x:342

match_recursive_try_match

int match_recursive_try_match(List input, Var pattern, List *out_bindings)

Matches input against pattern with the recursive reference engine. Returns 1 and writes a canonical association List of named bindings on success, including nil when no named binder is present. The binding List and star-capture Lists follow their owning List pool’s lifetime, possibly an ancestor of the current pool. A malformed pattern, mismatch, or null output pointer returns 0 and leaves the output unchanged.

Raises: <alloc-fail> or <size-limit> while analyzing or binding.

Source: lib/match-recursive.x:371

match_recursive_try_match_replace

int match_recursive_try_match_replace( List input, Var pattern, Var template, Var *out)

Matches input and writes the instantiated template on success. Returns 0 for a malformed pattern, mismatch, or null output pointer and leaves the output unchanged. A successful output may be any Var, including typed nil. Any constructed output List is canonical and follows its owning List pool’s lifetime, possibly an ancestor of the current pool.

Raises: <alloc-fail> or <size-limit> while matching or replacing.

Source: lib/match-recursive.x:383

match_recursive_try_search

int match_recursive_try_search( List input, Var pattern, Var *out_match, List *out_bindings)

Visits car, then cdr, then the node and writes the first matching node. The binding List and star-capture Lists are canonical and follow their owning List pool’s lifetime, possibly an ancestor of the current pool; bindings are nil when no named binder is present. Returns 0 for a malformed pattern, mismatch, or null output pointer and leaves both outputs unchanged. Explicit nil nodes are visited, but a proper List’s implicit terminal cdr is not.

Raises: <alloc-fail> or <size-limit> while searching or binding.

Source: lib/match-recursive.x:421

match_recursive_try_value

int match_recursive_try_value(Var input, Var pattern, List *out_bindings)

Matches any input against pattern with the recursive reference engine. Returns 1 and writes a canonical association List of named bindings on success, including nil when no named binder is present. The binding List and star-capture Lists follow their owning List pool’s lifetime, possibly an ancestor of the current pool. A malformed pattern, mismatch, or null output pointer returns 0 and leaves the output unchanged.

Raises: <alloc-fail> or <size-limit> while analyzing or binding.

Source: lib/match-recursive.x:357

Design notes

This direct matcher is the readable reference for differential tests. The prelude’s public Match operations run the compiled machine in match.x; include this module only when an independent recursive oracle is useful.

Tests and examples

make verify (unittest/test-match.x).