Add versions to the 'optional' library to gradually expose new functions.

Add functions `list.first()` and `list.last()`, both returning `optional`

PiperOrigin-RevId: 782140219

Author: dmitriplotnikov

bundle/src/main/java/dev/cel/bundle/CelEnvironment.java

@@ -46,7 +46,6 @@
 import dev.cel.compiler.CelCompilerBuilder;
 import dev.cel.compiler.CelCompilerLibrary;
 import dev.cel.extensions.CelExtensions;
-import dev.cel.extensions.CelOptionalLibrary;
 import dev.cel.parser.CelStandardMacro;
 import dev.cel.runtime.CelRuntimeBuilder;
 import dev.cel.runtime.CelRuntimeLibrary;
@@ -684,8 +683,8 @@ enum CanonicalCelExtension {
         (options, version) -> CelExtensions.math(options, version),
         (options, version) -> CelExtensions.math(options, version)),
     OPTIONAL(
-        (options, version) -> CelOptionalLibrary.INSTANCE,
-        (options, version) -> CelOptionalLibrary.INSTANCE),
+        (options, version) -> CelExtensions.optional(version),
+        (options, version) -> CelExtensions.optional(version)),
     STRINGS(
         (options, version) -> CelExtensions.strings(),
         (options, version) -> CelExtensions.strings()),

extensions/src/main/java/dev/cel/extensions/BUILD.bazel

@@ -27,6 +27,7 @@ java_library(
         ":sets_function",
         ":strings",
         "//common:options",
+        "//extensions:optional_library",
         "@maven//:com_google_guava_guava",
     ],
 )

extensions/src/main/java/dev/cel/extensions/CelExtensions.java

