module base.match

Pattern capturing for Op argument parsing.

There is only one basic buildings block for assembling patterns: Type. It can match ValueStreams and EventStreams 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:

• val() and evt(): Shorthands for Type('value') and Type('event')
• val.num: Shorthand for Type('value', 'num')
• evt.str: Shorthand for Type('event', 'str')
• pat * 2: Shorthand for Repeat(pat, 1, 2) (1-4 times pat)
• pat * 0: Shorthand for Repeat(pat, 1, nil) (1-* times pat)
• pat ^ 2: Shorthand for Repeat(pat, 0, 2) (0-4 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 Results. The method will either return the captured Results (or a table structuring them)

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

arg = (val.num / val.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. Type patterns without a type (val! and evt!) always behave like this.

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 = (val.str + val.num):named('key', 'value')
pattern:match(...)
-- returns { {key='a', value=1}, {key='b', value=2}, ...}

index

functions

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

tables

• val  – Value shorthands.
• evt  – Event shorthands.

details

functions

• Stream(metatype, type)  – Base Stream Pattern.
  When instantiated with type, only succeeds for Streams whose value and meta types match.

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

  parameters:

  • metatype (string): “value” or “event”
  • type (optional string): type name
• 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, keys)  – 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
  • keys (optional {string,...}): the keys to use when capturing matches
• 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

• val  – Value shorthands.

  Call or index with a string to obtain a Type instance. Call to obtain a wildcard pattern.

   val.str, val.num
   val['vec3'], val('vec3')
   val()
  

• evt  – Event shorthands.

  Call or index with a string to obtain an Type instance. Call to obtain a wildcard pattern.

   evt.bang, evt.str, evt.num
   evt['midi/message'], evt('midi/message')
   evt()