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:
- Initialize context with built-in variables (os, arch)
- Evaluate conditionals to determine which branches apply
- Evaluate immediate variables in definition order
- 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 (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 (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 (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
- type UndefinedVariableError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
GetLazyCache retrieves a cached lazy variable result. Returns the value and true if cached, or ("", false) otherwise.
func (*Context) GetLazyValue ¶
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 ¶
GetShellCache retrieves a cached shell() result. Returns the cached output and true if found, or ("", false) otherwise.
func (*Context) IsDefined ¶
IsDefined returns true if the variable is defined (user, lazy, or built-in).
func (*Context) IsLazy ¶
IsLazy returns true if the variable is a lazy variable (not yet evaluated).
func (*Context) LazyVariables ¶
LazyVariables returns a copy of all lazy variable names.
func (*Context) SetLazy ¶
SetLazy stores a lazy variable for on-demand evaluation (legacy string version). Deprecated: Use SetLazyValue for full AST support.
func (*Context) SetLazyValue ¶
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 ¶
SetShellCache stores a shell() result in the cache. Only successful executions should be cached; errors should not be cached.
type Evaluator ¶
type Evaluator struct {
// contains filtered or unexported fields
}
Evaluator evaluates AST values and expressions.
func NewEvaluator ¶
NewEvaluator creates a new evaluator with the given context.
func (*Evaluator) EvaluateCondition ¶
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 ¶
EvaluateValue evaluates an AST Value and returns the resulting string. It handles literal values, interpolations, and function calls.
func (*Evaluator) EvaluateVariables ¶
EvaluateVariables evaluates all immediate variables in definition order. Lazy variables are stored for on-demand evaluation.
Evaluation rules:
- Variables are evaluated in definition order
- Forward references (referencing a later immediate variable) cause an error
- Lazy variables are stored unevaluated for on-demand evaluation
- Built-in variables (os, arch) are always available
- Non-variable statements are skipped
func (*Evaluator) SetEmitter ¶
SetEmitter sets the event emitter for the output system.
func (*Evaluator) SetVerboseOutput ¶
SetVerboseOutput sets the output writer for verbose mode. When set, variable evaluations will be printed to this writer.
type ShellError ¶
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
Source Files