removed function patterns.edge_matches_pattern

Author: telmomenezes

docs/manual/patterns.md

@@ -2,23 +2,37 @@
 
 Hyperbase implements language to define hyperedge patterns. These patterns are valid hyperedges themselves, and are defined with the help of special atoms: *wildcards* and *variables*. The former are useful for simple matching, while the latter allow for the extraction of specific parts of a hyperedge.
 
-## Searching with wildcards
+## Matching with wildcards
 
 The basic wildcard is `*`. It matches any hyperedge. It allows for the definition of patterns like this:
 
+```clojure
+(plays/P.so * *)
 ```
-(plays/P * *)
+
+Here's how it can be used to match hyperedges:
+
+```python
+from hyperbase import hedge
+pattern = hedge("(plays/P.so * *)")
+edge = hedge("(plays/P.so alice/C chess/C)")
+edge.match(pattern)  # returns [{}]
+edge = hedge("(likes/P.so alice/C chess/C)")
+edge.match(pattern)  # returns []
 ```
 
-We can use them to search the hypergraph for matching hyperedges. For example:
+Notice that, in the first case, a list with an empty dictionary is returned (`[{}]`) to indicate a match. We will see later how these dictionaries are used to return the values taken by pattern variables. In the second case the edge does not match the pattern, so an empty list is returned.
 
-```pycon
->>> from hyperbase import *
->>> hg = hgraph('example.db')
->>> hg.add('(plays/P.so alice/C chess/C)')
-(plays/P.so alice/C chess/C)
->>> list(hg.search('(plays/P.so * *)'))
-[(plays/P.so alice/C chess/C)]
+Since an empty list evaluates to False, this method can also be used as a boolean condition:
+
+```python
+from hyperbase import hedge
+pattern = hedge("(plays/P.so * *)")
+edge = hedge("(plays/P.so alice/C chess/C)")
+if edge.match(pattern):
+    print("match found")  # this is printed
+else:
+    print("no match")
 ```
 
 There are two more wildcards:
@@ -30,19 +44,19 @@ Furthermore, it is possible to specify types and roles in wildcards, as in any o
 
 It is possible to specify the optional presence of further arguments with the special atom `...`, which simply indicates that any number (including zero) hyperedges may be present at that point. For instance:
 
-```
+```clojure
 (plays/P * *)
 ```
 
 does not match:
 
-```
+```clojure
 (plays/P.sox alice/C chess/C (at/T (the/M club/C)))
 ```
 
 but this pattern does:
 
-```
+```clojure
 (plays/P * * ...)
 ```
 

src/hyperbase/patterns/__init__.py

@@ -1,20 +1,74 @@
+from __future__ import annotations
+
+from hyperbase.hyperedge import Hyperedge, hedge
 from hyperbase.patterns.common import common_pattern
-from hyperbase.patterns.entrypoints import match_pattern, edge_matches_pattern
+from hyperbase.patterns.matcher import Matcher
 from hyperbase.patterns.merge import merge_patterns
 from hyperbase.patterns.properties import (is_wildcard, is_pattern, is_full_pattern, is_fun_pattern,
                                             is_unordered_pattern)
-from hyperbase.patterns.utils import more_general
+from hyperbase.patterns.utils import _normalize_fun_patterns, more_general
 from hyperbase.patterns.variables import (all_variables, apply_vars, apply_variables, extract_vars_map, is_variable,
                                            contains_variable, remove_variables)
 
 
