feat: allow registering custom boolean operators

Author: joaofreires

README.md

@@ -55,6 +55,28 @@ expr = "starts_with(user.name, 'Sn')"
 print(evaluate(expr, context={"user": {"name": "Snoopy"}}))  # True
 ```
 
+### Custom operators
+
+```py
+from boolia import evaluate, DEFAULT_OPERATORS
+
+custom_ops = DEFAULT_OPERATORS.copy()
+custom_ops.register(
+    "XOR", # The operator identifier
+    precedence=20, # Higher precedence than AND/OR
+    evaluator=lambda left, right: bool(left) ^ bool(right), # XOR logic
+    keywords=("xor",), # Use "xor" in expressions
+)
+
+print(evaluate("true xor false", operators=custom_ops))  # True
+print(evaluate("true xor true", operators=custom_ops))   # False
+```
+
+Operators can be declared with `keywords=("xor",)` for word-style syntax or `symbols=("^",)`
+for symbolic tokens. Use `compile_rule(expr, operators=custom_ops)` to persist custom
+operators inside compiled rules. When evaluating rules or rule groups you can still pass a
+different registry with `operators=` if you need to override their behavior.
+
 ### RuleBook
 
 ```py

boolia/__init__.py

@@ -2,6 +2,7 @@
 from .resolver import default_resolver_factory, MissingPolicy
 from .errors import MissingVariableError
 from .functions import FunctionRegistry, DEFAULT_FUNCTIONS
+from .operators import OperatorRegistry, DEFAULT_OPERATORS
 
 __all__ = [
     "evaluate",
@@ -15,4 +16,6 @@
     "MissingVariableError",
     "FunctionRegistry",
     "DEFAULT_FUNCTIONS",
+    "OperatorRegistry",
+    "DEFAULT_OPERATORS",
 ]

boolia/api.py

@@ -6,14 +6,15 @@
 from .ast import Node
 from .resolver import default_resolver_factory, MissingPolicy
 from .functions import FunctionRegistry, DEFAULT_FUNCTIONS
+from .operators import OperatorRegistry, DEFAULT_OPERATORS
 
 
 RuleEntry = Union["Rule", "RuleGroup"]
 RuleMember = Union[str, RuleEntry]
 
 
