Merge pull request #45 from AbdelrhmanBassiouny/match

Match

Author: AbdelrhmanBassiouny

doc/_toc.yml

@@ -15,6 +15,7 @@ parts:
         - file: eql/domain_mapping
         - file: eql/predicate_and_symbolic_function
         - file: eql/cache
+        - file: eql/match
         - file: eql/writing_rule_trees
         - file: eql/eql_for_sql_experts
 - caption: ORMatic

examples/eql/match.md

@@ -0,0 +1,125 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.4
+kernelspec:
+  display_name: Python 3
+  language: python
+  name: python3
+---
+
+# Pattern matching with `match` and `entity_matching`
+
+EQL provides a concise pattern-matching API for building nested structural queries.
+Use `match(type_)(...)` to describe a nested pattern on attributes, and wrap the outermost match
+with `entity_matching(type_, domain)(...)` when you also need to bind a search domain.
+
+The following example shows how nested patterns translate
+into an equivalent manual query built with `entity(...)` and predicates.
+
+```{code-cell} ipython3
+from dataclasses import dataclass
+from typing_extensions import List
+
+from krrood.entity_query_language.entity import (
+    let, entity, the,
+    match, entity_matching, Symbol,
+)
+from krrood.entity_query_language.predicate import HasType
+
+
+# --- Model -------------------------------------------------------------
+@dataclass
+class Body(Symbol):
+    name: str
+
+
+@dataclass
+class Handle(Body):
+    ...
+
+
+@dataclass
+class Container(Body):
+    ...
+
+
+@dataclass
+class Connection(Symbol):
+    parent: Body
+    child: Body
+
+
+@dataclass
+class FixedConnection(Connection):
+    ...
+
+
+@dataclass
+class World:
+    connections: List[Connection]
+
+
+# Build a small world with a few connections
+c1 = Container("Container1")
+h1 = Handle("Handle1")
+other_c = Container("ContainerX")
+other_h = Handle("HandleY")
+
+world = World(
+    connections=[
+        FixedConnection(parent=c1, child=h1),
+        FixedConnection(parent=other_c, child=h1),
+    ]
+)
+```
+
+## Matching a nested structure
+
+`entity_matching(FixedConnection, world.connections)` selects from `world.connections` items of type
+`FixedConnection`. Inner `match(...)` clauses describe constraints on attributes of that selected item.
+
+```{code-cell} ipython3
+fixed_connection_query = the(
+    entity_matching(FixedConnection, world.connections)(
+        parent=match(Container)(name="Container1"),
+        child=match(Handle)(name="Handle1"),
+    )
+)
+```
+
+## The equivalent manual query
+
+You can express the same query explicitly using `entity`, `let`, attribute comparisons, and `HasType` for
+attribute type constraints:
+
+```{code-cell} ipython3
+fc = let(FixedConnection, domain=None)
+fixed_connection_query_manual = the(
+    entity(
+        fc,
+        HasType(fc.parent, Container),
+        HasType(fc.child, Handle),
+        fc.parent.name == "Container1",
+        fc.child.name == "Handle1",
+    )
+)
+
+# The two query objects are structurally equivalent
+assert fixed_connection_query == fixed_connection_query_manual
+```
+
+## Evaluate the query
+
+```{code-cell} ipython3
+fixed_connection = fixed_connection_query.evaluate()
+print(type(fixed_connection).__name__, fixed_connection.parent.name, fixed_connection.child.name)
+```
+
+Notes:
+- Use `entity_matching` for the outer pattern when a domain is involved; inner attributes use `match`.
+- Nested `match(...)` can be composed arbitrarily deep following your object graph.
+- `entity_matching` is a syntactic sugar over the explicit `entity` + predicates form, so both are interchangeable.

src/krrood/entity_query_language/entity.py

@@ -1,5 +1,11 @@
 from __future__ import annotations
 
+from dataclasses import dataclass, field
+from functools import cached_property
+
+from black.strings import Match
+
+from .hashed_data import T
 from .symbol_graph import SymbolGraph
 from .utils import is_iterable
 
