Module matcher

Convenient utilities to match syntax structures of code.

• Iterators/Finders to traverse nodes.
• Predicates to check nodes’ properties.
• Classifiers to check nodes’ syntax.

Classifiers of syntax structures

A node can have a quadruple to describe its syntax:

(InterpretMode, SurroundingSyntax/SyntaxContext, DefClass/SyntaxClass, SyntaxNode)

Among them, InterpretMode, SurroundingSyntax, and SyntaxContext describes outer syntax. DefClass, SyntaxClass and typst::syntax::SyntaxNode describes inner syntax.

• typst::syntax::SyntaxNode: Its contextual version is typst::syntax::LinkedNode, containing AST information, like inner text and SyntaxKind, on the position.
• SyntaxClass: Provided by classify_syntax, it describes the context-free syntax of the node that are more suitable for IDE operations. For example, it identifies users’ half-typed syntax like half-completed labels and dot accesses.
• DefClass: Provided by classify_def, it describes the definition class of the node at the position. The difference between SyntaxClass and DefClass is that the latter matcher will skip the nodes that do not define a definition.
• SyntaxContext: Provided by classify_context, it describes the outer syntax of the node that are more suitable for IDE operations. For example, it identifies the context of a cursor on the comma in a function call.
• SurroundingSyntax: Provided by surrounding_syntax, it describes the surrounding syntax of the node that are more suitable for IDE operations. The difference between SyntaxContext and SurroundingSyntax is that the former is more specific and the latter is more general can be used for filtering customized snippets.
• InterpretMode: Provided by interpret_mode_at, it describes the how an interpreter should interpret the code at the position.

Some examples of the quadruple (the cursor is marked by |):

#(x|);
   ^ SyntaxContext::Paren, SyntaxClass::Normal(SyntaxKind::Ident)
#(x,|);
    ^ SyntaxContext::Element, SyntaxClass::Normal(SyntaxKind::Array)
#f(x,|);
     ^ SyntaxContext::Arg, SyntaxClass::Normal(SyntaxKind::FuncCall)

#show raw|: |it => it|
         ^ SurroundingSyntax::Selector
            ^ SurroundingSyntax::ShowTransform
                     ^ SurroundingSyntax::Regular

Structs

InterpretModeIter

An iterator over the variants of InterpretMode

SurroundingSyntaxIter

An iterator over the variants of SurroundingSyntax

Enums

ArgClass

Classes of arguments that can be operated on by IDE functionality.

BadCompletionCursor

The cursor is on an invalid position.

DefClass

Classes of def items that can be operated on by IDE functionality.

FieldClass

Classes of field syntax that can be operated on by IDE functionality.

InterpretMode

A mode in which a text document is interpreted.

PreviousDecl

A declaration that is an ancestor of the given node or the previous sibling of some ancestor.

PreviousItem

A node that is an ancestor of the given node or the previous sibling of some ancestor.

SurroundingSyntax

Classes of syntax context (outer syntax) that can be operated on by IDE

SyntaxClass

Classes of syntax that can be operated on by IDE functionality.

SyntaxContext

Classes of syntax context (outer syntax) that can be operated on by IDE functionality.

VarClass

Classes of variable (access) syntax that can be operated on by IDE functionality.

Functions

bad_completion_cursor

Checks if the cursor is on an invalid position for completion.

classify_context

Classifies node’s context (outer syntax) that can be operated on by IDE functionality.

classify_context_outer

Classifies node’s context (outer syntax) by outer node that can be operated on by IDE functionality.

classify_def

Classifies a definition strictly.

classify_def_loosely

Classifies a definition loosely.

classify_syntax

Classifies node’s syntax (inner syntax) that can be operated on by IDE functionality.

first_ancestor_expr

Finds the first ancestor node that is an expression.

interpret_mode_at

Determine the interpretation mode at the given position (context-sensitive).

is_ident_like

Whether the node can be recognized as an identifier.

is_mark

Whether the node can be recognized as a mark.

node_ancestors

Returns the ancestor iterator of the given node.

previous_decls

Finds the previous declarations starting from the given position. It checks PreviousItem and returns the found declarations.

previous_items

Finds the previous items (in the scope) starting from the given position inclusively. See PreviousItem for the possible items.

surrounding_syntax

Determines the surrounding syntax of the node at the position.