pattern.match — sicmutils 0.21.1

Implementation of a pattern matching system inspired by Gerald Jay Sussman's lecture notes for MIT 6.945. See pattern.rule for a higher-level API.

pattern.match and pattern.rule are spiritually similar to Alexey Radul's Rules library for Scheme, and the pattern matching system described in GJS and Hanson's Software Design for Flexibility.

all-results clj/s

(all-results pattern data)

Convenience function that creates an all-results-matcher from the supplied pattern and immediately applies it to data.

Equivalent to:

((all-results-matcher pattern pred) data)

all-results-matcher clj/s

(all-results-matcher pattern)

Takes a pattern and callback function f, and returns a matcher that takes a data argument and returns a sequence of every possible match of pattern to the data.

For a convenience function that applies the matcher to data immediately, see all-results.

NOTE: If you pass a segment matcher, f must accept two arguments - the binding map, and the sequence of all remaining items that the segment matcher rejected.

and clj/s

(and)

(and pattern)

(and pattern & more)

Takes a sequence of patterns and returns a matcher that will apply its arguments to the first pattern;

If that match succeeds, the next pattern will be called with the new, returned frame (and the original data and success continuation).

The returned matcher succeeds only of all patterns succeed, and returns the value of the final pattern.

as-segment-matcher clj/s

(as-segment-matcher f)

Takes a matcher and returns f with its metadata modified such that [[segment-matcher?]] will return true when applied to f.

bind clj/s

(bind sym)

(bind sym pred)

Takes a binding variable sym and an optional predicate pred, and returns a matcher that binds its input to sym in the returned frame.

The returned matcher only succeeds if input passes pred.

If sym is already present in frame, the matcher only succeeds if the values are equal, fails otherwise.

NOTE: If sym is the wildcard _, the returned matcher will not introduce a new binding, but will still check the predicate.

eq clj/s

(eq x)

(eq x eq-fn)

Takes some input x and returns a matcher which succeeds if its data input is equal to x (via = or the optional eq-fn argument). Fails otherwise.

The frame is not modified.

fail clj/s

(fail _ _ _)

Matcher which will fail for any input.

failed? clj/s

(failed? x)

Returns true if x is equivalent to the failure sentinel failure, false otherwise.

failure clj/s

Singleton object representing the failure of a matcher to match its input. Check for failure with failed?

Failure clj/s

foreach clj/s

(foreach pattern f data)

Convenience function that creates a foreach-matcher from the supplied pattern and callback f and immediately applies it to data.

Equivalent to:

((foreach-matcher pattern pred) data)

foreach-matcher clj/s

(foreach-matcher pattern f)

Takes a pattern and side-effecting callback function f, and returns a matcher that calls f with a map of bindings for every possible match of pattern to its input data.

For a convenience function that applies the matcher to data immediately, see foreach.

NOTE: If you pass a segment matcher, f must accept two arguments - the binding map, and the sequence of all remaining items that the segment matcher rejected.

frame-predicate clj/s

(frame-predicate pred)

Takes a predicate function pred and returns a matcher that succeeds (with no new bindings) if its data input passes the predicate, fails otherwise.

match clj/s

(match pattern data)

(match pattern pred data)

Convenience function that creates a matcher from the supplied pattern (and optional predicate pred) and immediately applies it to data.

Equivalent to:

((matcher pattern pred) data)

match-if clj/s

(match-if pred success-pattern)

(match-if pred success-pattern fail-pattern)

Returns a matcher that passes its frame on to success-pattern if pred succeeds on its data input, fail-pattern otherwise.

If no fail-matcher is supplied, the behavior is equivalent to match-when.

match-when clj/s

(match-when pred success-pattern)

Returns a matcher that passes its frame on to success-pattern if pred succeeds on its data input, fails otherwise.

matcher clj/s

(matcher pattern)

(matcher pattern pred)

Takes a pattern or matcher combinator, and returns a function from a data object to either:

• A successful map of bindings extracted by matching the supplied pattern or combinator to the input data
• An explicit failure object

Check for failure with failed?.

Optionally, you can supply a predicate pred. pred takes the map of bindings from a successful match and returns either:

• nil, false or the explicit failure object to force a match failure, potentially causing a backtrack back into the data
• a map of NEW bindings to merge into the binding map (and signal success)

Any other truthy value signals success with no new bindings.

not clj/s

(not pattern)

Takes a pattern and returns a matcher that will apply its arguments to the pattern. The returned pattern will succeed with the original frame if pattern fails, and fail if pattern succeeds.

or clj/s

(or)

(or pattern)

(or pattern & more)

Takes a sequence of patterns, and returns a matcher that will apply its arguments to each matcher in turn. Returns the value of the first pattern that succeeds.

pass clj/s

(pass frame _ succeed)

Matcher that succeeds (with no new bindings) for any input, passing along its input frame.

pattern->combinators clj/s

(pattern->combinators pattern)

Given a pattern (built using the syntax elements described in pattern.syntax), returns a matcher combinator that will successfully match data structures described by the input pattern, and fail otherwise.

predicate clj/s

(predicate pred)

Takes a predicate function pred and returns a matcher that succeeds (with no new bindings) if its data input passes the predicate, fails otherwise.

reverse-segment clj/s

(reverse-segment sym)

Returns a matcher that takes a binding variable sym, and succeeds if it's called with a sequential data argument with a prefix that is the REVERSE of the sequence bound to sym in frame.

Fails if any of the following are true:

• sym is not bound in the frame
• sym is bound to something other than a vector prefix created by segment
• the data argument does not have a prefix matching the reverse of vector bound to sym.

segment clj/s

(segment sym)

Takes a binding variable sym and returns a matcher that calls its success continuation with successively longer prefixes of its (sequential) data input bound to sym inside the frame.

If sym is already present in the frame, the returned matcher only succeeds if the bound value is a prefix of the data argument xs.

If sym matches the wildcard symbol _, the behavior is the same, but no new binding is introduced.

NOTE: the returned matcher will call its success continuation with TWO arguments; the new frame and the remaining elements in xs. This is a different contract than all other matchers, making segment appropriate for use inside sequence.

sequence clj/s

(sequence & patterns)

Takes a sequence of patterns and returns a matcher that accepts a sequential data input, and attempts to match successive items (or segments) in the sequence with the supplied patterns.

The returned matcher succeeds if patterns can consume all elements, fails otherwise (or of any of the supplied patterns fails on its argument).

On success, the returned matcher calls its success continuation with a frame processed by each pattern in sequence.

sequence* clj/s

(sequence* patterns)

Version of sequence that takes an explicit sequence of patterns, vs the multi-arity version. See sequence for documentation.

update-frame clj/s

(update-frame f & args)

Takes a function from frame to a new frame (or false) and any number of arguments args, and returns a matcher that will ignore its input and

• succeed with (apply f frame args) if that value is truthy,
• fail otherwise.

with-frame clj/s

(with-frame new-frame)

Takes a new-frame of bindings and returns a matcher that will ignore its input and always succeed by replacing the current map of bindings with new-frame.