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.