Package sxir/pkg/runtime/value

import "syntaxir.dev/sxir/pkg/runtime/value"

Overview

Package value defines the values a parse produces: nodes with their kinds, fields and JSON form, traversal and cursors, and syntax errors, including the errors that recovery records in the tree.

Index

Functions

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.

Types

type Cursor source

type Cursor struct {
	Root *Node
	Unit input.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 Node source

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

Node is a value produced by parsing. It is a CST node, a terminal, a list, or a struct built by an action. In JSON a string, tuple or list node is an object with the members start, end and value, and, with source information, rule and captures; an error value is one with start, end and error, and a struct one with type, start, end and fields.

func (*Node) Clone source

func (n *Node) Clone() *Node

Clone returns a deep copy of the tree n. Subtrees shared within the tree stay shared in the copy, and so do the slices of nodes and of values in fields that several places hold, which the copy holds once with their cycles. A Document moves the nodes it reuses after an edit, which changes trees returned by its earlier parses; a clone keeps a tree as it was.

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 holds text: a string node or an error value.

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) Rule source

func (n *Node) Rule() string

Rule returns the name of the rule that produced the node, if it was produced by a rule without an action, 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, for tests and debugging: 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: the kind of a node of the value model (string, tuple, list, error, or Missing for an inserted literal), or otherwise the name of a type defined in 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 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: its range is the skipped input and its Text() is its
	// message. It stores no text of the range.
	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 SyntaxError source

type SyntaxError struct {
	Pos  int // position, in the position unit of the parse
	Line int // 1-based line
	Col  int // 1-based column, in the position unit of the parse
	// Expected lists every entry that was expected at Pos: names, then literals, then classes,
	// each in byte order. Message shows at most the first ten of them.
	Expected []string
	Messages []string // messages given by @error
}

SyntaxError reports that the input did not match the grammar.

func (*SyntaxError) Error source

func (e *SyntaxError) Error() string

func (*SyntaxError) ExpectedInMessage source

func (e *SyntaxError) ExpectedInMessage() (shown []string, omitted int)

ExpectedInMessage returns the expected entries that Message lists when e has no messages from @error, and the number of entries after them that it leaves out. Message lists at most the first ten entries and ends a longer list with the count of the rest; Expected keeps every entry. Parsers that charge the message they build use it to build the same text.

func (*SyntaxError) Message source

func (e *SyntaxError) Message() string

Message describes the error without its position: the messages given by @error, or else the expected entries.

type SyntaxErrors source

type SyntaxErrors []*SyntaxError

SyntaxErrors is a list of syntax errors, including those recovered by error recovery.

func (SyntaxErrors) Error source

func (l SyntaxErrors) Error() string

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 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 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.