eval

Documentation

Overview

Package eval provides variable evaluation for Buildfiles.

The evaluation phase occurs after semantic analysis and before build planning. It evaluates immediate variables, handles conditionals, and prepares the context for recipe execution.

The evaluation process:

1. Initialize context with built-in variables (os, arch)
2. Evaluate conditionals to determine which branches apply
3. Evaluate immediate variables in definition order
4. Store lazy variables for on-demand evaluation

Built-in variables:

• os: Operating system name (runtime.GOOS)
• arch: Architecture name (runtime.GOARCH)

Index

• func InterpolateBlockCommand(block *ast.BlockCommand, ctx *CommandContext) (string, error)
• func InterpolateCommand(cmd *ast.LineCommand, ctx *CommandContext) (string, error)
• func ShellQuote(s string) string
• func ShellQuoteList(items []string) string
• type CommandContext
  • func NewCommandContext(parent *Context, target string, deps []string) *CommandContext
  • func (c *CommandContext) Get(name string) (string, bool)
  • func (c *CommandContext) GetCapture(name string) (string, bool)
  • func (c *CommandContext) IsDefined(name string) bool
  • func (c *CommandContext) Parent() *Context
  • func (c *CommandContext) SetCaptures(captures map[string]string)
  • func (c *CommandContext) SetStem(stem string)
• type Context
  • func NewContext() *Context
  • func (c *Context) CacheLazyResult(name, value string)
  • func (c *Context) ClearShellCache()
  • func (c *Context) Get(name string) (string, bool)
  • func (c *Context) GetLazy(name string) (string, bool)
  • func (c *Context) GetLazyCache(name string) (string, bool)
  • func (c *Context) GetLazyValue(name string) (*ast.Value, bool)
  • func (c *Context) GetShellCache(cmd string) (string, bool)
  • func (c *Context) IsDefined(name string) bool
  • func (c *Context) IsLazy(name string) bool
  • func (c *Context) LazyVariables() map[string]string
  • func (c *Context) Set(name, value string)
  • func (c *Context) SetLazy(name, unevaluatedValue string)
  • func (c *Context) SetLazyValue(name string, value *ast.Value)
  • func (c *Context) SetShellCache(cmd, output string)
  • func (c *Context) Variables() map[string]string
• type Evaluator
  • func NewEvaluator(ctx *Context) *Evaluator
  • func (e *Evaluator) Context() *Context
  • func (e *Evaluator) EvaluateCondition(cond ast.Condition) (bool, error)
  • func (e *Evaluator) EvaluateConditional(conditional *ast.Conditional) error
  • func (e *Evaluator) EvaluateValue(val *ast.Value) (string, error)
  • func (e *Evaluator) EvaluateVariables(stmts []ast.Statement) error
  • func (e *Evaluator) SetEmitter(emitter *output.Emitter)
  • func (e *Evaluator) SetVerboseOutput(w io.Writer)
• type ShellError
  • func (e *ShellError) Error() string
  • func (e *ShellError) Unwrap() error
• type UndefinedVariableError
  • func (e *UndefinedVariableError) Error() string

Functions

func InterpolateBlockCommand

func InterpolateBlockCommand(block *ast.BlockCommand, ctx *CommandContext) (string, error)

InterpolateBlockCommand interpolates a block command and returns the resulting string.

func InterpolateCommand

func InterpolateCommand(cmd *ast.LineCommand, ctx *CommandContext) (string, error)

InterpolateCommand interpolates a line command and returns the resulting string.

func ShellQuote

func ShellQuote(s string) string

ShellQuote quotes a string for safe use in shell commands. It uses single quotes and handles embedded single quotes. Simple alphanumeric values are not quoted.

func ShellQuoteList

func ShellQuoteList(items []string) string

ShellQuoteList quotes each item in a space-separated list individually. Returns a space-separated string of quoted items.

Types

type CommandContext

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

CommandContext extends Context with automatic variables and captures for command interpolation during recipe execution.

func NewCommandContext

func NewCommandContext(parent *Context, target string, deps []string) *CommandContext

NewCommandContext creates a command context with automatic variables set.

func (*CommandContext) Get

func (c *CommandContext) Get(name string) (string, bool)

Get retrieves a variable value. Priority: automatic > captures > parent context (including lazy variables)

func (*CommandContext) GetCapture

func (c *CommandContext) GetCapture(name string) (string, bool)

GetCapture retrieves a capture variable.

func (*CommandContext) IsDefined

func (c *CommandContext) IsDefined(name string) bool

IsDefined returns true if the variable is defined anywhere.

func (*CommandContext) Parent

func (c *CommandContext) Parent() *Context

Parent returns the parent evaluation context.

func (*CommandContext) SetCaptures

func (c *CommandContext) SetCaptures(captures map[string]string)

SetCaptures sets capture variables from pattern matching.

func (*CommandContext) SetStem

func (c *CommandContext) SetStem(stem string)

SetStem sets the stem automatic variable (for pattern targets).

type Context

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

Context holds the evaluation context for a Buildfile. It stores evaluated variables, lazy variables, and built-in values.

func NewContext

func NewContext() *Context

NewContext creates a new evaluation context with built-in variables initialized.

