Updating Regex ext to align with Google SQL and Adding Regex documentation

PiperOrigin-RevId: 772600803

Author: maskri17

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

@@ -15,7 +15,6 @@
 package dev.cel.extensions;
 
 import com.google.common.collect.ImmutableList;
-import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.errorprone.annotations.Immutable;
 import com.google.re2j.Matcher;
@@ -25,7 +24,6 @@
 import dev.cel.common.CelFunctionDecl;
 import dev.cel.common.CelOverloadDecl;
 import dev.cel.common.types.ListType;
-import dev.cel.common.types.MapType;
 import dev.cel.common.types.OptionalType;
 import dev.cel.common.types.SimpleType;
 import dev.cel.compiler.CelCompilerLibrary;
@@ -40,9 +38,8 @@
 final class CelRegexExtensions implements CelCompilerLibrary, CelRuntimeLibrary {
 
   private static final String REGEX_REPLACE_FUNCTION = "regex.replace";
-  private static final String REGEX_CAPTURE_FUNCTION = "regex.capture";
-  private static final String REGEX_CAPTUREALL_FUNCTION = "regex.captureAll";
-  private static final String REGEX_CAPTUREALLNAMED_FUNCTION = "regex.captureAllNamed";
+  private static final String REGEX_EXTRACT_FUNCTION = "regex.extract";
+  private static final String REGEX_EXTRACT_ALL_FUNCTION = "regex.extractAll";
 
   enum Function {
     REPLACE(
@@ -83,52 +80,36 @@ enum Function {
                   long count = (long) args[3];
                   return CelRegexExtensions.replace(target, pattern, replaceStr, count);
                 }))),
-    CAPTURE(
+    EXTRACT(
         CelFunctionDecl.newFunctionDeclaration(
-            REGEX_CAPTURE_FUNCTION,
+            REGEX_EXTRACT_FUNCTION,
             CelOverloadDecl.newGlobalOverload(
-                "regex_capture_string_string",
+                "regex_extract_string_string",
                 "Returns the first substring that matches the regex.",
                 OptionalType.create(SimpleType.STRING),
                 SimpleType.STRING,
                 SimpleType.STRING)),
         ImmutableSet.of(
             CelFunctionBinding.from(
-                "regex_capture_string_string",
+                "regex_extract_string_string",
                 String.class,
                 String.class,
-                CelRegexExtensions::captureFirstMatch))),
-    CAPTUREALL(
+                CelRegexExtensions::extract))),
+    EXTRACTALL(
         CelFunctionDecl.newFunctionDeclaration(
-            REGEX_CAPTUREALL_FUNCTION,
+            REGEX_EXTRACT_ALL_FUNCTION,
             CelOverloadDecl.newGlobalOverload(
-                "regex_captureAll_string_string",
-                "Returns an arrat of all substrings that match the regex.",
+                "regex_extractAll_string_string",
+                "Returns an array of all substrings that match the regex.",
                 ListType.create(SimpleType.STRING),
                 SimpleType.STRING,
                 SimpleType.STRING)),
         ImmutableSet.of(
             CelFunctionBinding.from(
-                "regex_captureAll_string_string",
+                "regex_extractAll_string_string",
                 String.class,
                 String.class,
-                CelRegexExtensions::captureAllMatches))),
-    CAPTUREALLNAMED(
-        CelFunctionDecl.newFunctionDeclaration(
-            REGEX_CAPTUREALLNAMED_FUNCTION,
-            CelOverloadDecl.newGlobalOverload(
-                "regex_captureAllNamed_string_string",
-                "Returns a map of all named captured groups as <named_group_name, captured_string>."
-                    + " Ignores the unnamed capture groups.",
-                MapType.create(SimpleType.STRING, SimpleType.STRING),
-                SimpleType.STRING,
-                SimpleType.STRING)),
-        ImmutableSet.of(
-            CelFunctionBinding.from(
-                "regex_captureAllNamed_string_string",
-                String.class,
-                String.class,
-                CelRegexExtensions::captureAllNamedGroups)));
+                CelRegexExtensions::extractAll)));
 
     private final CelFunctionDecl functionDecl;
     private final ImmutableSet<CelFunctionBinding> functionBindings;
@@ -200,67 +181,49 @@ private static String replace(String target, String regex, String replaceStr, lo
     return sb.toString();
   }
 
