Documentation ¶
Overview ¶
Package ext contains CEL extension libraries where each library defines a related set of constants, functions, macros, or other configuration settings which may not be covered by the core CEL spec.
Index ¶
- func Bindings() cel.EnvOption
- func Encoders() cel.EnvOption
- func FormatString(arg ref.Val, locale string) (string, error)
- func Lists() cel.EnvOption
- func Math() cel.EnvOption
- func NativeTypes(args ...any) cel.EnvOption
- func NewSetMembershipOptimizer() (cel.ASTOptimizer, error)
- func Protos() cel.EnvOption
- func Sets() cel.EnvOption
- func Strings(options ...StringsOption) cel.EnvOption
- type MathOption
- type NativeTypesOption
- type StringsOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bindings ¶ added in v0.15.0
Bindings returns a cel.EnvOption to configure support for local variable bindings in expressions.
Cel.Bind ¶
Binds a simple identifier to an initialization expression which may be used in a subsequenct result expression. Bindings may also be nested within each other.
cel.bind(<varName>, <initExpr>, <resultExpr>)
Examples:
cel.bind(a, 'hello', cel.bind(b, 'world', a + b + b + a)) // "helloworldworldhello" // Avoid a list allocation within the exists comprehension. cel.bind(valid_values, [a, b, c], [d, e, f].exists(elem, elem in valid_values))
Local bindings are not guaranteed to be evaluated before use.
func Encoders ¶ added in v0.6.0
Encoders returns a cel.EnvOption to configure extended functions for string, byte, and object encodings.
Base64.Decode ¶
Decodes base64-encoded string to bytes.
This function will return an error if the string input is not base64-encoded.
base64.decode(<string>) -> <bytes>
Examples:
base64.decode('aGVsbG8=') // return b'hello' base64.decode('aGVsbG8') // error
Base64.Encode ¶
Encodes bytes to a base64-encoded string.
base64.encode(<bytes>) -> <string>
Examples:
base64.encode(b'hello') // return b'aGVsbG8='
func FormatString ¶ added in v0.14.0
FormatString returns the string representation of a CEL value.
It is used to implement the %s specifier in the (string).format() extension function.
func Lists ¶ added in v0.17.0
Lists returns a cel.EnvOption to configure extended functions for list manipulation. As a general note, all indices are zero-based. # Slice
Returns a new sub-list using the indexes provided.
<list>.slice(<int>, <int>) -> <list>
Examples:
[1,2,3,4].slice(1, 3) // return [2, 3] [1,2,3,4].slice(2, 4) // return [3 ,4]
func Math ¶ added in v0.13.0
Math returns a cel.EnvOption to configure namespaced math helper macros and functions.
Note, all macros use the 'math' namespace; however, at the time of macro expansion the namespace looks just like any other identifier. If you are currently using a variable named 'math', the macro will likely work just as intended; however, there is some chance for collision.
Math.Greatest ¶
Returns the greatest valued number present in the arguments to the macro.
Greatest is a variable argument count macro which must take at least one argument. Simple numeric and list literals are supported as valid argument types; however, other literals will be flagged as errors during macro expansion. If the argument expression does not resolve to a numeric or list(numeric) type during type-checking, or during runtime then an error will be produced. If a list argument is empty, this too will produce an error.
math.greatest(<arg>, ...) -> <double|int|uint>
Examples:
math.greatest(1) // 1 math.greatest(1u, 2u) // 2u math.greatest(-42.0, -21.5, -100.0) // -21.5 math.greatest([-42.0, -21.5, -100.0]) // -21.5 math.greatest(numbers) // numbers must be list(numeric) math.greatest() // parse error math.greatest('string') // parse error math.greatest(a, b) // check-time error if a or b is non-numeric math.greatest(dyn('string')) // runtime error
Math.Least ¶
Returns the least valued number present in the arguments to the macro.
Least is a variable argument count macro which must take at least one argument. Simple numeric and list literals are supported as valid argument types; however, other literals will be flagged as errors during macro expansion. If the argument expression does not resolve to a numeric or list(numeric) type during type-checking, or during runtime then an error will be produced. If a list argument is empty, this too will produce an error.
math.least(<arg>, ...) -> <double|int|uint>
Examples:
math.least(1) // 1 math.least(1u, 2u) // 1u math.least(-42.0, -21.5, -100.0) // -100.0 math.least([-42.0, -21.5, -100.0]) // -100.0 math.least(numbers) // numbers must be list(numeric) math.least() // parse error math.least('string') // parse error math.least(a, b) // check-time error if a or b is non-numeric math.least(dyn('string')) // runtime error
Math.BitOr ¶
Introduced at version: 1
Performs a bitwise-OR operation over two int or uint values.
math.bitOr(<int>, <int>) -> <int> math.bitOr(<uint>, <uint>) -> <uint>
Examples:
math.bitOr(1u, 2u) // returns 3u math.bitOr(-2, -4) // returns -2
Math.BitAnd ¶
Introduced at version: 1
Performs a bitwise-AND operation over two int or uint values.
math.bitAnd(<int>, <int>) -> <int> math.bitAnd(<uint>, <uint>) -> <uint>
Examples:
math.bitAnd(3u, 2u) // return 2u math.bitAnd(3, 5) // returns 3 math.bitAnd(-3, -5) // returns -7
Math.BitXor ¶
Introduced at version: 1
math.bitXor(<int>, <int>) -> <int> math.bitXor(<uint>, <uint>) -> <uint>
Performs a bitwise-XOR operation over two int or uint values.
Examples:
math.bitXor(3u, 5u) // returns 6u math.bitXor(1, 3) // returns 2
Math.BitNot ¶
Introduced at version: 1
Function which accepts a single int or uint and performs a bitwise-NOT ones-complement of the given binary value.
math.bitNot(<int>) -> <int> math.bitNot(<uint>) -> <uint>
Examples
math.bitNot(1) // returns -1 math.bitNot(-1) // return 0 math.bitNot(0u) // returns 18446744073709551615u
Math.BitShiftLeft ¶
Introduced at version: 1
Perform a left shift of bits on the first parameter, by the amount of bits specified in the second parameter. The first parameter is either a uint or an int. The second parameter must be an int.
When the second parameter is 64 or greater, 0 will be always be returned since the number of bits shifted is greater than or equal to the total bit length of the number being shifted. Negative valued bit shifts will result in a runtime error.
math.bitShiftLeft(<int>, <int>) -> <int> math.bitShiftLeft(<uint>, <int>) -> <uint>
Examples
math.bitShiftLeft(1, 2) // returns 4 math.bitShiftLeft(-1, 2) // returns -4 math.bitShiftLeft(1u, 2) // return 4u math.bitShiftLeft(1u, 200) // returns 0u
Math.BitShiftRight ¶
Introduced at version: 1
Perform a right shift of bits on the first parameter, by the amount of bits specified in the second parameter. The first parameter is either a uint or an int. The second parameter must be an int.
When the second parameter is 64 or greater, 0 will always be returned since the number of bits shifted is greater than or equal to the total bit length of the number being shifted. Negative valued bit shifts will result in a runtime error.
The sign bit extension will not be preserved for this operation: vacant bits on the left are filled with 0.
math.bitShiftRight(<int>, <int>) -> <int> math.bitShiftRight(<uint>, <int>) -> <uint>
Examples
math.bitShiftRight(1024, 2) // returns 256 math.bitShiftRight(1024u, 2) // returns 256u math.bitShiftRight(1024u, 64) // returns 0u
Math.Ceil ¶
Introduced at version: 1
Compute the ceiling of a double value.
math.ceil(<double>) -> <double>
Examples:
math.ceil(1.2) // returns 2.0 math.ceil(-1.2) // returns -1.0
Math.Floor ¶
Introduced at version: 1
Compute the floor of a double value.
math.floor(<double>) -> <double>
Examples:
math.floor(1.2) // returns 1.0 math.floor(-1.2) // returns -2.0
Math.Round ¶
Introduced at version: 1
Rounds the double value to the nearest whole number with ties rounding away from zero, e.g. 1.5 -> 2.0, -1.5 -> -2.0.
math.round(<double>) -> <double>
Examples:
math.round(1.2) // returns 1.0 math.round(1.5) // returns 2.0 math.round(-1.5) // returns -2.0
Math.Trunc ¶
Introduced at version: 1
Truncates the fractional portion of the double value.
math.trunc(<double>) -> <double>
Examples:
math.trunc(-1.3) // returns -1.0 math.trunc(1.3) // returns 1.0
Math.Abs ¶
Introduced at version: 1
Returns the absolute value of the numeric type provided as input. If the value is NaN, the output is NaN. If the input is int64 min, the function will result in an overflow error.
math.abs(<double>) -> <double> math.abs(<int>) -> <int> math.abs(<uint>) -> <uint>
Examples:
math.abs(-1) // returns 1 math.abs(1) // returns 1 math.abs(-9223372036854775808) // overflow error
Math.Sign ¶
Introduced at version: 1
Returns the sign of the numeric type, either -1, 0, 1 as an int, double, or uint depending on the overload. For floating point values, if NaN is provided as input, the output is also NaN. The implementation does not differentiate between positive and negative zero.
math.sign(<double>) -> <double> math.sign(<int>) -> <int> math.sign(<uint>) -> <uint>
Examples:
math.sign(-42) // returns -1 math.sign(0) // returns 0 math.sign(42) // returns 1
Math.IsInf ¶
Introduced at version: 1
Returns true if the input double value is -Inf or +Inf.
math.isInf(<double>) -> <bool>
Examples:
math.isInf(1.0/0.0) // returns true math.isInf(1.2) // returns false
Math.IsNaN ¶
Introduced at version: 1
Returns true if the input double value is NaN, false otherwise.
math.isNaN(<double>) -> <bool>
Examples:
math.isNaN(0.0/0.0) // returns true math.isNaN(1.2) // returns false
Math.IsFinite ¶
Introduced at version: 1
Returns true if the value is a finite number. Equivalent in behavior to: !math.isNaN(double) && !math.isInf(double)
math.isFinite(<double>) -> <bool>
Examples:
math.isFinite(0.0/0.0) // returns false math.isFinite(1.2) // returns true
func NativeTypes ¶ added in v0.13.0
NativeTypes creates a type provider which uses reflect.Type and reflect.Value instances to produce type definitions that can be used within CEL.
All struct types in Go are exposed to CEL via their simple package name and struct type name:
```go package identity
type Account struct { ID int }
```
The type `identity.Account` would be exported to CEL using the same qualified name, e.g. `identity.Account{ID: 1234}` would create a new `Account` instance with the `ID` field populated.
Only exported fields are exposed via NativeTypes, and the type-mapping between Go and CEL is as follows:
| Go type | CEL type | |-------------------------------------|-----------| | bool | bool | | []byte | bytes | | float32, float64 | double | | int, int8, int16, int32, int64 | int | | string | string | | uint, uint8, uint16, uint32, uint64 | uint | | time.Duration | duration | | time.Time | timestamp | | array, slice | list | | map | map |
Please note, if you intend to configure support for proto messages in addition to native types, you will need to provide the protobuf types before the golang native types. The same advice holds if you are using custom type adapters and type providers. The native type provider composes over whichever type adapter and provider is configured in the cel.Env at the time that it is invoked.
There is also the possibility to rename the fields of native structs by setting the `cel` tag for fields you want to override. In order to enable this feature, pass in the `EnableStructTag` option. Here is an example to see it in action:
```go package identity
type Account struct { ID int OwnerName string `cel:"owner"` }
```
The `OwnerName` field is now accessible in CEL via `owner`, e.g. `identity.Account{owner: 'bob'}`. In case there are duplicated field names in the struct, an error will be returned.
func NewSetMembershipOptimizer ¶ added in v0.19.0
func NewSetMembershipOptimizer() (cel.ASTOptimizer, error)
NewSetMembershipOptimizer rewrites set membership tests using the `in` operator against a list of constant values of enum, int, uint, string, or boolean type into a set membership test against a map where the map keys are the elements of the list.
func Protos ¶ added in v0.13.0
Protos returns a cel.EnvOption to configure extended macros and functions for proto manipulation.
Note, all macros use the 'proto' namespace; however, at the time of macro expansion the namespace looks just like any other identifier. If you are currently using a variable named 'proto', the macro will likely work just as intended; however, there is some chance for collision.
Protos.GetExt ¶
Macro which generates a select expression that retrieves an extension field from the input proto2 syntax message. If the field is not set, the default value forthe extension field is returned according to safe-traversal semantics.
proto.getExt(<msg>, <fully.qualified.extension.name>) -> <field-type>
Examples:
proto.getExt(msg, google.expr.proto2.test.int32_ext) // returns int value
Protos.HasExt ¶
Macro which generates a test-only select expression that determines whether an extension field is set on a proto2 syntax message.
proto.hasExt(<msg>, <fully.qualified.extension.name>) -> <bool>
Examples:
proto.hasExt(msg, google.expr.proto2.test.int32_ext) // returns true || false
func Sets ¶ added in v0.15.0
Sets returns a cel.EnvOption to configure namespaced set relationship functions.
There is no set type within CEL, and while one may be introduced in the future, there are cases where a `list` type is known to behave like a set. For such cases, this library provides some basic functionality for determining set containment, equivalence, and intersection.
Sets.Contains ¶
Returns whether the first list argument contains all elements in the second list argument. The list may contain elements of any type and standard CEL equality is used to determine whether a value exists in both lists. If the second list is empty, the result will always return true.
sets.contains(list(T), list(T)) -> bool
Examples:
sets.contains([], []) // true sets.contains([], [1]) // false sets.contains([1, 2, 3, 4], [2, 3]) // true sets.contains([1, 2.0, 3u], [1.0, 2u, 3]) // true
Sets.Equivalent ¶
Returns whether the first and second list are set equivalent. Lists are set equivalent if for every item in the first list, there is an element in the second which is equal. The lists may not be of the same size as they do not guarantee the elements within them are unique, so size does not factor into the computation.
Examples:
sets.equivalent([], []) // true sets.equivalent([1], [1, 1]) // true sets.equivalent([1], [1u, 1.0]) // true sets.equivalent([1, 2, 3], [3u, 2.0, 1]) // true
Sets.Intersects ¶
Returns whether the first list has at least one element whose value is equal to an element in the second list. If either list is empty, the result will be false.
Examples:
sets.intersects([1], []) // false sets.intersects([1], [1, 2]) // true sets.intersects([[1], [2, 3]], [[1, 2], [2, 3.0]]) // true
func Strings ¶
func Strings(options ...StringsOption) cel.EnvOption
Strings returns a cel.EnvOption to configure extended functions for string manipulation. As a general note, all indices are zero-based.
CharAt ¶
Returns the character at the given position. If the position is negative, or greater than the length of the string, the function will produce an error:
<string>.charAt(<int>) -> <string>
Examples:
'hello'.charAt(4) // return 'o' 'hello'.charAt(5) // return '' 'hello'.charAt(-1) // error
Format ¶
Introduced at version: 1
Returns a new string with substitutions being performed, printf-style. The valid formatting clauses are:
`%s` - substitutes a string. This can also be used on bools, lists, maps, bytes, Duration and Timestamp, in addition to all numerical types (int, uint, and double). Note that the dot/period decimal separator will always be used when printing a list or map that contains a double, and that null can be passed (which results in the string "null") in addition to types. `%d` - substitutes an integer. `%f` - substitutes a double with fixed-point precision. The default precision is 6, but this can be adjusted. The strings `Infinity`, `-Infinity`, and `NaN` are also valid input for this clause. `%e` - substitutes a double in scientific notation. The default precision is 6, but this can be adjusted. `%b` - substitutes an integer with its equivalent binary string. Can also be used on bools. `%x` - substitutes an integer with its equivalent in hexadecimal, or if given a string or bytes, will output each character's equivalent in hexadecimal. `%X` - same as above, but with A-F capitalized. `%o` - substitutes an integer with its equivalent in octal.
<string>.format(<list>) -> <string>
Examples:
"this is a string: %s\nand an integer: %d".format(["str", 42]) // returns "this is a string: str\nand an integer: 42" "a double substituted with %%s: %s".format([64.2]) // returns "a double substituted with %s: 64.2" "string type: %s".format([type(string)]) // returns "string type: string" "timestamp: %s".format([timestamp("2023-02-03T23:31:20+00:00")]) // returns "timestamp: 2023-02-03T23:31:20Z" "duration: %s".format([duration("1h45m47s")]) // returns "duration: 6347s" "%f".format([3.14]) // returns "3.140000" "scientific notation: %e".format([2.71828]) // returns "scientific notation: 2.718280\u202f\u00d7\u202f10\u2070\u2070" "5 in binary: %b".format([5]), // returns "5 in binary; 101" "26 in hex: %x".format([26]), // returns "26 in hex: 1a" "26 in hex (uppercase): %X".format([26]) // returns "26 in hex (uppercase): 1A" "30 in octal: %o".format([30]) // returns "30 in octal: 36" "a map inside a list: %s".format([[1, 2, 3, {"a": "x", "b": "y", "c": "z"}]]) // returns "a map inside a list: [1, 2, 3, {"a":"x", "b":"y", "c":"d"}]" "true bool: %s - false bool: %s\nbinary bool: %b".format([true, false, true]) // returns "true bool: true - false bool: false\nbinary bool: 1"
Passing an incorrect type (a string to `%b`) is considered an error, as well as attempting to use more formatting clauses than there are arguments (`%d %d %d` while passing two ints, for instance). If compile-time checking is enabled, and the formatting string is a constant, and the argument list is a literal, then letting any arguments go unused/unformatted is also considered an error.
IndexOf ¶
Returns the integer index of the first occurrence of the search string. If the search string is not found the function returns -1.
The function also accepts an optional position from which to begin the substring search. If the substring is the empty string, the index where the search starts is returned (zero or custom).
<string>.indexOf(<string>) -> <int> <string>.indexOf(<string>, <int>) -> <int>
Examples:
'hello mellow'.indexOf('') // returns 0 'hello mellow'.indexOf('ello') // returns 1 'hello mellow'.indexOf('jello') // returns -1 'hello mellow'.indexOf('', 2) // returns 2 'hello mellow'.indexOf('ello', 2) // returns 7 'hello mellow'.indexOf('ello', 20) // error
Join ¶
Returns a new string where the elements of string list are concatenated.
The function also accepts an optional separator which is placed between elements in the resulting string.
<list<string>>.join() -> <string> <list<string>>.join(<string>) -> <string>
Examples:
['hello', 'mellow'].join() // returns 'hellomellow' ['hello', 'mellow'].join(' ') // returns 'hello mellow' [].join() // returns '' [].join('/') // returns ''
LastIndexOf ¶
Returns the integer index at the start of the last occurrence of the search string. If the search string is not found the function returns -1.
The function also accepts an optional position which represents the last index to be considered as the beginning of the substring match. If the substring is the empty string, the index where the search starts is returned (string length or custom).
<string>.lastIndexOf(<string>) -> <int> <string>.lastIndexOf(<string>, <int>) -> <int>
Examples:
'hello mellow'.lastIndexOf('') // returns 12 'hello mellow'.lastIndexOf('ello') // returns 7 'hello mellow'.lastIndexOf('jello') // returns -1 'hello mellow'.lastIndexOf('ello', 6) // returns 1 'hello mellow'.lastIndexOf('ello', -1) // error
LowerAscii ¶
Returns a new string where all ASCII characters are lower-cased.
This function does not perform Unicode case-mapping for characters outside the ASCII range.
<string>.lowerAscii() -> <string>
Examples:
'TacoCat'.lowerAscii() // returns 'tacocat' 'TacoCÆt Xii'.lowerAscii() // returns 'tacocÆt xii'
Strings.Quote ¶
Introduced in version: 1
Takes the given string and makes it safe to print (without any formatting due to escape sequences). If any invalid UTF-8 characters are encountered, they are replaced with \uFFFD.
strings.quote(<string>)
Examples:
strings.quote('single-quote with "double quote"') // returns '"single-quote with \"double quote\""' strings.quote("two escape sequences \a\n") // returns '"two escape sequences \\a\\n"'
Replace ¶
Returns a new string based on the target, which replaces the occurrences of a search string with a replacement string if present. The function accepts an optional limit on the number of substring replacements to be made.
When the replacement limit is 0, the result is the original string. When the limit is a negative number, the function behaves the same as replace all.
<string>.replace(<string>, <string>) -> <string> <string>.replace(<string>, <string>, <int>) -> <string>
Examples:
'hello hello'.replace('he', 'we') // returns 'wello wello' 'hello hello'.replace('he', 'we', -1) // returns 'wello wello' 'hello hello'.replace('he', 'we', 1) // returns 'wello hello' 'hello hello'.replace('he', 'we', 0) // returns 'hello hello' 'hello hello'.replace('', '_') // returns '_h_e_l_l_o_ _h_e_l_l_o_' 'hello hello'.replace('h', '') // returns 'ello ello'
Split ¶
Returns a list of strings split from the input by the given separator. The function accepts an optional argument specifying a limit on the number of substrings produced by the split.
When the split limit is 0, the result is an empty list. When the limit is 1, the result is the target string to split. When the limit is a negative number, the function behaves the same as split all.
<string>.split(<string>) -> <list<string>> <string>.split(<string>, <int>) -> <list<string>>
Examples:
'hello hello hello'.split(' ') // returns ['hello', 'hello', 'hello'] 'hello hello hello'.split(' ', 0) // returns [] 'hello hello hello'.split(' ', 1) // returns ['hello hello hello'] 'hello hello hello'.split(' ', 2) // returns ['hello', 'hello hello'] 'hello hello hello'.split(' ', -1) // returns ['hello', 'hello', 'hello']
Substring ¶
Returns the substring given a numeric range corresponding to character positions. Optionally may omit the trailing range for a substring from a given character position until the end of a string.
Character offsets are 0-based with an inclusive start range and exclusive end range. It is an error to specify an end range that is lower than the start range, or for either the start or end index to be negative or exceed the string length.
<string>.substring(<int>) -> <string> <string>.substring(<int>, <int>) -> <string>
Examples:
'tacocat'.substring(4) // returns 'cat' 'tacocat'.substring(0, 4) // returns 'taco' 'tacocat'.substring(-1) // error 'tacocat'.substring(2, 1) // error
Trim ¶
Returns a new string which removes the leading and trailing whitespace in the target string. The trim function uses the Unicode definition of whitespace which does not include the zero-width spaces. See: https://en.wikipedia.org/wiki/Whitespace_character#Unicode
<string>.trim() -> <string>
Examples:
' \ttrim\n '.trim() // returns 'trim'
UpperAscii ¶
Returns a new string where all ASCII characters are upper-cased.
This function does not perform Unicode case-mapping for characters outside the ASCII range.
<string>.upperAscii() -> <string>
Examples:
'TacoCat'.upperAscii() // returns 'TACOCAT' 'TacoCÆt Xii'.upperAscii() // returns 'TACOCÆT XII'
Reverse ¶
Introduced at version: 3
Returns a new string whose characters are the same as the target string, only formatted in reverse order. This function relies on converting strings to rune arrays in order to reverse
<string>.reverse() -> <string>
Examples:
'gums'.reverse() // returns 'smug' 'John Smith'.reverse() // returns 'htimS nhoJ'
Types ¶
type MathOption ¶ added in v0.21.0
type MathOption func(*mathLib) *mathLib
func MathVersion ¶ added in v0.21.0
func MathVersion(version uint32) MathOption
type NativeTypesOption ¶ added in v0.21.0
type NativeTypesOption func(*nativeTypeOptions) error
NativeTypesOption is a functional interface for configuring handling of native types.
func ParseStructTags ¶ added in v0.21.0
func ParseStructTags(enabled bool) NativeTypesOption
ParseStructTags configures if native types field names should be overridable by CEL struct tags.
type StringsOption ¶ added in v0.14.0
type StringsOption func(*stringLib) *stringLib
StringsOption is a functional interface for configuring the strings library.
func StringsLocale ¶ added in v0.14.0
func StringsLocale(locale string) StringsOption
StringsLocale configures the library with the given locale. The locale tag will be checked for validity at the time that EnvOptions are configured. If this option is not passed, string.format will behave as if en_US was passed as the locale.
func StringsValidateFormatCalls ¶ added in v0.17.2
func StringsValidateFormatCalls(value bool) StringsOption
StringsValidateFormatCalls validates type-checked ASTs to ensure that string.format() calls have valid formatting clauses and valid argument types for each clause.
Enabled by default.
func StringsVersion ¶ added in v0.14.0
func StringsVersion(version uint32) StringsOption
StringsVersion configures the version of the string library.
The version limits which functions are available. Only functions introduced below or equal to the given version included in the library. If this option is not set, all functions are available.
See the library documentation to determine which version a function was introduced. If the documentation does not state which version a function was introduced, it can be assumed to be introduced at version 0, when the library was first created.