func (*Context) CacheLazyResult

func (c *Context) CacheLazyResult(name, value string)

CacheLazyResult caches the result of a lazy variable evaluation.

func (*Context) ClearShellCache

func (c *Context) ClearShellCache()

ClearShellCache clears all cached shell() results. This can be used between builds or when the environment changes.

func (*Context) Get

func (c *Context) Get(name string) (string, bool)

Get retrieves the value of a variable. It returns the value and true if the variable is defined, or ("", false) otherwise. Built-in variables take precedence over user-defined variables. Note: For lazy variables, use GetOrEvaluateLazy with an evaluator.

func (*Context) GetLazy

func (c *Context) GetLazy(name string) (string, bool)

GetLazy retrieves a lazy variable's unevaluated value (legacy string version). For lazy variables stored with SetLazyValue, returns "__lazy__" as a marker.

func (*Context) GetLazyCache

func (c *Context) GetLazyCache(name string) (string, bool)

GetLazyCache retrieves a cached lazy variable result. Returns the value and true if cached, or ("", false) otherwise.

func (*Context) GetLazyValue

func (c *Context) GetLazyValue(name string) (*ast.Value, bool)

GetLazyValue retrieves a lazy variable's AST value. Returns the value and true if it's a lazy variable, or (nil, false) otherwise.

func (*Context) GetShellCache

func (c *Context) GetShellCache(cmd string) (string, bool)

GetShellCache retrieves a cached shell() result. Returns the cached output and true if found, or ("", false) otherwise.

func (*Context) IsDefined

func (c *Context) IsDefined(name string) bool

IsDefined returns true if the variable is defined (user, lazy, or built-in).

func (*Context) IsLazy

func (c *Context) IsLazy(name string) bool

IsLazy returns true if the variable is a lazy variable (not yet evaluated).

func (*Context) LazyVariables

func (c *Context) LazyVariables() map[string]string

LazyVariables returns a copy of all lazy variable names.

func (*Context) Set

func (c *Context) Set(name, value string)

Set sets the value of a variable. Built-in variables cannot be overwritten.

func (*Context) SetLazy

func (c *Context) SetLazy(name, unevaluatedValue string)

SetLazy stores a lazy variable for on-demand evaluation (legacy string version). Deprecated: Use SetLazyValue for full AST support.

func (*Context) SetLazyValue

func (c *Context) SetLazyValue(name string, value *ast.Value)

SetLazyValue stores a lazy variable's AST value for on-demand evaluation. The value is stored unevaluated and will be evaluated when first referenced.

func (*Context) SetShellCache

func (c *Context) SetShellCache(cmd, output string)

SetShellCache stores a shell() result in the cache. Only successful executions should be cached; errors should not be cached.

func (*Context) Variables

func (c *Context) Variables() map[string]string

Variables returns a copy of all evaluated variables (including built-ins).

type Evaluator

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

Evaluator evaluates AST values and expressions.

func NewEvaluator

func NewEvaluator(ctx *Context) *Evaluator

NewEvaluator creates a new evaluator with the given context.

func (*Evaluator) Context

func (e *Evaluator) Context() *Context

Context returns the evaluation context.

func (*Evaluator) EvaluateCondition

func (e *Evaluator) EvaluateCondition(cond ast.Condition) (bool, error)

EvaluateCondition evaluates a condition expression and returns the result.

func (*Evaluator) EvaluateConditional

func (e *Evaluator) EvaluateConditional(conditional *ast.Conditional) error

EvaluateConditional evaluates a conditional block. It evaluates the condition and executes the appropriate branch's body.

func (*Evaluator) EvaluateValue

func (e *Evaluator) EvaluateValue(val *ast.Value) (string, error)

EvaluateValue evaluates an AST Value and returns the resulting string. It handles literal values, interpolations, and function calls.

func (*Evaluator) EvaluateVariables

func (e *Evaluator) EvaluateVariables(stmts []ast.Statement) error

EvaluateVariables evaluates all immediate variables in definition order. Lazy variables are stored for on-demand evaluation.

Evaluation rules:

1. Variables are evaluated in definition order
2. Forward references (referencing a later immediate variable) cause an error
3. Lazy variables are stored unevaluated for on-demand evaluation
4. Built-in variables (os, arch) are always available
5. Non-variable statements are skipped

func (*Evaluator) SetEmitter

func (e *Evaluator) SetEmitter(emitter *output.Emitter)

SetEmitter sets the event emitter for the output system.

func (*Evaluator) SetVerboseOutput

func (e *Evaluator) SetVerboseOutput(w io.Writer)

SetVerboseOutput sets the output writer for verbose mode. When set, variable evaluations will be printed to this writer.

type ShellError

type ShellError struct {
	Command string
	Err     error
}

ShellError is returned when a shell command fails.

func (*ShellError) Error

func (e *ShellError) Error() string

func (*ShellError) Unwrap

func (e *ShellError) Unwrap() error

type UndefinedVariableError

type UndefinedVariableError struct {
	Name     string
	Location ast.SourceLocation
}

UndefinedVariableError is returned when a variable reference cannot be resolved.

func (*UndefinedVariableError) Error

func (e *UndefinedVariableError) Error() string