-def compile_expr(source: str) -> Node:
-    return parse(source)
+def compile_expr(source: str, *, operators: Optional[OperatorRegistry] = None) -> Node:
+    return parse(source, operators)
 
 
 def evaluate(
@@ -25,26 +26,33 @@ def evaluate(
     on_missing: MissingPolicy = "false",
     default_value: Any = None,
     functions: Optional[FunctionRegistry] = None,
+    operators: Optional[OperatorRegistry] = None,
 ) -> bool:
-    node = compile_expr(source_or_ast) if isinstance(source_or_ast, str) else source_or_ast
+    ops = operators or DEFAULT_OPERATORS
+    node = compile_expr(source_or_ast, operators=ops) if isinstance(source_or_ast, str) else source_or_ast
     ctx = context or {}
     tg = tags or set()
     res = resolver or default_resolver_factory(ctx, on_missing=on_missing, default_value=default_value)
     fns = functions or DEFAULT_FUNCTIONS
-    out = node.eval(res, tg, fns)
+    out = node.eval(res, tg, fns, ops)
     return bool(out)
 
 
 @dataclass
 class Rule:
     ast: Node
+    operators: OperatorRegistry = DEFAULT_OPERATORS
 
-    def evaluate(self, **kwargs) -> bool:
-        return evaluate(self.ast, **kwargs)
+    def evaluate(self, *, operators: Optional[OperatorRegistry] = None, **kwargs) -> bool:
+        local_kwargs = kwargs.copy()
+        implicit_ops = local_kwargs.pop("operators", None)
+        ops = operators or implicit_ops or self.operators
+        return evaluate(self.ast, operators=ops, **local_kwargs)
 
 
-def compile_rule(source: str) -> Rule:
-    return Rule(compile_expr(source))
+def compile_rule(source: str, *, operators: Optional[OperatorRegistry] = None) -> Rule:
+    ops = operators or DEFAULT_OPERATORS
+    return Rule(compile_expr(source, operators=ops), ops)
 
 
 class RuleGroup:

boolia/ast.py

@@ -6,23 +6,23 @@
 
 
 class Node:
-    def eval(self, resolve: Resolver, tags: Set[str], functions) -> Any:
+    def eval(self, resolve: Resolver, tags: Set[str], functions, operators) -> Any:
         raise NotImplementedError()
 
 
 @dataclass
 class Literal(Node):
     value: Any
 
-    def eval(self, resolve, tags, functions):
+    def eval(self, resolve, tags, functions, operators):
         return self.value
 
 
 @dataclass
 class Name(Node):
     parts: List[str]  # e.g., ["house","light","on"] or ["car"]
 
-    def eval(self, resolve, tags, functions):
+    def eval(self, resolve, tags, functions, operators):
         if len(self.parts) == 1:
             name = self.parts[0]
             val = resolve(self.parts)
@@ -39,8 +39,8 @@ class Unary(Node):
     op: str
     right: Node
 
-    def eval(self, resolve, tags, functions):
-        v = self.right.eval(resolve, tags, functions)
+    def eval(self, resolve, tags, functions, operators):
+        v = self.right.eval(resolve, tags, functions, operators)
         if self.op == "NOT":
             return not bool(v)
         raise ValueError(f"Unknown unary op {self.op}")
@@ -52,39 +52,18 @@ class Binary(Node):
     op: str
     right: Node
 
-    def eval(self, resolve, tags, functions):
-        if self.op == "AND":
-            return bool(self.left.eval(resolve, tags, functions)) and bool(self.right.eval(resolve, tags, functions))
-        if self.op == "OR":
-            return bool(self.left.eval(resolve, tags, functions)) or bool(self.right.eval(resolve, tags, functions))
-        le = self.left.eval(resolve, tags, functions)
-        r = self.right.eval(resolve, tags, functions)
-        if self.op == "EQ":
-            return le == r
-        if self.op == "NE":
-            return le != r
-        if self.op == "GT":
-            return le > r
-        if self.op == "LT":
-            return le < r
-        if self.op == "GE":
-            return le >= r
-        if self.op == "LE":
-            return le <= r
-        if self.op == "IN":
-            try:
-                return le in r
-            except TypeError:
-                return False
-        raise ValueError(f"Unknown binary op {self.op}")
+    def eval(self, resolve, tags, functions, operators):
+        left_val = self.left.eval(resolve, tags, functions, operators)
+        right_val = self.right.eval(resolve, tags, functions, operators)
+        return operators.evaluate(self.op, left_val, right_val)
 
 
 @dataclass
 class Call(Node):
     name: str
     args: List[Node]
 
-    def eval(self, resolve, tags, functions):
+    def eval(self, resolve, tags, functions, operators):
         fn = functions.get(self.name)
-        vals = [a.eval(resolve, tags, functions) for a in self.args]
+        vals = [a.eval(resolve, tags, functions, operators) for a in self.args]
         return fn(*vals)

boolia/lexer.py

@@ -1,25 +1,34 @@
-from typing import List, Tuple, Any
+from typing import List, Tuple, Any, Optional
+
+from .operators import OperatorRegistry, DEFAULT_OPERATORS
 
 Token = Tuple[str, Any]  # (type, value)
 
-KEYWORDS = {"and", "or", "not", "in", "true", "false", "null", "none"}
-SYMS = {
+_FIXED_KEYWORDS = {
+    "true": ("BOOL", True),
+    "false": ("BOOL", False),
+    "null": ("NULL", None),
+    "none": ("NULL", None),
+    "not": ("NOT", "not"),
+}
+
+_BASE_SYMBOLS = {
     "(": "LPAREN",
     ")": "RPAREN",
     ".": "DOT",
     ",": "COMMA",
-    "==": "EQ",
-    "!=": "NE",
-    ">=": "GE",
-    "<=": "LE",
-    ">": "GT",
-    "<": "LT",
 }
 
 
-def tokenize(s: str) -> List[Token]:
+def tokenize(s: str, operators: Optional[OperatorRegistry] = None) -> List[Token]:
     import re
 
+    ops = operators or DEFAULT_OPERATORS
+    keyword_tokens = ops.keyword_tokens()
+    symbol_tokens = _BASE_SYMBOLS.copy()
+    symbol_tokens.update(ops.symbol_tokens())
+    max_symbol_len = max((len(sym) for sym in symbol_tokens), default=0)
+
     tokens: List[Token] = []
     i = 0
     n = len(s)
@@ -35,14 +44,18 @@ def tokenize(s: str) -> List[Token]:
         if i >= n:
             break
 
-        if i + 1 < n and s[i : i + 2] in SYMS:
-            tokens.append((SYMS[s[i : i + 2]], s[i : i + 2]))
-            i += 2
-            continue
-
-        if s[i] in SYMS:
-            tokens.append((SYMS[s[i]], s[i]))
-            i += 1
+        matched_symbol = False
+        for length in range(max_symbol_len, 0, -1):
+            if i + length > n:
+                continue
+            frag = s[i : i + length]
+            token_type = symbol_tokens.get(frag)
+            if token_type is not None:
+                tokens.append((token_type, frag))
+                i += length
+                matched_symbol = True
+                break
+        if matched_symbol:
             continue
 
         m = string.match(s, i)
@@ -65,17 +78,18 @@ def tokenize(s: str) -> List[Token]:
         if m:
             name = m.group(0)
             low = name.lower()
-            if low in KEYWORDS:
-                if low == "true":
-                    tokens.append(("BOOL", True))
-                elif low == "false":
-                    tokens.append(("BOOL", False))
-                elif low in ("null", "none"):
-                    tokens.append(("NULL", None))
-                else:
-                    tokens.append((low.upper(), low))  # AND, OR, NOT, IN
-            else:
-                tokens.append(("IDENT", name))
+            fixed = _FIXED_KEYWORDS.get(low)
+            if fixed is not None:
+                tokens.append(fixed)
+                i = m.end()
+                continue
+            op_token = keyword_tokens.get(low)
+            if op_token is not None:
+                tokens.append((op_token, low))
+                i = m.end()
+                continue
+
+            tokens.append(("IDENT", name))
             i = m.end()
             continue