Package sxir/pkg/runtime/value/impl

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

Overview

Package valueimpl is the implementation of value.Node that the runtime packages, the engine and the generated Go parsers share: the node data, its kinds and fields, and the code that builds and reads them. It is not an API and not stable. Programs use the methods of value.Node. Generated code depends on this package through the library protocol version, which its ProtocolN constant names.

Index

Constants

const (
	TypeString  = "string"  // a node whose value is its text (literal, character class, atomic, and so on)
	TypeTuple   = "tuple"   // a sequence, or an operator of an operators rule without an action
	TypeList    = "list"    // a repetition
	TypeMissing = "missing" // literal inserted at an empty source range
	TypeError   = "error"   // range skipped by error recovery

	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
)

Names of the reserved node types.

const (
	BaseString = iota
	BaseTuple
	BaseList
	BaseError
	BaseMissing
)

The indexes in reservedTypes of the bases of node kinds.

const Protocol15 = 15

Protocol15 is declared because this package serves the node representation introduced by protocol version 15 of the Go library of generated parsers (syntaxir.dev/sxir/pkg/runtime/libgo). The package declares exactly this one constant, and the library refers to it, so that a copy of the library embedded in a generated parser builds only against a core that serves its representation. When the representation changes (testdata/representation.golden records it, and a test fails when the two differ), this constant is replaced by the one of the protocol version that makes the change.

Variables

var (
	MatchKind   = KindOf(TypeString, "")
	SeqKind     = KindOf(TypeTuple, "")
	ListKind    = KindOf(TypeList, "")
	ErrorKind   = KindOf(TypeError, "")
	MissingKind = KindOf(TypeMissing, "")

	BoxKind        = KindOf(typeBox, "")
	TupleValueKind = KindOf(TypeTupleValue, "")
	ListValueKind  = KindOf(TypeListValue, "")
)

Kinds of the reserved types without a rule.

Functions

func ElementPath source

func ElementPath[N any](d *Data[N], x *N, rep func(*N) *Data[N]) ([]int, bool)

ElementPath returns the path of x among the elements of the tuple node d and of the tuple nodes nested in it, breadth first. rep returns the representation of a node.

func SetField source

func SetField(fs *Fields, name string, v any)

SetField sets the field name of fs to v (adding it if absent).

Types

type CaptureLocation source

type CaptureLocation struct {
	Name  string
	Path  []int
	Side  bool
	Value any
}

CaptureLocation is where a capture of a node is: a path of tuple indexes into the node's value, or, for a capture whose value is not an element (one in a positive lookahead), its value.

func CaptureLocations source

func CaptureLocations[N any](d *Data[N], rep func(*N) *Data[N]) []CaptureLocation

CaptureLocations returns the locations of the captures of the tuple node d, in name order. A capture is located by the identity of its value among the elements of d's tuple and of the tuples nested in it, nearest first; a capture that did not match is left out. rep returns the representation of a node.

type Data source

type Data[N any] struct {
	// Kind holds the type and rule names (Type, Rule). Nodes share it: names are interned.
	Kind *Kind
	// Start and End are the range in the input, in the parse's position unit (End is exclusive).
	Start, End int32
	// Text is the string value of a string node.
	Text string
	// Children are the elements of a tuple or list value. An optional that did not match is nil.
	Children []*N
	// Fields are the struct fields and captures. Each value is a *N, int, string, bool, or nil.
	Fields Fields

	// Fresh reports that the node was created in the rule body currently being evaluated and has not
	// yet been returned to any rule. That rule may freely modify a fresh node.
	Fresh bool
	// Terminal reports that the node is a terminal.
	Terminal bool
	// Labeled reports that the captures in Fields are output (source information was requested).
	Labeled bool
	// Mark belongs to the Document that holds the node, which alone writes it. The engine's
	// Document stores the number of edits that the positions account for, and a generated
	// parser's Document the number of the last move after an edit that visited the node.
	Mark uint32
	// Box is the value of an action that is not a node (a box node).
	Box any
}