@@ -13,7 +19,8 @@
     Optional,
     Union,
     Iterable,
-    TypeVar,
+    Dict,
+    Generic,
     Type,
     Tuple,
     List,
@@ -37,22 +44,23 @@
     ForAll,
     Exists,
     Literal,
+    ResultQuantifier,
 )
 from .result_quantification_constraint import ResultQuantificationConstraint
 
 from .predicate import (
     Predicate,
     # type: ignore
     Symbol,  # type: ignore
+    HasType,
 )
 
-T = TypeVar("T")  # Define type variable "T"
 
 ConditionType = Union[SymbolicExpression, bool, Predicate]
 """
 The possible types for conditions.
 """
-EntityType = Union[SetOf[T], Entity[T], T, Iterable[T], Type[T]]
+EntityType = Union[SetOf[T], Entity[T], T, Iterable[T], Type[T], Match[T]]
 """
 The possible types for entities.
 """
@@ -61,7 +69,7 @@
 def an(
     entity_: EntityType,
     quantification: Optional[ResultQuantificationConstraint] = None,
-) -> Union[An[T], T, SymbolicExpression[T]]:
+) -> Union[An[T], T]:
     """
     Select a single element satisfying the given entity description.
 
@@ -70,7 +78,7 @@ def an(
     :return: A quantifier representing "an" element.
     :rtype: An[T]
     """
-    return An(entity_, _quantification_constraint_=quantification)
+    return _quantify_entity(An, entity_, _quantification_constraint_=quantification)
 
 
 a = an
