Documentation
¶
Overview ¶
Package cel defines the top-level interface for the Common Expression Language (CEL).
CEL is a non-Turing complete expression language designed to parse, check, and evaluate expressions against user-defined environments.
Example ¶
// Create the CEL environment with declarations for the input attributes and
// the desired extension functions. In many cases the desired functionality will
// be present in a built-in function.
decls := Declarations(
// Identifiers used within this expression.
decls.NewIdent("i", decls.String, nil),
decls.NewIdent("you", decls.String, nil),
// Function to generate a greeting from one person to another.
// i.greet(you)
decls.NewFunction("greet",
decls.NewInstanceOverload("greet_string_string",
[]*exprpb.Type{decls.String, decls.String},
decls.String)))
e, err := NewEnv(decls)
if err != nil {
log.Fatalf("environment creation error: %s\n", err)
}
// Parse and check the expression.
p, iss := e.Parse("i.greet(you)")
if iss != nil && iss.Err() != nil {
log.Fatalln(iss.Err())
}
c, iss := e.Check(p)
if iss != nil && iss.Err() != nil {
log.Fatalln(iss.Err())
}
// Create the program.
funcs := Functions(
&functions.Overload{
Operator: "greet",
Binary: func(lhs ref.Val, rhs ref.Val) ref.Val {
return types.String(
fmt.Sprintf("Hello %s! Nice to meet you, I'm %s.\n", rhs, lhs))
}})
prg, err := e.Program(c, funcs)
if err != nil {
log.Fatalf("program creation error: %s\n", err)
}
// Evaluate the program against some inputs. Note: the details return is not used.
out, _, err := prg.Eval(Vars(map[string]interface{}{
// Native values are converted to CEL values under the covers.
"i": "CEL",
// Values may also be lazily supplied.
"you": func() ref.Val { return types.String("world") },
}))
if err != nil {
log.Fatalf("runtime error: %s\n", err)
}
fmt.Println(out)
Output: Hello world! Nice to meet you, I'm CEL.
Index ¶
- func AstToCheckedExpr(a Ast) (*exprpb.CheckedExpr, error)
- func AstToParsedExpr(a Ast) (*exprpb.ParsedExpr, error)
- func NoVars() interpreter.Activation
- func Vars(vars map[string]interface{}) interpreter.Activation
- type Ast
- type Env
- type EnvOption
- func ClearBuiltIns() EnvOption
- func ClearMacros() EnvOption
- func Container(pkg string) EnvOption
- func CustomTypeProvider(provider ref.TypeProvider) EnvOption
- func Declarations(decls ...*exprpb.Decl) EnvOption
- func Macros(macros ...parser.Macro) EnvOption
- func Types(addTypes ...interface{}) EnvOption
- type EvalDetails
- type EvalOption
- type Issues
- type Program
- type ProgramOption
- type Source
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AstToCheckedExpr ¶
func AstToCheckedExpr(a Ast) (*exprpb.CheckedExpr, error)
AstToCheckedExpr converts an Ast to an protobuf CheckedExpr value.
If the Ast.IsChecked() returns false, this conversion method will return an error.
func AstToParsedExpr ¶
func AstToParsedExpr(a Ast) (*exprpb.ParsedExpr, error)
AstToParsedExpr converts an Ast to an protobuf ParsedExpr value.
func Vars ¶
func Vars(vars map[string]interface{}) interpreter.Activation
Vars takes an input map of variables and returns an Activation.
Types ¶
type Ast ¶
type Ast interface {
// Expr returns the proto serializable instance of the parsed/checked expression.
Expr() *exprpb.Expr
// IsChecked returns whether the Ast value has been successfully type-checked.
IsChecked() bool
// ResultType returns the output type of the expression if the Ast has been type-checked,
// else returns decls.Dyn as the parse step cannot infer the type.
ResultType() *exprpb.Type
// Source returns a view of the input used to create the Ast. This source may be complete or
// constructed from the SourceInfo.
Source() Source
// SourceInfo returns character offset and newling position information about expression
// elements.
SourceInfo() *exprpb.SourceInfo
}
Ast interface representing the checked or unchecked expression, its source, and related metadata such as source position information.
func CheckedExprToAst ¶
func CheckedExprToAst(checkedExpr *exprpb.CheckedExpr) Ast
CheckedExprToAst converts a checked expression proto message to an Ast.
func ParsedExprToAst ¶
func ParsedExprToAst(parsedExpr *exprpb.ParsedExpr) Ast
ParsedExprToAst converts a parsed expression proto message to an Ast.
type Env ¶
type Env interface {
// Check performs type-checking on the input Ast and yields a checked Ast and/or set of Issues.
//
// Checking has failed if the returned Issues value and its Issues.Err() value is non-nil.
// Issues should be inspected if they are non-nil, but may not represent a fatal error.
//
// It is possible to have both non-nil Ast and Issues values returned from this call: however,
// the mere presence of an Ast does not imply that it is valid for use.
Check(ast Ast) (Ast, Issues)
// Parse parses the input expression value `txt` to a Ast and/or a set of Issues.
//
// Parsing has failed if the returned Issues value and its Issues.Err() value is non-nil.
// Issues should be inspected if they are non-nil, but may not represent a fatal error.
//
// It is possible to have both non-nil Ast and Issues values returned from this call; however,
// the mere presence of an Ast does not imply that it is valid for use.
Parse(txt string) (Ast, Issues)
// Program generates an evaluable instance of the Ast within the environment (Env).
Program(ast Ast, opts ...ProgramOption) (Program, error)
}
Env defines functions for parsing and type-checking expressions against a set of user-defined constants, variables, and functions. The Env interface also defines a method for generating evaluable programs from parsed and checked Asts.
type EnvOption ¶
type EnvOption func(e *env) (*env, error)
EnvOption is a functional interface for configuring the environment.
func ClearBuiltIns ¶
func ClearBuiltIns() EnvOption
ClearBuiltIns option removes all standard types, operators, and macros from the environment.
Note: This option must be specified before Declarations and/or Macros if used together.
func ClearMacros ¶
func ClearMacros() EnvOption
ClearMacros options clears all parser macros.
Clearing macros will ensure CEL expressions can only contain linear evaluation paths, as comprehensions such as `all` and `exists` are enabled only via macros.
Note: This option is a no-op when used with ClearBuiltIns, and must be used before Macros if used together.
func Container ¶
Container sets the container for resolving variable names. Defaults to an empty container.
If all references within an expression are relative to a protocol buffer package, then specifying a container of `google.type` would make it possible to write expressions such as `Expr{expression: 'a < b'}` instead of having to write `google.type.Expr{...}`.
func CustomTypeProvider ¶
func CustomTypeProvider(provider ref.TypeProvider) EnvOption
CustomTypeProvider swaps the default ref.TypeProvider implementation with a custom one.
Note: This option must be specified before the Types option when used together.
func Declarations ¶
Declarations option extends the declaration set configured in the environment.
Note: This option must be specified after ClearBuiltIns if both are used together.
func Macros ¶
Macros option extends the macro set configured in the environment.
Note: This option must be specified after ClearBuiltIns and/or ClearMacros if used together.
func Types ¶
func Types(addTypes ...interface{}) EnvOption
Types adds one or more type declarations to the environment, allowing for construction of type-literals whose definitions are included in the common expression built-in set.
The input types may either be instances of `proto.Message` or `ref.Type`. Any other type provided to this option will result in an error.
Well-known protobuf types within the `google.protobuf.*` package are included in the standard environment by default.
Note: This option must be specified after the CustomTypeProvider option when used together.
type EvalDetails ¶
type EvalDetails interface {
// State of the evaluation, non-nil if the OptTrackState or OptExhaustiveEval is specified
// within EvalOptions.
State() interpreter.EvalState
}
EvalDetails holds additional information observed during the Eval() call.
type EvalOption ¶
type EvalOption int
EvalOption indicates an evaluation option that may affect the evaluation behavior or information in the output result.
const ( // OptTrackState will cause the runtime to return an immutable EvalState value in the Result. OptTrackState EvalOption = 1 << iota // OptExhaustiveEval causes the runtime to disable short-circuits and track state. OptExhaustiveEval EvalOption = 1<<iota | OptTrackState // OptFoldConstants evaluates functions and operators with constants as arguments at program // creation time. This flag is useful when the expression will be evaluated repeatedly against // a series of different inputs. OptFoldConstants EvalOption = 1 << iota )
type Issues ¶
type Issues interface {
fmt.Stringer
// Err returns an error value if the issues list contains one or more errors.
Err() error
// Errors returns the collection of errors encountered in more granular detail.
Errors() []common.Error
}
Issues defines methods for inspecting the error details of parse and check calls.
Note: in the future, non-fatal warnings and notices may be inspectable via the Issues interface.
type Program ¶
type Program interface {
// Eval returns the result of an evaluation of the Ast and environment against the input vars.
//
// If the evaluation is an error, the result will be nil with a non-nil error.
//
// If the OptTrackState or OptExhaustiveEval is used, the EvalDetails response will be non-nil.
Eval(vars interpreter.Activation) (ref.Val, EvalDetails, error)
}
Program is an evaluable view of an Ast.
type ProgramOption ¶
type ProgramOption func(p *prog) (*prog, error)
ProgramOption is a functional interface for configuring evaluation bindings and behaviors.
func EvalOptions ¶
func EvalOptions(opts ...EvalOption) ProgramOption
EvalOptions sets one or more evaluation options which may affect the evaluation or Result.
func Functions ¶
func Functions(funcs ...*functions.Overload) ProgramOption
Functions adds function overloads that extend or override the set of CEL built-ins.
func Globals ¶
func Globals(vars interpreter.Activation) ProgramOption
Globals sets the global variable values for a given program. These values may be shadowed within the Activation value provided to the Eval() function.
Source Files