compiler

type ActionGraph ¶ added in v0.23.0

type ActionGraph struct {
	Entry string            `json:"entry,omitempty"`
	Exit  string            `json:"exit,omitempty"`
	Nodes []ActionGraphNode `json:"nodes,omitempty"`
	Edges []ActionGraphEdge `json:"edges,omitempty"`
}

ActionGraph is a reviewable, high-level plan of the actions and control/data relationships produced from one expression. It deliberately contains no action arguments or parameter values. Kernel action implementations remain opaque; this graph describes Flow's lowering decisions, not their internals.

func BuildActionGraph(resolver CapabilityResolver, expr Expr) (*ActionGraph, error)

type ActionGraphDescription ¶ added in v0.23.0

type ActionGraphDescription struct {
	Kind        string
	Name        string
	Form        ActionGraphForm
	ChildLabels []string
}

ActionGraphDescription lets an expression extension describe its plan node and the labels for its Children. Labels should describe branch roles, not include runtime values or secrets.

type ActionGraphEdge ¶ added in v0.23.0

type ActionGraphEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
	Kind string `json:"kind"`
}

ActionGraphEdge connects action outputs, branch routes, or loop control.

type ActionGraphForm ¶ added in v0.23.0

type ActionGraphForm uint8

ActionGraphForm describes the control shape of an extension expression.

const (
	// ActionGraphOpaque marks an extension whose execution shape is not declared.
	ActionGraphOpaque ActionGraphForm = iota
	// ActionGraphParallel represents concurrent branches with a join.
	ActionGraphParallel
	// ActionGraphChoice represents mutually exclusive branches with a join.
	ActionGraphChoice
	// ActionGraphCatch represents protected work with recovery branches.
	ActionGraphCatch
)

type ActionGraphNode ¶ added in v0.23.0

type ActionGraphNode struct {
	ID        string   `json:"id"`
	Kind      string   `json:"kind"`
	Name      string   `json:"name,omitempty"`
	File      string   `json:"file,omitempty"`
	Line      int      `json:"line,omitempty"`
	Column    int      `json:"column,omitempty"`
	Modifiers []string `json:"modifiers,omitempty"`
}

ActionGraphNode is one action or synthetic control node in an ActionGraph.

type ActionGraphProvider ¶ added in v0.23.0

type ActionGraphProvider interface {
	DescribeActionGraph() ActionGraphDescription
}

ActionGraphProvider is an optional Expr extension contract. Expressions that do not implement it are shown as opaque extension nodes with contained child plans, rather than guessed execution semantics.

type ArgFieldSpec ¶ added in v0.23.0

type ArgFieldSpec struct {
	Name string
	Kind ArgKind
	// Optional suppresses the default required-field check for capability
	// references. It has no effect on ArgAny, ArgString, ArgInt, or ArgBool.
	Optional bool
}

ArgFieldSpec declares the compiler-level kind of one argument of a capability. Bundles publish their specs via Bundle.ArgSchemas.

type ArgKind ¶ added in v0.23.0

type ArgKind uint8

ArgKind describes the compiler-level type of one capability argument.

const (
	// ArgAny is untyped; no compile-time validation applies.
	ArgAny ArgKind = iota
	// ArgString is a plain string; the value is passed through.
	ArgString
	// ArgInt is an integer literal.
	ArgInt
	// ArgBool is a boolean literal.
	ArgBool
	// ArgCapabilityRef is a statically resolved reference to an action.
	// The parser must present a bare identifier; quoted strings are
	// rejected, and the value is translated through TranslateKeyword
	// and verified against the resolver at compile time.
	ArgCapabilityRef
	// ArgCapabilityRefList is a list of ArgCapabilityRef.
	ArgCapabilityRefList
)

type AssertExpr ¶ added in v0.8.0

type AssertExpr struct {
	Condition string
	Message   string
	Pos       Position
}

AssertExpr: assert(condition, message).

func (*AssertExpr) Analyze(CapabilityResolver) error

