variables

package
v0.8.17 Latest Latest
Warning

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

 Go to latest Published: Feb 11, 2026 License: MPL-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrRedeclared   = errors.New("this variable was declared twice in the same target")
	ErrVarNotFound  = errors.New("no matching variable found in this scope")
	ErrInvalidScope = errors.New("this action is not allowed in this scope")
	ErrSetArg       = errors.New("ARG values cannot be reassigned")

	ShellOutEnvs = map[string]struct{}{
		"HOME": {},
		"PATH": {},
	}
)

Functions

func AddEnv 

func AddEnv(envVars []string, key, value string) []string

AddEnv takes in a slice of env vars in key-value format and a new key-value string to it, taking care of possible overrides.

func ParseFlagArgs 

func ParseFlagArgs(args []string) ([]string, error)

ParseFlagArgs parses flag-form args. These can be represented as `--arg=value` or `--arg value`. The result is a slice that can be passed into ParseArgs or to ParseCommandLineArgs.

func ParseFlagArgsWithNonFlags 

func ParseFlagArgsWithNonFlags(args []string) (flags, nonFlags []string, err error)

ParseFlagArgsWithNonFlags parses flag-form args together with any possible optional additional args. e.g. "--flag1=value arg1 --flag2=value --flag3=value arg2 arg3".

func ParseKeyValue 

func ParseKeyValue(s string) (string, string, bool)

ParseKeyValue pases a key-value type into its parts if a key value needs to contain a = or \, it must be escaped using '\=', and '\\' respectively once an unescaped '=' is found, all remaining chars will be used as-is without the need to be escaped. the key and value are returned, along with a bool that is true if a value was defined (i.e. an equal was found)

e.g. ParseKeyValue("foo") -> `foo`, “, false 

ParseKeyValue("foo=")      -> `foo`,  ``,       true
ParseKeyValue("foo=bar")   -> `foo`,  `bar`,    true
ParseKeyValue(`f\=oo=bar`) -> `f=oo`, `bar`,    true
ParseKeyValue(`foo=bar=`)  -> `foo",  `bar=`,   true
ParseKeyValue(`foo=bar\=`) -> `foo",  `bar\=`,  true

func SetLocally 

func SetLocally(s *Scope, locally bool)

SetLocally sets the locally built-in arg value.

func SetPlatformArgs 

func SetPlatformArgs(s *Scope, platr *platutil.Resolver)

SetPlatformArgs sets the platform-specific built-in args to a specific platform.

Types

type Collection 

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

Collection is a collection of variable scopes used within a single target.

func NewCollection 

func NewCollection(opts NewCollectionOpt) *Collection

NewCollection creates a new Collection to be used in the context of a target.

func (*Collection) AbsRef 

func (c *Collection) AbsRef() domain.Reference

AbsRef returns a ref that any other reference should be relative to as part of the stack frame.

func (*Collection) Args 

func (c *Collection) Args() *Scope

Args returns a copy of the args.

func (*Collection) DeclareEnv 

func (c *Collection) DeclareEnv(name string, value string)

DeclareEnv declares an env var.

func (*Collection) DeclareVar 

func (c *Collection) DeclareVar(name string, opts ...DeclareOpt) (string, string, error)

DeclareVar declares a variable. The effective value may be different than the default, if the variable has been overridden.

func (*Collection) EnterFrame 

func (c *Collection) EnterFrame(
	frameName string,
	absRef domain.Reference,
	overriding *Scope,
	globals *Scope,
	globalImports map[string]domain.ImportTrackerVal,
)

EnterFrame creates a new stack frame.

func (*Collection) EnvVars 

func (c *Collection) EnvVars() *Scope

EnvVars returns a copy of the env vars.

func (*Collection) ExitFrame 

func (c *Collection) ExitFrame()

ExitFrame exits the latest stack frame.

func (*Collection) Expand 

func (c *Collection) Expand(word string, shellOut shell.EvalShellOutFn) (string, error)

Expand expands variables within the given word.

func (*Collection) ExpandOld 

func (c *Collection) ExpandOld(word string) string

ExpandOld expands variables within the given word, it does not perform shelling-out. It will eventually be removed when the ShellOutAnywhere feature is fully-adopted.