Data is the representation of a node. N is value.Node, which holds a Data as its only field, so that a *value.Node converts to a *Data[value.Node] and back; the parameter breaks the import cycle between the two packages.

type Fields source

type Fields []NodeField

Fields is the list of a node's fields. Each name appears at most once.

func (Fields) Get source

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

Get returns the value of the field name.

func (Fields) Sorted source

func (fs Fields) Sorted() Fields

Sorted returns a copy sorted lexicographically by name.

type JSONOutput source

type JSONOutput struct {
	W   io.Writer
	Buf []byte
}

JSONOutput coalesces the small fragments of a node's JSON while preserving writer errors and the already-written prefix when an unsupported value is encountered.

func (*JSONOutput) Bytes source

func (out *JSONOutput) Bytes(data []byte) error

Bytes writes data, which may be longer than the buffer.

func (*JSONOutput) Encoded source

func (out *JSONOutput) Encoded(value any) error

Encoded writes value as encoding/json encodes it.

func (*JSONOutput) Flush source

func (out *JSONOutput) Flush() error

Flush writes the buffered bytes to W.

func (*JSONOutput) Number source

func (out *JSONOutput) Number(n int32) error

Number writes n as a JSON number.

func (*JSONOutput) Raw source

func (out *JSONOutput) Raw(s string) error

Raw writes s, which is JSON text.

type Kind source

type Kind struct {
	Type, Rule string
	Reserved   int // the index of a reserved type in reservedTypes with no rule, or -1
	// Base is the index in reservedTypes of what the nodes are: the reserved type itself, with or
	// without a rule, or for a named node type the string, tuple or list node it converts. It is
	// -1 for a struct.
	Base int
}

Kind is the pair of type and rule names of nodes. Kinds are interned (KindOf), so that a node holds one pointer for both names.

func KindOf source

func KindOf(typ, rule string) *Kind

KindOf returns the interned kind of the type and rule names. It is meant for compilation and loading; parsing uses kinds prepared then.

func NodeTypeKind source

func NodeTypeKind(typ string, base int) *Kind

NodeTypeKind returns the interned kind of the nodes of the named node type typ that convert a node of the base (BaseString, BaseTuple or BaseList). It has no rule.

func (*Kind) IsNodeType source

func (k *Kind) IsNodeType() bool

IsNodeType reports whether k is the kind of a named node type.

func (*Kind) RuleName source

func (k *Kind) RuleName() string

RuleName returns the rule name of k, or "" for a nil kind.

func (*Kind) TypeName source

func (k *Kind) TypeName() string

TypeName returns the type name of k, or "" for a nil kind.

type NodeField source

type NodeField struct {
	Name  string
	Value any
}

NodeField is a field of a node (a struct field or a capture).

type RuleKinds source

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

RuleKinds are the kinds of a rule's nodes: those of the reserved types, which the rule gives its name to (finish).

func NewRuleKinds source

func NewRuleKinds(rule string) RuleKinds

NewRuleKinds returns the kinds of the nodes of the rule.

func (*RuleKinds) Named source

func (rk *RuleKinds) Named(k *Kind, rule string) *Kind

Named returns the kind k with the rule's name. A node of a named node type keeps no rule.

type Shape source

type Shape uint8

Shape is what a node stands for in the value model.

const (
	ShapeString     Shape = iota // a node whose value is a string (Text)
	ShapeTuple                   // a node whose value is a tuple (Children)
	ShapeList                    // a node whose value is a list (Children)
	ShapeError                   // an error value of recovery (Error or Missing)
	ShapeBox                     // a box carrying a value other than a node
	ShapeTupleValue              // a tuple value (Children)
	ShapeListValue               // a list value (Children)
	ShapeStruct                  // a struct value (Fields)
)

func ShapeOfKind source

func ShapeOfKind(k *Kind, terminal bool) Shape

ShapeOfKind returns what a node of the kind stands for, given whether it is a terminal.