@@ -38,6 +38,24 @@ public final class CelExtensions {
   private static final CelListsExtensions LISTS_EXTENSIONS_ALL = new CelListsExtensions();
   private static final CelRegexExtensions REGEX_EXTENSIONS = new CelRegexExtensions();
 
+  /**
+   * Implementation of optional values.
+   *
+   * <p>Refer to README.md for available functions.
+   */
+  public static CelOptionalLibrary optional() {
+    return CelOptionalLibrary.INSTANCE;
+  }
+
+  /**
+   * Implementation of optional values.
+   *
+   * <p>Refer to README.md for available functions for each supported version.
+   */
+  public static CelOptionalLibrary optional(int version) {
+    return new CelOptionalLibrary(version);
+  }
+
   /**
    * Extended functions for string manipulation.
    *

extensions/src/main/java/dev/cel/extensions/CelOptionalLibrary.java

@@ -19,6 +19,7 @@
 import static com.google.common.collect.ImmutableList.toImmutableList;
 
 import com.google.common.collect.ImmutableList;
+import com.google.common.collect.Iterables;
 import com.google.common.primitives.Ints;
 import com.google.common.primitives.UnsignedLong;
 import com.google.protobuf.ByteString;
@@ -55,6 +56,7 @@
 
 /** Internal implementation of CEL optional values. */
 public final class CelOptionalLibrary implements CelCompilerLibrary, CelInternalRuntimeLibrary {
+  // TODO migrate from this constant to the CelExtensions.optional()
   public static final CelOptionalLibrary INSTANCE = new CelOptionalLibrary();
 
   /** Enumerations of function names used for supporting optionals. */
@@ -66,7 +68,10 @@ public enum Function {
     OPTIONAL_UNWRAP("optional.unwrap"),
     OPTIONAL_OF_NON_ZERO_VALUE("optional.ofNonZeroValue"),
     OR("or"),
-    OR_VALUE("orValue");
+    OR_VALUE("orValue"),
+    FIRST("first"),
+    LAST("last");
+
     private final String functionName;
 
     public String getFunction() {
@@ -80,6 +85,16 @@ public String getFunction() {
 
   private static final String UNUSED_ITER_VAR = "#unused";
 
+  private final int version;
+
+  CelOptionalLibrary() {
+    this(Integer.MAX_VALUE);
+  }
+
+  CelOptionalLibrary(int version) {
+    this.version = version;
+  }
+
   @Override
   public void setParserOptions(CelParserBuilder parserBuilder) {
     if (!parserBuilder.getOptions().enableOptionalSyntax()) {
@@ -90,8 +105,10 @@ public void setParserOptions(CelParserBuilder parserBuilder) {
     }
     parserBuilder.addMacros(
         CelMacro.newReceiverMacro("optMap", 2, CelOptionalLibrary::expandOptMap));
-    parserBuilder.addMacros(
-        CelMacro.newReceiverMacro("optFlatMap", 2, CelOptionalLibrary::expandOptFlatMap));
+    if (version >= 1) {
+      parserBuilder.addMacros(
+          CelMacro.newReceiverMacro("optFlatMap", 2, CelOptionalLibrary::expandOptFlatMap));
+    }
   }
 
   @Override
@@ -172,6 +189,23 @@ public void setCheckerOptions(CelCheckerBuilder checkerBuilder) {
                 optionalTypeV,
                 OptionalType.create(mapTypeKv),
                 paramTypeK)));
+    if (version >= 2) {
+      checkerBuilder.addFunctionDeclarations(
+          CelFunctionDecl.newFunctionDeclaration(
+              Function.FIRST.functionName,
+              CelOverloadDecl.newMemberOverload(
+                  "optional_list_first",
+                  "Return the first value in a list if present, otherwise optional.none()",
+                  optionalTypeV,
+                  listTypeV)),
+          CelFunctionDecl.newFunctionDeclaration(
+              Function.LAST.functionName,
+              CelOverloadDecl.newMemberOverload(
+                  "optional_list_last",
+                  "Return the last value in a list if present, otherwise optional.none()",
+                  optionalTypeV,
+                  listTypeV)));
+    }
   }
 
   @Override
@@ -241,6 +275,14 @@ public void setRuntimeOptions(
             Optional.class,
             Long.class,
             CelOptionalLibrary::indexOptionalList));
+
+    if (version >= 2) {
+      runtimeBuilder.addFunctionBindings(
+          CelFunctionBinding.from(
+              "optional_list_first", Collection.class, CelOptionalLibrary::listOptionalFirst),
+          CelFunctionBinding.from(
+              "optional_list_last", Collection.class, CelOptionalLibrary::listOptionalLast));
+    }
   }
 
   private static ImmutableList<Object> elideOptionalCollection(Collection<Optional<Object>> list) {
@@ -372,5 +414,18 @@ private static Object indexOptionalList(Optional<?> optionalList, long index) {
     return Optional.of(list.get(castIndex));
   }
 
-  private CelOptionalLibrary() {}
+  @SuppressWarnings("rawtypes")
+  private static Object listOptionalFirst(Collection<Object> list) {
+    if (list.isEmpty()) {
+      return Optional.empty();
+    }
+    if (list instanceof List) {
+      return Optional.ofNullable(((List) list).get(0));
+    }
+    return Optional.ofNullable(Iterables.getFirst(list, null));
+  }
+
+  private static Object listOptionalLast(Collection<Object> list) {
+    return Optional.ofNullable(Iterables.getLast(list, null));
+  }
 }

extensions/src/main/java/dev/cel/extensions/README.md

@@ -722,6 +722,36 @@ lists.range(5) -> [0, 1, 2, 3, 4]
 lists.range(0) -> []
 ```
 
+### Last
+
+Introduced in the 'optional' extension version 2
+
+Returns an optional with the last value from the list or `optional.None` if the
+list is empty.
+
+    <list(T)>.last() -> <Optional(T)>
+
+Examples:
+
+    [1, 2, 3].last().value() == 3
+    [].last().orValue('test') == 'test'
+
+This is syntactic sugar for list[list.size()-1].
+
+### First
+
+Introduced in the 'optional' extension version 2
+
+Returns an optional with the first value from the list or `optional.None` if the
+list is empty.
+
+    <list(T)>.first() -> <Optional(T)>
+
+Examples:
+
+     [1, 2, 3].first().value() == 1
+     [].first().orValue('test') == 'test'
+
 ## Regex
 
 Regex introduces support for regular expressions in CEL.

extensions/src/test/java/dev/cel/extensions/CelOptionalLibraryTest.java

@@ -56,7 +56,7 @@
 import org.junit.runner.RunWith;
 
 @RunWith(TestParameterInjector.class)
-@SuppressWarnings("unchecked")
+@SuppressWarnings({"unchecked", "SingleTestParameter"})
 public class CelOptionalLibraryTest {
 
   @SuppressWarnings("ImmutableEnumChecker") // Test only
@@ -93,13 +93,17 @@ private enum ConstantTestCases {
   }
 
   private static CelBuilder newCelBuilder() {
+    return newCelBuilder(Integer.MAX_VALUE);
+  }
+
+  private static CelBuilder newCelBuilder(int version) {
     return CelFactory.standardCelBuilder()
         .setOptions(CelOptions.current().enableTimestampEpoch(true).build())
         .setStandardMacros(CelStandardMacro.STANDARD_MACROS)
         .setContainer("cel.expr.conformance.proto3")
         .addMessageTypes(TestAllTypes.getDescriptor())
-        .addRuntimeLibraries(CelOptionalLibrary.INSTANCE)
-        .addCompilerLibraries(CelOptionalLibrary.INSTANCE);
+        .addRuntimeLibraries(CelExtensions.optional(version))
+        .addCompilerLibraries(CelExtensions.optional(version));
   }
 
   @Test
@@ -1496,4 +1500,40 @@ public void optionalType_typeComparison() throws Exception {
 
     assertThat(cel.createProgram(ast).eval()).isEqualTo(true);
   }
+
+  @Test
+  @TestParameters("{expression: '[].first().hasValue() == false'}")
+  @TestParameters("{expression: '[\"a\",\"b\",\"c\"].first().value() == \"a\"'}")
+  public void listFirst_success(String expression) throws Exception {
+    Cel cel = newCelBuilder().build();
+    boolean result = (boolean) cel.createProgram(cel.compile(expression).getAst()).eval();
+    assertThat(result).isTrue();
+  }
+
+  @Test
+  @TestParameters("{expression: '[].last().hasValue() == false'}")
+  @TestParameters("{expression: '[1, 2, 3].last().value() == 3'}")
+  public void listLast_success(String expression) throws Exception {
+    Cel cel = newCelBuilder().build();
+    boolean result = (boolean) cel.createProgram(cel.compile(expression).getAst()).eval();
+    assertThat(result).isTrue();
+  }
+
+  @Test
+  @TestParameters("{expression: '[1].first()', expectedError: 'undeclared reference to ''first'''}")
+  @TestParameters("{expression: '[2].last()', expectedError: 'undeclared reference to ''last'''}")
+  public void listFirstAndLast_throws_earlyVersion(String expression, String expectedError)
+      throws Exception {
+    // Configure Cel with an earlier version of the 'optional' library, which did not support
+    // 'first' and 'last'
+    Cel cel = newCelBuilder(1).build();
+    assertThat(
+            assertThrows(
+                CelValidationException.class,
+                () -> {
+                  cel.createProgram(cel.compile(expression).getAst()).eval();
+                }))
+        .hasMessageThat()
+        .contains(expectedError);
+  }
 }