expr

Documentation

Overview

Package expr implements a small expression language used by iterion's `compute` nodes and `when` edge clauses.

Grammar (informal):

expr     := or
or       := and ( "||" and )*
and      := not ( "&&" not )*
not      := "!" not | cmp
cmp      := add ( ( "==" | "!=" | "<" | "<=" | ">" | ">=" ) add )?
add      := mul ( ( "+" | "-" ) mul )*
mul      := unary ( ( "*" | "/" | "%" ) unary )*
unary    := "-" unary | primary
primary  := number | string | bool | funcCall | path | "(" expr ")"
funcCall := IDENT "(" ( expr ( "," expr )* )? ")"
path     := IDENT ( "." IDENT )*

The path namespaces recognized by the evaluator depend on the Context: `vars`, `input`, `outputs`, `artifacts`, `loop.<name>.{iteration,max,previous_output[.field]}`, and `run.{id}` are the standard ones.

Builtin functions: `length`, `concat`, `unique`, `contains`. See the builtins map below for signatures and semantics. Function calls are disambiguated from path lookups purely by the presence of `(` directly after the leading IDENT — there is no separate keyword set.

Index

• type AST
  • func MustParse(src string) *AST
  • func Parse(src string) (*AST, error)
  • func (a *AST) Eval(ctx *Context) (interface{}, error)
  • func (a *AST) EvalBool(ctx *Context) (bool, error)
  • func (a *AST) Refs() []Ref
  • func (a *AST) Source() string
• type Context
• type Ref

Types

type AST

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

AST is the parsed form of an expression. It is opaque outside the package.

func MustParse

func MustParse(src string) *AST

MustParse is like Parse but panics on error. Intended for tests / constants.

func Parse

func Parse(src string) (*AST, error)

Parse parses an expression string and returns its AST. Returns an error on malformed input. The returned AST can be evaluated many times against different contexts.

func (*AST) Eval

func (a *AST) Eval(ctx *Context) (interface{}, error)

Eval evaluates the AST against the context and returns the resulting value (typed as bool, int64, float64, string, or nil for absent paths).

func (*AST) EvalBool

func (a *AST) EvalBool(ctx *Context) (bool, error)

EvalBool evaluates and coerces the result to bool. Non-bool truthy values follow standard rules: nil → false, "" → false, 0 → false, others → true.

func (*AST) Refs

func (a *AST) Refs() []Ref

Refs returns the unique namespace.path tuples referenced by the expression. Used by the compiler to validate that all references resolve.

func (*AST) Source

func (a *AST) Source() string

Source returns the original source string for debugging.

type Context

type Context struct {
	Vars      func(path []string) interface{}
	Input     func(path []string) interface{}
	Outputs   func(path []string) interface{}
	Artifacts func(path []string) interface{}
	Loop      func(path []string) interface{} // loop.<name>.<...>
	Run       func(path []string) interface{} // run.<...>
}

Context provides values that path expressions resolve against.

Each callback receives the dotted path *after* the namespace prefix and returns the resolved value (or nil if not found). The evaluator never inspects the structure beyond what the callback returns.

type Ref

type Ref struct {
	Namespace string
	Path      []string
}

Ref is a single namespace.path reference extracted from an expression.