Package pego/query

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

var ErrCycle = errors.New("structural query graph cycle")

var ErrNoSourceInfo = errors.New("structural query: rule constraints need values with source information; compile the grammar with source information")

#type Capture source

type Capture struct {
	Name, Category string
	Value          any
	Parent         *pego.Node
	Path           []Edge
}

Capture borrows Value and Parent from the graph. Path identifies the edges from the root: "element" (Index) into a tuple, a list or a node's value, "field" (Name) into a struct or error, "capture" (Name) to a node's capture that is not an element, and "value" from a node to its value. Shared occurrences remain distinct.

#type Edge source

type Edge struct {
	Kind  string
	Name  string
	Index int
}

Edge is one edge of the path from the root to a captured value (Capture).

#type FieldPattern source

type FieldPattern struct {
	Name    string
	Pattern Pattern
}

FieldPattern requires the field Name, whose value matches Pattern.

#type Match source

type Match struct{ Captures []Capture }

Match is one match of a pattern: the values its captures name.

#type Option source

type Option func(*options)

Option configures one query evaluation.

#func WithContext source

func WithContext(ctx context.Context) Option

WithContext selects cooperative cancellation. Nil disables it.

#func WithWorkLimits source

func WithWorkLimits(limits pego.WorkLimits) Option

WithWorkLimits bounds query work. MaxSteps is charged for traversal, matching, paths and results; MaxInputWork is unused by structural queries. A zero limit means unlimited work.

#type Pattern source

type Pattern struct {
	Type     string
	Rule     string
	Category string
	Capture  string
	Fields   []FieldPattern
	Value    *Pattern
	Elements []Pattern
}

Pattern is a programmatic structural pattern. Empty Type, Rule and Category are unconstrained. Categories are node, struct, tuple, list, int, string, bool, nil and error. Type names a struct type, or error for the values of error recovery. Rule requires a node produced by the rule, which only grammars compiled with source information record. Fields require a struct or error value; extra fields are allowed. Elements match the first elements of a tuple or list, and see through a node to its value as the language's x[i] does; extra elements are allowed. Value matches the value of a node.

#type Query source

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

Query is a compiled pattern. It is immutable and safe for concurrent use.

#func Compile source

func Compile(pattern Pattern, out *schema.Output) (*Query, error)

Compile validates and copies a pattern. A nil schema defers type and field checks until evaluation; a supplied schema is validated first and rejects known impossibilities. To compile many patterns with one schema, Prepare it once.

#func (*Query) Matches source

func (q *Query) Matches(root *pego.Node, opts ...Option) ([]Match, error)

Matches evaluates the pattern at every value reachable from root, per incoming edge, visiting each value before its outgoing edges: the elements of a tuple, a list or a node's value by index, then a node's captures that are not elements, by name, and the fields of a struct by name. Every node, struct, tuple, list and error value is a candidate. Results borrow graph values; callers must keep the graph stable. Structural matching inspects no source text and therefore consumes no input work. Cancellation, work-limit exhaustion and cycles (ErrCycle) return an error without partial results. A query with a rule constraint reports ErrNoSourceInfo when the graph has nodes but none records a rule.

#type Schema source

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

Schema is an output schema validated once for compiling many queries. It owns a deep copy of the schema it was prepared from, so later changes to that schema do not affect it. It is immutable and safe for concurrent use. Obtain one from Prepare: a nil or zero Schema holds no schema and defers type and field checks until evaluation.

#func Prepare source

func Prepare(out *schema.Output) (*Schema, error)

Prepare validates and copies the schema. Compiling a pattern with the result performs the same checks as Compile with the schema, but does not validate the schema again.

#func (*Schema) Compile source

func (s *Schema) Compile(pattern Pattern) (*Query, error)

Compile validates and copies a pattern, rejecting known impossibilities in the prepared schema. A nil or zero Schema defers type and field checks until evaluation, as a nil *schema.Output does.