Documentation
¶
Index ¶
- Constants
- Variables
- func ExpressionEvaluateAsIter(ctx context.Context, env Env, expressionString string) (any, error)
- func ExpressionEvaluateAsIterWithTracking(ctx context.Context, env Env, expressionString string, ...) (any, error)
- func ExpressionEvaluteAsArray(ctx context.Context, env Env, expressionString string) ([]any, error)
- func ExpressionEvaluteAsArrayWithTracking(ctx context.Context, env Env, expressionString string, ...) ([]any, error)
- func ExpressionEvaluteAsBool(ctx context.Context, env Env, expressionString string) (bool, error)
- func ExpressionEvaluteAsBoolWithTracking(ctx context.Context, env Env, expressionString string, ...) (bool, error)
- func ExtractExprIdentifiers(exprStr string) []string
- func ExtractExprPaths(exprStr string) []string
- func ExtractVarKey(s string) string
- func ExtractVarKeysFromMultiple(strs ...string) []string
- func ExtractVarRefs(raw string) []string
- func FormatPath(segments []pathSegment) string
- func GetEnvVarName(s string) string
- func GetFilePath(s string) string
- func HasVars(raw string) bool
- func IsEnvReference(s string) bool
- func IsFileReference(s string) bool
- func IsVarPattern(s string) bool
- func NewCompileError(expr string, cause error) error
- func NewResolveError(path string, cause error) error
- func NewRunError(expr string, cause error) error
- func NormalizeExpression(ctx context.Context, expressionString string, varsystem varsystem.VarMap) (string, error)
- func ReadEnvVar(envRef string) (string, error)
- func ReadFileContent(fileRef string) (string, error)
- func ResolvePath(data map[string]any, path string) (any, bool)
- func SetPath(data map[string]any, path string, value any) error
- type Env
- type EnvReferenceError
- type ExpressionError
- type FileReferenceError
- type InterpolationError
- type InterpolationResult
- type UnifiedEnv
- func (e *UnifiedEnv) Clone() *UnifiedEnv
- func (e *UnifiedEnv) Eval(ctx context.Context, exprStr string) (any, error)
- func (e *UnifiedEnv) EvalBool(ctx context.Context, exprStr string) (bool, error)
- func (e *UnifiedEnv) EvalInterpolated(ctx context.Context, exprStr string) (any, error)
- func (e *UnifiedEnv) EvalIter(ctx context.Context, exprStr string) (any, error)
- func (e *UnifiedEnv) EvalString(ctx context.Context, exprStr string) (string, error)
- func (e *UnifiedEnv) Get(path string) (any, bool)
- func (e *UnifiedEnv) GetData() map[string]any
- func (e *UnifiedEnv) GetTracker() *tracking.VariableTracker
- func (e *UnifiedEnv) Has(path string) bool
- func (e *UnifiedEnv) Interpolate(raw string) (string, error)
- func (e *UnifiedEnv) InterpolateCtx(ctx context.Context, raw string) (string, error)
- func (e *UnifiedEnv) InterpolateWithResult(raw string) (InterpolationResult, error)
- func (e *UnifiedEnv) Merge(other *UnifiedEnv) *UnifiedEnv
- func (e *UnifiedEnv) ResolveValue(raw string) (any, error)
- func (e *UnifiedEnv) Set(path string, value any) error
- func (e *UnifiedEnv) WithFunc(name string, fn any) *UnifiedEnv
- func (e *UnifiedEnv) WithTracking(t *tracking.VariableTracker) *UnifiedEnv
Constants ¶
const ( // FileRefPrefix is the prefix for file references in expressions. FileRefPrefix = "#file:" // EnvRefPrefix is the prefix for environment variable references. EnvRefPrefix = "#env:" )
Variables ¶
var ( ErrNilEnv = errors.New("cannot evaluate on nil UnifiedEnv") ErrKeyNotFound = errors.New("key not found") ErrEmptyPath = errors.New("empty path") ErrEmptyExpression = errors.New("empty expression") )
Common errors
Functions ¶
func ExpressionEvaluateAsIter ¶
ExpressionEvaluateAsIter evaluates the expression and returns an iterator sequence (iter.Seq[any] for slices, iter.Seq2[string, any] for maps) if the result is iterable. Otherwise, it returns an error.
func ExpressionEvaluateAsIterWithTracking ¶
func ExpressionEvaluateAsIterWithTracking(ctx context.Context, env Env, expressionString string, tracker *tracking.VariableTracker) (any, error)
ExpressionEvaluateAsIterWithTracking evaluates an iterable expression with variable access tracking
func ExpressionEvaluteAsArrayWithTracking ¶
func ExpressionEvaluteAsArrayWithTracking(ctx context.Context, env Env, expressionString string, tracker *tracking.VariableTracker) ([]any, error)
ExpressionEvaluteAsArrayWithTracking evaluates an array expression with variable access tracking
func ExpressionEvaluteAsBool ¶
func ExpressionEvaluteAsBoolWithTracking ¶
func ExpressionEvaluteAsBoolWithTracking(ctx context.Context, env Env, expressionString string, tracker *tracking.VariableTracker) (bool, error)
ExpressionEvaluteAsBoolWithTracking evaluates a boolean expression with variable access tracking
func ExtractExprIdentifiers ¶
ExtractExprIdentifiers extracts top-level identifiers from a pure expr-lang expression. It performs a simple lexical scan to find variable references without full AST parsing. Returns identifiers like "node", "env" from expressions like "node.response.status == 200".
func ExtractExprPaths ¶
ExtractExprPaths extracts full dot-notation paths from expr-lang expressions. Uses AST parsing for robust extraction. Example: "node.response.status == 200" → ["node.response.status"]
func ExtractVarKey ¶
ExtractVarKey extracts the variable key from a {{ key }} pattern. Returns the key without braces, or empty string if not a valid pattern.
func ExtractVarKeysFromMultiple ¶
ExtractVarKeysFromMultiple extracts all unique variable keys from multiple strings.
func ExtractVarRefs ¶
ExtractVarRefs extracts all variable references from a string without resolving them. Returns a deduplicated list of variable references (including #env: and #file: refs).
func FormatPath ¶
func FormatPath(segments []pathSegment) string
FormatPath formats path segments back into a string.
func GetEnvVarName ¶
GetEnvVarName extracts the environment variable name from a reference. Returns empty string if not an env reference.
func GetFilePath ¶
GetFilePath extracts the file path from a file reference. Returns empty string if not a file reference.
func IsEnvReference ¶
IsEnvReference checks if a string is an environment variable reference (#env:VAR).
func IsFileReference ¶
IsFileReference checks if a string is a file reference (#file:/path).
func IsVarPattern ¶
IsVarPattern checks if a string is exactly a {{ key }} pattern (no surrounding text).
func NewCompileError ¶
NewCompileError creates an error for compilation failures.
func NewResolveError ¶
NewResolveError creates an error for variable resolution failures.
func NewRunError ¶
NewRunError creates an error for runtime evaluation failures.
func NormalizeExpression ¶
func ReadEnvVar ¶
ReadEnvVar reads the value of an environment variable reference. Returns the value and whether it was found.
func ReadFileContent ¶
ReadFileContent reads the content of a file reference. Returns the file content as a string, or an error if the file cannot be read.
func ResolvePath ¶
ResolvePath looks up a value in nested maps using dot notation and array indexing. Supports paths like:
- "name" (simple key)
- "node.response.body" (nested path)
- "items[0]" (array index)
- "items[0].id" (array index with nested path)
- "nodes[0].response.headers.Content-Type" (mixed)
For backwards compatibility with flat key maps (e.g., from varsystem), this function first checks if the path exists as a direct key in the map before attempting path resolution.
Types ¶
type EnvReferenceError ¶
EnvReferenceError represents an error when reading a #env: reference.
func (*EnvReferenceError) Error ¶
func (e *EnvReferenceError) Error() string
func (*EnvReferenceError) Unwrap ¶
func (e *EnvReferenceError) Unwrap() error
type ExpressionError ¶
type ExpressionError struct {
Expression string // The expression that failed
Phase string // "compile", "run", or "resolve"
Cause error // The underlying error
}
ExpressionError represents a structured error from expression evaluation.
func (*ExpressionError) Error ¶
func (e *ExpressionError) Error() string
func (*ExpressionError) Unwrap ¶
func (e *ExpressionError) Unwrap() error
type FileReferenceError ¶
FileReferenceError represents an error when reading a #file: reference.
func (*FileReferenceError) Error ¶
func (e *FileReferenceError) Error() string
func (*FileReferenceError) Unwrap ¶
func (e *FileReferenceError) Unwrap() error
type InterpolationError ¶
type InterpolationError struct {
Input string // The original input string
VarRef string // The variable reference that failed
Cause error // The underlying error
}
InterpolationError represents an error during {{ }} interpolation.
func (*InterpolationError) Error ¶
func (e *InterpolationError) Error() string
func (*InterpolationError) Unwrap ¶
func (e *InterpolationError) Unwrap() error
type InterpolationResult ¶
type InterpolationResult struct {
Value string // The interpolated string
ReadVars map[string]any // Variables that were read during interpolation
}
InterpolationResult holds the result of interpolation along with tracked reads.
type UnifiedEnv ¶
type UnifiedEnv struct {
// contains filtered or unexported fields
}
UnifiedEnv provides a unified interface for variable resolution, expression evaluation, and string interpolation. It operates on hierarchical (non-flattened) data.
func NewUnifiedEnv ¶
func NewUnifiedEnv(data map[string]any) *UnifiedEnv
NewUnifiedEnv creates a new UnifiedEnv with the given hierarchical data.
func (*UnifiedEnv) Clone ¶
func (e *UnifiedEnv) Clone() *UnifiedEnv
Clone creates a deep copy of the UnifiedEnv.
func (*UnifiedEnv) Eval ¶
Eval evaluates a pure expr-lang expression and returns the result. This is the fast path for condition fields - NO {{ }} interpolation. Use Interpolate() for text fields that need {{ }} support.
func (*UnifiedEnv) EvalBool ¶
EvalBool evaluates a pure expr-lang expression and returns the result as a boolean. This is the fast path for condition fields (if node) - NO {{ }} interpolation.
func (*UnifiedEnv) EvalInterpolated ¶
EvalInterpolated first interpolates {{ }} patterns, then evaluates the result. Use this when you need both interpolation AND expression evaluation.
func (*UnifiedEnv) EvalIter ¶
EvalIter evaluates a pure expr-lang expression and returns an iterator. Returns iter.Seq[any] for slices/arrays, or iter.Seq2[string, any] for maps. This is the fast path for loop fields (for/foreach node) - NO {{ }} interpolation.
func (*UnifiedEnv) EvalString ¶
EvalString evaluates an expression and returns the result as a string.
func (*UnifiedEnv) Get ¶
func (e *UnifiedEnv) Get(path string) (any, bool)
Get retrieves a value at the given path and optionally tracks the read. The path can use dot notation (e.g., "node.response.body") and array indexing (e.g., "items[0].id").
func (*UnifiedEnv) GetData ¶
func (e *UnifiedEnv) GetData() map[string]any
GetData returns the underlying hierarchical data map.
func (*UnifiedEnv) GetTracker ¶
func (e *UnifiedEnv) GetTracker() *tracking.VariableTracker
GetTracker returns the variable tracker (may be nil).
func (*UnifiedEnv) Has ¶
func (e *UnifiedEnv) Has(path string) bool
Has returns true if a value exists at the given path.
func (*UnifiedEnv) Interpolate ¶
func (e *UnifiedEnv) Interpolate(raw string) (string, error)
Interpolate replaces {{ varKey }} patterns with resolved values from the environment. Supports:
- {{ path.to.value }} - Nested path resolution
- {{ #env:VAR_NAME }} - Environment variables
- {{ #file:/path/to/file }} - File contents
- {{ items[0].id }} - Array access
The context parameter is reserved for future use (cancellation, timeouts).
func (*UnifiedEnv) InterpolateCtx ¶
InterpolateCtx is like Interpolate but accepts a context for cancellation.
func (*UnifiedEnv) InterpolateWithResult ¶
func (e *UnifiedEnv) InterpolateWithResult(raw string) (InterpolationResult, error)
InterpolateWithResult replaces {{ varKey }} patterns and returns both the result and a map of all variables that were read during interpolation.
func (*UnifiedEnv) Merge ¶
func (e *UnifiedEnv) Merge(other *UnifiedEnv) *UnifiedEnv
Merge combines another UnifiedEnv's data into this one. Values from other take precedence in case of conflicts.
func (*UnifiedEnv) ResolveValue ¶
func (e *UnifiedEnv) ResolveValue(raw string) (any, error)
ResolveValue resolves an input that may contain {{ expr }} patterns. - If input is exactly "{{ expr }}", returns the typed value (bool, int, etc.) - If input has text around {{ }}, returns interpolated string - If input has no {{ }}, returns the input string as-is
func (*UnifiedEnv) Set ¶
func (e *UnifiedEnv) Set(path string, value any) error
Set sets a value at the given path, creating intermediate maps as needed.
func (*UnifiedEnv) WithFunc ¶
func (e *UnifiedEnv) WithFunc(name string, fn any) *UnifiedEnv
WithFunc returns a copy of the UnifiedEnv with a custom function added. Custom functions are available in expr-lang expressions.
func (*UnifiedEnv) WithTracking ¶
func (e *UnifiedEnv) WithTracking(t *tracking.VariableTracker) *UnifiedEnv
WithTracking returns a copy of the UnifiedEnv with tracking enabled. Variable reads will be recorded in the provided tracker.
Source Files