textmate_grammar.engine.matcher

Port of vscode-textmate’s src/matcher.ts.

Scope selectors such as text.html.php - (meta.embedded | meta.tag), L:text.html.php meta.tag are parsed into small composable predicate functions evaluated against a scope path. The semantics are intentionally 1:1 with the TypeScript source; comments throughout this module reference the corresponding sections of matcher.ts (and of grammar.ts/theme.ts where matcher.ts delegates the name-matching logic).

Note on ordering: the only ordering information matcher.ts itself produces is the L: (priority -1) / R: (priority 1) selector prefix, surfaced as MatcherWithPriority.priority. Sorting injections by that priority happens in grammar.ts (task 3b); specificity ordering of theme rules lives in theme.ts and is out of this plan’s scope.

Module Contents

Classes

MatcherWithPriority

matcher.ts interface MatcherWithPriority<T> { matcher; priority }.

ScopePath

The parent-linked scope chain matchers are evaluated against.

Functions

create_matchers

Port of matcher.ts createMatchers.

scopes_are_matching

Port of grammar.ts scopesAreMatching (matcher.ts delegates to it).

match_scope_identifiers

Port of grammar.ts nameMatcher, the matches_name matcher.ts is fed.

match_scope_names

Name matcher over a ScopePath parent chain.

Data

API

textmate_grammar.engine.matcher.T = 'TypeVar(...)'
textmate_grammar.engine.matcher.Matcher = None
textmate_grammar.engine.matcher.MatchesName = None
textmate_grammar.engine.matcher.Priority = None
class textmate_grammar.engine.matcher.MatcherWithPriority

Bases: typing.NamedTuple

matcher.ts interface MatcherWithPriority<T> { matcher; priority }.

matcher is a predicate over whatever input the caller evaluates against (grammar.ts uses the flat scope-name list of the current token); priority is the parsed L:/R: prefix.

matcher: collections.abc.Callable[[Any], bool] = None
priority: textmate_grammar.engine.matcher.Priority = None
class textmate_grammar.engine.matcher.ScopePath

Bases: typing.Protocol

The parent-linked scope chain matchers are evaluated against.

A scope path is a linked chain of scope names: the node a caller holds is the innermost scope, .name its scope name and .parent points towards the shallower scope; the root scope has parent = None. Materialized root-first this equals theme.ts’ ScopeStack.getSegments() (i.e. grammar.ts’ getScopeNames()). Minimal on purpose; the state stack built in task 3a satisfies this protocol structurally.

name: str = None
parent: textmate_grammar.engine.matcher.ScopePath | None = None
textmate_grammar.engine.matcher.create_matchers(selector: str, matches_name: textmate_grammar.engine.matcher.MatchesName[textmate_grammar.engine.matcher.T]) → list[textmate_grammar.engine.matcher.MatcherWithPriority]

Port of matcher.ts createMatchers.

Parses selector into its comma-separated branches and returns one MatcherWithPriority per branch. Callers treat the branch matchers as alternatives (matcher.ts consumers use matchers.some(...)). Only priority carries ordering information; the matchers are pure predicates.

textmate_grammar.engine.matcher.scopes_are_matching(scope_name: str, selector_scope: str) → bool

Port of grammar.ts scopesAreMatching (matcher.ts delegates to it).

True when the stack scope scope_name equals selector_scope or extends it at a . boundary: text.html matches text.html.php but not text.htmlx.

textmate_grammar.engine.matcher.match_scope_identifiers(identifiers: list[str], scopes: list[str]) → bool

Port of grammar.ts nameMatcher, the matches_name matcher.ts is fed.

Every identifier must occur as a subsequence of scopes, scanning strictly left to right: identifier order matters and each identifier consumes its position (repeated identifiers need repeated scopes). A stack scope matches an identifier via scopes_are_matching().

textmate_grammar.engine.matcher.match_scope_names(identifiers: list[str], scopes_path: textmate_grammar.engine.matcher.ScopePath | None) → bool

Name matcher over a ScopePath parent chain.

Equivalent to grammar.ts nameMatcher fed getScopeNames(): the chain is collected from the innermost node through the parents and then reversed to root-first order (theme.ts ScopeStack.getSegments()).