Package dev.cel.common

Class CelOptions.Builder

  • Enclosing class:
    CelOptions
    public abstract static class CelOptions.Builder
extends java.lang.Object
    Builder for configuring the CelOptions.

    • Method Detail

      • enableReservedIds

        public abstract CelOptions.Builder enableReservedIds​(boolean value)
        Check for use of reserved identifiers during parsing.

        See the language spec for a list of reserved identifiers.

      • enableOptionalSyntax

        public abstract CelOptions.Builder enableOptionalSyntax​(boolean value)
        EnableOptionalSyntax enables syntax for optional field and index selection (e.g: msg.?field).

        Note: This option is automatically enabled for the parser by adding CelOptionalLibrary to the environment.

      • maxExpressionCodePointSize

        public abstract CelOptions.Builder maxExpressionCodePointSize​(int value)
        Set a limit on the size of the expression string which may be parsed in terms of the number of code points contained within the string.

      • maxParseErrorRecoveryLimit

        public abstract CelOptions.Builder maxParseErrorRecoveryLimit​(int value)
        Limit the number of error recovery attempts which may be made by the parser for a given syntax error before terminating the parse completely.

      • maxParseRecursionDepth

        public abstract CelOptions.Builder maxParseRecursionDepth​(int value)
        Limit the amount of recursion within parse expressions.

      • populateMacroCalls

        public abstract CelOptions.Builder populateMacroCalls​(boolean value)
        Populate macro_calls map in source_info with macro calls parsed from the expression.

      • retainRepeatedUnaryOperators

        public abstract CelOptions.Builder retainRepeatedUnaryOperators​(boolean value)
        Retain all invocations of unary '-' and '!' that occur in source in the abstract syntax.

        By default the parser collapses towers of repeated unary '-' and '!' into zero or one instance by assuming these operators to be inverses of themselves. This behavior may not always be desirable.

      • retainUnbalancedLogicalExpressions

        public abstract CelOptions.Builder retainUnbalancedLogicalExpressions​(boolean value)
        Retain the original grouping of logical connectives '&&' and '||' without attempting to rebalance them in the abstract syntax.

        The default rebalancing can reduce the overall nesting depth of the generated protos representing abstract syntax, but it relies on associativity of the operations themselves. This behavior may not always be desirable.

      • enableCompileTimeOverloadResolution

        public abstract CelOptions.Builder enableCompileTimeOverloadResolution​(boolean value)
        Require overloads to resolve (narrow to a single candidate) during type checking.

        This eliminates run-time overload dispatch and avoids implicit coercions of the result type to type dyn. However, this configuration should only be used if your application is not handling any form of dynamic data such as JSON or google.protobuf.Any.

      • enableHomogeneousLiterals

        public abstract CelOptions.Builder enableHomogeneousLiterals​(boolean value)
        During type checking require list-, and map literals to be type-homogeneous in their element-, key-, and value types, respectively.

        Without this flag one can use type-mismatched elements, keys, and values, and the type checker will implicitly coerce them to type dyn.

        This flag is recommended for all new uses of CEL.

      • enableTimestampEpoch

        public abstract CelOptions.Builder enableTimestampEpoch​(boolean value)
        Enable the int64_to_timestamp overload which creates a timestamp from Uxix epoch seconds.

        This option will be automatically enabled after a sufficient period of time has elapsed to ensure that all runtimes support the implementation.

        TODO: Remove this feature once it has been auto-enabled.

      • enableHeterogeneousNumericComparisons

        public abstract CelOptions.Builder enableHeterogeneousNumericComparisons​(boolean value)
        Enable the less_equals_double_int64 and other cross-type numeric comparisons for double, int64, and uint64 values.

        This feature adds the declarations for these overloads to the CEL standard environment, but the runtime functions are enabled by default.

        TODO: Remove this feature once it has been auto-enabled.

      • enableNamespacedDeclarations

        @Deprecated
