Use re2 instead of re for match expressions

CEL specifies that match should use re2 pattern matching and not re
semantics.

README.rst

@@ -37,6 +37,21 @@ Installation
 
 You now have the CEL run-time available to Python-based applications.
 
+
+re2
+---
+
+CEL specifies that regular expressions use re2 syntax,
+https://github.com/google/re2/wiki/Syntax. To keep its dependencies minimal and
+this implementation easily embeddable, cel-python uses the Python standard
+library ``re`` syntax by default. If a ``re2`` package is installed or the
+``re2`` extra is provided, cel-python will use ``re2`` syntax instead.
+
+::
+
+    pip install cel-python[re2]
+
+
 Command Line
 ============
 

pyproject.toml

@@ -44,6 +44,10 @@ python-dateutil = "^2.9.0.post0"
 pyyaml = "^6.0.1"
 types-pyyaml = "^6.0.12.20240311"
 types-python-dateutil = "^2.9.0.20240316"
+google-re2 = { version = "^1.0", optional = true }
+
+[tool.poetry.extras]
+re2 = ["google-re2"]
 
 [tool.poetry.group.dev.dependencies]
 behave = "^1.2.6"
@@ -55,6 +59,7 @@ pytest-cov = "^5.0.0"
 sphinx = "^6.0"
 tox = "^4.15.0"
 pre-commit = "^3.5"
+google-re2-stubs = "^0.1.0"
 
 [build-system]
 requires = ["poetry-core"]

src/celpy/evaluation.py

@@ -51,6 +51,12 @@
 import celpy.celtypes
 from celpy.celparser import tree_dump
 
+_USE_RE2 = True
+try:
+    import re2
+except ImportError:
+    _USE_RE2 = False
+
 # A CEL type annotation. Used in an environment to describe objects as well as functions.
 # This is a list of types, plus Callable for conversion functions.
 Annotation = Union[
@@ -59,10 +65,8 @@
     Type[celpy.celtypes.FunctionType],  # Concrete class for annotations
 ]
 
-
 logger = logging.getLogger("evaluation")
 
-
 class CELSyntaxError(Exception):
     """CEL Syntax error -- the AST did not have the expected structure."""
     def __init__(self, arg: Any, line: Optional[int] = None, column: Optional[int] = None) -> None:
@@ -293,6 +297,27 @@ def operator_in(item: Result, container: Result) -> Result:
     return result
 
 
+def _function_matches_re(text: str, pattern: str) -> Result:
+    try:
+        m = re.search(pattern, text)
+    except re.error as ex:
+        return CELEvalError("match error", ex.__class__, ex.args)
+
+    return celpy.celtypes.BoolType(m is not None)
+
+
+def _function_matches_re2(text: str, pattern: str) -> Result:
+    try:
+        m = re2.search(pattern, text)
+    except re2.error as ex:
+        return CELEvalError("match error", ex.__class__, ex.args)
+
+    return celpy.celtypes.BoolType(m is not None)
+
+
+function_matches = _function_matches_re2 if _USE_RE2 else _function_matches_re
+
+
 def function_size(container: Result) -> Result:
     """
     The size() function applied to a Value. Delegate to Python's :py:func:`len`.
@@ -340,7 +365,7 @@ def function_size(container: Result) -> Result:
     # StringType methods
     "endsWith": lambda s, text: celpy.celtypes.BoolType(s.endswith(text)),
     "startsWith": lambda s, text: celpy.celtypes.BoolType(s.startswith(text)),
-    "matches": lambda s, pattern: celpy.celtypes.BoolType(re.search(pattern, s) is not None),
+    "matches": function_matches,
     "contains": lambda s, text: celpy.celtypes.BoolType(text in s),
     # TimestampType methods. Type details are redundant, but required because of the lambdas
     "getDate": lambda ts, tz_name=None: celpy.celtypes.IntType(ts.getDate(tz_name)),

tests/test_evaluation.py

@@ -37,6 +37,7 @@
 import celpy.evaluation  # For monkeypatching
 from celpy import celparser, celtypes
 from celpy.evaluation import *
+from celpy.evaluation import _function_matches_re, _function_matches_re2
 
 
 def test_exception_syntax_error():
@@ -158,6 +159,25 @@ def test_operator_in():
     assert isinstance(operator_in(celtypes.IntType(-1), container_2), CELEvalError)
 
 
+def test_function_matches_re2():
+    empty_string = celtypes.StringType("")
+    # re2-specific patterns which behave differently than standard re
+    assert _function_matches_re2(empty_string, "^\\z")
+    assert isinstance(_function_matches_re2(empty_string, "^\\Z"), CELEvalError)
+
+
+def test_function_matches_re():
+    empty_string = celtypes.StringType("")
+    # re2-specific patterns which behave differently than standard re
+    assert isinstance(_function_matches_re(empty_string, "^\\z"), CELEvalError)
+    assert _function_matches_re(empty_string, "^\\Z")
+
+
+def test_function_matches():
+    empty_string = celtypes.StringType("")
+    assert function_matches(empty_string, "^$")
+
+
 def test_function_size():
     container_1 = celtypes.ListType([
         celtypes.IntType(42),