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

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

@@ -66,7 +66,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 +83,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 +103,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 +187,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 +273,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 +412,27 @@ private static Object indexOptionalList(Optional<?> optionalList, long index) {
     return Optional.of(list.get(castIndex));
   }
 
-  private CelOptionalLibrary() {}
+  private static Object listOptionalFirst(Collection<Object> list) {
+    if (list.isEmpty()) {
+      return Optional.empty();
+    }
+    if (list instanceof List) {
+      return Optional.of(((List<Object>) list).get(0));
+    }
+    return list.stream().findFirst();
+  }
+
+  private static Object listOptionalLast(Collection<Object> list) {
+    if (list.isEmpty()) {
+      return Optional.empty();
+    }
+    if (list instanceof List) {
+      return Optional.of(((List<Object>) list).get(list.size() - 1));
+    }
+    Object last = null;
+    for (Object element : list) {
+      last = element;
+    }
+    return Optional.of(last);
+  }
 }

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

@@ -57,6 +57,7 @@
 
 @RunWith(TestParameterInjector.class)
 @SuppressWarnings("unchecked")
+@SuppressWarnings("SingleTestParameter")
 public class CelOptionalLibraryTest {
 
   @SuppressWarnings("ImmutableEnumChecker") // Test only
@@ -1496,4 +1497,22 @@ 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();
+  }
 }