Better match

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

@@ -25,8 +25,12 @@ 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
+from krrood.entity_query_language.match import (
+    match,
+    entity_matching,
 )
 from krrood.entity_query_language.predicate import HasType
 
@@ -123,3 +127,159 @@ 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 dataclasses import dataclass
+from typing_extensions import List
+from krrood.entity_query_language.match import match_any
+
+
+@dataclass
+class Drawer(Symbol):
+    handle: Handle
+    container: Container
+
+
+@dataclass
+class Cabinet(Symbol):
+    container: Container
+    drawers: List[Drawer]
+
+
+# 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])
+views = [drawer1, cabinet1]
+
+# Query: find the cabinet that has a drawer whose handle is named "Handle1"
+drawer_pattern = the(entity_matching(Drawer, views)(handle=match(Handle)(name="Handle1")))
+cabinet_query = the(entity_matching(Cabinet, views)(drawers=match_any(drawer_pattern)))
+
+found_cabinet = cabinet_query.evaluate()
+print(found_cabinet.container.name, found_cabinet.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_drawer = select_any(Drawer)
+cabinet_with_selected_drawer = the(
+    entity_matching(Cabinet, views)(
+        drawers=selected_drawer(handle=match(Handle)(name="Handle1"))
+    )
+)
+
+ans = cabinet_with_selected_drawer.evaluate()
+print(ans[selected_drawer].handle.name)
+```
+
+## 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 dataclasses import dataclass
+from typing_extensions import List
+from krrood.entity_query_language.match import match_any
+
+
+@dataclass
+class Drawer(Symbol):
+    handle: Handle
+    container: Container
+
+
+@dataclass
+class Cabinet(Symbol):
+    container: Container
+    drawers: List[Drawer]
+
+
+# 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])
+views = [drawer1, cabinet1]
+
+# Query: find the cabinet that has a drawer whose handle is named "Handle1"
+drawer_pattern = the(entity_matching(Drawer, views)(handle=match(Handle)(name="Handle1")))
+cabinet_query = the(entity_matching(Cabinet, views)(drawers=match_any(drawer_pattern)))
+
+found_cabinet = cabinet_query.evaluate()
+print(found_cabinet.container.name, found_cabinet.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_drawer = select_any(Drawer)
+cabinet_with_selected_drawer = the(
+    entity_matching(Cabinet, views)(
+        drawers=selected_drawer(handle=match(Handle)(name="Handle1"))
+    )
+)
+
+ans = cabinet_with_selected_drawer.evaluate()
+print(ans[selected_drawer].handle.name)
+```

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
 

examples/eql/writing_queries.md

@@ -42,7 +42,8 @@ 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

examples/eql/writing_rule_trees.md

@@ -24,7 +24,8 @@ Lets define our domain model and build a small world. We will then build a rule
 instances to the world.
 
 ```{code-cell} ipython3
-from krrood.entity_query_language.entity import entity, an, let, and_, Symbol, inference
+from krrood.entity_query_language.entity import entity, let, and_, Symbol, inference
+from krrood.entity_query_language.quantify_entity import an
 
 from krrood.entity_query_language.rule import refinement, alternative
 from krrood.entity_query_language.conclusion import Add