-  private static Optional<String> captureFirstMatch(String target, String regex) {
+  private static Optional<String> extract(String target, String regex) {
     Pattern pattern = compileRegexPattern(regex);
     Matcher matcher = pattern.matcher(target);
 
-    if (matcher.find()) {
-      // If there are capture groups, return the first one.
-      if (matcher.groupCount() > 0) {
-        return Optional.ofNullable(matcher.group(1));
-      } else {
-        // If there are no capture groups, return the entire match.
-        return Optional.of(matcher.group(0));
-      }
+    if (!matcher.find()) {
+      return Optional.empty();
     }
 
-    return Optional.empty();
-  }
-
-  private static ImmutableList<String> captureAllMatches(String target, String regex) {
-    Pattern pattern = compileRegexPattern(regex);
-
-    Matcher matcher = pattern.matcher(target);
-    ImmutableList.Builder<String> builder = ImmutableList.builder();
-
-    while (matcher.find()) {
-      // If there are capture groups, return all of them. Otherwise, return the entire match.
-      if (matcher.groupCount() > 0) {
-        // Add all the capture groups to the result list.
-        for (int i = 1; i <= matcher.groupCount(); i++) {
-          String group = matcher.group(i);
-          if (group != null) {
-            builder.add(group);
-          }
-        }
-      } else {
-        builder.add(matcher.group(0));
-      }
+    int groupCount = matcher.groupCount();
+    if (groupCount > 1) {
+      throw new IllegalArgumentException(
+          "Regular expression has more than one capturing group: " + regex);
     }
 
-    return builder.build();
+    String result = (groupCount == 1) ? matcher.group(1) : matcher.group(0);
+
+    return Optional.ofNullable(result);
   }
 
-  private static ImmutableMap<String, String> captureAllNamedGroups(String target, String regex) {
-    ImmutableMap.Builder<String, String> builder = ImmutableMap.builder();
+  private static ImmutableList<String> extractAll(String target, String regex) {
     Pattern pattern = compileRegexPattern(regex);
+    Matcher matcher = pattern.matcher(target);
 
-    Set<String> groupNames = pattern.namedGroups().keySet();
-    if (groupNames.isEmpty()) {
-      return builder.buildOrThrow();
+    if (matcher.groupCount() > 1) {
+      throw new IllegalArgumentException(
+          "Regular expression has more than one capturing group: " + regex);
     }
 
-    Matcher matcher = pattern.matcher(target);
+    ImmutableList.Builder<String> builder = ImmutableList.builder();
+    boolean hasOneGroup = matcher.groupCount() == 1;
 
     while (matcher.find()) {
-
-      for (String groupName : groupNames) {
-        String capturedValue = matcher.group(groupName);
-        if (capturedValue != null) {
-          builder.put(groupName, capturedValue);
+      if (hasOneGroup) {
+        String group = matcher.group(1);
+        // Add the captured group's content only if it's not null (e.g. optional group didn't match)
+        if (group != null) {
+          builder.add(group);
         }
+      } else { // No capturing groups (matcher.groupCount() == 0)
+        builder.add(matcher.group(0));
       }
     }
-    return builder.buildOrThrow();
+
+    return builder.build();
   }
 }

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

@@ -703,4 +703,81 @@ Examples:
 ```
 lists.range(5) -> [0, 1, 2, 3, 4]
 lists.range(0) -> []
+```
+
+## Regex
+
+Regex introduces support for regular expressions in CEL.
+
+This library provides functions for capturing groups, replacing strings using
+regex patterns, Regex configures namespaced regex helper functions. Note, all
+functions use the 'regex' namespace. If you are currently using a variable named
+'regex', the macro will likely work just as intended; however, there is some
+chance for collision.
+
+### Replace
+
+The `regex.replace` function replaces all occurrences of a regex pattern in a
+string with a replacement string. Optionally, you can limit the number of
+replacements by providing a count argument. Both numeric ($N) and named
+(${name}) capture group references are supported in the replacement string, with
+validation for correctness. An error will be thrown for invalid regex or replace
+string.
+
+```
+regex.replace(target: string, pattern: string, replacement: string) -> string
+regex.replace(target: string, pattern: string, replacement: string, count: int) -> string
+```
+
+Examples:
+
+```
+regex.replace('banana', 'a', 'x', 0) == 'banana'
+regex.replace('banana', 'a', 'x', 1) == 'bxnana'
+regex.replace('banana', 'a', 'x', 2) == 'bxnxna'
+regex.replace('foo bar', '(fo)o (ba)r', '$2 $1') == 'ba fo'
+
+regex.replace('test', '(.)', '$2') \\ Runtime Error invalid replace string
+regex.replace('foo bar', '(', '$2 $1') \\ Runtime Error invalid regex string
+regex.replace('id=123', 'id=(?P<value>\\\\d+)', 'value: ${values}') \\ Runtime Error invalid replace string
+
+```
+
+### Extract
+
+The `regex.extract` function returns the first match of a regex pattern in a
+string. If no match is found, it returns an optional none value. An error will
+be thrown for invalid regex or for multiple capture groups.
+
+```
+regex.extract(target: string, pattern: string) -> optional<string>
+```
+
+Examples:
+
+```
+regex.extract('hello world', 'hello(.*)') == optional.of(' world')
+regex.extract('item-A, item-B', 'item-(\\w+)') == optional.of('A')
+regex.extract('HELLO', 'hello') == optional.empty()
+
+regex.extract('testuser@testdomain', '(.*)@([^.]*)')) \\ Runtime Error multiple extract group
+```
+
+### Extract All
+
+The `regex.extractAll` function returns a list of all matches of a regex
+pattern in a target string. If no matches are found, it returns an empty list.
+An error will be thrown for invalid regex or for multiple capture groups.
+
+```
+regex.extractAll(target: string, pattern: string) -> list<string>
+```
+
+Examples:
+
+```
+regex.extractAll('id:123, id:456', 'id:\\d+') == ['id:123', 'id:456']
+regex.extractAll('id:123, id:456', 'assa') == []
+
+regex.extractAll('testuser@testdomain', '(.*)@([^.]*)') \\ Runtime Error multiple capture group
 ```

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

@@ -180,8 +180,7 @@ public void getAllFunctionNames() {
             "flatten",
             "lists.range",
             "regex.replace",
-            "regex.capture",
-            "regex.captureAll",
-            "regex.captureAllNamed");
+            "regex.extract",
+            "regex.extractAll");
   }
 }