func (a *AssertExpr) Build(_ context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (a *AssertExpr) Children() []Expr

func (*AssertExpr) Node()

type Associativity ¶ added in v0.23.0

type Associativity uint8

const (
	Left Associativity = iota
	Right
)

type Atom ¶ added in v0.23.0

type Atom struct {
	Name            string
	Params          map[string]string
	Modifiers       []string
	ModifierSources []ModifierSource // parallel to Modifiers; same length
	Args            map[string]*Value
	Prompt          string
	Targets         []string
	Excludes        []string
	// ConfigInject marks an atom written as `op @config`. For stream
	// operators, every field of the operator's config struct that has
	// a matching @config.<json_name> value is injected into its
	// parameters at build time.
	ConfigInject bool
	Pos          Position // source position of the atom, for compile-time diagnostics
}

Atom is a single runtime action call.

func (*Atom) Analyze(CapabilityResolver) error

func (a *Atom) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (*Atom) Children() []Expr

func (*Atom) Node()

type AtomAdviseFunc ¶ added in v0.23.0

type AtomAdviseFunc func(atom *Atom, builder *action.Builder[any, any]) error

type AtomSpec ¶ added in v0.23.0

type AtomSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Tags        []string        `json:"tags,omitempty"`
	Scope       string          `json:"scope,omitempty"`
	ReqFields   []FieldSpec     `json:"req_fields,omitempty"`
	ResFields   []FieldSpec     `json:"res_fields,omitempty"`
	Example     json.RawMessage `json:"example,omitempty"`
}

type BoundarySpec ¶ added in v0.23.0

type BoundarySpec struct {
	Name        string
	Description string
	Consume     func(stream action.AnyStreamAction) *action.Builder[any, any]
}

BoundarySpec is a stream-to-unary adapter. It is the only place in a pipeline where iter.Seq2[T, error] becomes a single value.

func BoundaryByName(name string) (BoundarySpec, bool)

func NamedBoundaries() []BoundarySpec

type BuildContext ¶ added in v0.23.0

type BuildContext struct {
	Resolver   CapabilityResolver
	Modifiers  *ModifierTable
	Advisers   []AtomAdviseFunc
	Introspect bool
}

BuildContext carries every dependency a node needs to lower itself into a runnable action. It is deliberately a small value struct: the AST knows how to Build itself, core just provides the pieces.

type Bundle ¶ added in v0.23.0

type Bundle struct {
	ID           string
	Alias        string // Local @require qualifier replacing library namespaces for this compilation.
	Libraries    []action.Library
	Directives   []Directive
	Modifiers    []Modifier
	Operators    []Operator
	Primaries    []PrimaryExtension
	Materialize  Materializer
	OnPreprocess func(meta map[string]any) PreprocessContributions
	AtomAdvise   func(atom *Atom, builder *action.Builder[any, any]) error
	WrapPipeline func(meta map[string]any, inner action.AnyAction) (action.AnyAction, error)
	Hooks        []action.AnyHook

	ArgSchemas map[string][]ArgFieldSpec

	AcceptedOptions []string

	SelfTest func() []SelfTestSection
	Fixtures fs.FS

	// Shutdowns are invoked by the runner host after the outer invocation
	// completes. Compile and Execute do not close bundle resources.
	Shutdowns []ShutdownFunc
}

Bundle is one extension distribution.

func (b Bundle) AllSelfTests() []SelfTestSection

type BundleFactory ¶ added in v0.23.0

type BundleFactory func(opts map[string]string) Bundle

func Lookup(id string) (BundleFactory, bool)

func LookupBundleForModule(target string) (BundleFactory, bool)

type CapabilityContract ¶ added in v0.23.0

type CapabilityContract struct {
	Name   string
	Input  TypeDescriptor
	Output TypeDescriptor
}

type CapabilityRef ¶ added in v0.23.0

type CapabilityRef struct {
	Raw       string
	Canonical string
}

CapabilityRef is a statically resolved reference to an action, stream, or operator. Raw is the identifier as written in the DSL; Canonical is the name after translating native keywords. Both are held so diagnostics can point at the source form.

