parse

Documentation

Overview

Package parse is the engine-neutral M parse substrate: it runs the tree-sitter-m grammar through a pure-Go WASM runtime (wazero) with no CGO, exposing a small Tree/Node API that fmt/lint/lsp build on (spec §4).

The grammar (tree-sitter-m) is C compiled to WASM; the mainstream Go tree-sitter binding is CGO, which would kill the CGO_ENABLED=0 static-binary premise. Embedding the grammar WASM and driving it via wazero keeps the whole binary static and lets the Go and TypeScript tiers share one grammar artifact. The .wasm bundles the tree-sitter runtime + the M grammar + a thin C shim (see ../wasm); build it with ../wasm/build.sh.

.mac is parsed as M, mechanically the same as .m; non-MUMPS .mac constructs (embedded SQL, preprocessor, ObjectScript) are out of scope (spec §4/§13).

Index

• func GrammarHash() string
• type Capture
• type Match
• type Node
  • func (n Node) Child(i uint32) Node
  • func (n Node) ChildCount() uint32
  • func (n Node) EndByte() uint32
  • func (n Node) EndPoint() Point
  • func (n Node) FieldNameForChild(i uint32) string
  • func (n Node) HasError() bool
  • func (n Node) IsError() bool
  • func (n Node) IsMissing() bool
  • func (n Node) IsNamed() bool
  • func (n Node) IsNull() bool
  • func (n Node) NamedChild(i uint32) Node
  • func (n Node) NamedChildCount() uint32
  • func (n Node) SExpr() string
  • func (n Node) StartByte() uint32
  • func (n Node) StartPoint() Point
  • func (n Node) Symbol() uint16
  • func (n Node) Text() []byte
  • func (n Node) Type() string
• type Parser
  • func New(ctx context.Context) (*Parser, error)
  • func (p *Parser) Close(ctx context.Context) error
  • func (p *Parser) GrammarABIVersion() uint32
  • func (p *Parser) NewQuery(source string) (*Query, error)
  • func (p *Parser) Parse(ctx context.Context, src []byte) (*Tree, error)
  • func (p *Parser) SymbolCount() uint32
• type Point
• type Query
  • func (q *Query) Close()
  • func (q *Query) Matches(n Node) []Match
• type Tree
  • func (t *Tree) Close()
  • func (t *Tree) RootNode() Node

Functions

func GrammarHash

func GrammarHash() string

GrammarHash is the sha256 of the embedded grammar WASM, printed by the consumer's --version for the pin/mirror audit trail (spec §4).

Types

type Capture

type Capture struct {
	Name string
	Node Node
}

Capture is a captured node together with its @name from the query.

type Match

type Match struct {
	PatternIndex uint32
	Captures     []Capture
}

Match is one match of a query pattern: the pattern's index plus its captures in capture order.

type Node

type Node struct {
	// contains filtered or unexported fields
}

Node is a handle to a node in a Tree. It is a value type but refers back to the owning Tree; it stays valid until the Tree is closed.

func (Node) Child

func (n Node) Child(i uint32) Node

Child returns the i-th child (all children, including anonymous tokens).

func (Node) ChildCount

func (n Node) ChildCount() uint32

ChildCount is the number of children (named and anonymous tokens).

func (Node) EndByte

func (n Node) EndByte() uint32

EndByte is the byte offset where the node's source span ends.

func (Node) EndPoint

func (n Node) EndPoint() Point

EndPoint is the node's end position as a row/column point.

func (Node) FieldNameForChild

func (n Node) FieldNameForChild(i uint32) string

FieldNameForChild is the grammar field name (e.g. "name") under which child i sits, or "" if the child is not in a field.

func (Node) HasError

func (n Node) HasError() bool

HasError reports whether the node or any descendant is an error/missing node.

func (Node) IsError

func (n Node) IsError() bool

IsError reports whether the node is a syntax-error node.

func (Node) IsMissing

func (n Node) IsMissing() bool

IsMissing reports whether the node was inserted by error recovery.

