module base.match

Pattern capturing for Op argument parsing.

There is only one basic buildings block for assembling patterns: Type. It can match SigStreams and EvtStreams depending on its metatype argument and can take an optional type name to match as an argument.

In addition to this primitive, the following modifiers are available: Repeat, Sequence, Choice, and Optional. They can be used directly, but there is also a number of shorthands for assembling patterns quickly:

• const(), sig() and evt(): Shorthands for Type('='), Type('~'), Type('!')
• const.sym: Shorthand for Type('=', T.sym)
• sig.num: Shorthand for Type('~', T.num)
• evt.str: Shorthand for Type('!', T.str)
• pat * 2: Shorthand for Repeat(pat, 1, 2) (1-2 times pat)
• pat * 0: Shorthand for Repeat(pat, 1, nil) (1-* times pat)
• pat ^ 2: Shorthand for Repeat(pat, 0, 2) (0-2 times pat)
• pat ^ 0: Shorthand for Repeat(pat, 0, nil) (0-* times pat)
• a + b + … + z: Shorthand for Sequence{ a, b, …, z }
• a / b / … / z: Shorthand for Choice{ a, b, …, z }
• -pat: Shorthand for Optional(pat)

To perform the actual matching, call the :match method on a pattern and pass a sequence of RTNodes. The method will either return the captured RTNodes (or a table structuring them)

Any ambiguous pattern can be set to ‘recall mode’ by invoking it. Recalling patterns will memorize the first RTNode they match, and only match further RTNodes of the same type. For example

arg = (sig.num / sig.str)!
pattern = arg + arg

…will match either two numbers or two strings, but not one number and one string. Recalling works on Choice and Type patterns.

On Sequence patterns, a special method :named exists. It takes a sequence of keys that are used instead of integers when constructing the capture table:

pattern = (sig.str + sig.num):named('key', 'value')
pattern:match(...)
-- returns { {key='a', value=1}, {key='b', value=2}, ...}

index

functions

• Type(metatype, type)  – Base Result Pattern.
• Predicate(metatype, predicate, name)  – Predicate function Pattern.
• Repeat(inner, min, max)  – Repeat a pattern.
• Sequence(elements, keys)  – Match multiple patterns in order.
• Choice(elements)  – Match one of multiple options.
• Optional(elements, keys)  – Optionally match a pattern.

tables

• const  – Type shorthands for matching Constants.
• sig  – Type shorthands for matching ValueStreams and Constants.
• evt  – Type shorthands for matching EvtStreams.
• any  – Type shorthands for matching any Results.

details

functions

• Type(metatype, type)  – Base Result Pattern.
  When instantiated with type, only succeeds for Results whose type and metatypes match.

  Otherwise, matches Streams based only on metatype for the first match, but using both afterwards (recall mode).

  parameters:

  • metatype (optional string): `‘~’, ‘!’ or ‘=’
  • type (optional string): type name
• Predicate(metatype, predicate, name)  – Predicate function Pattern.
  Only succeeds for Results whose metatype matches and for which the predicate function returns true.

  parameters:

  • metatype (optional string): `‘~’, ‘!’ or ‘=’
  • predicate (function): gets type as an argument
  • name (string): printable alias for error reporting
• Repeat(inner, min, max)  – Repeat a pattern.
  Matches a given inner pattern as many times as possible, within the given minimum/maximum counts. Matching this pattern results in a sequence of the individual captures produced by the inner pattern.

  parameters:

  • inner (Pattern): the original pattern
  • min (optional number): minimum amount of repetitions
  • max (optional number): maximum amount of repetitions (default infinite)
• Sequence(elements, keys)  – Match multiple patterns in order.
  Matches the inner patterns in order, only succeeds if all of them match. Captures the individual captures produced by the inner patterns in a sequence, or table with keys specified in keys or using the :named(…) modifier.

  parameters:

  • elements ({Pattern,...}): the inner patterns
  • keys (optional {string,...}): the keys to use when capturing matches
• Choice(elements)  – Match one of multiple options.
  Matches using the first matching pattern in elements and returns its captured value. Supports recalling the matched subpattern.

  parameters:

  • elements ({Pattern,...}): the inner patterns
• Optional(elements, keys)  – Optionally match a pattern.
  Matches using the first matching pattern in elements and returns its captured value. Supports recalling the matched subpattern.

  parameters:

  • elements ({Pattern,...}): the inner patterns
  • keys (optional {string,...}): the keys to use when capturing matches

tables

• const  – Type shorthands for matching Constants.

  Call or index with a type or string to obtain an Type instance. Call with a function and name to obtain a Predicate instance. Call to obtain a wildcard pattern.

   const.bang, const.str, const.num
   const['midi/message'], const(Primitive 'midi/message')
   const(function(typ) return typ.__class == Array end, "array")
   const()
  

• sig  – Type shorthands for matching ValueStreams and Constants.

  Call or index with a type or string to obtain a Type instance. Call with a function and name to obtain a Predicate instance. Call to obtain a wildcard pattern.

   sig.str, sig.num
   sig['vec3'], sig(T.vec3)
   sig(function(typ) return typ.__class == Array end, "array")
   sig()
  

• evt  – Type shorthands for matching EvtStreams.

  Call or index with a type or string to obtain an Type instance. Call with a function and name to obtain a Predicate instance. Call to obtain a wildcard pattern.

   evt.bang, evt.str, evt.num
   evt['midi/message'], evt(Primitive 'midi/message')
   evt(function(typ) return typ.__class == Struct end, "struct")
   evt()
  

• any  – Type shorthands for matching any Results.

  Call or index with a type or string to obtain an Type instance. Call with a function and name to obtain a Predicate instance. Call to obtain a wildcard pattern.

   any.bang, any.str, any.num
   any['midi/message'], any(Primitive 'midi/message')
   any(function(typ) return typ.__class == Array end, "array")
   any()