func ParseCapabilityRef(raw string) (CapabilityRef, error)

func ParseCapabilityRefList(line string) ([]CapabilityRef, error)

type CapabilityResolver ¶ added in v0.23.0

type CapabilityResolver interface {
	Action(name string) (action.AnyAction, bool)
	Stream(name string) (action.AnyStreamAction, bool)
	Operator(name string) (action.NamedOperator, bool)
	Mount(lib action.Library) error
	MountWithAlias(lib action.Library, alias string) error
}

CapabilityResolver decouples compiler analysis and building from concrete capability registries.

type Catalog ¶ added in v0.23.0

type Catalog struct {
	Atoms      []AtomSpec      `json:"atoms"`
	Sources    []SourceSpec    `json:"sources"`
	Operators  []OperatorSpec  `json:"operators"`
	Modifiers  []ModifierSpec  `json:"modifiers"`
	Directives []DirectiveSpec `json:"directives"`
}

Catalog is a machine-readable dump of the compiler surface: every atom, stream source, operator, modifier, and directive known to the resolver and tables. Consumed by `nflow catalog`, `nflow list`, `nflow show`, and the linter. Regenerated on every build — no manual maintenance.

func BuildCatalog(
	resolver CapabilityResolver,
	mt *ModifierTable,
	dt *DirectiveTable,
	ot *OperatorTable,
) Catalog

type CompileAndRunReq ¶ added in v0.23.0

type CompileAndRunReq struct {
	Source  string
	Payload any
}

type CompileOption ¶ added in v0.23.0

type CompileOption func(*compileConfig)

func BundleConfig(bundles ...Bundle) []CompileOption

func WithActionGraph() CompileOption

func WithActionIntrospection() CompileOption

func WithArgSchemas(schemas map[string][]ArgFieldSpec) CompileOption

func WithAtomAdvisors(fns ...AtomAdviseFunc) CompileOption

func WithCLIArgs(args []string) CompileOption

func WithConfigMap(cfg map[string]string) CompileOption

func WithLineModifiers(lookups ...LineLookup) CompileOption

func WithOnPreprocess(fns ...OnPreprocessFunc) CompileOption

func WithPipelineWrappers(fns ...PipelineWrapFunc) CompileOption

type CompileReq ¶ added in v0.23.0

type CompileReq struct {
	Source             string
	Name               string
	Line               int
	InheritedPrimaries []PrimaryExtension
	Prepared           *PreparedSource
}

type CompileRes ¶ added in v0.23.0

type CompileRes struct {
	Program     action.AnyAction
	Meta        map[string]any
	AST         Expr
	ActionGraph *ActionGraph `json:"action_graph,omitempty"`
}

type ConditionalExpr ¶

type ConditionalExpr struct {
	Cond Expr
	Then Expr
	Else Expr
	Pos  Position
}

ConditionalExpr: cond ? then : else.

func (c *ConditionalExpr) Analyze(r CapabilityResolver) error

