Package sxir/pkg/runtime/value
import "syntaxir.dev/sxir/pkg/runtime/value"
Generated from the source of this version. Also on pkg.go.dev.
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
func Walktype Cursortype CycleErrortype Nodefunc (*Node) Clonefunc (*Node) Elemfunc (*Node) Elemsfunc (*Node) Endfunc (*Node) Fieldfunc (*Node) Fieldsfunc (*Node) IsTerminalfunc (*Node) Kindfunc (*Node) Lenfunc (*Node) MarshalJSONfunc (*Node) Rulefunc (*Node) Startfunc (*Node) Stringfunc (*Node) Textfunc (*Node) Typefunc (*Node) Valuefunc (*Node) WriteJSONtype NodeKindtype SyntaxErrortype SyntaxErrorstype TruncatedSyntaxErrorstype WalkActiontype WalkEdgetype WalkEdgeKindtype WalkVisit
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) 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.
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.
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.