Package pego/runtime

import "github.com/ornew/pego/runtime"

const (
	TypeTupleValue = "(tuple)" // a tuple value: the Value of a tuple node
	TypeListValue  = "(list)"  // a list value: the Value of a list node, or a list made by an action
)

const (
	// TerminalClass, class, id: consumes one character of Classes[class], or records the
	// expectation id where it is expected.
	TerminalClass uint16 = iota
	// TerminalLiteral, literal, id: matches Literals[literal], or records id at its start.
	TerminalLiteral
	// TerminalSeq, operations...: matches the operations in turn.
	TerminalSeq
	// TerminalChoice, table, operations...: matches the first of the operations that matches.
	// Unless table is TerminalNoTable, the choice begins with a run of guarded alternatives
	// and Prepare builds the dispatch table number table for it if the table fits.
	TerminalChoice
	// TerminalOptional, operation: matches the operation or nothing.
	TerminalOptional
	// TerminalNot, operation: succeeds, consuming nothing, where the operation does not match.
	TerminalNot
	// TerminalGuard, class, id, operation: an alternative of a choice that is skipped where the
	// next character is not a member of Classes[class], recording id at the position of the
	// choice, as the generated code of a choice skips such an alternative; otherwise it is the
	// operation.
	TerminalGuard
	// TerminalGuardClass, class, id, operations...: a TerminalGuard of an alternative that
	// begins with the class Classes[class], whose operations are the rest of the alternative:
	// where the guard admits the next character, the class matches it, so the character is
	// consumed and the operations are matched in turn.
	TerminalGuardClass
)

const (
	RuleMemo uint8 = 1 << iota
	RuleLeader
	RuleNovalue
	RuleDocMemo
	RuleSplice
)

const (
	BaseString = iota
)

const TerminalNoTable uint16 = 0xffff

var (
	// RawKindMatch, RawKindSeq and RawKindList are for generated parsers; not a stable API.
	RawKindMatch = KindOf("string", "")
	RawKindSeq   = KindOf("tuple", "")
	RawKindList  = KindOf("list", "")
)

var DocumentBusy = fmt.Errorf("document is already parsing")

var EmptyFrame = &CaptureFrame{}

var EmptyTFrame = &TCaptureFrame{}

var ErrStreamClosed = errors.New("stream iterator is closed")

var ErrWorkLimit = errors.New("parse work limit exceeded")

#func Alloc source

func Alloc[T any](s *Chunk[T]) *T

Alloc returns a new zero value from the chunk, which grows from 8 to 256 values. It allocates the first three values independently, so a later published value cannot retain discarded early siblings through a chunk.

Alloc is for generated parsers; not a stable API.

#func AllocSlice source

func AllocSlice[T any](s *Chunk[T], n int) []T

AllocSlice returns n zero values with capacity n, so appending cannot overwrite another returned slice. Small-list chunks grow from 64 to 1,024 elements; a list of more than 256 elements is allocated on its own, and so is the first nonempty small list, to keep its backing values separate from later published lists of the same type. An empty list is not nil.

AllocSlice is for generated parsers; not a stable API.

#func DocumentParseConverted source

func DocumentParseConverted[T any](d *documentState, o parseOptions, convert func(*Node, *WorkControl, error) T) (res T, err error)

DocumentParseConverted keeps Node parsing and final typed conversion inside the same work-controlled invocation and memo cleanup boundary.

DocumentParseConverted is for generated parsers; not a stable API.

#func KindOf source

func KindOf(typ, rule string) *nodeKind

KindOf returns the interned kind of the type and rule names (rules and actions prepare theirs).

KindOf is for generated parsers; not a stable API.

#func NewGrammar source

func NewGrammar(maxDepth int) *grammar

NewGrammar returns an empty grammar with the default rule-call limit MaxDepth.

NewGrammar is for generated parsers; not a stable API.

#func NewNodeTypeKinds source

func NewNodeTypeKinds(typ string) *nodeTypeKinds

NewNodeTypeKinds returns the interned kinds of the named node type typ.

NewNodeTypeKinds is for generated parsers; not a stable API.

#func ResolveOptions source

func ResolveOptions(g *grammar, opts []ParseOption) (parseOptions, error)

ResolveOptions applies opts to the defaults of grammar g.

ResolveOptions is for generated parsers; not a stable API.

#func RunParseConverted source

func RunParseConverted[T any](r *Rule, input string, o parseOptions, conv func(*Node, *WorkControl, error) T) (res T, err error)

RunParseConverted shares admission and counters with a Node-to-typed converter.

RunParseConverted is for generated parsers; not a stable API.

#func RunParseStream source

func RunParseStream(r *Rule, reader io.Reader, emit func(*Node) error, opts []ParseOption) error

RunParseStream parses the input read from reader with rule r, passing each committed element of the rule's #stream repetition to emit.

RunParseStream is for generated parsers; not a stable API.

#func RunParseStreamWork source

func RunParseStreamWork(r *Rule, reader io.Reader, emit func(*Node, *WorkControl) error, opts []ParseOption) (err error)

RunParseStreamWork is RunParseStream with emit also given the parse's work control, so that converting elements to typed values is charged to it.

RunParseStreamWork is for generated parsers; not a stable API.

#func SetNodeElems source

func SetNodeElems(n *Node, elems []*Node)

SetNodeElems replaces the elements of the tuple or list n, which can make a cycle.

SetNodeElems is for generated parsers and tests; not a stable API.

#func SetNodeField source

func SetNodeField(n *Node, name string, v any)

SetNodeField sets the field name of n to v, adding it if absent.

SetNodeField is for generated parsers and tests; not a stable API.

#func SetNodeStart source

func SetNodeStart(n *Node, start int)

SetNodeStart replaces the start of the range of n.

SetNodeStart is for generated parsers and tests; not a stable API.

#func SetNodeText source

func SetNodeText(n *Node, text string)

SetNodeText replaces the string of the KindString node n.

SetNodeText is for generated parsers and tests; not a stable API.

#func SliceIdentity source

func SliceIdentity(value []any) nodeJSONSliceID

SliceIdentity is for generated parsers; not a stable API.

#func TAs source

func TAs[T any](v any) T

TAs returns v as a T, or the zero T (nil) if it is not one.

TAs is for generated parsers; not a stable API.

#func TBack source

func TBack(h *TPubHooks, v any) any

TBack returns the value of a field of an open type (a string node, a tuple or list node, an error value, a union, node or any) as a value of the typed runtime: the inverse of TPub, except that a tuple or list node becomes a tuple node and a []any a tuple value.

TBack is for generated parsers; not a stable API.

#func TDeref source

func TDeref[T any](p *T) any

#func TFreshNode source

func TFreshNode(v any) any

TFreshNode returns v if it is a fresh string, tuple or list node, and otherwise nil. Taken from the value of a rule's body before the rule finishes it, it is the node the body made and nothing else holds yet (see TConvertResultOwned).

TFreshNode is for generated parsers; not a stable API.

#func TKid source

func TKid(kids []any, i int) any

TKid returns element i of a tuple's elements (nil if there is none).

TKid is for generated parsers; not a stable API.

#func TListOf source

func TListOf(kids []any) any

TListOf returns a list value of kids, for reading a list field of a struct in an action.

TListOf is for generated parsers; not a stable API.

#func TMatchAs source

func TMatchAs[N any](x *TMatch) *N

TMatchAs returns the public form of x, a string node of a named node type whose Go type N is struct{ TNode[string] }: N has the layout of TNode[string] (the types package declares it so, and the parser package refers to the schema constant of the types package it was generated with, so a parser and a types package of different schemas do not compile together), so the public value is x's own TNode seen as an N. A node so publishes as one value wherever it appears, as a plain string node does, without allocating or remembering it.

TMatchAs is for generated parsers; not a stable API.

#func TParse source

func TParse[T any](r *TRule, input string, opts []ParseOption, ext any, conv func(any) T) (T, error)