public abstract CelOptions.Builder enableNamespacedDeclarations​(boolean value)
        Deprecated.
        This will be removed in the future. Please update your codebase to not rely on existence of certain expression nodes that would be collapsed/removed with this feature enabled.
        Enables the usage of namespaced functions and identifiers. This causes the type-checker to rewrite the AST to support namespacing (e.g: a field selector of form `namespace.msg.field` gets rewritten as a fully qualified identifier name of `namespace.msg.field`).

        TODO: Remove this feature once it has been auto-enabled.

      • disableCelStandardEquality

        public abstract CelOptions.Builder disableCelStandardEquality​(boolean value)
        Disable standard CEL equality in favor of the legacy Java equality calls for (in)equality tests.

        This feature is how the legacy CEL-Java APIs were originally configured, and in most cases will yield identical results to CEL equality, with the exception that equality between well-known protobuf types (wrapper types, protobuf.Value, protobuf.Any) may not compare correctly to simple and aggregate CEL types.

        Additionally, Java equality across numeric types such as double and long, will be trivially false, whereas CEL equality will compare the values as though they exist on a continuous number line.

      • enableRegexPartialMatch

        public abstract CelOptions.Builder enableRegexPartialMatch​(boolean value)
        Treat regex matches calls as substring (unanchored) match patterns.

        The default treatment for pattern matching within RE2 is full match within Java; however, the CEL standard specifies that the matches() function is a substring match.

      • enableUnsignedComparisonAndArithmeticIsUnsigned

        public abstract CelOptions.Builder enableUnsignedComparisonAndArithmeticIsUnsigned​(boolean value)
        Treat unsigned integers as unsigned when doing arithmetic and comparisons.

        Prior to turning on this feature, attempts to perform arithmetic or comparisons on unsigned integers larger than 2^63-1 may result in a runtime exception in the form of an IllegalArgumentException.

      • enableUnsignedLongs

        public abstract CelOptions.Builder enableUnsignedLongs​(boolean value)
        Use UnsignedLong values to represent unsigned integers within CEL instead of the nearest Java equivalent of Long.

      • enableProtoDifferencerEquality

        public abstract CelOptions.Builder enableProtoDifferencerEquality​(boolean value)
        Perform equality using ProtoEquality proto equality.

        CEL's alternative implementation to the Message#equals comes with a few key differences:

        • NaN is not equal to itself.
        • Any values are unpacked before comparison.
        • If two Any values cannot be unpacked, they are compared by bytes.

      • errorOnDuplicateMapKeys

        public abstract CelOptions.Builder errorOnDuplicateMapKeys​(boolean value)
        Throw errors on duplicate keys in map literals.

      • errorOnIntWrap

        public abstract CelOptions.Builder errorOnIntWrap​(boolean value)
        Throw errors when ints or uints wrap.

        Prior to this feature, int and uint arithmetic wrapped, i.e. was coerced into range via mod 2^64. The spec settled on throwing an error instead. Note that this makes arithmetic non- associative.

      • resolveTypeDependencies

        public abstract CelOptions.Builder resolveTypeDependencies​(boolean value)
        Enable or disable the resolution of Descriptor type dependencies as part of the CEL environment setup. Defaults to disabled.

        Disabling this feature should only be done when you know that only the types provided will be referenced within the CEL expression. This means that either the type set provided was complete, or that the type set is only what is referenced within expressions.

      • enableUnknownTracking

        public abstract CelOptions.Builder enableUnknownTracking​(boolean value)
        Enable tracking unknown attributes and function invocations encountered during evaluation.

        When enabled, the evaluator will track unknown attributes (leaf values in the activations) and function results (a particular invocation that was identified as unknown).

      • comprehensionMaxIterations

        public abstract CelOptions.Builder comprehensionMaxIterations​(int value)
        Limit the total number of iterations permitted within comprehension loops.

        If the limit is reached, then an evaluation exception will be thrown. This limit also affects nested comprehension interactions as well.

        A negative value will disable max iteration checks.

        Note: comprehension limits are not supported within the async CEL interpreter.