+def match_pattern(
+        edge: Hyperedge | str | list[object] | tuple[object, ...],
+        pattern: Hyperedge | str | list[object] | tuple[object, ...],
+        curvars: dict[str, Hyperedge] | None = None
+) -> list[dict[str, Hyperedge]]:
+    """
+    Matches an edge to a pattern. This means that, if the edge fits the
+    pattern, then a list of dictionaries will be returned. If the pattern
+    specifies variables, then the returned dictionaries will be populated
+    with the values for each pattern variable. There can be more than one
+    dictionary in the list if there are multiple ways of matching the
+    variables. If the pattern specifies no variables but the edge matches
+    it, then a list with a single empty dictionary is returned. If the
+    edge does not match the pattern, an empty list is returned.
+
+    Patterns are themselves edges. They can match families of edges
+    by employing special atoms:
+
+    - `\\*` represents a general wildcard (matches any entity)
+    - `.` represents an atomic wildcard (matches any atom)
+    - `(\\*)` represents an edge wildcard (matches any non-atom)
+    - `...` at the end indicates an open-ended pattern.
+
+    The wildcards (`\\*`, `.` and `(\\*)`) can be used to specify variables,
+    for example `\\*x`, `(CLAIM)` or `.ACTOR`. In case of a match, these
+    variables are assigned the hyperedge they correspond to. For example, consider
+    the edge:
+
+    `(is/P.so (my/Mp name/Cn) mary/Cp)`
+
+    - matching to the pattern: `(is/P.so (my/Mp name/Cn) \\*)`
+    produces the result: `[{}]`
+    - matching to the pattern: `(is/P.so (my/Mp name/Cn) \\*NAME)`
+    produces the result: `[{'NAME', mary/Cp}]`
+    - matching to the pattern: `(is/P.so . \\*NAME)`
+    produces the result: `[]`
+    """
+    _edge = hedge(edge)
+    _pattern = hedge(pattern)
+    if _edge is None or _pattern is None:
+        return []
+    _pattern = _normalize_fun_patterns(_pattern)
+
+    matcher: Matcher = Matcher(
+        edge=_edge,
+        pattern=_pattern,
+        curvars=curvars,
+    )
+
+    return matcher.results
+
+
 __all__ = [
     'all_variables',
     'apply_vars',
     'apply_variables',
     'common_pattern',
     'contains_variable',
-    'edge_matches_pattern',
     'extract_vars_map',
     'is_full_pattern',
     'is_fun_pattern',

src/hyperbase/patterns/counter.py

@@ -4,7 +4,6 @@
 
 from hyperbase import hedge
 from hyperbase.hyperedge import Hyperedge
-from hyperbase.patterns.entrypoints import edge_matches_pattern
 
 
 class PatternCounter:
@@ -34,22 +33,22 @@ def __init__(
 
     def _matches_expansions(self, edge: Hyperedge) -> bool:
         for expansion in self.expansions:
-            if edge_matches_pattern(edge, expansion):
+            if edge.match(expansion):
                 return True
         return False
 
     def _force_subtypes(self, edge: Hyperedge) -> bool:
         force_subtypes = False
         for st_pattern in self.match_subtypes:
-            if edge_matches_pattern(edge, st_pattern):
+            if edge.match(st_pattern):
                 force_subtypes = True
         return force_subtypes
 
     def _force_root_expansion(self, edge: Hyperedge) -> tuple[bool, bool]:
         force_root = False
         force_expansion = False
         for root_pattern in self.match_roots:
-            if edge_matches_pattern(edge, root_pattern):
+            if edge.match(root_pattern):
                 force_root = True
                 force_expansion = True
             elif _inner_edge_matches_pattern(edge, root_pattern):
@@ -141,13 +140,13 @@ def _edge2pattern(edge: Hyperedge, root: bool = False, subtype: bool = False) ->
         return hedge('{}.{}'.format(pattern, ar))
 
 
-def _inner_edge_matches_pattern(edge: Hyperedge, pattern: str, hg: object = None) -> bool:
+def _inner_edge_matches_pattern(edge: Hyperedge, pattern: str) -> bool:
     if edge.atom:
         return False
     for subedge in edge:
-        if edge_matches_pattern(subedge, pattern, hg=hg):
+        if subedge.match(pattern):
             return True
     for subedge in edge:
-        if _inner_edge_matches_pattern(subedge, pattern, hg=hg):
+        if _inner_edge_matches_pattern(subedge, pattern):
             return True
     return False

src/hyperbase/patterns/entrypoints.py

@@ -1,7 +1,7 @@
 import unittest
 
 from hyperbase import hedge
-from hyperbase.patterns import (match_pattern, edge_matches_pattern, is_wildcard, is_pattern, is_full_pattern,
+from hyperbase.patterns import (match_pattern, is_wildcard, is_pattern, is_full_pattern,
                                  apply_vars, is_unordered_pattern, common_pattern, more_general,
                                  is_variable, contains_variable, merge_patterns)
 
@@ -468,47 +468,6 @@ def test_match_pattern_debug_case_2(self):
                           'cellular/Ma/en usage/Cc.s/en))))', '(said/Pd.{sr}.<f----- */C *)'),
             [{}])
 
-    def test_edge_matches_pattern_simple1(self):
-        self.assertTrue(edge_matches_pattern(hedge('(a b)'), '(a b)'))
-
-    def test_edge_matches_pattern_simple2(self):
-        self.assertFalse(edge_matches_pattern(hedge('(a b)'), '(a a)'))
-
-    def test_edge_matches_pattern_wildcard1(self):
-        self.assertTrue(edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s great/C)'), '(is/Pd hyperbase/Cp.s *)'))
-
-    def test_edge_matches_pattern_wildcard2(self):
-        self.assertFalse(edge_matches_pattern(hedge('(was/Pd hyperbase/Cp.s great/C)'), '(is/Pd hyperbase/Cp.s *)'))
-
-    def test_edge_matches_pattern_atomic_wildcard1(self):
-        self.assertTrue(edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s great/C)'), '(is/Pd hyperbase/Cp.s .)'))
-
-    def test_edge_matches_pattern_atomic_wildcard2(self):
-        self.assertFalse(
-            edge_matches_pattern(hedge('(was/Pd hyperbase /Cp.s great/C)'), '(is/Pd.sc hyperbase/Cp.s .)'))
-
-    def test_edge_matches_pattern_atomic_wildcard3(self):
-        self.assertFalse(
-            edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s (fairly/M great/C))'), '(is/Pd hyperbase/Cp.s .)'))
-
-    def test_edge_matches_pattern_edge_wildcard1(self):
-        self.assertTrue(
-            edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s (fairly/M great/C))'), '(is/Pd hyperbase/Cp.s (*))'))
-
-    def test_edge_matches_pattern_edge_wildcard2(self):
-        self.assertFalse(edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s great/C)'), '(is/Pd hyperbase/Cp.s (*))'))
-
-    def test_edge_matches_pattern_open_ended1(self):
-        self.assertTrue(edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s great/C)'), '(is/Pd hyperbase/Cp.s * ...)'))
-
-    def test_edge_matches_pattern_open_ended2(self):
-        self.assertTrue(
-            edge_matches_pattern(hedge('(is/Pd hyperbase/Cp.s great/C extra/C)'), '(is/Pd hyperbase/Cp.s * ...)'))
-
-    def test_edge_matches_pattern_open_ended3(self):
-        self.assertFalse(
-            edge_matches_pattern(hedge('(is/Pd humanity/Cp.s great/C extra/C)'), '(is/Pd hyperbase/Cp.s * ...)'))
-
     def test_match_pattern_complex(self):
         s = ('(says/Pd.rr.|f--3s-/en (calls/Pr.so.|f--3s-/en */C (*/M (draconian/Ma/en (+/B.am/. coronavirus/Cc.s/en '
              'restrictions/Cc.p/en)))) */R)')