func (*Collection) Get 

func (c *Collection) Get(name string, opts ...ScopeOpt) (string, bool)

Get returns a variable by name.

func (*Collection) Globals 

func (c *Collection) Globals() *Scope

Globals returns a copy of the globals.

func (*Collection) Imports 

func (c *Collection) Imports() *domain.ImportTracker

Imports returns the imports tracker of the current frame.

func (*Collection) IsStackAtBase 

func (c *Collection) IsStackAtBase() bool

IsStackAtBase returns whether the stack has size 1.

func (*Collection) Org 

func (c *Collection) Org() string

Org returns the organization name.

func (*Collection) Overriding 

func (c *Collection) Overriding() *Scope

Overriding returns a copy of the overriding args.

func (*Collection) Project 

func (c *Collection) Project() string

Project returns the project name.

func (*Collection) ResetEnvVars 

func (c *Collection) ResetEnvVars(envs *Scope)

ResetEnvVars resets the collection's env vars.

func (*Collection) SetArg 

func (c *Collection) SetArg(name string, value string)

SetArg sets the value of an arg.

func (*Collection) SetGlobals 

func (c *Collection) SetGlobals(globals *Scope)

SetGlobals sets the global variables.

func (*Collection) SetLocally 

func (c *Collection) SetLocally(locally bool)

SetLocally sets the locally flag, updating the builtin args.

func (*Collection) SetOrg 

func (c *Collection) SetOrg(org string)

SetOrg sets the organization name.

func (*Collection) SetOverriding 

func (c *Collection) SetOverriding(overriding *Scope)

SetOverriding sets the overriding args.

func (*Collection) SetPlatform 

func (c *Collection) SetPlatform(platr *platutil.Resolver)

SetPlatform sets the platform, updating the builtin args.

func (*Collection) SetProject 

func (c *Collection) SetProject(project string)

SetProject sets the project name.

func (*Collection) SortedOverridingVariables 

func (c *Collection) SortedOverridingVariables() []string

SortedOverridingVariables returns the overriding variable names in a sorted slice.

func (*Collection) SortedVariables 

func (c *Collection) SortedVariables(opts ...ScopeOpt) []string

SortedVariables returns the current variable names in a sorted slice.

func (*Collection) StackString 

func (c *Collection) StackString() string

StackString returns the stack as a string.

func (*Collection) TopOverriding 

func (c *Collection) TopOverriding() *Scope

TopOverriding returns a copy of the top-level overriding args, for use in commands that may need to re-parse the base target but have drastically different variable scopes.

func (*Collection) UnsetArg 

func (c *Collection) UnsetArg(name string)

UnsetArg removes an arg if it exists.

func (*Collection) UpdateVar 

func (c *Collection) UpdateVar(name, value string, pncvf ProcessNonConstantVariableFunc) (retErr error)

UpdateVar updates the value of an existing variable. It will override the value of the variable, regardless of where the value was previously defined.

It returns ErrVarNotFound if the variable was not found.

type DeclareOpt 

type DeclareOpt func(declarePrefs) declarePrefs

DeclareOpt is an option function for declaring variables.

func AsArg 

func AsArg() DeclareOpt

AsArg is an option function to declare an argument.

func AsGlobal 

func AsGlobal() DeclareOpt

AsGlobal is an option function to declare a global variable.

func WithPNCVFunc 

func WithPNCVFunc(f ProcessNonConstantVariableFunc) DeclareOpt

WithPNCVFunc is an option function to apply a ProcessNonConstantVariableFunc to ARGs. This supports deprecated functionality and is never used in Earthfiles with `VERSION 0.7` and higher.

func WithValue 

func WithValue(val string) DeclareOpt

WithValue is an option function for setting a variable's value. For ARGs, this is only the default value - it can be overridden when calling a target at the CLI.

type DefaultArgs 

type DefaultArgs struct {
	EarthlyVersion  string
	EarthlyBuildSha string
}

DefaultArgs contains additional builtin ARG values which need to be passed in from outside of the scope of this package.

type NewCollectionOpt 

type NewCollectionOpt struct {
	PlatformResolver *platutil.Resolver
	GitMeta          *gitutil.GitMetadata
	OverridingVars   *Scope
	AssignedVars     *Scope
	Features         *features.Features
	GlobalImports    map[string]domain.ImportTrackerVal
	NativePlatform   specs.Platform
	Target           domain.Target
	BuiltinArgs      DefaultArgs
	Console          conslogging.ConsoleLogger
	Push             bool
	CI               bool
}

NewCollectionOpt contains supported arguments which the `NewCollection` function may accept.

type ProcessNonConstantVariableFunc 

type ProcessNonConstantVariableFunc func(name string, expression string) (value string, argIndex int, err error)

ProcessNonConstantVariableFunc is a function which takes in an expression and turns it into a state, target input and arg index.

type Scope 

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

Scope represents a variable scope.

func BuiltinArgs 

func BuiltinArgs(
	target domain.Target,
	platr *platutil.Resolver,
	gitMeta *gitutil.GitMetadata,
	defaultArgs DefaultArgs,
	ftrs *features.Features,
	push, ci bool,
) *Scope

BuiltinArgs returns a scope containing the builtin args.

func CombineScopes 

func CombineScopes(scopes ...*Scope) *Scope

CombineScopes combines all the variables across all scopes, with the following precedence:

1. Active variables 2. Inactive variables 3. All other things equal, left-most scopes have precedence.

func CombineScopesInactive 

func CombineScopesInactive(scopes ...*Scope) *Scope

CombineScopesInactive combines all scopes (leaving all variables inactive), with left-most scope having precedence.

func NewScope 

func NewScope() *Scope

NewScope creates a new variable scope.

func ParseArgs 

func ParseArgs(args []string, pncvf ProcessNonConstantVariableFunc, current *Collection) (*Scope, error)

ParseArgs parses args passed as --build-arg to an Earthly command, such as BUILD or FROM.

func ParseCommandLineArgs 

func ParseCommandLineArgs(args []string) (*Scope, error)

ParseCommandLineArgs parses a slice of old build args (the ones passed via --build-arg) and returns a new scope.

func ParseEnvVars 

func ParseEnvVars(envVars []string) *Scope

ParseEnvVars parses env vars from a slice of strings of the form "key=value".

func RemoveReservedArgsFromScope 

func RemoveReservedArgsFromScope(scope *Scope) *Scope

RemoveReservedArgsFromScope returns a new scope omits any builtin arguments.

func (*Scope) Add 

func (s *Scope) Add(name, value string, opts ...ScopeOpt) bool

Add sets a variable to a value within this scope. It returns true if the value was set.

func (*Scope) BuildArgs 

func (s *Scope) BuildArgs(opts ...ScopeOpt) []string

BuildArgs returns s as a slice of build args, as they would have been passed in originally at the CLI or in a BUILD command.

func (*Scope) Clone 

func (s *Scope) Clone() *Scope

Clone returns a copy of the scope.

func (*Scope) DebugString 

func (s *Scope) DebugString() string

DebugString returns a string that can be printed while debugging.

func (*Scope) Get 

func (s *Scope) Get(name string, opts ...ScopeOpt) (string, bool)

Get gets a variable by name.

func (*Scope) Map 

func (s *Scope) Map(opts ...ScopeOpt) map[string]string

Map returns a name->value variable map of variables in this scope.

func (*Scope) Remove 

func (s *Scope) Remove(name string)

Remove removes a variable from the scope.

func (*Scope) Sorted 

func (s *Scope) Sorted(opts ...ScopeOpt) []string

Sorted returns a sorted list of variable names in this Scope.

type ScopeOpt 

type ScopeOpt func(scopeOpts) scopeOpts

ScopeOpt is an option function for setting flags when adding to or getting from a Scope.

func NoOverride 

func NoOverride() ScopeOpt

NoOverride only applies to Add. When passed to Add, NoOverride will prevent Add from overriding an existing value.

This will also prevent Add from applying other opts to the existing variable, so if the caller wishes to set options on the existing value, they should update the value on a false return from Add.

func WithActive 

func WithActive() ScopeOpt

WithActive is a ScopeOpt for active variables. When passed to Add, it sets the variable to active; when passed to Get or Map, it causes them to only return active variables.

Source Files

View all Source files

Directories

Path Synopsis

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.