func (Node) IsNamed

func (n Node) IsNamed() bool

IsNamed reports whether the node is a named (rule) node vs. an anonymous token.

func (Node) IsNull

func (n Node) IsNull() bool

IsNull reports whether the handle is the tree-sitter null node (e.g. an out-of-range Child index).

func (Node) NamedChild

func (n Node) NamedChild(i uint32) Node

NamedChild returns the i-th named child (skips anonymous tokens).

func (Node) NamedChildCount

func (n Node) NamedChildCount() uint32

NamedChildCount is the number of named (rule) children, skipping tokens.

func (Node) SExpr

func (n Node) SExpr() string

SExpr returns the Lisp-style s-expression of the subtree (handy for tests).

func (Node) StartByte

func (n Node) StartByte() uint32

StartByte is the byte offset where the node's source span begins.

func (Node) StartPoint

func (n Node) StartPoint() Point

StartPoint is the node's start position as a row/column point.

func (Node) Symbol

func (n Node) Symbol() uint16

Symbol is the node's numeric grammar symbol id.

func (Node) Text

func (n Node) Text() []byte

Text returns the node's source slice, using the Tree's retained source.

func (Node) Type

func (n Node) Type() string

Type is the node's grammar type name (e.g. "command", "routine_header").

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

Parser owns one wazero instance of the grammar WASM. Parse and the Node/Tree accessors funnel through it; wazero modules are not reentrant, so every WASM-touching operation holds mu. Construct with New; release with Close. One Parser can produce many Trees sequentially.

func New

func New(ctx context.Context) (*Parser, error)

New instantiates the embedded grammar WASM in a fresh wazero runtime (pure-Go, CGO_ENABLED=0). The ctx is retained for subsequent WASM calls.

func (*Parser) Close

func (p *Parser) Close(ctx context.Context) error

Close deletes the parser and tears down the WASM runtime.

func (*Parser) GrammarABIVersion

func (p *Parser) GrammarABIVersion() uint32

GrammarABIVersion is the tree-sitter language ABI version of the embedded grammar.

func (*Parser) NewQuery

func (p *Parser) NewQuery(source string) (*Query, error)

NewQuery compiles a tree-sitter query against the M grammar. A compile error is returned with its kind and byte offset.

func (*Parser) Parse

func (p *Parser) Parse(ctx context.Context, src []byte) (*Tree, error)

Parse parses src as a fresh M document and returns its syntax tree. A tree with syntax errors is returned normally (inspect via Node.HasError); only a total grammar failure yields an error. The caller should Close the Tree.

func (*Parser) SymbolCount

func (p *Parser) SymbolCount() uint32

SymbolCount is the number of grammar symbols (rules + tokens).

type Point

type Point struct {
	Row    uint32
	Column uint32
}

Point is a zero-based source position (tree-sitter row/column, in bytes).

type Query

type Query struct {
	// contains filtered or unexported fields
}

Query is a compiled tree-sitter query against the M grammar. Compile one with Parser.NewQuery, run it over a Node with Matches, and Close it when done. Queries use tree-sitter's S-expression pattern syntax with @captures, e.g.

(command (command_keyword) @kw)

This is the substrate lint/lsp build their rules on (spec §4/§6).

func (*Query) Close

func (q *Query) Close()

Close frees the compiled query.

func (*Query) Matches

func (q *Query) Matches(n Node) []Match

Matches runs the query over the subtree rooted at n and returns its matches, grouped per match in document order. Captured nodes belong to n's Tree and stay valid until that Tree is closed.

type Tree

type Tree struct {
	// contains filtered or unexported fields
}

Tree is a parsed syntax tree. It owns the WASM-side tree plus every node handle produced from it; Close frees them all. A Tree is valid only while its Parser is open, and is not safe for concurrent use.

func (*Tree) Close

func (t *Tree) Close()

Close frees the tree and all node handles derived from it.

func (*Tree) RootNode

func (t *Tree) RootNode() Node

RootNode returns the tree's root node.