TParse parses the whole input with the typed rule r, and returns the result converted by conv (before the parser's scratch memory, which the result may be in, is cleared). ext holds the generated code's chunks.

TParse is for generated parsers; not a stable API.

#func TParseResolved source

func TParseResolved[T any](r *TRule, input string, o parseOptions, ext any, conv func(any) T) (res T, err error)

TParseResolved consumes options already applied by the public entry point.

TParseResolved is for generated parsers; not a stable API.

#func TPtr source

func TPtr[T any](p *T) any

TPtr and TDeref return the value of a field of a pointer type as a value of the typed runtime.

TPtr is for generated parsers; not a stable API.

#func TPub source

func TPub(h *TPubHooks, v any) any

TPub returns the public form of a value: *TNode[string] and *Error for TMatch and TError, a *TNode[any] for a tuple or list node and a []any for a tuple or list value, with the public forms of their elements.

TPub is for generated parsers; not a stable API.

#func TPubIn source

func TPubIn(h *TPubHooks, a any, v any) any

TPubIn is TPub with the generated code's chunks a (a *tslabs, or nil), which the public forms of values of named node types (tnodeType.pub) are made from and remembered in.

TPubIn is for generated parsers; not a stable API.

#func TRegisterNodeType source

func TRegisterNodeType(name string, pub func(a any, x TVal) any) uint16

TRegisterNodeType registers a named node type of a grammar and returns its index. Types of different grammars have different indexes even when their names are the same.

TRegisterNodeType is for generated parsers; not a stable API.

#func TSetNodeType source

func TSetNodeType(v any, nt uint16) any

TSetNodeType gives v, a string, tuple or list node that back made, the named node type nt.

TSetNodeType is for generated parsers; not a stable API.

#func TypedDocumentParse source

func TypedDocumentParse[T any](d *Document, root *TRule, o parseOptions, a workControlSetter, publish func(any) T) (res T, err error)

TypedDocumentParse parses the Document d with the typed rule root and returns the value that publish makes of the parse result. The values of a typed Document parse are write-once: they are published as they are, and later parses reuse them, so publish must not write to them. a is the generated code's allocation chunks.

TypedDocumentParse is for generated parsers; not a stable API.

#func UnboxNode source

func UnboxNode(n *Node) any

UnboxNode returns the value that the carrier n stands for: the box's value for a box, nil for nil, and n otherwise.

UnboxNode is for generated parsers; not a stable API.

#func UnboxValue source

func UnboxValue(v any) any

UnboxValue is UnboxNode for a value that may be a carrier.

UnboxValue is for generated parsers; not a stable API.

#func Walk source

func Walk(root *Node, visit func(WalkVisit) (WalkAction, error)) error

Walk visits the root, then children in slice order, then fields in sorted name order. Nested []any values are visited in index order. Other containers are leaves. Shared nodes and lists are visited per edge; only cycles on the active path are rejected. Callback errors return unchanged; Stop succeeds; Skip omits the value's descendants. The graph must not be mutated concurrently. Walk does not mutate or retain it.

#type ActCtx source

type ActCtx struct {
	P *Parser

	Lhs, Rhs, Op any
	// contains filtered or unexported fields
}

ActCtx is the context of evaluating an action or a predicate.

ActCtx is for generated parsers; not a stable API.

#func (*ActCtx) And source

func (c *ActCtx) And(l any, r func() any) any

#func (*ActCtx) Binary source

func (c *ActCtx) Binary(op string, l, r any) any

#func (*ActCtx) Cap source

func (c *ActCtx) Cap(slot int) any

#func (*ActCtx) Cast source

func (c *ActCtx) Cast(v any, t *FieldType, line, col int) any

Cast returns v if it fits t, the type of a cast, and raises an evaluation error otherwise. The error names the input position where the action started and, when line is positive, the grammar position of the cast.

#func (*ActCtx) Concat source

func (c *ActCtx) Concat(args ...any) any

#func (*ActCtx) Convert source

func (c *ActCtx) Convert(typ string, v any) any

Convert evaluates a node type constructor T{v}: it converts v to the named node type typ.

#func (*ActCtx) EndList source

func (c *ActCtx) EndList(base int) any

EndList returns a list of the elements pushed since base.

#func (*ActCtx) FilterList source

func (c *ActCtx) FilterList(list any, f func(item any) any) any

#func (*ActCtx) Fold source

func (c *ActCtx) Fold(fn string, right bool, acc, list any, f func(acc, item any) any) any

#func (*ActCtx) Length source

func (c *ActCtx) Length(x any) any

#func (*ActCtx) List source

func (c *ActCtx) List(args ...any) any

#func (*ActCtx) ListItems source

func (c *ActCtx) ListItems(fn string, v any) []*Node

#func (*ActCtx) Lookup source

func (c *ActCtx) Lookup(name string) any

#func (*ActCtx) MapList source

func (c *ActCtx) MapList(list any, f func(item any) any) any

#func (*ActCtx) Member source

func (c *ActCtx) Member(x any, name string) any

Member reads x.Name.

#func (*ActCtx) NewList source

func (c *ActCtx) NewList(items []*Node) *Node

#func (*ActCtx) NewStruct source

func (c *ActCtx) NewStruct(typ string, kv ...any) any

#func (*ActCtx) Or source

func (c *ActCtx) Or(l any, r func() any) any

#func (*ActCtx) PushItems source

func (c *ActCtx) PushItems(v any)

#func (*ActCtx) PushList source

func (c *ActCtx) PushList(args ...any)

#func (*ActCtx) PushMap source

func (c *ActCtx) PushMap(list any, f func(item any) any)

#func (*ActCtx) Text source

func (c *ActCtx) Text(x any) any

#func (*ActCtx) TextStr source

func (c *ActCtx) TextStr(x any) string

TextStr returns text(x) as a string. Comparisons of two texts use it directly, since storing a string in an interface allocates.

#func (*ActCtx) Tuple source

func (c *ActCtx) Tuple(args ...any) any

Tuple returns a tuple value of the arguments, as a tuple literal builds it.

#func (*ActCtx) Unary source

func (c *ActCtx) Unary(op string, v any) any

#type CaptureFrame source

type CaptureFrame struct{ Vals []*Node }

CaptureFrame is for generated parsers; not a stable API.

#type Chunk source

type Chunk[T any] struct {
	// contains filtered or unexported fields
}

Chunk owns unused values and the next allocation size for one type. Generated parsers keep one per type of a typed value and take the values from it (Alloc, AllocSlice). Handed-out values are never reused, even when a parse discards them.

Chunk is for generated parsers; not a stable API.

#type Class source

type Class struct {
	ASCII [2]uint64
	Wide  []rune
	Neg   bool
}

Class is a character class for generated parsers; not a stable API. ASCII is the bitset of the characters below 128 that the class matches, Wide the inclusive [lo, hi] pairs of the members at or above 128, and Neg inverts the membership of the characters at or above 128 (the bitset already accounts for it below).

#func (*Class) Has source

func (c *Class) Has(r rune) bool

Has reports whether r belongs to the class.

#type ClassStep source

type ClassStep struct {
	C  *Class
	ID ExpID
}

ClassStep is one character class of a sequence, with the expectation to record when it fails.

#type Cursor source

type Cursor struct {
	Root *Node
	Unit PositionUnit
}

Cursor filters edge-oriented node visits using spans in Unit. Unit must match the parse that populated Root's positions; it is never inferred or converted. Parent spans do not prune traversal. Scalar and list values have no spans.

#func (Cursor) At source

func (c Cursor) At(position int32, visit func(WalkVisit) (WalkAction, error)) error

At visits nodes containing position, including zero-width nodes at position.

#func (Cursor) Range source

func (c Cursor) Range(start, end int32, visit func(WalkVisit) (WalkAction, error)) error

Range visits nodes overlapping [start,end). An empty range matches no nodes. Zero-width nodes match when start <= node.Start < end.

#type CycleError source

type CycleError struct{ Path []WalkEdge }

CycleError describes an active-path back-edge, including the root and failing edge.

#func (*CycleError) Error source

func (e *CycleError) Error() string

#type Document source

type Document struct {
	State *documentState
	// contains filtered or unexported fields
}

Document incrementally parses the configured start rule. It belongs to one goroutine; returned nodes may be shared with later parses.

Of its fields and methods, BeginParse, EndParse, ResolveParseOptions, State are for generated parsers; not a stable API.

#func MakeDocument source

func MakeDocument(root *Rule, text string, opts []ParseOption) (d *Document, err error)

MakeDocument is for generated parsers; not a stable API.

#func (*Document) BeginParse source

func (d *Document) BeginParse() error

#func (*Document) Edit source

func (d *Document) Edit(start, end int, text string) error

Edit replaces [start,end) in the Document's position unit.

#func (*Document) EndParse source

func (d *Document) EndParse()

#func (*Document) Parse source

func (d *Document) Parse(opts ...ParseOption) (*Node, error)

Parse parses the current text, applying invocation options after the Document's construction defaults. An invocation cannot change its unit.

#func (*Document) ResolveParseOptions source

func (d *Document) ResolveParseOptions(opts []ParseOption) (parseOptions, error)

#func (*Document) Stats source

func (d *Document) Stats() ParseStats

Stats returns the evaluation and reuse counts of the last Parse.

#func (*Document) Text source

func (d *Document) Text() string

Text returns the current exact input, including invalid UTF-8 bytes.

#type DocumentSliceKey source

type DocumentSliceKey struct {
	First    any
	Length   int
	Capacity int
}

A slice's first element, length and capacity identify an exact slice view. The element pointer keeps the backing array visible to the collector while cloning. Empty slices without capacity have no elements or mutable backing array to share.

DocumentSliceKey is for generated parsers; not a stable API.

#type Env source

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

Env is for generated parsers; not a stable API.

#type Error source

type Error struct {
	Span
	Text    string
	Message string
}

Error is input skipped by error recovery (#recover).

#func TPubError source

func TPubError(v any) *Error

TPubError is for generated parsers; not a stable API.

#type ExpID source

type ExpID int32

ExpID is an expectation: an index into descs. With MsgBit set, it is an @error message.

ExpID is for generated parsers; not a stable API.

const (
	IdAny ExpID = iota
	IdBeginInput
	IdEndInput
	IdBeginLine
	IdEndLine
)

const MsgBit ExpID = 1 << 30

#func RenamedExpected source

func RenamedExpected(p *Parser, expected []ExpID, name ExpID) []ExpID

RenamedExpected is for generated parsers; not a stable API.

#type ExpMark source

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

ExpMark is the expectation record before isolate.

ExpMark is for generated parsers; not a stable API.

#type FieldType source

type FieldType struct {
	Kind byte // i int, s string, b bool, z nil, n node[_], S node[string], v node[elem], E error, N struct or named node type, l list, t tuple (alts), o optional, u union, _ top
	Name string
	Elem *FieldType
	Alts []*FieldType
	Text string
}

FieldType is a type that a cast checks a dynamically typed value against. Generated code declares one for each cast.

FieldType is for generated parsers; not a stable API.

#type Fields source

type Fields []NodeField

Fields lists the fields of a node. It encodes to JSON as an object with keys in sorted order.

#func WalkFields source

func WalkFields(n *Node) Fields

findElement returns the path of x among the elements of the tuple node n and of the tuple nodes nested in it, breadth first. WalkFields returns the fields that Walk visits, in name order: the fields of a struct, and the captures of a node with source information except those whose values are its elements, which Walk visits as elements. Visiting those again would make Walk exponential in the nesting of operator nodes, whose captures are their operands. The captures of a node without source information are not part of the tree.

WalkFields is for generated parsers; not a stable API.

#func (Fields) Get source

func (fs Fields) Get(name string) (any, bool)

Get returns the value of the field name.

#func (Fields) MarshalJSON source

func (fs Fields) MarshalJSON() ([]byte, error)

MarshalJSON encodes the fields as an object with keys in sorted order.

#type Mark source

type Mark struct {
	Pos, Trail int
	// contains filtered or unexported fields
}

Mark is for generated parsers; not a stable API.

#type Node source

type Node struct {
	RawKind     *nodeKind // the type and rule names (Type, Rule)
	RawStart    int32     // the range in the input, in the parse's position unit (End is exclusive)
	RawEnd      int32
	RawText     string  // the text of a string node
	RawChildren []*Node // the elements of a tuple or list
	RawFields   Fields  // struct fields and captures

	RawFresh    bool
	RawTerminal bool
	// contains filtered or unexported fields
}

Node is a value of a parse result: a node, whose value is a string, a tuple or a list, an error value of recovery, a struct built by an action, or a carrier of another value. In JSON a node is an object with the members start, end and value, and, with source information, rule and captures.

Of its fields and methods, BaseNode, RawChildren, RawEnd, RawField, RawFields, RawFresh, RawKind, RawStart, RawTerminal, RawText are for generated parsers; not a stable API.

#func NewNode source

func NewNode(k NodeKind, start, end int, text string, elems []*Node, typ string, fields Fields, value any) *Node

NewNode returns a node of kind k with the range [start, end). text is the string of a KindString node, elems the elements of a tuple or list, typ the type name of a KindStruct node, fields its fields (or captures), and value the value of a KindValue node.

NewNode is for generated parsers and tests; not a stable API.

#func RunParse source

func RunParse(r *Rule, input string, opts []ParseOption) (n *Node, err error)

RunParse parses the whole input with rule r.

RunParse is for generated parsers; not a stable API.

#func RunParseResolved source

func RunParseResolved(r *Rule, input string, o parseOptions) (n *Node, err error)

RunParseResolved is for generated parsers; not a stable API.

#func (*Node) BaseNode source

func (n *Node) BaseNode() *Node

BaseNode returns the node n of a named node type as the string, tuple or list node it was converted from: a copy with the kind of that node (n itself for other nodes).

#func (*Node) Clone source

func (n *Node) Clone() *Node

Clone copies a Node graph while preserving shared Node identities and repeated []any or []*Node slice views. It does not clone arbitrary mutable action values.

#func (*Node) Elem source

func (n *Node) Elem(i int) *Node

Elem returns the element i of a tuple or a list: a node, or nil for an optional that did not match. It panics if i is out of the range [0, Len()).

#func (*Node) Elems source

func (n *Node) Elems() iter.Seq2[int, *Node]

Elems returns the elements of a tuple or a list in order, as Elem does.

#func (*Node) End source

func (n *Node) End() int

End returns the end of the range of the input that the node spans (exclusive), in the position unit of the parse.

#func (*Node) Field source

func (n *Node) Field(name string) any

Field returns the value of the field name of a struct, and, with source information, the value of the capture name of a node: a *Node, an int, a string, a bool, or nil.

#func (*Node) Fields source

func (n *Node) Fields() iter.Seq2[string, any]

Fields returns the fields of a struct, and, with source information, the captures of a node, in the order the action wrote them.

#func (*Node) IsTerminal source

func (n *Node) IsTerminal() bool

IsTerminal reports whether the node is a terminal.

#func (*Node) Kind source

func (n *Node) Kind() NodeKind

Kind returns what the node stands for.

#func (*Node) Len source

func (n *Node) Len() int

Len returns the number of elements of a tuple or a list (KindTuple, KindList, KindTupleValue, KindListValue), and 0 for other nodes and nil.

#func (*Node) MarshalJSON source

func (n *Node) MarshalJSON() ([]byte, error)

MarshalJSON encodes the node as an object (see Node).

#func (*Node) RawField source

func (n *Node) RawField(name string) any

RawField returns the value of the field or capture name, whether or not it is public.

#func (*Node) Rule source

func (n *Node) Rule() string

Rule returns the name of the rule that produced the node, with source information, or "".

#func (*Node) Start source

func (n *Node) Start() int

Start returns the start of the range of the input that the node spans, in the position unit of the parse.

#func (*Node) String source

func (n *Node) String() string

String renders the value as an S-expression of its shape, without positions: a string is quoted, a tuple is ( ), a list [ ], nil is nil, a struct is Name{Field: value}, and an error is error("message"). A node of a named node type N is written with N before its brackets: N("text"), N( ) and N[ ]. With source information, a node is followed by @rule, a captured element is preceded by name:, and a capture whose value is not an element is written after the elements as &name:value.

#func (*Node) Text source

func (n *Node) Text() string

Text returns the string value of a KindString node, and the message of a KindError value; it returns "" for other nodes and nil.

#func (*Node) Type source

func (n *Node) Type() string

Type returns the node's type name: string, tuple, list or error for the kinds of nodes, or the name of a type of the grammar.

#func (*Node) Value source

func (n *Node) Value() any

Value returns the value of a KindValue node (such as an int, a string or a bool) and the string of a KindString node; it returns nil for other nodes and nil.

#func (*Node) WriteJSON source

func (n *Node) WriteJSON(w io.Writer) error

WriteJSON writes the live node graph as JSON without recursive Node or []any traversal. A nil receiver writes null. Shared edges are encoded separately; active-path cycles fail. It does not close or flush w, and an error may leave a prefix written. Maps and other containers delegate to encoding/json and are outside the iterative depth guarantee. Callers must not mutate reachable values concurrently with this method.

#type NodeField source

type NodeField struct {
	Name  string
	Value any
}

NodeField is a field of a node.

#type NodeKind source

type NodeKind uint8

NodeKind is what a Node stands for in the value model.

const (
	// KindString is a node whose value is a string, the text it matched: Text.
	KindString NodeKind = iota
	// KindTuple is a node whose value is a tuple: Len and Elem.
	KindTuple
	// KindList is a node whose value is a list: Len and Elem.
	KindList
	// KindError is an error value of recovery: Text is its message.
	KindError
	// KindStruct is a struct built by an action: Type and Field.
	KindStruct
	// KindTupleValue is a tuple built by an action, without a range: Len and Elem.
	KindTupleValue
	// KindListValue is a list built by an action, without a range: Len and Elem.
	KindListValue
	// KindValue is any other value built by an action, such as an int or a bool: Value.
	KindValue
)

#func (NodeKind) String source

func (k NodeKind) String() string

#type OperatorsRule source

type OperatorsRule struct {
	Skip     matcher
	Operands []*OperatorsRuleLine
	Prefix   []*OperatorsRuleOp
	Led      []*OperatorsRuleOp
}

OperatorsRule is for generated parsers; not a stable API.

#type OperatorsRuleLine source

type OperatorsRuleLine struct {
	Scope  []string
	M      matcher
	Action func(*ActCtx) any
	// Value makes the value of an operand line without an action, and of an operator line's
	// operator, from the value of the line's expression.
	Value Shaper
}

OperatorsRuleLine is for generated parsers; not a stable API.

#type OperatorsRuleOp source

type OperatorsRuleOp struct {
	Id    int
	Kind  string
	Assoc string
	Level int
	Line  *OperatorsRuleLine
}

OperatorsRuleOp is for generated parsers; not a stable API.

#type ParseOption source

type ParseOption func(*parseOptions)

ParseOption configures an individual parsing invocation. Options apply in order.

#func WithContext source

func WithContext(ctx context.Context) ParseOption

WithContext selects cooperative cancellation for one invocation. A nil context is equivalent to context.Background.

#func WithDiagnosticCallback source

func WithDiagnosticCallback(f func(*SyntaxError) error) ParseOption

WithDiagnosticCallback reports each committed #recover error during ParseStream or Iterate, immediately before the corresponding stream element. Recoveries in abandoned alternatives are not reported. The callback receives an independent copy; returning an error stops parsing, suppresses that element and is returned unchanged. A nil callback disables delivery. The option is invalid with other entry points. Recoveries after the #stream repetition are reported before the result. With or without this option, recovered errors remain available at the end of the stream.

#func WithDiagnosticLimit source

func WithDiagnosticLimit(n int) ParseOption

WithDiagnosticLimit retains at most n committed stream recoveries, keeping the latest ones. Zero retains every error, as without the option. Negative values are invalid. The option, including zero, is valid only with stream entry points. When errors are dropped, the result is a *TruncatedSyntaxErrors.

#func WithMaxDepth source

func WithMaxDepth(n int) ParseOption

WithMaxDepth limits nested rule calls. Zero selects the generated default; a negative effective limit returns an error before parsing. A larger limit does not guarantee that the host stack can accommodate it.

#func WithProfile source

func WithProfile(profile *Profile) ParseOption

WithProfile accumulates complete generated rule-call metrics. It is independent of trace delivery filters. A Profile must not be shared by concurrent parses.

#func WithTrace source

func WithTrace(trace func(TraceEvent)) ParseOption

WithTrace observes actual generated calls synchronously. Callback panics propagate unchanged after cleanup; an aborted parse can omit exit events. Events do not expose input or parser state. ExaminedKnown is true only for Document parses, where Examined is the frontier used for edit reuse.

#func WithTraceFilter source

func WithTraceFilter(rules ...string) ParseOption

WithTraceFilter selects named rules and their nested calls. Unknown names match nothing. With no names, every entered rule is selected.

#func WithTraceMaxDepth source

func WithTraceMaxDepth(n int) ParseOption

WithTraceMaxDepth limits delivered events, counting the start rule as one. Zero and negative values leave delivery unlimited; parsing is unaffected.

#func WithUnit source

func WithUnit(unit PositionUnit) ParseOption

WithUnit selects the unit of input positions (CodePoints by default).

#func WithWorkLimits source

func WithWorkLimits(limits WorkLimits) ParseOption

WithWorkLimits bounds cumulative examined input and execution work. Zero leaves a counter unlimited; counters are never rolled back.

#type ParseStats source

type ParseStats struct {
	Evaluated int
	Reused    int
}

ParseStats counts rule evaluations and reused memo results in the last Parse.

#type Parser source

type Parser struct {
	Control *WorkControl

	// Observation observes the parse; it is nil unless the parse options select it.
	Observation *observation

	// Document is set only by the private incremental runner.
	Document *documentState

	In []rune // code points (CodePoints)

	Pos int

	MaxDepth int // invocation-local maximum nesting
	Depth    int // nesting of rule calls

	Env *Env

	Frame *CaptureFrame
	Trail []undo
	Cut   bool

	// Silent is positive inside lookaheads, where expectations are not recorded.
	Silent int

	Recovered []*SyntaxError

	KidStack []*Node

	// Stream is set only by ParseStream: positions then index its buffer.
	Stream *streamInput
	// contains filtered or unexported fields
}

Parser is for generated parsers; not a stable API.

#func (*Parser) Anchor source

func (p *Parser) Anchor(ok bool, desc ExpID) (*Node, bool)

#func (*Parser) AtEnd source

func (p *Parser) AtEnd() bool

#func (*Parser) AtEndBatch source

func (p *Parser) AtEndBatch() bool

AtEndBatch, AtLineStartBatch and their Ordinary forms are AtEnd and AtLineStart for the parsers that cannot stream (no ParseStream); small enough to inline.

#func (*Parser) AtEndBatchOrdinary source

func (p *Parser) AtEndBatchOrdinary() bool

AtEndBatchOrdinary is AtEndBatch in an ordinary parse (ExpectOrdinary).

#func (*Parser) AtEndOrdinary source

func (p *Parser) AtEndOrdinary() bool

AtEndOrdinary is AtEnd in an ordinary parse (ExpectOrdinary).

#func (*Parser) AtLineEnd source

func (p *Parser) AtLineEnd() bool

#func (*Parser) AtLineEndOrdinary source

func (p *Parser) AtLineEndOrdinary() bool

AtLineEndOrdinary is AtLineEnd in an ordinary parse (ExpectOrdinary).

#func (*Parser) AtLineStart source

func (p *Parser) AtLineStart() bool

#func (*Parser) AtLineStartBatch source

func (p *Parser) AtLineStartBatch() bool

#func (*Parser) AtLineStartBatchOrdinary source

func (p *Parser) AtLineStartBatchOrdinary() bool

AtLineStartBatchOrdinary is AtLineStartBatch in an ordinary parse (ExpectOrdinary).

#func (*Parser) AtLineStartOrdinary source

func (p *Parser) AtLineStartOrdinary() bool

AtLineStartOrdinary is AtLineStart in an ordinary parse (ExpectOrdinary).

#func (*Parser) AttachCaptures source

func (p *Parser) AttachCaptures(v *Node, names []string, f *CaptureFrame, start, end int) *Node

AttachCaptures attaches the non-nil captures as fields of the node. A node of another rule, or one that is itself captured, is first wrapped in a tuple node.

#func (*Parser) Bind source

func (p *Parser) Bind(name string, t func(*ActCtx) any) (ok bool)

Bind evaluates the value of a binding and binds it to the variable name. The compiler has checked that the value fits the variable.

#func (*Parser) Call source

func (p *Parser) Call(r *Rule, min int) (*Node, bool)

Call calls rule r at level min. An observed or Document parse takes callTracked, so that the call path of other parses has no observation or Document bookkeeping; callBody has the same logic with that bookkeeping.

#func (*Parser) DiagnosticAttr source

func (p *Parser) DiagnosticAttr(m matcher, name ExpID) (*Node, bool)

#func (*Parser) DropKids source

func (p *Parser) DropKids(base int)

DropKids pops p.KidStack[base:].

#func (*Parser) EmitStream source

func (p *Parser) EmitStream(v *Node, end int)

EmitStream passes a committed element of the start rule's #stream repetition to the caller and commits the input before end. Elements are final once emitted: a caller error ends the parse unchanged.

#func (*Parser) Enter source

func (p *Parser) Enter()

Enter counts one more rule call and fails the parse beyond the nesting limit.

#func (*Parser) ErrorAttr source

func (p *Parser) ErrorAttr(m matcher, msg ExpID) (*Node, bool)

ErrorAttr replaces the expectations of a failing m with the message msg (an ID with MsgBit), reported at the farthest position m reached.

#func (*Parser) ExaminedBegin source

func (p *Parser) ExaminedBegin() int

ExaminedBegin starts measuring an observed call's examined frontier in a Document parse, returning the enclosing frontier for ExaminedEnd. The call itself, and any memo entry it reads or records, extends the frontier as in an unobserved parse, so observation does not change reuse.

#func (*Parser) ExaminedEnd source

func (p *Parser) ExaminedEnd(enclosing int) (int, bool)

ExaminedEnd returns the call's frontier and merges it into the enclosing one. Outside a Document parse the frontier is unknown. A call that reuses a growing left-recursive seed sees the frontier recorded with an earlier seed; such results are provisional and never reused after an edit, so in a provisional context the report is raised to the call's end without changing the frontier the Document keeps.

#func (*Parser) Expect source

func (p *Parser) Expect(pos int, id ExpID)

Expect records that id was expected at pos.

#func (*Parser) ExpectOrdinary source

func (p *Parser) ExpectOrdinary(pos int, id ExpID)

ExpectOrdinary is expect in an ordinary parse: one without work controls and outside a Document (p.Control == nil && p.Document == nil). The generated rule bodies have a branch for such parses that calls the Ordinary forms of the runtime helpers, which leave out the work charges and the Document's record of the examined input.

#func (*Parser) Finish source

func (p *Parser) Finish(r *Rule, f *CaptureFrame, v *Node, start int) *Node

Finish makes the rule's value from the value of its body.

#func (*Parser) FirstCall source

func (p *Parser) FirstCall(r *Rule) bool

FirstCall records a call of rule r at the current position and reports whether its memoization is deferred: it is the first call there, and repeated calls of the rule have been rare so far. Results are reused only when a rule is called again at a position, which is rare, so memoizing every first call cost an entry each for nothing; deferring memoization to the second call evaluates a rule at most twice per position, which keeps parse time linear.

#func (*Parser) InputWork source

func (p *Parser) InputWork(n uint64)

Work helpers keep long engine-owned scans between bounded reservations.

InputWork has one guarded call so that it inlines into the matchers.

#func (*Parser) InvokePlain source

func (p *Parser) InvokePlain(r *Rule, min int) (*Node, bool)

InvokePlain is an unmemoized call of a rule without captures: invoke without the capture frame (the body never writes one, so the caller's stays current), with the failure handling of call.

#func (*Parser) Isolate source

func (p *Parser) Isolate(pos int) ExpMark

Isolate starts a separate expectation record whose farthest position is pos.

#func (*Parser) Keep source

func (p *Parser) Keep(ids []ExpID) []ExpID

Keep copies ids into the append-only arena.

#func (*Parser) Kids source

func (p *Parser) Kids(base int) []*Node

Kids returns p.KidStack[base:] as a child list and pops it.

#func (*Parser) LiteralText source

func (p *Parser) LiteralText(start int, text string) string

LiteralText returns source bytes if replacement decoding accepted a shorter spelling than the literal, retaining the usual constant-text success path.

#func (*Parser) MakeError source

func (p *Parser) MakeError(pos int, expected []ExpID) *SyntaxError

#func (*Parser) Mark source

func (p *Parser) Mark() Mark

#func (*Parser) MatchAny source

func (p *Parser) MatchAny(build bool) (*Node, bool)

#func (*Parser) MatchAnyOrdinary source

func (p *Parser) MatchAnyOrdinary(build bool) (*Node, bool)

MatchAnyOrdinary is MatchAny in an ordinary parse (ExpectOrdinary).

#func (*Parser) MatchLiteral source

func (p *Parser) MatchLiteral(rs []rune, text string, desc ExpID, build bool) (*Node, bool)

#func (*Parser) MatchLiteralFold source

func (p *Parser) MatchLiteralFold(rs []rune, desc ExpID, build bool) (*Node, bool)

MatchLiteralFold is MatchLiteral for a case-insensitive literal. rs is the literal with each ASCII letter lowercased, and each input character is folded the same way before it is compared, so only ASCII letters ignore case. The node text is the consumed input. Peek records the examined characters and the work of each one, so the loop needs no bookkeeping of its own.

#func (*Parser) MatchLiteralFoldOrdinary source

func (p *Parser) MatchLiteralFoldOrdinary(rs []rune, desc ExpID, build bool) (*Node, bool)

MatchLiteralFoldOrdinary is MatchLiteralFold in an ordinary parse (ExpectOrdinary).

#func (*Parser) MatchLiteralOrdinary source

func (p *Parser) MatchLiteralOrdinary(rs []rune, text string, desc ExpID, build bool) (*Node, bool)

MatchLiteralOrdinary is MatchLiteral in an ordinary parse (ExpectOrdinary).

#func (*Parser) MergeExpected source

func (p *Parser) MergeExpected(far int, ids []ExpID)

MergeExpected records the expectations ids at far. ids may alias the stack above the current record (writes only happen below the read position).

#func (*Parser) NewBranch source

func (p *Parser) NewBranch(kind *nodeKind, start int, children []*Node) *Node

NewBranch returns the node of kind (RawKindSeq or RawKindList) with children from start to the current position, allocated like NewNode(Node{RawKind: kind, ...}).

#func (*Parser) NewBranchOrdinary source

func (p *Parser) NewBranchOrdinary(kind *nodeKind, start int, children []*Node) *Node

NewBranchOrdinary is NewBranch in an ordinary parse (ExpectOrdinary).

#func (*Parser) NewErrorNode source

func (p *Parser) NewErrorNode(start int, e *SyntaxError) *Node

NewErrorNode returns the node that stands for the input from start to the current position, which a recovery (#recover) skipped after the syntax error e: an error node with the message of e, allocated like NewNode.

NewErrorNode is for generated parsers; not a stable API.

#func (*Parser) NewFrame source

func (p *Parser) NewFrame(n int) *CaptureFrame

NewFrame returns a capture frame with n slots.

#func (*Parser) NewNode source

func (p *Parser) NewNode(v Node) *Node

NewNode returns a copy of v allocated from the node slab. A slab stays alive while any of its nodes is referenced.

#func (*Parser) NewNodeOrdinary source

func (p *Parser) NewNodeOrdinary(v Node) *Node

NewNodeOrdinary is NewNode in an ordinary parse (ExpectOrdinary).

#func (*Parser) NewTerminal source

func (p *Parser) NewTerminal(start int, text string) *Node

NewTerminal returns the node of text matched from start to the current position, allocated like NewNode(Node{RawKind: RawKindMatch, ...}).

#func (*Parser) NewTerminalOrdinary source

func (p *Parser) NewTerminalOrdinary(start int, text string) *Node

NewTerminalOrdinary is NewTerminal in an ordinary parse (ExpectOrdinary).

#func (*Parser) NextOrdinary source

func (p *Parser) NextOrdinary() (r rune, size int, ok bool)

NextOrdinary is PeekOrdinary with the common case, a code-point input, written so that the compiler inlines it (the named results keep it within the inlining budget).

#func (*Parser) Nodes source

func (p *Parser) Nodes(n int) []*Node

Nodes returns a child list of length and capacity n from the pointer slab.

#func (*Parser) OperatorsRuleParse source

func (p *Parser) OperatorsRuleParse(r *Rule, min int) (*Node, bool)

OperatorsRuleParse parses an expression with operators that bind tighter than min. Each level of its recursion (the operand of a prefix operator, the right operand of an infix operator) counts against the nesting limit, like a rule call.

#func (*Parser) Peek source

func (p *Parser) Peek() (rune, int, bool)

Peek returns the character at the current position and its size in units.

#func (*Parser) PeekOrdinary source

func (p *Parser) PeekOrdinary() (rune, int, bool)

PeekOrdinary is peek in an ordinary parse (ExpectOrdinary).

#func (*Parser) Predicate source

func (p *Parser) Predicate(t func(*ActCtx) any) (ok bool)

#func (*Parser) RecoverAttr source

func (p *Parser) RecoverAttr(m, skip matcher, build bool) (*Node, bool)

RecoverAttr records the error of a failing m, skips what skip matches and returns an Error node. It fails without recovering when skip fails or skips nothing.

#func (*Parser) RecoveryErrorText source

func (p *Parser) RecoveryErrorText(e *SyntaxError) string

RecoveryErrorText is only for engine-owned Error-node materialization. Public post-return Error/Message calls remain caller work. The local builder owns its immutable output and is never pooled or written after return.

#func (*Parser) RejectWorkClass source

func (p *Parser) RejectWorkClass(ch rune, ranges []WorkRange, negated bool) bool

#func (*Parser) Reset source

func (p *Parser) Reset(m Mark)

#func (*Parser) Restore source

func (p *Parser) Restore(pos, rec int)

Restore goes back to the position pos and to the recovered errors of the first rec, as a failed alternative does.

#func (*Parser) ScopeValue source

func (p *Parser) ScopeValue(s Shaper, v *Node, start int) *Node

ScopeValue returns the value of a scope whose body matched [start, p.Pos) with the result v.

#func (*Parser) SetCapture source

func (p *Parser) SetCapture(slot int, v *Node)

#func (*Parser) SetCaptureOrdinary source

func (p *Parser) SetCaptureOrdinary(slot int, v *Node)

SetCaptureOrdinary is SetCapture in an ordinary parse (ExpectOrdinary).

#func (*Parser) ShapeCapture source

func (p *Parser) ShapeCapture(s Shaper, v *Node, start int) *Node

ShapeCapture is ShapeSingle for a capture or a recovered expression, whose value is the unit node of the range matched when the expression has no value.

#func (*Parser) ShapeSingle source

func (p *Parser) ShapeSingle(s Shaper, v *Node, start int) (*Node, bool)

ShapeSingle returns the value of the result v where the expression takes one element; ok is false when it has no value.

#func (*Parser) Single source

func (p *Parser) Single(size int, build bool) (*Node, bool)

Single consumes one character of size units.

#func (*Parser) StepWork source

func (p *Parser) StepWork()

#func (*Parser) StreamStart source

func (p *Parser) StreamStart()

StreamStart is called when the start rule's #stream repetition starts. The capture frames allocated so far, including the start rule's, stay in use; elements allocate their nodes from chunks of their own.

#func (*Parser) Text source

func (p *Parser) Text(start, end int) string

#func (*Parser) TextEqual source

func (p *Parser) TextEqual(l, r string) bool

#func (*Parser) TooDeep source

func (p *Parser) TooDeep()

TooDeep fails the parse for exceeding the nesting limit.

#func (*Parser) Unisolate source

func (p *Parser) Unisolate(m ExpMark) (far int, inner []ExpID)

Unisolate ends the separate record and returns its farthest position and expectations. The expectations alias the stack and are valid only until the next record (passing them to MergeExpected is fine; keep copies them).

#type PositionUnit source

type PositionUnit int

PositionUnit is the unit of input positions.

const (
	// CodePoints counts Unicode code points. It is the default.
	CodePoints PositionUnit = iota
	// Bytes counts UTF-8 bytes.
	Bytes
)

#type Profile source

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

Profile accumulates generated rule execution across invocations. Its zero value is ready to use. It must not be used concurrently; recursive parses on the same goroutine have independent accounting state. It retains no input, nodes, callbacks or per-position history after a parse returns.

#func (*Profile) Snapshot source

func (pr *Profile) Snapshot() ProfileSnapshot

Snapshot returns independent, deterministically ordered counters. A rule with no completed call, or with a completed call outside a Document parse, reports Examined and Wasted as unknown rather than inferring examined input from matched ranges. Like parsing, Snapshot requires exclusive access to the Profile.

#type ProfileLocation source

type ProfileLocation struct {
	Pos   int `json:"pos"`
	Level int `json:"level"`
}

ProfileLocation identifies a position and Operators Rule binding level.

#type ProfileSnapshot source

type ProfileSnapshot struct {
	Parses   int           `json:"parses"`
	Entered  int           `json:"entered"`
	Calls    int           `json:"calls"`
	Evals    int           `json:"evals"`
	MemoHits int           `json:"memoHits"`
	Skipped  int           `json:"skipped"`
	Time     time.Duration `json:"time"`
	Rules    []RuleProfile `json:"rules"`
}

ProfileSnapshot is an owned copy of a profile, with Rules sorted by name. Parses and Entered include calls interrupted before exit; Calls and the other completed-call metrics include only calls that emitted an exit. Time sums completed root rule calls, excluding input setup, end checks and conversion. Counters use each invocation's position unit without normalization.

#type Rule source

type Rule struct {
	Id     int
	Name   string
	Scope  []string // capture names of the rule body, in slot order
	Body   func(p *Parser, min int) (*Node, bool)
	Action func(c *ActCtx) any
	Value  Shaper // makes the rule's value from the value of its body, without an action
	// NodeType, if not "", is the named node type the rule's value is converted to, whose kinds
	// are nodeKinds.
	NodeType string

	// OpNodeType, if not "", is the named node type every operator node of an Operators Rule is
	// converted to, whose kinds are opKinds.
	OpNodeType string

	// Memo means the rule's results are memoized. It is false for transient rules, whose entries
	// could never be reused.
	Memo bool
	// Leader is the leader of a left-recursive cycle; its results are always memoized.
	Leader bool
	// DocMemo means Documents memoize the rule, transient or not. It is false
	// for the other rules of a left-recursive cycle, whose results depend on
	// the leader's growing seed, as in the engine.
	DocMemo bool
	// Seen is the rule's index among the memoized rules whose memoization is deferred to the
	// second call at a position (FirstCall), or -1.
	Seen          int
	OperatorsRule *OperatorsRule
	Novalue       bool // value-free twin, called where the value is discarded
	// Splice means the rule makes no node of its own: its value is the result of its body as it is,
	// and the captures of its body end with it. Its callers take the elements of the value.
	Splice bool
	// Where, if not "", names the rule in the message of a failed action, instead of Name: the
	// hidden rule of an inline action is named by the rule that holds the action.
	Where string
	// Vars are the variables the rule or its callees read, sorted. Memo entries are keyed by their
	// values at the call, since definitions inside the rule are undone when it returns.
	Vars []string
	// contains filtered or unexported fields
}

Rule is for generated parsers; not a stable API.

#func NewRules source

func NewRules[S ~struct {
	Name  string
	Value *Shaper
	Flags uint8
	Seen  int32
	Scope uint16
	Vars  uint16
}, E ~struct {
	Id         int
	Where      string
	NodeType   string
	OpNodeType string
}](specs []S, strs [][]string, extras []E) []*Rule

NewRules builds the rule table of the specs, with the string lists their Scope and Vars index and the rare fields in extras. The entries have the fields of RuleSpec and RuleExtra in their order, in types of the caller, so that generated code can write them without field names (go vet accepts unkeyed fields only for a type of the same package).

For generated parsers; not a stable API.

#type RuleExtra source

type RuleExtra struct {
	Id         int
	Where      string
	NodeType   string
	OpNodeType string
}

RuleExtra holds the fields of the Rule with the Id that are rarely set.

For generated parsers; not a stable API.

#type RuleProfile source

type RuleProfile struct {
	Rule          string            `json:"rule"`
	Entered       int               `json:"entered"`
	Calls         int               `json:"calls"`
	Evals         int               `json:"evals"`
	MemoHits      int               `json:"memoHits"`
	Matched       int               `json:"matched"`
	Failed        int               `json:"failed"`
	Consumed      int               `json:"consumed"`
	Skipped       int               `json:"skipped"`
	SkipReasons   []SkipReasonCount `json:"skipReasons"`
	Repeats       int               `json:"repeats"`
	MaxEvals      int               `json:"maxEvals"`
	MaxEvalsAt    ProfileLocation   `json:"maxEvalsAt"`
	Examined      int               `json:"examined"`
	ExaminedKnown bool              `json:"examinedKnown"`
	Wasted        int               `json:"wasted"`
	WastedKnown   bool              `json:"wastedKnown"`
	Time          time.Duration     `json:"time"`
	SelfTime      time.Duration     `json:"selfTime"`
}

RuleProfile describes actual generated calls of one rule. Skipped counts only identifiable optimized dispatch sites and is separate from Entered. Examined sums, over completed calls, the input from each call's position to its trace Examined frontier; Wasted sums the same for completed failed calls that did not reuse a memo result. Both are known only when every completed call of the rule had a known frontier, that is, when the rule was profiled only in Document parses; like the frontier, they are conservative. Within one invocation, Time counts recursive calls of the same rule once; SelfTime excludes children. Reentrant invocations are accumulated separately. Both include instrumentation and callback costs within the timed boundary.

#type RuleSpec source

type RuleSpec struct {
	Name  string
	Value *Shaper
	Flags uint8
	Seen  int32
	Scope uint16
	Vars  uint16
}

RuleSpec is the compact form of the analysis results of a rule, which generated parsers keep as static data. Its Id is its position in the table. Scope and Vars index the string lists given to NewRules, 0 for none; a nil Value is the zero Shaper. Seen is the Seen field of the Rule plus one, so that the zero value is the -1 of a rule whose memoization is not deferred.

For generated parsers; not a stable API.

#type Shaper source

type Shaper struct {
	Elems bool       // the method returns the tuple node of its elements
	K     int        // the number of valued elements
	Mode  singleMode // how the expression takes one element
	Tuple bool       // the value of a scope is the node of its tuple, rather than its one element
	// Shared means the tuple node the method returns (Elems) is the result of a splice rule, shared
	// through its memo entry: a node that takes it as its own takes a copy.
	Shared bool
}

Shaper converts the result of an expression's method to the value where the expression takes one element or is a scope (a rule body, a repetition element or an Operators Rule line). The generator fills it from the expression's static shape, as the engine does.

Shaper is for generated parsers; not a stable API.

#type SkipReasonCount source

type SkipReasonCount struct {
	Reason string `json:"reason"`
	Count  int    `json:"count"`
}

SkipReasonCount counts calls omitted by one identifiable dispatch reason.

#type Span source

type Span struct{ Start, End int }

Span is the range of input a typed value covers, in the parse's position unit (End is exclusive).

Of its fields and methods, TSetSpan, TSpan are for generated parsers; not a stable API.

#func (Span) Range source

func (s Span) Range() (start, end int)

Range returns the start and the end (exclusive) of the span.

#func (*Span) TSetSpan source

func (s *Span) TSetSpan(start, end int)

#func (*Span) TSpan source

func (s *Span) TSpan() (int, int)

#type StreamIterator source

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

StreamIterator returns the committed elements of a stream one at a time. It is single-owner: Next and Close must not overlap, including from callbacks. Close releases the parser state but never closes or interrupts the reader.

#func NewStreamIterator source

func NewStreamIterator(pull *StreamPull[*Node]) *StreamIterator

NewStreamIterator returns the iterator over the elements pull yields.

NewStreamIterator is for generated parsers; not a stable API.

#func (*StreamIterator) Close source

func (it *StreamIterator) Close()

Close abandons unfinished parsing, after which Next returns ErrStreamClosed. It is idempotent and does not change the result of a finished stream. It cannot interrupt a Read already blocked in caller code, and must not overlap a call to Next.

#func (*StreamIterator) Next source

func (it *StreamIterator) Next() (*Node, bool, error)

Next returns (node, true, nil) for each committed element, with a nil node for an element without a value. At the end of a clean stream it returns (nil, false, nil), and after a failure (nil, false, err); later calls return the same result.

#type StreamPull source

type StreamPull[T any] struct {
	// contains filtered or unexported fields
}

StreamPull advances a stream parse synchronously to one committed element at a time. The standard library pull coroutine has no independently scheduled producer.

StreamPull is for generated parsers; not a stable API.

#func IterateStream source

func IterateStream[T any](g *grammar, opts []ParseOption, parse func(emit func(T) error) error) (*StreamPull[T], error)

IterateStream validates the options of a stream entry point of grammar g and returns a lazy iterator over the elements that parse passes to emit.

IterateStream is for generated parsers; not a stable API.

#func (*StreamPull[T]) Close source

func (it *StreamPull[T]) Close()

#func (*StreamPull[T]) Next source

func (it *StreamPull[T]) Next() (v T, ok bool, err error)

#type SyntaxError source

type SyntaxError struct {
	Pos      int
	Line     int
	Col      int
	Expected []string
	Messages []string
}

SyntaxError reports that the input does not match the grammar.

#func (*SyntaxError) Error source

func (e *SyntaxError) Error() string

#func (*SyntaxError) Message source

func (e *SyntaxError) Message() string

Message describes the error without its position.

#type SyntaxErrors source

type SyntaxErrors []*SyntaxError

SyntaxErrors lists the syntax errors recovered from with #recover.

#func (SyntaxErrors) Error source

func (l SyntaxErrors) Error() string

#type TActCtx source

type TActCtx struct {
	P            *TParser
	F            *TCaptureFrame
	Start, End   int
	Cbase        int
	Lhs, Rhs, Op any
}

TActCtx is the context of evaluating an action or a predicate (ActCtx in the typed runtime).

TActCtx is for generated parsers; not a stable API.

#func (*TActCtx) And source

func (c *TActCtx) And(l any, r func() any) any

#func (*TActCtx) Binary source

func (c *TActCtx) Binary(op string, l, r any) any

#func (*TActCtx) Cap source

func (c *TActCtx) Cap(slot int) any

#func (*TActCtx) Cast source

func (c *TActCtx) Cast(v any, t *FieldType, line, col int) any

Cast is ActCtx.Cast for the values of the typed runtime.

#func (*TActCtx) Compare source

func (c *TActCtx) Compare(op string, l, r TOperand) any

Compare applies a comparison operator as binary does, comparing two strings directly.

#func (*TActCtx) Concat source

func (c *TActCtx) Concat(args ...any) any

#func (*TActCtx) Convert source

func (c *TActCtx) Convert(nt uint16, v any) any

Convert evaluates a node type constructor T{v} (ActCtx.Convert): it converts v to the named node type with the index nt.

#func (*TActCtx) EndList source

func (c *TActCtx) EndList(base int) any

#func (*TActCtx) FieldOperand source

func (c *TActCtx) FieldOperand(x any, name string) TOperand

FieldOperand reads x.Name as member does, keeping a string field of a struct unboxed.

#func (*TActCtx) FilterList source

func (c *TActCtx) FilterList(list any, f func(item any) any) any

#func (*TActCtx) Finish source

func (c *TActCtx) Finish(v any) any

Finish checks and finishes the value v of an action (see result): a struct the action made takes the rule's range, and the value is no longer fresh. A value other than a node needs no carrier here.

#func (*TActCtx) Fold source

func (c *TActCtx) Fold(fn string, right bool, acc, list any, f func(acc, item any) any) any

#func (*TActCtx) Length source

func (c *TActCtx) Length(x any) any

#func (*TActCtx) List source

func (c *TActCtx) List(args ...any) any

#func (*TActCtx) ListItems source

func (c *TActCtx) ListItems(fn string, v any) []any

#func (*TActCtx) Lookup source

func (c *TActCtx) Lookup(name string) any

#func (*TActCtx) MadeOf source

func (c *TActCtx) MadeOf(n TVal, fields ...any) any

MadeOf finishes a struct value n made by an action from the field values it was made of: n takes the range that covers the field values that are nodes, or the range of the rule if there is none (see NewStruct). The variadic list stays on the stack of the generated constructor.

MadeOf is for generated parsers; not a stable API.

#func (*TActCtx) MapList source

func (c *TActCtx) MapList(list any, f func(item any) any) any

#func (*TActCtx) Member source

func (c *TActCtx) Member(x any, name string) any

#func (*TActCtx) NewList source

func (c *TActCtx) NewList(items []any) any

#func (*TActCtx) Or source

func (c *TActCtx) Or(l any, r func() any) any

#func (*TActCtx) PushItems source

func (c *TActCtx) PushItems(v any)

#func (*TActCtx) PushList source

func (c *TActCtx) PushList(args ...any)

#func (*TActCtx) PushMap source

func (c *TActCtx) PushMap(list any, f func(item any) any)

#func (*TActCtx) Result source

func (c *TActCtx) Result(action func(*TActCtx) any, where string) (n any)

Result evaluates an action. Its errors fail the parse: tparse reports them with the rule name, which result records in p.Where instead of deferring a recovery for each action.

#func (*TActCtx) Text source

func (c *TActCtx) Text(x any) any

#func (*TActCtx) TextStr source

func (c *TActCtx) TextStr(x any) string

#func (*TActCtx) Tuple source

func (c *TActCtx) Tuple(args ...any) any

Tuple returns a tuple value of the arguments, as a tuple literal builds it.

#func (*TActCtx) Unary source

func (c *TActCtx) Unary(op string, v any) any

#type TCaptureFrame source

type TCaptureFrame struct{ Vals []any }

TCaptureFrame is for generated parsers; not a stable API.

#type TError source

type TError struct {
	Error
	// contains filtered or unexported fields
}

TError is for generated parsers; not a stable API.

#func NewTError source

func NewTError(start, end int, text, message string) *TError

NewTError returns a fresh error value for the input range [start, end) that recovery skipped.

NewTError is for generated parsers; not a stable API.

#func (*TError) TField source

func (e *TError) TField(name string) (any, bool)

#func (*TError) TFresh source

func (e *TError) TFresh() bool

#func (*TError) TKids source

func (e *TError) TKids() []any

#func (*TError) TName source

func (e *TError) TName() string

#func (*TError) TSetFresh source

func (e *TError) TSetFresh(f bool)

#func (*TError) TStruct source

func (e *TError) TStruct() bool

#func (*TError) TText source

func (e *TError) TText() (string, bool)

#type TMatch source

type TMatch struct {
	TNode[string]

	Nt uint16
	// contains filtered or unexported fields
}

TMatch and TError are a string node and an Error while the typed runtime handles them: whether the value is fresh (see Node.RawFresh) is part of the state of the parse, not of the result. The result holds pointers to the embedded TNode[string] and Error (TPub). A string node of a named node type has nt, the type's registered index (TRegisterNodeType; 0 for a plain string node).

TMatch is for generated parsers; not a stable API.

#func (*TMatch) TField source

func (m *TMatch) TField(string) (any, bool)

#func (*TMatch) TFresh source

func (m *TMatch) TFresh() bool

#func (*TMatch) TKids source

func (m *TMatch) TKids() []any

#func (*TMatch) TName source

func (m *TMatch) TName() string

#func (*TMatch) TSetFresh source

func (m *TMatch) TSetFresh(f bool)

#func (*TMatch) TStruct source

func (m *TMatch) TStruct() bool

#func (*TMatch) TText source

func (m *TMatch) TText() (string, bool)

#type TNode source

type TNode[T any] struct {
	Span
	Value T
}

TNode is a node whose Value has type T: a string node (TNode[string]) holds the text a literal, a character class, ., a #atomic or _ matched, and a tuple or list node holds its elements. A node of a statically unknown value is a TNode[any] whose Value is a string, or a []any of the elements of a tuple or list.

#func TPubMatch source

func TPubMatch(v any) *TNode[string]

TPubMatch is for generated parsers; not a stable API.

#func TPubNode source

func TPubNode(h *TPubHooks, v any) *TNode[any]

TPubNode returns the public form of a node of a statically unknown value: a TNode[any], also for a node of a named node type, as the node it was converted from.

TPubNode is for generated parsers; not a stable API.

#func TPubNodeIn source

func TPubNodeIn(h *TPubHooks, a any, v any) *TNode[any]

TPubNodeIn is TPubNode with the chunks a (see TPubIn).

TPubNodeIn is for generated parsers; not a stable API.

#type TOperand source

type TOperand struct {
	V     any
	Str   string
	IsStr bool
}

TOperand is an operand of a comparison: a string field read without boxing it (Str, with IsStr), or any other value (V).

TOperand is for generated parsers; not a stable API.

#type TOperatorsRule source

type TOperatorsRule struct {
	Skip     tmatcher
	Operands []*TOperatorsRuleLine
	Prefix   []*TOperatorsRuleOp
	Led      []*TOperatorsRuleOp
}

TOperatorsRule is for generated parsers; not a stable API.

#type TOperatorsRuleLine source

type TOperatorsRuleLine struct {
	Scope  []string
	M      tmatcher
	Action func(*TActCtx) any
	// Value makes the value of an operand line without an action, and of an operator line's
	// operator, from the value of the line's expression.
	Value Shaper
}

TOperatorsRuleLine is for generated parsers; not a stable API.

#type TOperatorsRuleOp source

type TOperatorsRuleOp struct {
	Id    int
	Kind  string
	Assoc string
	Level int
	Line  *TOperatorsRuleLine
}

TOperatorsRuleOp is for generated parsers; not a stable API.

#type TParser source

type TParser struct {
	*Parser
	Ext      any    // the generated code's allocation chunks
	Where    string // the rule whose action is being evaluated
	Frame    *TCaptureFrame
	Trail    []tundo
	Created  []TVal // struct values made by the action being evaluated
	KidStack []any

	// TypedDocument is set only by typed Document parses (TypedDocumentParse).
	TypedDocument *typedDocumentState
	// contains filtered or unexported fields
}

TParser is the parser state of the typed runtime.

TParser is for generated parsers; not a stable API.

#func (*TParser) Anchor source

func (p *TParser) Anchor(ok bool, desc ExpID) (any, bool)

#func (*TParser) AttachCaptures source

func (p *TParser) AttachCaptures(v any, names []string, vals []any, start, end int) any

AttachCaptures attaches the non-nil captures vals (named names) as fields of the value (a CST node), first wrapping it in a tuple node unless it is a fresh one that is not itself captured.

#func (*TParser) Bind source

func (p *TParser) Bind(name string, t func(*TActCtx) any) (ok bool)

Bind is Parser.Bind for the typed runtime.

#func (*TParser) Call source

func (p *TParser) Call(r *TRule, min int) (any, bool)

#func (*TParser) CallMemo source

func (p *TParser) CallMemo(r *TRule, inv func(*TParser) (any, bool)) (any, bool)

CallMemo is the memoized part of call, for the rule r invoked by inv (the generated i<id>): the rule is called at the position again, or its memoization is no longer deferred.

#func (*TParser) ClassFast source

func (p *TParser) ClassFast(c *Class) bool

ClassFast consumes one ASCII character of c and reports whether it did. It changes nothing otherwise, and the caller then runs ClassSkip for the other characters and the expectation. It is small enough for the compiler to inline into the generated parser.

#func (*TParser) ClassSkip source

func (p *TParser) ClassSkip(c *Class, id ExpID) bool

ClassSkip consumes one character of c in an ordinary parse and reports whether there was one; otherwise it records the expectation id at the position.

#func (*TParser) ClassesSkip source

func (p *TParser) ClassesSkip(steps []ClassStep) bool

ClassesSkip consumes one character of each step's class in turn in an ordinary parse and reports whether all matched; at the first that does not it records that step's expectation.

#func (*TParser) DiagnosticAttr source

func (p *TParser) DiagnosticAttr(m tmatcher, name ExpID) (any, bool)

#func (*TParser) DocumentCall source

func (p *TParser) DocumentCall(r *TRule, min int, inv func(*TParser) (any, bool)) (any, bool)

DocumentCall memoizes typed rule entries (rule.DocMemo), including generated direct wrappers. Examined and provisional metadata stays outside batch memo entries.

#func (*TParser) DropCreated source

func (p *TParser) DropCreated(base int)

#func (*TParser) DropKids source

func (p *TParser) DropKids(base int)

#func (*TParser) DropTrail source

func (p *TParser) DropTrail(base int)

DropTrail discards undo history whose effects are already restored or whose frame is returning. Clear its references before truncating the backing slice.

#func (*TParser) ErrorAttr source

func (p *TParser) ErrorAttr(m tmatcher, msg ExpID) (any, bool)

#func (*TParser) Finish source

func (p *TParser) Finish(r *TRule, f *TCaptureFrame, v any, start int) any

Finish makes the rule's value from the value of its body, and checks it against the rule's declared type if needed.

#func (*TParser) FreeFrame source

func (p *TParser) FreeFrame(f *TCaptureFrame)

FreeFrame makes the frame f, which nothing refers to any more, available to NewFrame. A rule's frame is dead when the rule returns: the values have been copied into its result, and the trail entries that refer to it are gone.

#func (*TParser) InvokePlain source

func (p *TParser) InvokePlain(r *TRule, min int) (any, bool)

#func (*TParser) Kids source

func (p *TParser) Kids(base int) []any

Kids returns p.KidStack[base:] as a value list and pops it.

#func (*TParser) ListField source

func (p *TParser) ListField(kids []any) any

ListField materializes a typed struct's list field during an action read. The ordinary TField path remains independent of a parser or work controller.

#func (*TParser) Mark source

func (p *TParser) Mark() Mark

#func (*TParser) MatchAny source

func (p *TParser) MatchAny(build bool) (any, bool)

#func (*TParser) MatchAnyOrdinary source

func (p *TParser) MatchAnyOrdinary(build bool) (any, bool)

MatchAnyOrdinary is MatchAny in an ordinary parse (parser.ExpectOrdinary).

#func (*TParser) MatchLiteral source

func (p *TParser) MatchLiteral(rs []rune, text string, desc ExpID, build bool) (any, bool)

#func (*TParser) MatchLiteralFold source

func (p *TParser) MatchLiteralFold(rs []rune, desc ExpID, build bool) (any, bool)

MatchLiteralFold is MatchLiteral for a case-insensitive literal (see Parser.MatchLiteralFold).

#func (*TParser) MatchLiteralOrdinary source

func (p *TParser) MatchLiteralOrdinary(rs []rune, text string, desc ExpID, build bool) (any, bool)

MatchLiteralOrdinary is MatchLiteral in an ordinary parse (parser.ExpectOrdinary).

#func (*TParser) NewFrame source

func (p *TParser) NewFrame(n int) *TCaptureFrame

#func (*TParser) NewMatch source

func (p *TParser) NewMatch(start, end int, text string, fresh bool) *TMatch

#func (*TParser) NewMatchOrdinary source

func (p *TParser) NewMatchOrdinary(start, end int, text string, fresh bool) *TMatch

#func (*TParser) NewNode source

func (p *TParser) NewNode(typ string, start, end int, kids []any) *TSeq

#func (*TParser) NewNodeOrdinary source

func (p *TParser) NewNodeOrdinary(typ string, start, end int, kids []any) *TSeq

#func (*TParser) NewVals source

func (p *TParser) NewVals(n int) []any

NewVals returns a value list of length and capacity n.

#func (*TParser) OperatorsRuleParse source

func (p *TParser) OperatorsRuleParse(r *TRule, min int) (any, bool)

OperatorsRuleParse is parser.OperatorsRuleParse for typed values.

#func (*TParser) Predicate source

func (p *TParser) Predicate(t func(*TActCtx) any) (ok bool)

#func (*TParser) PushKid source

func (p *TParser) PushKid(v any)

#func (*TParser) RecoverAttr source

func (p *TParser) RecoverAttr(m, skip tmatcher, build bool) (any, bool)

#func (*TParser) Reset source

func (p *TParser) Reset(m Mark)

#func (*TParser) ScopeValue source

func (p *TParser) ScopeValue(s Shaper, v any, start int) any

ScopeValue returns the value of a scope whose body matched [start, p.Pos) with the result v.

#func (*TParser) SetCapture source

func (p *TParser) SetCapture(slot int, v any)

#func (*TParser) SetCaptureOrdinary source

func (p *TParser) SetCaptureOrdinary(slot int, v any)

SetCaptureOrdinary is SetCapture in an ordinary parse (parser.ExpectOrdinary); so are NewNodeOrdinary and NewMatchOrdinary.

#func (*TParser) ShapeCapture source

func (p *TParser) ShapeCapture(s Shaper, v any, start int) any

ShapeCapture is ShapeSingle for a capture or a recovered expression, whose value is the unit node of the range matched when the expression has no value.

#func (*TParser) ShapeSingle source

func (p *TParser) ShapeSingle(s Shaper, v any, start int) (any, bool)

ShapeSingle returns the value of the result v where the expression takes one element; ok is false when it has no value.

#func (*TParser) Single source

func (p *TParser) Single(size int, build bool) (any, bool)

#func (*TParser) SkipTerminal source

func (p *TParser) SkipTerminal(t *TerminalProgram) bool

SkipTerminal matches t in an ordinary parse and reports whether it matched. It consumes the same input as the generated code of the expression and records the same expectations at the same positions. On failure the position is unspecified, as after the generated code; the caller restores it.

#func (*TParser) TConvertResult source

func (p *TParser) TConvertResult(r *TRule, v any) any

TConvertResult converts v, the value of rule r, to the rule's named node type.

#func (*TParser) TConvertResultOwned source

func (p *TParser) TConvertResultOwned(r *TRule, v, body any) any

TConvertResultOwned converts v, the value of rule r, to the rule's named node type, like TConvertResult. If v is body, the fresh node of the rule's body (TFreshNode), the rule returns the node it made itself, which nothing else holds, so it gets the type in place instead of being copied: the copy tconvert makes keeps a node that others hold as it is.

#func (*TParser) UseCtx source

func (p *TParser) UseCtx(c TActCtx) *TActCtx

#type TPubHooks source

type TPubHooks struct {
	Match func(*TNode[string]) any
	Error func(*Error) any
	Node  func(*TNode[any]) any
	Back  func(any) any
}

TPubHooks makes the public forms of the values the typed runtime builds that the generated package defines types for: a string node, an error value and a node of a statically unknown value are public values of the package's own types, which implement the package's unions. Back is the inverse: it returns the runtime's form of such a public value, and any other value unchanged.

TPubHooks is for generated parsers; not a stable API.

#type TRule source

type TRule struct {
	*Rule
	Body          func(p *TParser, min int) (any, bool)
	Action        func(c *TActCtx) any
	OperatorsRule *TOperatorsRule
	// Entry is the generated method that calls the rule as call(r, 0) does (u<id> or s<id>). The
	// generated parser sets it only for the start rules, which TParse runs through it; every other
	// rule is called through the generated methods that name it. A flat rule (one the generator prints
	// as one function) has no body or action and is called only through it.
	Entry func(p *TParser) (any, bool)
	// Nt is the registered index of the named node type the rule's value is converted to
	// (rule.NodeType), or 0.
	Nt uint16
	// OpNt is the registered index of the named node type every operator node of an Operators
	// Rule is converted to (rule.OpNodeType), or 0.
	OpNt uint16
}

TRule is a rule of the typed runtime: the rule's analysis results and its typed body.

TRule is for generated parsers; not a stable API.

#func NewTRules source

func NewTRules(rules []*Rule) []*TRule

NewTRules returns the typed rules that share the analysis results of rules, one for one.

For generated parsers; not a stable API.

#type TSeq source

type TSeq struct {
	Span
	Typ  string
	Kids []any
	// contains filtered or unexported fields
}

TSeq is a tuple node, a list node, a tuple value (TypeTupleValue) or a list value (TypeListValue) of the typed runtime. A tuple node's fields are its captures. A tuple or list node of a named node type has nt, as TMatch does; typ stays "tuple" or "list".

TSeq is for generated parsers; not a stable API.

#func (*TSeq) TField source

func (n *TSeq) TField(name string) (any, bool)

#func (*TSeq) TFresh source

func (n *TSeq) TFresh() bool

#func (*TSeq) TKids source

func (n *TSeq) TKids() []any

#func (*TSeq) TName source

func (n *TSeq) TName() string

#func (*TSeq) TSetFresh source

func (n *TSeq) TSetFresh(f bool)

#func (*TSeq) TStruct source

func (n *TSeq) TStruct() bool

#func (*TSeq) TText source

func (n *TSeq) TText() (string, bool)

#type TVal source

type TVal interface {
	TSpan() (int, int)
	TSetSpan(start, end int)
	TName() string                  // type name
	TText() (string, bool)          // text of a string node or an error value
	TKids() []any                   // children of a CST node
	TField(name string) (any, bool) // field value, and whether the type has the field (structs)
	TStruct() bool                  // a struct type
	TFresh() bool
	TSetFresh(bool)
}

TVal is a node value of the typed runtime: a value of a struct type, *TMatch, *TError or *TSeq.

TVal is for generated parsers; not a stable API.

#func AsTval source

func AsTval(v any) TVal

AsTval returns v as a node value, or nil. Values never hold nil pointers: nil is always the untyped nil.

AsTval is for generated parsers; not a stable API.

#type TerminalProgram source

type TerminalProgram struct {
	Code     []uint16
	Classes  []*Class
	Literals []TerminalText
	// contains filtered or unexported fields
}

TerminalProgram is a value-free expression made only of literals, character classes, sequences, choices, options and negative lookaheads, which generated parsers match through this table instead of straight-line code; not a stable API.

#func (*TerminalProgram) Prepare source

func (t *TerminalProgram) Prepare() *TerminalProgram

Prepare builds the dispatch tables of the choices of t from the classes of their guards and returns t. Generated parsers declare a program as static data and prepare it once.

#type TerminalText source

type TerminalText struct {
	Runes []rune
	Text  string
}

TerminalText is a literal of a TerminalProgram, as the generated code passes it to MatchLiteral.

#type TraceEvent source

type TraceEvent struct {
	Kind              TraceKind
	Rule              string
	Level, Depth, Pos int
	Matched           bool
	End               int
	Memo              bool
	Evals             int
	Examined          int
	ExaminedKnown     bool
	SkipReason        string
}

TraceEvent observes actual generated rule execution. Positions use the invocation's selected unit. Examined is valid only when ExaminedKnown, which holds for exits of Document parses: it is then the exclusive end of the input the Document treats the call as having examined when deciding reuse after an edit. That frontier is conservative and can exceed the input actually read. An aborted parse may leave enters without exits.

#type TraceKind source

type TraceKind uint8

TraceKind distinguishes entered calls, completed calls and skipped dispatch.

const (
	TraceEnter TraceKind = iota
	TraceExit
	TraceSkipped
)

#type TruncatedSyntaxErrors source

type TruncatedSyntaxErrors struct {
	Errors          SyntaxErrors
	Total           uint64
	Dropped         uint64
	CountsSaturated bool
}

TruncatedSyntaxErrors is the incomplete result of a stream parsed with a positive diagnostic limit. Errors is the retained tail in occurrence order. Saturated counts are lower bounds; truncation and the tail remain exact.

#func (*TruncatedSyntaxErrors) Error source

func (e *TruncatedSyntaxErrors) Error() string

#func (*TruncatedSyntaxErrors) Unwrap source

func (e *TruncatedSyntaxErrors) Unwrap() error

Unwrap exposes the retained errors to errors.As as SyntaxErrors.

#type TypedDocumentCloneBase source

type TypedDocumentCloneBase struct {
	Control *WorkControl
	Values  map[any]any
	Slices  map[DocumentSliceKey]any
	Tasks   []TypedDocumentCloneTask
}

TypedDocumentCloneBase is the state of a CloneAST copy of a published typed Document value. The generated typedDocumentClone embeds it and adds the copies of the grammar's types.

TypedDocumentCloneBase is for generated parsers; not a stable API.

#func (*TypedDocumentCloneBase) Begin source

func (c *TypedDocumentCloneBase) Begin(control *WorkControl)

#func (*TypedDocumentCloneBase) ReleaseBase source

func (c *TypedDocumentCloneBase) ReleaseBase()

#func (*TypedDocumentCloneBase) Remember source

func (c *TypedDocumentCloneBase) Remember(from, to any)

#func (*TypedDocumentCloneBase) Step source

func (c *TypedDocumentCloneBase) Step(n uint64)

#type TypedDocumentCloneTask source

type TypedDocumentCloneTask struct{ Source, Target any }

TypedDocumentCloneTask is a value whose copy (target) has yet to be filled from source.

TypedDocumentCloneTask is for generated parsers; not a stable API.

#type WalkAction source

type WalkAction uint8

WalkAction controls descent after a visit.

const (
	WalkContinue WalkAction = iota
	WalkSkip
	WalkStop
)

#type WalkEdge source

type WalkEdge struct {
	Kind       WalkEdgeKind
	ChildIndex int
	FieldName  string
	ListIndex  int
}

WalkEdge identifies an incoming edge. Only its Kind's index or name is meaningful.

#type WalkEdgeKind source

type WalkEdgeKind uint8

WalkEdgeKind identifies the incoming edge of a value.

const (
	WalkRoot WalkEdgeKind = iota
	WalkChild
	WalkField
	WalkListElement
)

#type WalkTask source

type WalkTask struct {
	Visit    WalkVisit
	Exit     bool
	Identity any
}

WalkTask is for generated parsers; not a stable API.

#type WalkVisit source

type WalkVisit struct {
	Value  any
	Node   *Node
	Parent *Node
	Depth  int
	Edge   WalkEdge
}

WalkVisit describes a live value and its nearest owning node. Depth counts edges. Node is populated only for non-nil *Node values; Value retains typed nil leaves.

#type WorkControl source

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

WorkControl is private state for a single parser invocation. Callers must split long operations into bounded reservations so cancellation can be observed between chunks.

WorkControl is for generated parsers; not a stable API.

#func (*WorkControl) Charge source

func (c *WorkControl) Charge(inputWork, steps uint64)

Charge atomically reserves input-work and step units. Cancellation wins when it is observed at a poll or when either reservation would fail; otherwise input-work exhaustion takes priority over step exhaustion. A failed reservation leaves both counters unchanged.

#func (*WorkControl) Check source

func (c *WorkControl) Check()

Check observes cancellation at an explicit engine checkpoint. It is safe on a nil receiver.

#type WorkLimitError source

type WorkLimitError struct {
	Kind      WorkLimitKind
	Limit     uint64
	Used      uint64
	Requested uint64
}

WorkLimitError reports a reservation that would exceed one work limit. Used is the counter value before the rejected reservation; Requested is the complete atomic reservation that could not be made.

#func (*WorkLimitError) Error source

func (e *WorkLimitError) Error() string

#func (*WorkLimitError) Is source

func (e *WorkLimitError) Is(target error) bool

Is reports whether target is the work-limit sentinel.

#type WorkLimitKind source

type WorkLimitKind uint8

WorkLimitKind identifies the counter that exhausted its limit.

const (
	InputWorkLimit WorkLimitKind = iota
	StepWorkLimit
)

#type WorkLimits source

type WorkLimits struct {
	MaxInputWork uint64
	MaxSteps     uint64
}

WorkLimits bounds cumulative engine work for one parse invocation. A zero limit leaves that counter unlimited. Scanning input may charge only input work, so MaxSteps alone does not bound it; MaxInputWork does.

#type WorkRange source

type WorkRange struct{ Lo, Hi rune }

WorkRange is for generated parsers; not a stable API.