Merge pull request #52 from AbdelrhmanBassiouny/better_match

Better match

Author: AbdelrhmanBassiouny

examples/eql/cache.md

@@ -28,7 +28,8 @@ from dataclasses import dataclass
 
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import entity, an, let, contains, Symbol
+from krrood.entity_query_language.entity import entity, let, contains, Symbol
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass

examples/eql/comparators.md

@@ -21,9 +21,10 @@ from dataclasses import dataclass
 from typing_extensions import List
 
 from krrood.entity_query_language.entity import (
-    entity, an, let, Symbol,
+    entity, let, Symbol,
     in_, contains, not_, and_, or_,
 )
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass

examples/eql/domain_mapping.md

@@ -29,12 +29,11 @@ from typing_extensions import List, Dict
 from krrood.entity_query_language.entity import (
     entity,
     set_of,
-    an,
     let,
     flatten,
     Symbol,
 )
-
+from krrood.entity_query_language.quantify_entity import an
 
 @dataclass
 class Body(Symbol):

examples/eql/eql_for_sql_experts.md

@@ -55,7 +55,8 @@ from dataclasses import dataclass, field
 
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import let, Symbol, entity, an, and_, in_, contains, set_of
+from krrood.entity_query_language.entity import let, Symbol, entity, and_, in_, contains, set_of
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass

examples/eql/intro.md

@@ -28,7 +28,8 @@ from dataclasses import dataclass
 
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import entity, an, let, contains, Symbol
+from krrood.entity_query_language.entity import entity, let, contains, Symbol
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass

examples/eql/logical_operators.md

@@ -21,7 +21,8 @@ from dataclasses import dataclass
 
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import entity, an, or_, Symbol, let, not_, and_
+from krrood.entity_query_language.entity import entity, or_, Symbol, let, not_, and_
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass

examples/eql/match.md

