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

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

PiperOrigin-RevId: 789826893

Author: dmitriplotnikov

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

@@ -47,7 +47,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;
@@ -694,8 +693,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

@@ -33,6 +33,7 @@ java_library(
         ":encoders",
         ":lists",
         ":math",
+        ":optional_library",
         ":protos",
         ":regex",
         ":sets",
@@ -177,6 +178,7 @@ java_library(
         "//common/ast",
         "//common/types",
         "//compiler:compiler_builder",
+        "//extensions:extension_library",
         "//parser:macro",
         "//parser:operator",
         "//parser:parser_builder",

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

@@ -16,6 +16,7 @@
 
 import com.google.common.collect.ImmutableSet;
 import dev.cel.common.CelFunctionDecl;
+import dev.cel.common.CelVarDecl;
 import dev.cel.parser.CelMacro;
 import java.util.Comparator;
 
@@ -66,6 +67,9 @@ default ImmutableSet<CelMacro> macros() {
       return ImmutableSet.of();
     }
 
-    // TODO - Add a method for variables.
+    /** Returns the set of variables defined by this extension library. */
+    default ImmutableSet<CelVarDecl> variables() {
+      return ImmutableSet.of();
+    }
   }
 }

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

@@ -36,6 +36,24 @@ public final class CelExtensions {
   private static final CelEncoderExtensions ENCODER_EXTENSIONS = new CelEncoderExtensions();
   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.library().latest();
+  }
+
+  /**
+   * Implementation of optional values.
+   *
+   * <p>Refer to README.md for available functions for each supported version.
+   */
+  public static CelOptionalLibrary optional(int version) {
+    return CelOptionalLibrary.library().version(version);
+  }
+
   /**
    * Extended functions for string manipulation.
    *
@@ -311,6 +329,8 @@ public static CelExtensionLibrary<? extends CelExtensionLibrary.FeatureSet> getE
         return CelListsExtensions.library();
       case "math":
         return CelMathExtensions.library(options);
+      case "optional":
+        return CelOptionalLibrary.library();
       case "protos":
         return CelProtoExtensions.library();
       case "regex":