match

Macro input pattern matching utilities.

class macro_polo.match.DelimitedMacroMatcher(delimiter, matcher)

A delimited macro match pattern.

Parameters:

• delimiter (Delimiter)

• matcher (MacroMatcher)

delimiter: Delimiter

The delimiter to match.

match(tokens)

Attempt to match against a token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

matcher: MacroMatcher

The inner matcher.

class macro_polo.match.MacroMatch(size, captures)

Result of a successful macro match.

Parameters:

• size (int)

• captures (Mapping[str, Token | TokenTree | list[Token | TokenTree | list[MacroMatcherCapture] | MacroMatcherEmptyCapture] | MacroMatcherEmptyCapture])

captures: Mapping[str, Token | TokenTree | list[Token | TokenTree | list[MacroMatcherCapture] | MacroMatcherEmptyCapture] | MacroMatcherEmptyCapture]

Captured tokens.

size: int

Number of tokens matched.

exception macro_polo.match.MacroMatchError

Exception raised for macro matching errors.

class macro_polo.match.MacroMatcher(*args)

A macro match pattern.

Parameters:

args (MacroMatcherItem)

Return type:

Self

full_match(tokens)

Attempt to match against an entire token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

match(tokens)

Attempt to match against a token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

macro_polo.match.MacroMatcherCapture

Captured token(s), possibly repeating.

alias of Token | TokenTree | list[MacroMatcherCapture] | MacroMatcherEmptyCapture

class macro_polo.match.MacroMatcherEmptyCapture(depth)

An empty macro capture.

Preserves nesting depth information, primarily to enable better transcription error messages.

Parameters:

depth (int)

depth: int

Repeater nesting depth.

macro_polo.match.MacroMatcherItem

Union of types that can appear in a MacroMatcher.

alias of Token | DelimitedMacroMatcher | MacroMatcherVar | MacroMatcherRepeater | MacroMatcherUnion | MacroMatcherNegativeLookahead

class macro_polo.match.MacroMatcherNegativeLookahead(*args)

A negative lookahead macro match.

Matches zero tokens only if MacroMatcher would fail to match, and fails to match otherwise.

Parameters:

args (MacroMatcherItem)

Return type:

Self

match(tokens)

Attempt to match against a token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

class macro_polo.match.MacroMatcherRepeater(matcher, mode, sep=None)

A repeated sub-matcher.

Parameters:

• matcher (MacroMatcher)

• mode (MacroMatcherRepeaterMode)

• sep (Token | None)

property base_captures: Mapping[str, MacroMatcherEmptyCapture]

Get a set of empty captures for this matcher.

This is used to provide empty capture lists for matchers that match zero times, allowing transcribers to handle empty captures properly.

match(tokens)

Attempt to match against a token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

matcher: MacroMatcher

The matcher to repeat.

mode: MacroMatcherRepeaterMode

The repitition mode.

sep: Token | None

An optional separator token.

class macro_polo.match.MacroMatcherRepeaterMode(*values)

Matcher repeat mode.

ONE_OR_MORE = '+'

Match ≥1 times.

ZERO_OR_MORE = '*'

Match ≥0 times.

ZERO_OR_ONE = '?'

Match ≤1 times.

class macro_polo.match.MacroMatcherUnion(*args)

A union of macro matchers.

The first sub-matcher to match is used.

Parameters:

args (MacroMatcher)

match(tokens)

Attempt to match against a token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

class macro_polo.match.MacroMatcherVar(name, type)

A capture-variable in a macro matcher.

Parameters:

• name (str)

• type (MacroMatcherVarType)

match(tokens)

Attempt to match against a token sequence.

Parameters:

tokens (Sequence[Token])

Return type:

MacroMatch | None

name: str

The name to bind captured tokens to.

type: MacroMatcherVarType

The type of token(s) to match.

class macro_polo.match.MacroMatcherVarType(*values)

Capture-variable type.

NAME = 'name'

Any token.NAME token.

NULL = 'null'

Always matches, capturing an empty TokenTree

NUMBER = 'number'

Any token.NUMBER token.

OP = 'op'

Any non-delimeter token.OP token.

STRING = 'string'

Any token.STRING token.

TOKEN = 'token'

Any non-delimiter token.

TOKEN_TREE = 'tt'

Any non-delimiter token or a delimited sequence of tokens.