func (c *ConditionalExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (c *ConditionalExpr) Children() []Expr

func (*ConditionalExpr) Node()

type ContractProvider ¶ added in v0.23.0

type ContractProvider interface {
	Contract(name string) (CapabilityContract, bool)
}

type DecoratedExpr ¶ added in v0.23.0

type DecoratedExpr struct {
	Inner     Expr
	Modifiers []string
	Pos       Position
}

DecoratedExpr wraps any primary with postfix modifiers, so constructs like `{ ... }:timeout=5s` and `loop(...) until(...):retry=3` behave like atoms for policy purposes. Build lowers Inner and applies the modifier chain through the same ModifierTable used for atoms.

func (d *DecoratedExpr) Analyze(r CapabilityResolver) error

func (d *DecoratedExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (d *DecoratedExpr) Children() []Expr

func (*DecoratedExpr) Node()

type Directive ¶ added in v0.23.0

type Directive struct {
	Name    string
	Example string
	Handler func(context.Context, DirectiveReq) (DirectiveRes, error)
}

func (d Directive) Action() *action.BuiltAction[DirectiveReq, DirectiveRes]

type DirectiveReq ¶ added in v0.23.0

type DirectiveReq struct {
	Lines   []string
	Body    []string
	I       int
	Out     map[string]any
	File    string
	BaseDir string
	Table   *DirectiveTable

	// Recurse runs the full preprocess on another .nflow file and
	// returns its cleaned body plus merged metadata. Used by @include
	// so directives in included files produce declarations in the
	// parent's Out map.
	Recurse func(absPath string) (clean string, meta map[string]any, err error)
}

type DirectiveRes ¶ added in v0.23.0

type DirectiveRes struct {
	Next int

	// BlankLines lists 0-based line indices whose output must be empty
	// even when the source line has content. Block directives use it
	// to remove their own delimiter lines (e.g. @scope's header and
	// closing brace) without consuming the body, so nested directives
	// inside the body still run through the outer preprocess loop.
	BlankLines []int
}

type DirectiveSpec ¶ added in v0.23.0

type DirectiveSpec struct {
	Name    string `json:"name"`
	Example string `json:"example,omitempty"`
}

type DirectiveTable ¶ added in v0.23.0

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

func NewDirectiveTable(ds ...Directive) *DirectiveTable

func (t *DirectiveTable) Actions() []action.AnyAction

func (t *DirectiveTable) All() []Directive

func (t *DirectiveTable) ByName(name string) (*action.BuiltAction[DirectiveReq, DirectiveRes], bool)

type DynamicResolver ¶ added in v0.23.0

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

func NewDynamicResolver(baseLibs ...action.Library) (*DynamicResolver, error)

func (r *DynamicResolver) Action(name string) (action.AnyAction, bool)

func (r *DynamicResolver) ActionNames() []string

func (r *DynamicResolver) Actions() []action.AnyAction

func (r *DynamicResolver) Contract(name string) (CapabilityContract, bool)

func (r *DynamicResolver) Mount(lib action.Library) error

func (r *DynamicResolver) MountWithAlias(lib action.Library, alias string) error

func (r *DynamicResolver) Operator(name string) (action.NamedOperator, bool)

func (r *DynamicResolver) Operators() []action.NamedOperator

func (r *DynamicResolver) Stream(name string) (action.AnyStreamAction, bool)

func (r *DynamicResolver) Streams() []action.AnyStreamAction

type Expr ¶

type Expr interface {
	Node()
	Children() []Expr
	Analyze(resolver CapabilityResolver) error
	Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)
}

Expr is the root of the AST. Every node knows how to report its children, how to validate its contract (Analyze), and how to lower itself into a runnable action (Build). Core never switches on concrete AST types.

type FallbackExpr ¶

type FallbackExpr struct {
	L, R Expr
	Pos  Position
}

FallbackExpr: left || right.

func (f *FallbackExpr) Analyze(r CapabilityResolver) error

func (f *FallbackExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (f *FallbackExpr) Children() []Expr

func (*FallbackExpr) Node()

type FieldSpec ¶ added in v0.23.0

type FieldSpec struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Required bool   `json:"required,omitempty"`
	Usage    string `json:"usage,omitempty"`
}

type KeywordMapping ¶ added in v0.23.0

type KeywordMapping struct {
	Keyword string
	Target  string
}

KeywordMapping pairs a native DSL keyword with the canonical action name it compiles to.

func KeywordMappings() []KeywordMapping

type KeywordPrimary ¶ added in v0.23.0

type KeywordPrimary interface {
	PrimaryExtension
	Keyword() string
}

KeywordPrimary is the keyword-dispatch contract.

type Lexer ¶

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

func NewLexer(src string) *Lexer

func (l *Lexer) Next() Token

type LineLookup ¶ added in v0.23.0

type LineLookup struct {
	Source ModifierSource
	Fn     func(line int) []string
}

LineLookup pairs a line-indexed modifier function with the source that produced it. Every modifier Fn returns is attributed to Source.

func LineModifiersFromOptions(mt *ModifierTable, opts []CompileOption) []LineLookup

type LoopExpr ¶

type LoopExpr struct {
	Body  Expr
	Until string
	Pos   Position
}

LoopExpr: loop(body) until(condition).

func (l *LoopExpr) Analyze(r CapabilityResolver) error

func (l *LoopExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (l *LoopExpr) Children() []Expr

func (*LoopExpr) Node()

type MapEntry ¶ added in v0.8.0

type MapEntry struct {
	Key   string
	Value *Value
}

type MaterializeReq ¶ added in v0.23.0

type MaterializeReq struct {
	Ctx      context.Context
	Meta     map[string]any
	Resolver CapabilityResolver
	Compile  func(name, source string, modifiers ...string) (action.AnyAction, error)
	Alias    string
	// Introspection enables retaining child-action relationships on materialized actions.
	Introspection bool
}

MaterializeReq passes context, metadata, and compiler to the materialization phase.

type Materializer ¶ added in v0.23.0

type Materializer func(req MaterializeReq) error

Materializer converts declarations from meta into executable actions in the resolver.

type MergeablePrimary ¶ added in v0.23.0

type MergeablePrimary interface {
	PrimaryExtension
	MergeWith(older PrimaryExtension) PrimaryExtension
}

MergeablePrimary is implemented by primary extensions that know how to combine themselves with an already-installed primary handling the same token or keyword.

NewPrimaryExtensionTable calls MergeWith instead of panicking when it encounters a duplicate and the newer extension implements this interface. The older extension is passed as the argument; the newer decides how to combine them.

This is what lets a bundle whose primary carries per-compilation state — the macros bundle is the canonical case — be installed more than once during a sub-pipeline compile without triggering the "duplicates fail loudly" panic. A genuine cross-bundle conflict (two unrelated bundles claiming the same token) still panics, because neither implements the interface.

type Modifier ¶ added in v0.23.0

type Modifier struct {
	Name        string
	Owner       ModifierOwner
	ValueKind   ModifierKind
	Unique      bool
	Inheritable bool
	Example     string
	Apply       func(b *action.Builder[any, any], raw string) error
}

Modifier is one `:name` or `:name=value` annotation on an atom.

Name is the identifier without the leading colon. Apply runs once per occurrence, in source order, on the atom's builder. The raw string is the DSL text after `=`, or "" for a flag. The parser has already stripped surrounding quotes and expanded adjacent tokens, so no modifier needs to worry about either.

Owner declares which subsystem owns the name. A modifier whose name is reserved by the Kernel or the grammar must be declared by its owner; NewModifierTable panics on a mismatch.

func Duration(name string, apply func(*action.Builder[any, any], time.Duration) *action.Builder[any, any]) Modifier

func Flag(name string, apply func(*action.Builder[any, any]) *action.Builder[any, any]) Modifier

func Float64(name string, apply func(*action.Builder[any, any], float64) *action.Builder[any, any]) Modifier

func Int(name string, apply func(*action.Builder[any, any], int) *action.Builder[any, any]) Modifier

func Int32(name string, apply func(*action.Builder[any, any], int32) *action.Builder[any, any]) Modifier

func Int64(name string, apply func(*action.Builder[any, any], int64) *action.Builder[any, any]) Modifier

func String(name string, apply func(*action.Builder[any, any], string) *action.Builder[any, any]) Modifier

func StringList(name string, apply func(*action.Builder[any, any], []string) *action.Builder[any, any]) Modifier

func WithInheritable(m Modifier) Modifier

func WithOwner(m Modifier, owner ModifierOwner) Modifier

func WithUnique(m Modifier) Modifier

type ModifierKind ¶ added in v0.23.0

type ModifierKind uint8

ModifierKind describes the compiler-level value shape of a modifier. The typed constructors (Duration, Int, Flag, ...) set it automatically, so most code never references it directly.

const (
	// ModifierKindAny accepts any value. It is the zero value, so a
	// modifier built via a raw struct literal (not a typed constructor)
	// performs no value validation.
	ModifierKindAny ModifierKind = iota
	ModifierKindFlag
	ModifierKindString
	ModifierKindStringList
	ModifierKindInt
	ModifierKindInt32
	ModifierKindInt64
	ModifierKindFloat64
	ModifierKindDuration
)

func (k ModifierKind) String() string

type ModifierOwner ¶ added in v0.23.0

type ModifierOwner uint8

ModifierOwner identifies which subsystem owns a modifier name.

const (
	// OwnerBundle means the modifier is owned by the bundle that
	// declares it. Any bundle may declare a modifier with this owner.
	OwnerBundle ModifierOwner = iota
	// OwnerKernel means the modifier is a standard Kernel policy
	// modifier. Only the modifiers_core bundle may declare it.
	OwnerKernel
	// OwnerGrammar means the modifier is owned by the nflow grammar.
	// No bundle may declare it.
	OwnerGrammar
)

func RequiredModifierOwner(name string) ModifierOwner

type ModifierSource ¶ added in v0.23.0

type ModifierSource struct {
	Kind  string
	Label string
}

ModifierSource records where a modifier came from. Both fields are free-form strings: core never interprets them. Extensions and the parser populate them; `nflow explain` renders them.

Kind is a short category. Reserved values: "atom" for a modifier written directly on the atom. Extensions add their own ("scope", "profile", "pipeline", …).

Label identifies the specific origin within a kind — a profile name, a pipeline name. Empty when the kind alone is enough.

type ModifierSpec ¶ added in v0.23.0

type ModifierSpec struct {
	Name      string `json:"name"`
	ValueKind string `json:"value_kind"`
	Example   string `json:"example,omitempty"`
}

type ModifierTable ¶ added in v0.23.0

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

ModifierTable indexes modifiers by name. Construction is eager: a duplicate name, or a reserved name declared by the wrong owner, panics.

func NewModifierTable(modifiers ...Modifier) *ModifierTable

func (t *ModifierTable) Actions() []action.AnyAction

func (t *ModifierTable) All() []Modifier

func (t *ModifierTable) ApplyAll(target action.AnyAction, raws []string) (action.AnyAction, error)

func (t *ModifierTable) ByName(name string) (Modifier, bool)

type OnPreprocessFunc ¶ added in v0.23.0

type OnPreprocessFunc func(meta map[string]any) PreprocessContributions

OnPreprocessFunc is the compile-time hook fired between Preprocess and Parse. BundleConfig wires it from Bundle.OnPreprocess.

type Operator ¶ added in v0.23.0

type Operator struct {
	Meta    OperatorMeta
	Handler func(context.Context, OperatorReq) (OperatorRes, error)
}

func (o Operator) Action() *action.BuiltAction[OperatorReq, OperatorRes]

type OperatorMeta ¶ added in v0.23.0

type OperatorMeta struct {
	Name          string
	Token         TokenType
	Precedence    int
	Associativity Associativity
	Description   string
	Example       string
}

type OperatorReq ¶ added in v0.23.0

type OperatorReq struct {
	Left  Expr
	Right Expr
	Meta  *OperatorMeta
}

type OperatorRes ¶ added in v0.23.0

type OperatorRes struct {
	Node Expr
}

type OperatorSpec ¶ added in v0.23.0

type OperatorSpec struct {
	Name        string `json:"name"`
	Token       string `json:"token,omitempty"`
	Description string `json:"description,omitempty"`
	Example     string `json:"example,omitempty"`
}

type OperatorTable ¶ added in v0.23.0

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

func NewOperatorTable(ops ...Operator) *OperatorTable

func (t *OperatorTable) Actions() []action.AnyAction

func (t *OperatorTable) All() []OperatorMeta

func (t *OperatorTable) ByName(name string) (OperatorMeta, *action.BuiltAction[OperatorReq, OperatorRes], bool)

func (t *OperatorTable) ByToken(tok TokenType) (OperatorMeta, *action.BuiltAction[OperatorReq, OperatorRes], bool)

type ParallelExpr ¶

type ParallelExpr struct {
	Branches []Expr
	Pos      Position
}

ParallelExpr: N branches executed concurrently.

func (p *ParallelExpr) Analyze(r CapabilityResolver) error

func (p *ParallelExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (p *ParallelExpr) Children() []Expr

func (*ParallelExpr) Node()

type Parser ¶

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

func NewParser(ctx context.Context, ops *OperatorTable, src string) *Parser

func NewParserWithFile(
	ctx context.Context,
	ops *OperatorTable,
	primaries *PrimaryExtensionTable,
	src, file string,
) *Parser

func NewParserWithFileOffset(
	ctx context.Context,
	ops *OperatorTable,
	primaries *PrimaryExtensionTable,
	src, file string,
	lineBase int,
) *Parser

func NewParserWithPrimaries(
	ctx context.Context,
	ops *OperatorTable,
	primaries *PrimaryExtensionTable,
	src string,
) *Parser

func (p *Parser) Advance()

func (p *Parser) Context() context.Context

func (p *Parser) Cur() Token

func (p *Parser) Current() Token

func (p *Parser) Fail(_ int, format string, args ...any) error

func (p *Parser) File() string

func (p *Parser) Next()

func (p *Parser) Parse() (Expr, error)

func (p *Parser) ParseExpr(minPrec int) (Expr, error)

func (p *Parser) Peek(offset int) Token

func (p *Parser) Position() Position

func (p *Parser) Src() string

func (p *Parser) SubParse(src string) (Expr, error)

func (p *Parser) WithLineModifiers(lookups ...LineLookup) *Parser

type PipeExpr ¶ added in v0.23.0

type PipeExpr struct {
	L, R Expr
	Pos  Position
}

PipeExpr: left -> right.

func (p *PipeExpr) Analyze(r CapabilityResolver) error

func (p *PipeExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (p *PipeExpr) Children() []Expr

func (*PipeExpr) Node()

type PipelineWrapFunc ¶ added in v0.23.0

type PipelineWrapFunc func(meta map[string]any, inner action.AnyAction) (action.AnyAction, error)

type Position ¶ added in v0.8.0

type Position struct {
	File string
	Line int
	Col  int
}

func PositionOf(err error) (Position, bool)

func (p Position) String() string

type Positioned ¶ added in v0.23.0

type Positioned interface {
	Position() Position
}

Positioned is implemented by errors that carry a source position. Walk the chain with errors.As to find the first one.

type PostfixExtension ¶ added in v0.23.0

type PostfixExtension interface {
	PrimaryExtension
	PostfixToken() TokenType
	MatchesPostfix(p *Parser) bool
	ParsePostfix(p *Parser, left Expr) (Expr, error)
}

PostfixExtension handles an operator-like form whose left operand has already been parsed. MatchesPostfix must not advance the parser; ParsePostfix is called only after it returns true.

type PreparedSource ¶ added in v0.23.0

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

PreparedSource is the result of preprocessing one source. Its fields are intentionally opaque so callers can inspect metadata and pass the value to CompileAction without separating the source from its metadata.

func PrepareSource(ctx context.Context, dt *DirectiveTable, source, name string, opts ...CompileOption) (*PreparedSource, error)

func (p *PreparedSource) ActionIntrospectionEnabled() bool

func (p *PreparedSource) Contributions() PreprocessContributions

func (p *PreparedSource) Metadata() map[string]any

type PreprocessContributions ¶ added in v0.23.0

type PreprocessContributions struct {
	Primaries   []PrimaryExtension
	CompileOpts []CompileOption
}

func PreprocessContributionsFromMeta(meta map[string]any, opts ...CompileOption) PreprocessContributions

type PrimaryExtension ¶ added in v0.23.0

type PrimaryExtension interface {
	Name() string
	Parse(p *Parser) (Expr, error)
}

PrimaryExtension is the shared contract for parser extensions. Implementations provide Name and Parse plus token, keyword, or postfix dispatch as needed.

type PrimaryExtensionTable ¶ added in v0.23.0

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

func DefaultPrimaryExtensions() *PrimaryExtensionTable

func NewPrimaryExtensionTable(exts ...PrimaryExtension) *PrimaryExtensionTable

func (t *PrimaryExtensionTable) All() []PrimaryExtension

func (t *PrimaryExtensionTable) ByKeyword(kw string) (PrimaryExtension, bool)

func (t *PrimaryExtensionTable) ByPostfix(tok TokenType) (PostfixExtension, bool)

func (t *PrimaryExtensionTable) ByToken(tt TokenType) (PrimaryExtension, bool)

type ProjectionExpr ¶

type ProjectionExpr struct {
	Raw string
	Pos Position
}

ProjectionExpr: raw content `{ ... }`.

func (*ProjectionExpr) Analyze(CapabilityResolver) error

func (p *ProjectionExpr) Build(ctx context.Context, bCtx *BuildContext) (action.AnyAction, error)

func (p *ProjectionExpr) Children() []Expr

func (*ProjectionExpr) Node()

type RunReq ¶ added in v0.23.0

type RunReq struct {
	Program action.AnyAction
	Payload any
}

type RunRes ¶ added in v0.23.0

type RunRes struct {
	Output any
}

type SelfTestFeature ¶ added in v0.23.0

type SelfTestFeature struct {
	Name   string
	DSL    string
	Files  map[string]string
	Skip   string
	Source string
}

type SelfTestSection ¶ added in v0.23.0

type SelfTestSection struct {
	Name     string
	Features []SelfTestFeature
}

type ShutdownFunc ¶ added in v0.23.0

type ShutdownFunc func(context.Context) error

ShutdownFunc releases a resource explicitly owned by a bundle. Implementations must honor ctx so host shutdown remains bounded.

type SourceLoader ¶ added in v0.23.0

type SourceLoader interface {
	Load(currentFile, target string) (data []byte, resolvedPath string, err error)
}

SourceLoader resolves a directive-referenced source fragment such as the target of @include. CurrentFile is the path of the file that issued the reference; Target is the raw path from the directive.

The returned resolvedPath is used for cycle detection and error reporting. Its only requirement is stability for the same file across calls within one preprocess run.

type SourceSpec ¶ added in v0.23.0

type SourceSpec struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Tags        []string    `json:"tags,omitempty"`
	ReqFields   []FieldSpec `json:"req_fields,omitempty"`
}

SourceSpec describes a stream source (fs.walk, cov.items, ...). A source has a typed request but no typed item — the item type is a per-item element, not a whole response.

type Token ¶

type Token struct {
	Type   TokenType
	Lit    string
	Line   int
	Offset int
}

type TokenPrimary ¶ added in v0.23.0

type TokenPrimary interface {
	PrimaryExtension
	TokenType() TokenType
}

TokenPrimary is the token-dispatch contract.

type TokenType ¶

type TokenType uint8

const (
	TokEOF TokenType = iota
	TokIdent
	TokString
	TokNumber
	TokArrow
	TokPipe
	TokAmpersand
	TokOrOr
	TokLParen
	TokRParen
	TokLBrace
	TokRBrace
	TokColon
	TokEquals
	TokComma
	TokQuestion
	TokHash
	TokTilde
	TokAtBrace
	TokAtPrompt
)

func (t TokenType) String() string

type TypeDescriptor ¶ added in v0.23.0

type TypeDescriptor struct {
	Type   reflect.Type
	Stream bool
}

type Value ¶ added in v0.8.0

type Value struct {
	Kind  ValueKind
	Str   string
	Num   float64
	Bool  bool
	Ref   string
	Map   []MapEntry
	Slice []*Value
}

func (v *Value) IsWholeStateRef() bool

type ValueKind ¶ added in v0.8.0

type ValueKind uint8

const (
	ValueString ValueKind = iota
	ValueBare
	ValueNumber
	ValueBool
	ValueNull
	ValueRef
	ValueMap
	ValueSlice
)