@@ -21,12 +21,17 @@ The following example shows how nested patterns translate
 into an equivalent manual query built with `entity(...)` and predicates.
 
 ```{code-cell} ipython3
+from krrood.entity_query_language.symbol_graph import SymbolGraph
 from dataclasses import dataclass
 from typing_extensions import List
 
 from krrood.entity_query_language.entity import (
-    let, entity, the,
-    match, entity_matching, Symbol,
+    let, entity, Symbol,
+)
+from krrood.entity_query_language.quantify_entity import the, an
+from krrood.entity_query_language.match import (
+    match,
+    entity_matching,
 )
 from krrood.entity_query_language.predicate import HasType
 
@@ -61,7 +66,19 @@ class FixedConnection(Connection):
 @dataclass
 class World:
     connections: List[Connection]
+    
+@dataclass
+class Drawer(Symbol):
+    handle: Handle
+    container: Container
+
+
+@dataclass
+class Cabinet(Symbol):
+    container: Container
+    drawers: List[Drawer]
 
+SymbolGraph()
 
 # Build a small world with a few connections
 c1 = Container("Container1")
@@ -123,3 +140,131 @@ 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.
+
+## Selecting inner objects with `select()`
+
+Use `select(Type)` when you want the matched inner objects to appear in the result. The evaluation then
+returns a mapping from the selected variables to the concrete objects (a unification dictionary).
+
+```{code-cell} ipython3
+from krrood.entity_query_language.match import select
+
+container, handle = select(Container), select(Handle)
+fixed_connection_query = the(
+    entity_matching(FixedConnection, world.connections)(
+        parent=container(name="Container1"),
+        child=handle(name="Handle1"),
+    )
+)
+
+answers = fixed_connection_query.evaluate()
+print(answers[container].name, answers[handle].name)
+```
+
+## Existential matches in collections with `match_any()`
+
+When matching a container-like attribute (for example, a list), use `match_any(pattern)` to express that
+at least one element of the collection should satisfy the given pattern.
+
+Below we add two simple view classes and build a small scene of drawers and a cabinet.
+
+```{code-cell} ipython3
+from krrood.entity_query_language.match import match_any
+
+# Build a simple set of views
+drawer1 = Drawer(handle=h1, container=c1)
+drawer2 = Drawer(handle=Handle("OtherHandle"), container=other_c)
+cabinet1 = Cabinet(container=c1, drawers=[drawer1, drawer2])
+cabinet2 = Cabinet(container=other_c, drawers=[drawer2])
+views = [drawer1, drawer2, cabinet1, cabinet2]
+
+# Query: find the cabinet that has any drawer from the set {drawer1, drawer2}
+cabinet_query = an(entity_matching(Cabinet, views)(drawers=match_any([drawer1, drawer2])))
+
+found_cabinets = list(cabinet_query.evaluate())
+assert len(found_cabinets) == 2
+print(found_cabinets[0].container.name, found_cabinets[0].drawers[0].handle.name)
+print(found_cabinets[1].container.name, found_cabinets[1].drawers[0].handle.name)
+```
+
+## Selecting elements from collections with `select_any()`
+
+If you want to retrieve a specific element from a collection attribute while matching, use `select_any(Type)`.
+It behaves like `match_any(Type)` but also selects the matched element so you can access it in the result.
+
+```{code-cell} ipython3
+from krrood.entity_query_language.match import select_any
+
+selected_drawers = select_any([drawer1, drawer2])
+# Query: find the cabinet that has any drawer from the set {drawer1, drawer2}
+cabinet_query = an(entity_matching(Cabinet, views)(drawers=selected_drawers))
+
+ans = list(cabinet_query.evaluate())
+assert len(ans) == 2
+print(ans)
+```
+
+## Selecting inner objects with `select()`
+
+Use `select(Type)` when you want the matched inner objects to appear in the result. The evaluation then
+returns a mapping from the selected variables to the concrete objects (a unification dictionary).
+
+```{code-cell} ipython3
+from krrood.entity_query_language.match import select
+
+container, handle = select(Container), select(Handle)
+fixed_connection_query = the(
+    entity_matching(FixedConnection, world.connections)(
+        parent=container(name="Container1"),
+        child=handle(name="Handle1"),
+    )
+)
+
+answers = fixed_connection_query.evaluate()
+print(answers[container].name, answers[handle].name)
+```
+
+## Existential matches in collections with `match_any()`
+
+When having multiple possible matches, and you care only if at least the attribute matches one possibility, use
+`match_any(IterableOfPossibleValues)` to express that
+at least one element of the collection should satisfy the given pattern.
+
+Below we add two simple view classes and build a small scene of drawers and a cabinet.
+
+```{code-cell} ipython3
+from krrood.entity_query_language.match import match_any
+
+# Build a simple set of views
+drawer1 = Drawer(handle=h1, container=c1)
+drawer2 = Drawer(handle=Handle("OtherHandle"), container=other_c)
+cabinet1 = Cabinet(container=c1, drawers=[drawer1, drawer2])
+cabinet2 = Cabinet(container=other_c, drawers=[drawer2])
+views = [drawer1, drawer2, cabinet1, cabinet2]
+
+# Query: find the cabinet that has any drawer from the set {drawer1, drawer2}
+cabinet_query = an(entity_matching(Cabinet, views)(drawers=match_any([drawer1, drawer2])))
+
+found_cabinets = list(cabinet_query.evaluate())
+assert len(found_cabinets) == 2
+print(found_cabinets[0].container.name, found_cabinets[0].drawers[0].handle.name)
+print(found_cabinets[1].container.name, found_cabinets[1].drawers[0].handle.name)
+```
+
+## Selecting elements from collections with `select_any()`
+
+If you want to retrieve a specific element from a collection attribute while matching, use `select_any(Type)`.
+It behaves like `match_any(Type)` but also selects the matched element so you can access it in the result.
+
+```{code-cell} ipython3
+from krrood.entity_query_language.match import select_any, entity_selection
+
+selected_drawers = select_any([drawer1, drawer2])
+# Query: find the cabinet that has any drawer from the set {drawer1, drawer2}
+cabinet = entity_selection(Cabinet, views)
+cabinet_query = an(cabinet(drawers=selected_drawers))
+
+ans = list(cabinet_query.evaluate())
+assert len(ans) == 2
+print(ans)
+```

examples/eql/predicate_and_symbolic_function.md

@@ -26,8 +26,9 @@ Lets first define our model and some sample data.
 from dataclasses import dataclass
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import entity, let, an, Symbol
+from krrood.entity_query_language.entity import entity, let, Symbol
 from krrood.entity_query_language.predicate import Predicate, symbolic_function
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass

examples/eql/result_quantifiers.md

@@ -27,7 +27,8 @@ from dataclasses import dataclass
 
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import entity, let, the, Symbol, an
+from krrood.entity_query_language.entity import entity, let, Symbol
+from krrood.entity_query_language.quantify_entity import an, the
 from krrood.entity_query_language.result_quantification_constraint import AtLeast, AtMost, Exactly, Range
 from krrood.entity_query_language.failures import MultipleSolutionFound, LessThanExpectedNumberOfSolutions, GreaterThanExpectedNumberOfSolutions
 
@@ -81,7 +82,7 @@ Below we reuse the same `World` and `Body` setup from above.
 The world contains exactly two bodies, so all the following examples will evaluate successfully.
 
 ```{code-cell} ipython3
-# Require at least two results
+# Require at least one result
 query = an(
     entity(body := let(Body, domain=world.bodies)),
     quantification=AtLeast(1),

examples/eql/writing_queries.md

@@ -35,14 +35,15 @@ This approach ensures that your class definitions remain pure and decoupled from
 outside the explicit symbolic context. Consequently, your classes can focus exclusively on their domain logic, 
 leading to better adherence to the [Single Responsibility Principle](https://realpython.com/solid-principles-python/#single-responsibility-principle-srp).
 
-Here is a query that does work due to the missing `let` statement:
+Here is a query example that finds all bodies in a world whose name starts with "B":
 
 ```{code-cell} ipython3
 from dataclasses import dataclass
 
 from typing_extensions import List
 
-from krrood.entity_query_language.entity import entity, an, let, Symbol
+from krrood.entity_query_language.entity import entity, let, Symbol
+from krrood.entity_query_language.quantify_entity import an
 
 
 @dataclass