compiler

package
v0.25.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	IntrospectionKindAction   = "action"
	IntrospectionKindSequence = "sequence"
	IntrospectionKindBranch   = "branch"
	IntrospectionKindWraps    = "wraps"
)
View Source 
const VersionUnknown = "dev"

VersionUnknown marks a compiler with no release identity. It is the default for `go run` and for binaries built without the linker's -X github.com/nexssp/flow/cli.Version=... injection.

Variables

View Source 
var Version = VersionUnknown

Version is the compiler version string that the @flow_version directive compares against. It is populated by the CLI at init time from its linker-injected build metadata. When a test or embedded runner leaves it unset, VersionUnknown tells the directive to accept any constraint — a source build has no release identity to compare.

Functions

func Analyze added in v0.23.0 

func Analyze(resolver CapabilityResolver, expr Expr) error

Analyze runs polymorphic contract validation on the AST. It is a compile-time gate: any edge whose producer output cannot be coerced into the consumer input fails here, before Execute is ever reached.

The rule mirrors runtime Coerce exactly — nominal assignability first, then a JSON round-trip for the same struct-to-struct cases the runtime decoder handles. If a pipeline compiles here, it will not fail at runtime with "cannot coerce input into target".

func ApplyConstants added in v0.23.0 

func ApplyConstants(lines []string, start int, constants map[string]string)

ApplyConstants rewrites `${key}` references in lines[start:] to their declared values. It is the single substitution primitive for compile-time constants; both the @const directive handlers and the @include merge path call it.

Substitution is textual and idempotent: an already-substituted value no longer contains a `${...}` pattern, so re-application over the same slice is a no-op. Lines that contain no `${` are skipped without a replacement pass, keeping the common case free of allocations.

lines is mutated in place. start is a half-open lower bound: lines [0, start) are untouched.

func AtomNames added in v0.23.0 

func AtomNames(e Expr) []string

func Build added in v0.23.0 

func Build(
	ctx context.Context,
	resolver CapabilityResolver,
	modifiers *ModifierTable,
	e Expr,
	advisers ...AtomAdviseFunc,
) (action.AnyAction, error)

Build lowers an AST into runnable action composition, resolving every capability through the supplied resolver. The nested composition is an implementation detail; BuildActionGraph exposes the logical data and control flow when a reviewable graph is requested.

The function is a thin dispatcher: every node implements its own Build method. Core never switches on concrete AST types.

func BuildEnv added in v0.23.0 

func BuildEnv(input any) map[string]any

func CompileAction added in v0.23.0 

func CompileAction(
	resolver CapabilityResolver,
	dt *DirectiveTable,
	mt *ModifierTable,
	ot *OperatorTable,
	pt *PrimaryExtensionTable,
	opts ...CompileOption,
) *action.BuiltAction[CompileReq, CompileRes]

func CompileAndRun added in v0.23.0 

func CompileAndRun(
	resolver CapabilityResolver,
	dt *DirectiveTable,
	mt *ModifierTable,
	ot *OperatorTable,
	pt *PrimaryExtensionTable,
	_ ...CompileOption,
) *action.BuiltAction[CompileAndRunReq, RunRes]

func ComposedPipe added in v0.23.0 

func ComposedPipe(left, right action.AnyAction) action.AnyAction

ComposedPipe is the Flow adapter for Kernel's dynamic pipe composition. Flow owns the DSL/lowering decision; Kernel owns invocation, cancellation, error propagation, and lifecycle behavior.

func Decode added in v0.23.0 

func Decode[T any](raw map[string]string) (T, error)

Decode maps a string map to a typed options struct. This is the contract that each external Bundle uses to read its @require block.

Tags: 

nflow:"key"     name of the key in the @require block
default:"..."   value when the key is missing

Unknown keys are rejected — a typo in .nflow should cause a loud failure during loading, not silently default.

Supported field types: string, bool, int, int64, time.Duration, float64. Any other type is a design error for the Bundle.

func DetectRequiredBundles added in v0.23.0 

func DetectRequiredBundles(expr Expr) []string

DetectRequiredBundles inspects an AST and returns the list of bundle IDs that must be compiled into the binary.

func IndexTopLevel added in v0.23.0 

func IndexTopLevel(s string, target byte) int

IndexTopLevel returns the index of the first occurrence of target in s at bracket depth zero, outside quoted strings. Returns -1 when absent. Companion to SplitTopLevel.

func IsReservedActionName added in v0.23.0 

func IsReservedActionName(name string) bool

IsReservedActionName reports whether name is reserved by the nflow grammar.

func Library added in v0.23.0 

func Library(
	resolver CapabilityResolver,
	dt *DirectiveTable,
	mt *ModifierTable,
	ot *OperatorTable,
	pt *PrimaryExtensionTable,
	opts ...CompileOption,
) action.Library

func LocalSymbolsFrom added in v0.25.0 

func LocalSymbolsFrom(ctx context.Context) map[string]SymbolNamespace

LocalSymbolsFrom returns the file-local namespaces installed on ctx.

func LookupSymbol added in v0.25.0 

func LookupSymbol(namespace, name string) (any, bool)

LookupSymbol resolves `<namespace>.<name>`. Analysis uses it to reject unknown symbols before a program runs.

func MergeSymbolNamespaces added in v0.25.0 

func MergeSymbolNamespaces(ctx context.Context, env map[string]any) map[string]any

MergeSymbolNamespaces returns a fresh environment containing every registered global namespace, then any file-local namespace from ctx (overriding globals of the same name), then the caller's env (overriding both). Caller wins on collision, matching WithSymbolNamespaces.

func ModifierName added in v0.23.0 

func ModifierName(raw string) string

ModifierName returns the name portion of a raw modifier string, before any '='.

func ModifierOwnerName added in v0.23.0 

func ModifierOwnerName(owner ModifierOwner) string

ModifierOwnerName renders an owner for use in error messages.

func ModifiersToMap added in v0.23.0 

func ModifiersToMap(modifiers []string) map[string]any

ModifiersToMap parses a slice of raw modifier strings (e.g. "ext=txt", "by=rel_path", "tests") into a map of parameters for stream sources and operators.

func ParseBlockOptions added in v0.23.0 

func ParseBlockOptions(lines []string, start int) (opts map[string]string, next int, err error)

ParseBlockOptions reads a `{ key: value, ... }` block via ReadBlock and parses each entry as a `key: value` pair. Returns nil for an empty block.

func ParseList added in v0.23.0 

func ParseList(line string) []string

ParseList extracts the first bracketed list `[a, b, c]` from a line. Returns nil for `[]` or when no brackets are present.

func Preprocess added in v0.23.0 

func Preprocess(ctx context.Context, dt *DirectiveTable, source, file string) (clean string, meta map[string]any, err error)

Preprocess executes directives from the dt table.

Cycle detection uses a call-stack, not a global set. This allows diamond dependencies (A → B → common, A → C → common) while still catching true cycles (A → B → A). The error message carries the exact include chain so the user sees which edge closes the loop.

Source fragments referenced by directives are read through the loader installed with WithSourceLoader; the default reads from the filesystem.

func PreprocessDots added in v0.23.0 

func PreprocessDots(src string) string

func ReadBlock added in v0.23.0 

func ReadBlock(lines []string, start int) (body []string, next int, err error)

ReadBlock extracts the raw body of a `{ ... }` block starting at lines[start]. Handles all three shapes uniformly: 

inline:      @x NAME { a: 1, b: 2 }
multi-line:  @x NAME {
               a: 1
               b: 2
             }
tail-brace:  @x NAME {
               a: 1
               b: 2 }

Returns one entry per top-level comma-separated element. Callers interpret entries: `key: value` for @config/@llm/@sandbox/@pool, `Field Type` for @schema.

Comments (`#`, `//`) and blank lines inside the block are dropped.

func Register added in v0.23.0 

func Register(id string, factory BundleFactory)

Register registers a bundle factory under the given ID.

func RegisterBoundary added in v0.23.0 

func RegisterBoundary(spec BoundarySpec)

func RegisterBundle added in v0.23.0 

func RegisterBundle(id string, factory BundleFactory)

RegisterBundle is a compatibility alias for Register.

func RegisterNamespace added in v0.25.0 

func RegisterNamespace(ns SymbolNamespace)

RegisterNamespace adds or replaces a symbolic namespace. Bundles call it from init(). Re-registration under the same name replaces the previous definition, so tests and hot-reload do not need explicit cleanup. The Symbols map is copied; the caller retains ownership of the original.

func RunAction added in v0.23.0 

func RunAction() *action.BuiltAction[RunReq, RunRes]

func SourceError added in v0.8.0 

func SourceError(pos Position, format string, args ...any) error

SourceError creates a compile-time error carrying pos. The returned error implements Positioned, so diagnostics can extract the exact file:line:col — no string parsing required.

%w in format is passed to fmt.Errorf, so wrapped errors are reachable via errors.Is / errors.As as usual.

func SplitTopLevel added in v0.23.0 

func SplitTopLevel(s string, sep byte) []string

SplitTopLevel splits s on sep, respecting quoted strings (" ' `), balanced brackets, and backslash escapes. Returns the raw segments, not trimmed. Callers trim themselves.

func StripExprComments added in v0.23.0 

func StripExprComments(raw string) string

StripExprComments removes `#` comments from an expression that will be handed to expr-lang.

`#` is depth-aware: inside parentheses `#` is expr-lang's iterator placeholder — filter(# > 0), all(items, # != "x"), map(#.name) — and survives verbatim. Only at parenthesis depth 0 does `#` begin a comment, because that is the only position where a bare `#` would be syntactically invalid in expr-lang.

Line terminators (\n, \r\n) are preserved so any error expr-lang reports keeps its line number aligned with the source text the expression was cut from. That alignment is what wrapMacroError and the projection diagnostic rely on.

Every path that hands user-authored text to expr-lang goes through this function: @assert, assert(), loop() until, match() conditions, @on_error conditions and targets, and projection bodies.

func SuggestModifierFix added in v0.23.0 

func SuggestModifierFix(target action.AnyAction, name string) string

SuggestModifierFix returns a human-readable explanation for why a modifier name cannot be applied to a given action, or empty when no better fix than "unknown modifier" is available.

The dominant real-world mistake: the author writes :file=... where the action takes @{ file: ... }. The check against the action's Req struct catches that before the runtime sees a modifier-table miss.

func TrackActionComposition added in v0.23.0 

func TrackActionComposition(
	ctx *BuildContext,
	act action.AnyAction,
	composition action.IntrospectionComposition,
) action.AnyAction

TrackActionComposition records explicit composition only when the current compilation opted into action introspection. Children and notes must be structural and must not contain argument or runtime values.

func TranslateKeyword added in v0.23.0 

func TranslateKeyword(name string) (string, bool)

TranslateKeyword resolves a parsed atom name to its canonical action name. It returns ("", false) when name is not a native keyword.

func TrimQuotes added in v0.23.0 

func TrimQuotes(s string) string

TrimQuotes removes one matched pair of surrounding quotes (" ' `), or returns s unchanged.

func ValidateBundle added in v0.23.0 

func ValidateBundle(b Bundle) error

func ValidateModifierValue added in v0.23.0 

func ValidateModifierValue(kind ModifierKind, value string) error

ValidateModifierValue checks that value matches the modifier's kind. It does not run Apply; callers that mutate a builder use it to fail fast with a stable message before invoking the handler.

func WithCompileConfig added in v0.23.0 

func WithCompileConfig(ctx context.Context, cfg map[string]string, cliArgs []string) context.Context

func WithLocalSymbols added in v0.25.0 

func WithLocalSymbols(ctx context.Context, syms map[string]SymbolNamespace) context.Context

WithLocalSymbols installs file-local symbol namespaces for one compilation. Program source reaches this through the compiler after preprocessing; the process-global registry is never touched by source.

func WithSourceLoader added in v0.23.0 

func WithSourceLoader(ctx context.Context, loader SourceLoader) context.Context

WithSourceLoader installs a loader for directive-referenced sources. The default loader reads from the filesystem.

func WithStrict added in v0.23.0 

func WithStrict(ctx context.Context) context.Context

WithStrict returns ctx marked for strict validation.

func WithSymbolNamespaces added in v0.25.0 

func WithSymbolNamespaces(env map[string]any) map[string]any

WithSymbolNamespaces returns a fresh environment with every registered namespace bound under its name. Caller-supplied keys win on collision. Namespace maps are shared read-only; do not mutate them.

Types

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 added in v0.23.0 

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

BuildActionGraph builds the deterministic, high-level action graph for expr. It is only run when explicitly requested; normal compilation adds no graph construction or allocation. Action and stream parameters are never copied.

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 added in v0.23.0 

func (*AssertExpr) Analyze(CapabilityResolver) error

func (*AssertExpr) Build added in v0.23.0 

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

func (*AssertExpr) Children added in v0.23.0 

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

func (*AssertExpr) Node added in v0.23.0 

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 added in v0.23.0 

func (*Atom) Analyze(CapabilityResolver) error

func (*Atom) Build added in v0.23.0 

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

func (*Atom) Children added in v0.23.0 

func (*Atom) Children() []Expr

func (*Atom) Node added in v0.23.0 

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 added in v0.23.0 

func BoundaryByName(name string) (BoundarySpec, bool)

func NamedBoundaries added in v0.23.0 

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
	Symbols         []SymbolNamespace

	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 (Bundle) AllSelfTests added in v0.23.0 

func (b Bundle) AllSelfTests() []SelfTestSection

type BundleFactory added in v0.23.0 

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

func Lookup added in v0.23.0 

func Lookup(id string) (BundleFactory, bool)

Lookup returns the factory registered for the exact ID.

func LookupBundleForModule added in v0.23.0 

func LookupBundleForModule(target string) (BundleFactory, bool)

LookupBundleForModule provides backward compatibility for unit tests.

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 added in v0.23.0 

func ParseCapabilityRef(raw string) (CapabilityRef, error)

ParseCapabilityRef parses a single bare identifier. Quoted values are rejected: a capability reference is grammar, not data.

func ParseCapabilityRefList added in v0.23.0 

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

ParseCapabilityRefList parses `[noop, const]` into capability references. It reuses ParseList for splitting, then runs every entry through ParseCapabilityRef so quoted members are rejected.

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 added in v0.23.0 

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

BuildCatalog extracts the full compiler surface from the live resolver and tables. Atom fields come from TypedPayload when the atom is a *BuiltAction[Req, Res]; free-form actions show no fields.

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 added in v0.23.0 

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

BundleConfig collects every extension point from a set of bundles into a single set of CompileOptions. Called once at startup.

func WithActionGraph added in v0.23.0 

func WithActionGraph() CompileOption

WithActionGraph asks CompileAction to return an AST-derived Flow lowering plan in CompileRes.ActionGraph; it does not inspect the built Kernel action. Use WithActionIntrospection for the latter. This option is opt-in so ordinary compilation does not allocate plan nodes or edges.

func WithActionIntrospection added in v0.23.0 

func WithActionIntrospection() CompileOption

WithActionIntrospection opts into recording Kernel action composition while the program is built. Ordinary compilation does not retain child references.

func WithArgSchemas added in v0.23.0 

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

func WithAtomAdvisors added in v0.23.0 

func WithAtomAdvisors(fns ...AtomAdviseFunc) CompileOption

func WithCLIArgs added in v0.23.0 

func WithCLIArgs(args []string) CompileOption

WithCLIArgs carries the raw command-line flags into the compile context so @flag.X references can be resolved and validated at compile time. A nil slice disables @flag validation, which is the right behavior for embedded runs and pure-compile tests that do not model a CLI invocation; an empty non-nil slice enables validation with zero known flags, so any @flag reference in the source is rejected.

func WithConfigMap added in v0.23.0 

func WithConfigMap(cfg map[string]string) CompileOption

WithConfigMap carries the @config key→value map into the compile context. It is called by the config bundle's OnPreprocess hook after preprocessing has collected the source's @config directives. A nil map leaves any existing config untouched so an unrelated option (e.g. WithCLIArgs from the CLI) is not silently wiped by a later call.

func WithLineModifiers added in v0.23.0 

func WithLineModifiers(lookups ...LineLookup) CompileOption

WithLineModifiers appends line-indexed modifier lookups. Multiple options accumulate; later lookups override earlier ones on the same modifier name. Extensions compose lookups this way — a pipeline's inherited policy is registered before nested @scope spans.

func WithOnPreprocess added in v0.23.0 

func WithOnPreprocess(fns ...OnPreprocessFunc) CompileOption

func WithPipelineWrappers added in v0.23.0 

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 (*ConditionalExpr) Analyze added in v0.23.0 

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

func (*ConditionalExpr) Build added in v0.23.0 

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

func (*ConditionalExpr) Children added in v0.23.0 

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

func (*ConditionalExpr) Node added in v0.23.0 

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 (*DecoratedExpr) Analyze added in v0.23.0 

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

func (*DecoratedExpr) Build added in v0.23.0 

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

func (*DecoratedExpr) Children added in v0.23.0 

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

func (*DecoratedExpr) Node added in v0.23.0 

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 (Directive) Action added in v0.23.0 

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 added in v0.23.0 

func NewDirectiveTable(ds ...Directive) *DirectiveTable

func (*DirectiveTable) Actions added in v0.23.0 

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

func (*DirectiveTable) All added in v0.23.0 

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

func (*DirectiveTable) ByName added in v0.23.0 

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 added in v0.23.0 

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

func (*DynamicResolver) Action added in v0.23.0 

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

func (*DynamicResolver) ActionNames added in v0.23.0 

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

ActionNames returns every canonical action name in stable order.

func (*DynamicResolver) Actions added in v0.23.0 

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

Actions returns each mounted action once, keyed by its canonical metadata name.

func (*DynamicResolver) Contract added in v0.23.0 

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

func (*DynamicResolver) Mount added in v0.23.0 

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

func (*DynamicResolver) MountWithAlias added in v0.23.0 

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

func (*DynamicResolver) Operator added in v0.23.0 

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

func (*DynamicResolver) Operators added in v0.23.0 

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

Operators returns mounted stream operators in stable order.

func (*DynamicResolver) Stream added in v0.23.0 

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

func (*DynamicResolver) Streams added in v0.23.0 

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

Streams returns mounted stream sources in stable order.

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 (*FallbackExpr) Analyze added in v0.23.0 

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

func (*FallbackExpr) Build added in v0.23.0 

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

func (*FallbackExpr) Children added in v0.23.0 

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

func (*FallbackExpr) Node added in v0.23.0 

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 added in v0.23.0 

func KeywordMappings() []KeywordMapping

KeywordMappings returns the canonical keyword list. The returned slice is owned by core and must not be mutated.

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 

func NewLexer(src string) *Lexer

func (*Lexer) Next 

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 added in v0.23.0 

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

LineModifiersFromOptions returns the line-indexed modifier lookups that the given CompileOptions would install, each filtered through mt so non-inheritable metadata modifiers are dropped and unknown modifiers pass through for ApplyAll to reject. Sources are preserved.

Used by diagnostics such as nflow explain that need to render inherited modifiers without compiling a program. Extensions publish their lookups through Bundle.OnPreprocess as CompileOptions.

type LoopExpr 

type LoopExpr struct {
	Body  Expr
	Until string
	Pos   Position
}

LoopExpr: loop(body) until(condition).

func (*LoopExpr) Analyze added in v0.23.0 

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

func (*LoopExpr) Build added in v0.23.0 

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

func (*LoopExpr) Children added in v0.23.0 

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

func (*LoopExpr) Node added in v0.23.0 

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 added in v0.23.0 

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

func Flag added in v0.23.0 

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

Flag handles modifiers that take no value (`:coalesce`, `:dedup`). Passing a value is rejected loudly — `:dedup=yes` in the DSL is a mistake the author should see, not silently accept.

func Float64 added in v0.23.0 

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

func Int added in v0.23.0 

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

func Int32 added in v0.23.0 

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

func Int64 added in v0.23.0 

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

func String added in v0.23.0 

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

func StringList added in v0.23.0 

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

func WithInheritable added in v0.23.0 

func WithInheritable(m Modifier) Modifier

WithInheritable marks a modifier as eligible for scope inheritance. @scope and @pipeline propagate only inheritable modifiers to nested atoms; metadata modifiers (tags, status, route) stay on the wrapper they were declared on.

func WithOwner added in v0.23.0 

func WithOwner(m Modifier, owner ModifierOwner) Modifier

WithOwner returns m with the given owner. The Kernel policy bundle uses it to declare its modifiers as OwnerKernel without a package-level constructor for every policy.

func WithUnique added in v0.23.0 

func WithUnique(m Modifier) Modifier

WithUnique marks a modifier as single-use: applying it more than once to the same atom is a compile-time error.

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 (ModifierKind) String added in v0.23.0 

func (k ModifierKind) String() string

String returns a stable identifier for the kind, suitable for JSON catalogs, lint messages, and CLI output.

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 added in v0.23.0 

func RequiredModifierOwner(name string) ModifierOwner

RequiredModifierOwner returns the owner required by a modifier name. A name not in any reserved set requires OwnerBundle.

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 added in v0.23.0 

func NewModifierTable(modifiers ...Modifier) *ModifierTable

func (*ModifierTable) Actions added in v0.23.0 

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

func (*ModifierTable) All added in v0.23.0 

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

func (*ModifierTable) ApplyAll added in v0.23.0 

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

ApplyAll wraps target once, applies every modifier in source order, and builds once. Two allocations total: the Builder and the BuiltAction.

When a modifier name is unknown, the hint path checks whether the name matches a field of the action's request struct. That is the common DSL-author mistake — writing :file=... where the action takes @{ file: ... } — and it produces a fix-the-typo message instead of a bare "unknown modifier".

func (*ModifierTable) ByName added in v0.23.0 

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 (Operator) Action added in v0.23.0 

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 added in v0.23.0 

func NewOperatorTable(ops ...Operator) *OperatorTable

func (*OperatorTable) Actions added in v0.23.0 

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

func (*OperatorTable) All added in v0.23.0 

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

func (*OperatorTable) ByName added in v0.23.0 

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

func (*OperatorTable) ByToken added in v0.23.0 

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 (*ParallelExpr) Analyze added in v0.23.0 

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

func (*ParallelExpr) Build added in v0.23.0 

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

func (*ParallelExpr) Children 

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

func (*ParallelExpr) Node added in v0.23.0 

func (*ParallelExpr) Node()

type Parser 

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

func NewParser 

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

NewParser is the no-file convenience used in tests. Parse errors report only the line number.

func NewParserWithFile added in v0.8.0 

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

NewParserWithFile carries the source path so parse errors are formatted as `file:line`, which terminals make clickable.

func NewParserWithFileOffset added in v0.23.0 

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

NewParserWithFileOffset additionally shifts reported line numbers by lineBase. Used when a fragment (e.g. a @pipeline body) is parsed in isolation but its errors must point at the parent file's lines.

func NewParserWithPrimaries added in v0.23.0 

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

NewParserWithPrimaries is kept for compatibility with callers that pass a primaries table explicitly.

func (*Parser) Advance added in v0.23.0 

func (p *Parser) Advance()

Advance is an alias for Next, exported for external primary extensions.

func (*Parser) Context added in v0.23.0 

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

Context returns the parser's context. Extensions reach caller-installed values through it — a trace sink, a policy context, a filename-keyed cache. The parser itself never reads those values; only primaries and line lookups do. It is the sanctioned way for an extension to reach a caller-provided sink without package-level state.

func (*Parser) Cur added in v0.23.0 

func (p *Parser) Cur() Token

Cur returns the token under the cursor.

func (*Parser) Current added in v0.23.0 

func (p *Parser) Current() Token

Current is an alias for Cur, exported for external primary extensions.

func (*Parser) Fail added in v0.23.0 

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

Fail reports a parse error at the given line offset by lineBase. Exported so external primary extensions can format errors the same way the built-in parser does.

func (*Parser) File added in v0.23.0 

func (p *Parser) File() string

File returns the source file path, or "".

func (*Parser) Next added in v0.23.0 

func (p *Parser) Next()

Next advances the cursor by one token.

func (*Parser) Parse added in v0.23.0 

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

func (*Parser) ParseExpr added in v0.23.0 

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

ParseExpr parses a sub-expression with the given minimum precedence. Exported so primary extensions can recurse without reimplementing the precedence-climbing loop.

func (*Parser) Peek added in v0.23.0 

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

Peek returns the token at offset from Cur without advancing. Peek(0) is the current token; offsets beyond the input return the final EOF token.

func (*Parser) Position added in v0.23.0 

func (p *Parser) Position() Position

Position returns the parser's current source position, including file, line, and column. Exposed so primary extensions can stamp AST nodes they construct without re-implementing column arithmetic.

func (*Parser) Src added in v0.23.0 

func (p *Parser) Src() string

Src returns the source text under parse.

func (*Parser) SubParse added in v0.23.0 

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

SubParse parses a fresh source fragment in this parser's context. The same operator table, primary table, and source-file metadata are reused. External primary extensions call it to re-enter the parser with substituted text.

func (*Parser) WithLineModifiers added in v0.23.0 

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

WithLineModifiers replaces the parser's line-modifier lookup chain. The parser calls them in order; later lookups win over earlier ones on modifier-name collision.

type PipeExpr added in v0.23.0 

type PipeExpr struct {
	L, R Expr
	Pos  Position
}

PipeExpr: left -> right.

func (*PipeExpr) Analyze added in v0.23.0 

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

func (*PipeExpr) Build added in v0.23.0 

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

func (*PipeExpr) Children added in v0.23.0 

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

func (*PipeExpr) Node added in v0.23.0 

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 added in v0.23.0 

func PositionOf(err error) (Position, bool)

PositionOf walks the unwrap chain of err and returns the first Position it finds. The bool is false when no positioned error exists.

func (Position) String added in v0.8.0 

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 added in v0.23.0 

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

PrepareSource preprocesses source and computes its extension contributions once. Use the returned value when metadata must be inspected before the same source is compiled, such as runner materialization.

func (*PreparedSource) ActionIntrospectionEnabled added in v0.23.0 

func (p *PreparedSource) ActionIntrospectionEnabled() bool

ActionIntrospectionEnabled reports whether this source was prepared with Kernel composition capture requested.

func (*PreparedSource) Contributions added in v0.23.0 

func (p *PreparedSource) Contributions() PreprocessContributions

Contributions returns compile-time contributions already computed for this source. It does not invoke extension callbacks again.

func (*PreparedSource) Metadata added in v0.23.0 

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

Metadata returns the directive metadata associated with this source.

type PreprocessContributions added in v0.23.0 

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

func PreprocessContributionsFromMeta added in v0.23.0 

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 added in v0.23.0 

func DefaultPrimaryExtensions() *PrimaryExtensionTable

DefaultPrimaryExtensions returns an empty extension table.

func NewPrimaryExtensionTable added in v0.23.0 

func NewPrimaryExtensionTable(exts ...PrimaryExtension) *PrimaryExtensionTable

func (*PrimaryExtensionTable) All added in v0.23.0 

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

func (*PrimaryExtensionTable) ByKeyword added in v0.23.0 

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

func (*PrimaryExtensionTable) ByPostfix added in v0.23.0 

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

ByPostfix returns the postfix extension registered for tok, if any.

func (*PrimaryExtensionTable) ByToken added in v0.23.0 

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

type ProjectionExpr 

type ProjectionExpr struct {
	Raw string
	Pos Position
}

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

func (*ProjectionExpr) Analyze added in v0.23.0 

func (*ProjectionExpr) Analyze(CapabilityResolver) error

func (*ProjectionExpr) Build added in v0.23.0 

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

func (*ProjectionExpr) Children added in v0.23.0 

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

func (*ProjectionExpr) Node added in v0.23.0 

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 SymbolNamespace added in v0.25.0 

type SymbolNamespace struct {
	Name    string
	Symbols map[string]any
}

SymbolNamespace groups compile-time symbolic values that .nflow programs reference as `<namespace>.<name>`. Bundles register namespaces from init so that programs in any repo use them without local declarations. Symbols resolve during parse/analyze (unknown names fail compilation) and bind into the expression environment at build time.

func Namespaces added in v0.25.0 

func Namespaces() []SymbolNamespace

Namespaces returns a copy of every registered namespace, sorted by name. Callers cannot mutate the registry through the result.

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 (TokenType) String 

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 (*Value) IsWholeStateRef added in v0.8.0 

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
)

Source Files

View all Source files

Directories

Path Synopsis
Package redact masks well-known credential-shaped field names before a value is handed to a logger.
 Package redact masks well-known credential-shaped field names before a value is handed to a logger.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.