@@ -89,7 +97,23 @@ def the(
     :return: A quantifier representing "an" element.
     :rtype: The[T]
     """
-    return The(entity_)
+    return _quantify_entity(The, entity_)
+
+
+def _quantify_entity(
+    quantifier: Type[ResultQuantifier], entity_: EntityType, **quantifier_kwargs
+) -> Union[ResultQuantifier[T], T]:
+    """
+    Apply the given quantifier to the given entity.
+
+    :param quantifier: The quantifier to apply.
+    :param entity_: The entity to quantify.
+    :param quantifier_kwargs: Keyword arguments to pass to the quantifier.
+    :return: The quantified entity.
+    """
+    if isinstance(entity_, Match):
+        entity_ = entity_.expression
+    return quantifier(entity_, **quantifier_kwargs)
 
 
 def entity(
@@ -319,3 +343,111 @@ def inference(
     return lambda **kwargs: Variable(
         _type_=type_, _name__=type_.__name__, _kwargs_=kwargs, _is_inferred_=True
     )
+
+
+@dataclass
+class Match(Generic[T]):
+    """
+    Construct a query that looks for the pattern provided by the type and the keyword arguments.
+    """
+
+    type_: Type[T]
+    """
+    The type of the variable.
+    """
+    kwargs: Dict[str, Any]
+    """
+    The keyword arguments to match against.
+    """
+    variable: CanBehaveLikeAVariable[T] = field(init=False)
+    """
+    The created variable from the type and kwargs.
+    """
+    conditions: List[ConditionType] = field(init=False, default_factory=list)
+    """
+    The conditions that define the match.
+    """
+
+    def _resolve(self, variable: Optional[CanBehaveLikeAVariable] = None):
+        """
+        Resolve the match by creating the variable and conditions expressions.
+
+        :param variable: An optional pre-existing variable to use for the match; if not provided, a new variable will be created.
+        :return:
+        """
+        self.variable = variable if variable else self._create_variable()
+        for k, v in self.kwargs.items():
+            attr = getattr(self.variable, k)
+            if isinstance(v, Match):
+                v._resolve(attr)
+                self.conditions.append(HasType(attr, v.type_))
+                self.conditions.extend(v.conditions)
+            else:
+                self.conditions.append(attr == v)
+
+    def _create_variable(self) -> Variable[T]:
+        """
+        Create a variable with the given type.
+        """
+        return let(self.type_, None)
+
+    @cached_property
+    def expression(self) -> Entity[T]:
+        """
+        Return the entity expression corresponding to the match query.
+        """
+        self._resolve()
+        return entity(self.variable, *self.conditions)
+
+
+@dataclass
+class MatchEntity(Match[T]):
+    """
+    A match that can also take a domain and should be used as the outermost match in a nested match statement.
+    This is because the inner match statements derive their domain from the outer match as they are basically attributes
+    of the outer match variable.
+    """
+
+    domain: DomainType
+    """
+    The domain to use for the variable created by the match.
+    """
+
+    def _create_variable(self) -> Variable[T]:
+        """
+        Create a variable with the given type and domain.
+        """
+        return let(self.type_, self.domain)
+
+
+def match(type_: Type[T]) -> Union[Type[T], Callable[..., Match[T]]]:
+    """
+    This returns a factory function that creates a Match instance that looks for the pattern provided by the type and the
+    keyword arguments.
+
+    :param type_: The type of the variable (i.e., The class you want to instantiate).
+    :return: The factory function for creating the match query.
+    """
+
+    def match_factory(**kwargs) -> Match[T]:
+        return Match(type_, kwargs)
+
+    return match_factory
+
+
+def entity_matching(
+    type_: Type[T], domain: DomainType
+) -> Union[Type[T], Callable[..., MatchEntity[T]]]:
+    """
+    Same as :py:func:`krrood.entity_query_language.entity.match` but with a domain to use for the variable created
+     by the match.
+
+    :param type_: The type of the variable (i.e., The class you want to instantiate).
+    :param domain: The domain used for the variable created by the match.
+    :return: The factory function for creating the match query.
+    """
+
+    def match_factory(**kwargs) -> MatchEntity[T]:
+        return MatchEntity(type_, kwargs, domain)
+
+    return match_factory

src/krrood/entity_query_language/symbolic.py

@@ -43,7 +43,6 @@
     GreaterThanExpectedNumberOfSolutions,
     LessThanExpectedNumberOfSolutions,
     InvalidEntityType,
-    UnsupportedOperation,
     UnSupportedOperand,
 )
 from .hashed_data import HashedValue, HashedIterable, T
@@ -1091,20 +1090,39 @@ def _evaluate__(
         sources: Optional[Dict[int, HashedValue]] = None,
         parent: Optional[SymbolicExpression] = None,
     ) -> Iterable[OperationResult]:
+
         sources = sources or {}
+
         self._eval_parent_ = parent
+
         if self._id_ in sources:
             yield OperationResult(sources, self._is_false_, self)
             return
-        child_val = self._child_._evaluate__(sources, parent=self)
-        for child_v in child_val:
-            for v in self._apply_mapping_(child_v[self._child_._id_]):
-                self._is_false_ = not bool(v)
-                yield OperationResult(
-                    {**child_v.bindings, self._id_: v},
-                    self._is_false_,
-                    self,
-                )
+
+        yield from (
+            self._build_operation_result_and_update_truth_value_(
+                child_result, mapped_value
+            )
+            for child_result in self._child_._evaluate__(sources, parent=self)
+            for mapped_value in self._apply_mapping_(child_result[self._child_._id_])
+        )
+
+    def _build_operation_result_and_update_truth_value_(
+        self, child_result: OperationResult, current_value: Any
+    ) -> OperationResult:
+        """
+        Set the current truth value of the operation result, and build the operation result to be yielded.
+
+        :param child_result: The current result from the child operation.
+        :param current_value: The current value of this operation that is derived from the child result.
+        :return: The operation result.
+        """
+        self._is_false_ = not bool(current_value)
+        return OperationResult(
+            {**child_result.bindings, self._id_: current_value},
+            self._is_false_,
+            self,
+        )
 
     @abstractmethod
     def _apply_mapping_(self, value: HashedValue) -> Iterable[HashedValue]: