Documentation
¶
Overview ¶
Package expr evaluates the expressions and {{ }} templates of a workflow.
Index ¶
- func CallsTemplate(v any) bool
- func Parse(input string) error
- func Reads(input, name string) [][]string
- func ReadsNothing(input string) bool
- func Refs(v any, name string) (keys []string, dynamic bool)
- func ReplaceTemplates(s, repl string) string
- func TemplateExprs(s string) []string
- type Expr
- func (e *Expr) Eval(input string, env any) (any, error)
- func (e *Expr) EvalOrEvalTemplate(input string, env any) (string, error)
- func (e *Expr) EvalTemplate(input string, env any) (string, error)
- func (e *Expr) EvalTemplateMap(input map[string]any, env any) (map[string]any, error)
- func (e *Expr) EvalTemplateWithTypePreservation(input string, env any) (any, error)
- func (e *Expr) Options(env any) []ex.Option
- type FieldError
- type TemplateError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CallsTemplate ¶ added in v1.19.0
CallsTemplate reports whether a template in v calls template, whose argument is evaluated as templates once it runs, so that what it reads cannot be known before then. v is as Refs takes it.
func Parse ¶ added in v1.20.0
Parse reports whether input is an expression that parses, without evaluating it, so that a workflow can be checked before it runs.
func Reads ¶ added in v1.20.0
Reads returns the constant keys that input, an expression, reads from the object name, as chains: outputs.auth.token is read as [auth token], and as [auth] too. A key read in a way that cannot be known before it runs, such as name[k], is not returned. An expression that does not parse reads nothing here.
func ReadsNothing ¶ added in v1.20.0
ReadsNothing reports whether input, an expression that parses, reads no variable, so that it evaluates the same whatever it is evaluated against, as true or 1 == 1 does. A function it calls, such as now(), is not a variable.
func Refs ¶ added in v1.18.0
Refs returns the names that the templates in v read from the object name, as name.key or name['key']. v is a string, or a map or array of them at any depth, as a value under vars is. dynamic is true when a template reads the object in a way whose key cannot be known before it runs, such as name[k] or the object as a whole, so that it may read any key. keys come in the order they are first read, a map's values in the order of its sorted keys.
An expression that does not parse reads nothing here; evaluating it reports the error.
func ReplaceTemplates ¶ added in v1.24.0
ReplaceTemplates returns s with repl in place of each {{ }} template in it, for what is written around the templates to be read without them.
func TemplateExprs ¶ added in v1.20.0
TemplateExprs returns the expressions of the {{ }} templates in s, in the order they come.
Types ¶
type Expr ¶
type Expr struct {
// BeforeTemplate, when it is set, is called with the text template() is
// about to expand, at any depth. An error it returns stops the
// evaluation, and is found in the error returned with errors.As.
BeforeTemplate func(text string) error
// contains filtered or unexported fields
}
Expr evaluates expressions and templates against an environment such as a step's context.
func (*Expr) EvalOrEvalTemplate ¶
func (*Expr) EvalTemplate ¶
EvalTemplate replaces each {{ }} template in input with the value of its expression. A template that does not compile or fails to run is an error naming the template, and no string is returned: a value with the error written into it would otherwise be sent on, as a URL or a header, as if it were right.
func (*Expr) EvalTemplateMap ¶
EvalTemplateMap evaluates every template in the keys and values of input, at any depth, keeping the type of a value that is a single template and evaluating a key as text. The errors of all the keys and values that could not be evaluated are joined, each as a *FieldError naming the value by its keys as written. A key that comes to the same key as another is an error too. The map is returned with the errors, so that a caller can still see what could be evaluated, such as credentials to hide from the errors: it holds nil where a value could not be evaluated, and leaves out a key that could not be, or that came to a key taken.
func (*Expr) EvalTemplateWithTypePreservation ¶
func (*Expr) Options ¶
Options builds the expr options used to compile every workflow expression.
Two guards that used to live here have been removed because neither did anything. ex.DisableBuiltin had no effect on all / any / one / filter / map / count: expr's parser recognises those as predicate builtins before it looks at the disabled set (parser.go, the `predicates` table), so the calls were dead and the functions have always been reachable. A per-key blocklist that filtered the environment was equally inert, because the filtered copy only ever reached the type checker while ex.Run receives the caller's env, and enforcing it would have broken the documented way of reading credentials into `vars`.
What still bounds an expression is the length check in validateExpression, the evaluation timeout in executeWithTimeout, and the argument limits on the functions registered below.
type FieldError ¶ added in v1.18.0
type FieldError struct {
Path string
// EvaluatedPath is Path with the keys that hold templates as they were
// evaluated, which is what tells a value such as a header named by a
// template apart. It is empty where it is not known.
EvaluatedPath string
Err error
}
FieldError is an error in the value under a key of a map evaluated by EvalTemplateMap. Path names the value from the top of that map, as in headers.authorization or items[0].name.
func (*FieldError) Error ¶ added in v1.18.0
func (e *FieldError) Error() string
func (*FieldError) Unwrap ¶ added in v1.18.0
func (e *FieldError) Unwrap() error
type TemplateError ¶ added in v1.18.0
type TemplateError struct {
Template string // The template as written, braces included
Err error // Why it could not be evaluated
}
TemplateError is a {{ }} template that could not be evaluated.
func (*TemplateError) Error ¶ added in v1.18.0
func (e *TemplateError) Error() string
func (*TemplateError) Unwrap ¶ added in v1.18.0
func (e *TemplateError) Unwrap() error
Source Files