syncraft 0.2.5__py3-none-any.whl → 0.2.7__py3-none-any.whl

syncraft/syntax.py

@@ -6,13 +6,15 @@ from typing import (
 )
 from dataclasses import dataclass, field, replace
 from functools import reduce
-from syncraft.algebra import Algebra, Error, Either, Right, Left
-from syncraft.constraint import Bindable, FrozenDict
-from syncraft.ast import Then, ThenKind, Marked, Choice, Many, ChoiceKind, Nothing, Collect, E, Collector
+from syncraft.algebra import Algebra, Error, Right, Left, Incomplete
+from syncraft.cache import Cache
+from syncraft.constraint import Bindable
+from syncraft.ast import Then, ThenKind, Marked, Choice, Many, ChoiceKind, Nothing, Collect, E, Collector, SyncraftError
 from types import MethodType, FunctionType
 import keyword
-
-
+import re
+from enum import Enum
+from rich import print
 
 def valid_name(name: str) -> bool:
     return (name.isidentifier() 
@@ -32,56 +34,27 @@ S = TypeVar('S', bound=Bindable)  # State type
 @dataclass(frozen=True)
 class Description:
     name: Optional[str] = None
-    newline: Optional[str] = None
     fixity: Literal['infix', 'prefix', 'postfix'] = 'infix'
     parameter: Tuple[Any, ...] = field(default_factory=tuple)
 
     def update(self, 
                *,
-               newline: Optional[str] = None,
                name: Optional[str] = None,
                fixity: Optional[Literal['infix', 'prefix', 'postfix']] = None,
                parameter: Optional[Tuple[Any, ...]] = None) -> 'Description':
         return Description(
             name=name if name is not None else self.name,
-            newline= newline if newline is not None else self.newline,
             fixity=fixity if fixity is not None else self.fixity,
             parameter=parameter if parameter is not None else self.parameter
         )
         
-    def to_string(self, interested: Callable[[Any], bool]) -> Optional[str]:
-        if self.name is not None:
-            if self.fixity == 'infix':
-                assert len(self.parameter) == 2, "Expected exactly two parameters for infix operator"
-                left  = self.parameter[0].to_string(interested) if interested(self.parameter[0]) else '...'
-                right = self.parameter[1].to_string(interested) if interested(self.parameter[1]) else '...'
-                if self.parameter[1].meta.newline is not None:
-                    new = '\u2570' # '\u2936'
-                    return f"{left}\n{new} \"{self.parameter[1].meta.newline}\" {self.name} {right}"
-                return f"{left} {self.name} {right}"
-            elif self.fixity == 'prefix':
-                if len(self.parameter) == 0:
-                    return self.name
-                tmp = [x.to_string(interested) if interested(x) else '...' for x in self.parameter]
-                return f"{self.name}({','.join(str(x) for x in tmp)})" 
-            elif self.fixity == 'postfix':
-                if len(self.parameter) == 0:
-                    return self.name
-                tmp = [x.to_string(interested) if interested(x) else '...' for x in self.parameter]
-                return f"({','.join(str(x) for x in tmp)}).{self.name}" 
-            else:
-                return f"Invalid fixity: {self.fixity}"
-        return None
-
-
-
 
 @dataclass(frozen=True)
 class Syntax(Generic[A, S]):
     """
     The core signature of Syntax is take an Algebra Class and return an Algebra Instance.
     """
-    alg: Callable[[Type[Algebra[Any, Any]]], Algebra[A, S]]
+    alg: Callable[[Type[Algebra[Any, Any]], Cache[Any, Any]], Algebra[A, S]]
     meta: Description = field(default_factory=Description, repr=False)
 
     def algebra(self, name: str | MethodType | FunctionType, *args: Any, **kwargs: Any) -> Syntax[A, S]:
@@ -98,8 +71,8 @@ class Syntax(Generic[A, S]):
         Returns:
             A new Syntax reflecting the transformed algebra.
         """
-        def algebra_run(cls: Type[Algebra[Any, S]]) -> Algebra[Any, S]:
-            a = self.alg(cls)
+        def algebra_run(cls: Type[Algebra[Any, S]], cache: Cache[Any, Any]) -> Algebra[Any, S]:
+            a = self(cls, cache)
             if isinstance(name, str):
                 attr = getattr(a, name, None) or getattr(cls, name, None)
                 if attr is None:
@@ -124,16 +97,14 @@ class Syntax(Generic[A, S]):
     def as_(self, typ: Type[B]) -> B:
         return cast(typ, self)  # type: ignore
 
-    def __call__(self, alg: Type[Algebra[Any, Any]]) -> Algebra[A, S]:
-        return self.alg(alg)
+    def __call__(self, alg: Type[Algebra[Any, Any]], cache: Cache[Any, Any]) -> Algebra[A, S]:
+        return self.alg(alg, cache)
+
 
-    def to_string(self, interested: Callable[[Any], bool]) -> Optional[str]:
-        return self.meta.to_string(interested)
 
     def describe(
         self,
         *,
-        newline: Optional[str] = None,
         name: Optional[str] = None,
         fixity: Optional[Literal['infix', 'prefix', 'postfix']] = None,
         parameter: Optional[Tuple[Syntax[Any, S], ...]] = None,
@@ -141,12 +112,10 @@ class Syntax(Generic[A, S]):
         return self.__class__(
             alg=self.alg,
             meta=self.meta.update(
-                name=name, newline=newline, fixity=fixity, parameter=parameter
+                name=name, fixity=fixity, parameter=parameter
             ),
         )
 
-    def newline(self, info: str = '') -> Syntax[A, S]:
-        return self.describe(newline=info)
 
     ######################################################## value transformation ########################################################
     def map(self, f: Callable[[A], B]) -> Syntax[B, S]:
@@ -158,7 +127,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax yielding B with the same resulting state.
         """
-        return self.__class__(lambda cls: self.alg(cls).map(f), meta=self.meta)  # type: ignore
+        return self.__class__(lambda cls, cache: self(cls, cache).map(f), meta=self.meta)  # type: ignore
 
     def bimap(self, f: Callable[[A], B], i: Callable[[B], A]) -> Syntax[B, S]:
         """Bidirectionally map values with an inverse, keeping round-trip info.
@@ -173,7 +142,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax yielding B with state alignment preserved.
         """
-        return self.__class__(lambda cls: self.alg(cls).bimap(f, i), meta=self.meta)  # type: ignore
+        return self.__class__(lambda cls, cache: self(cls, cache).bimap(f, i), meta=self.meta)  # type: ignore
 
     def map_all(self, f: Callable[[A, S], Tuple[B, S]]) -> Syntax[B, S]:
         """Map both value and state on success.
@@ -184,7 +153,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax yielding transformed value and state.
         """
-        return self.__class__(lambda cls: self.alg(cls).map_all(f), meta=self.meta)  # type: ignore
+        return self.__class__(lambda cls, cache: self(cls, cache).map_all(f), meta=self.meta)  # type: ignore
 
     def map_error(self, f: Callable[[Optional[Any]], Any]) -> Syntax[A, S]:
         """Transform the error payload when this syntax fails.
@@ -195,7 +164,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax that preserves successes and maps failures.
         """
-        return self.__class__(lambda cls: self.alg(cls).map_error(f), meta=self.meta)
+        return self.__class__(lambda cls, cache: self(cls, cache).map_error(f), meta=self.meta)
 
     def map_state(self, f: Callable[[S], S]) -> Syntax[A, S]:
         """Map the input state before running this syntax.
@@ -206,7 +175,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax that runs with f(state).
         """
-        return self.__class__(lambda cls: self.alg(cls).map_state(f), meta=self.meta)
+        return self.__class__(lambda cls, cache: self(cls, cache).map_state(f), meta=self.meta)
 
     def flat_map(self, f: Callable[[A], Algebra[B, S]]) -> Syntax[B, S]:
         """Chain computations where the next step depends on the value.
@@ -217,7 +186,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax yielding the result of the chained computation.
         """
-        return self.__class__(lambda cls: self.alg(cls).flat_map(f))  # type: ignore
+        return self.__class__(lambda cls, cache: self(cls, cache).flat_map(f))  # type: ignore
 
     def many(self, *, at_least: int = 1, at_most: Optional[int] = None) -> Syntax[Many[A], S]:
         """Repeat this syntax and collect results into Many.
@@ -232,7 +201,7 @@ class Syntax(Generic[A, S]):
             Syntax producing Many of values.
         """
         return self.__class__(
-            lambda cls: self.alg(cls).many(at_least=at_least, at_most=at_most)  # type: ignore
+            lambda cls, cache: self(cls, cache).many(at_least=at_least, at_most=at_most)  # type: ignore
         ).describe(
             name='*', fixity='prefix', parameter=(self,)
         )  # type: ignore
@@ -283,13 +252,11 @@ class Syntax(Generic[A, S]):
                 ):
                     return Many(value=(left,) + tuple([b.right for b in bs]))
                 case _:
-                    raise ValueError(f"Bad data shape {a}")
+                    raise SyncraftError(f"Bad data shape {a}", offending=a, expect="Then(BOTH) with Choice on the right")
 
         def i(a: Many[A]) -> Then[A, Choice[Many[Then[B | None, A]], Optional[Nothing]]]:
             if not isinstance(a, Many) or len(a.value) < 1:
-                raise ValueError(
-                    f"sep_by inverse expect Many with at least one element, got {a}"
-                )
+                raise SyncraftError(f"sep_by inverse expect Many with at least one element, got {a}", offending=a, expect="Many with at least one element")
             if len(a.value) == 1:
                 return Then(
                     kind=ThenKind.BOTH,
@@ -349,7 +316,7 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax that marks downstream failures as committed.
         """
-        return self.__class__(lambda cls: self.alg(cls).cut())
+        return self.__class__(lambda cls, cache: self(cls, cache).cut())
 
     ###################################################### operator overloading #############################################
     def __floordiv__(self, other: Syntax[B, S]) -> Syntax[Then[A, B], S]:
@@ -363,14 +330,14 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax producing Then(left, right, kind=LEFT).
         """
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         ret: Syntax[Then[A, B], S] = self.__class__(
-            lambda cls: self.alg(cls).then_left(other.alg(cls))  # type: ignore
+            lambda cls, cache: self(cls, cache).then_left(other(cls, cache))  # type: ignore
         )  # type: ignore
         return ret.describe(name=ThenKind.LEFT.value, fixity='infix', parameter=(self, other)).as_(Syntax[Then[A, B], S])
 
     def __rfloordiv__(self, other: Syntax[B, S]) -> Syntax[Then[B, A], S]:
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         return other.__floordiv__(self)
 
     def __add__(self, other: Syntax[B, S]) -> Syntax[Then[A, B], S]:
@@ -384,14 +351,14 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax producing Then(left, right, kind=BOTH).
         """
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         ret: Syntax[Then[A, B], S] = self.__class__(
-            lambda cls: self.alg(cls).then_both(other.alg(cls))  # type: ignore
+            lambda cls, cache: self(cls, cache).then_both(other(cls, cache))  # type: ignore
         )  # type: ignore
         return ret.describe(name=ThenKind.BOTH.value, fixity='infix', parameter=(self, other)).as_(Syntax[Then[A, B], S])
 
     def __radd__(self, other: Syntax[B, S]) -> Syntax[Then[B, A], S]:
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         return other.__add__(self)
 
     def __rshift__(self, other: Syntax[B, S]) -> Syntax[Then[A, B], S]:
@@ -405,14 +372,14 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax producing Then(left, right, kind=RIGHT).
         """
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         ret: Syntax[Then[A, B], S] = self.__class__(
-            lambda cls: self.alg(cls).then_right(other.alg(cls))  # type: ignore
+            lambda cls, cache: self(cls, cache).then_right(other(cls, cache))  # type: ignore
         )  # type: ignore
         return ret.describe(name=ThenKind.RIGHT.value, fixity='infix', parameter=(self, other)).as_(Syntax[Then[A, B], S])
 
     def __rrshift__(self, other: Syntax[B, S]) -> Syntax[Then[B, A], S]:
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         return other.__rshift__(self)
 
     def __or__(self, other: Syntax[B, S]) -> Syntax[Choice[A, B], S]:
@@ -426,14 +393,14 @@ class Syntax(Generic[A, S]):
         Returns:
             Syntax producing Choice.LEFT or Choice.RIGHT.
         """
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         ret: Syntax[Choice[A, B], S] = self.__class__(
-            lambda cls: self.alg(cls).or_else(other.alg(cls))  # type: ignore
-        )  # type: ignore
+            lambda cls, cache: self(cls, cache).or_else(other(cls, cache))  # type: ignore
+        )  
         return ret.describe(name='|', fixity='infix', parameter=(self, other))
 
     def __ror__(self, other: Syntax[B, S]) -> Syntax[Choice[B, A], S]:
-        other = other if isinstance(other, Syntax) else self.lift(other).as_(Syntax[B, S])
+        other = other if isinstance(other, Syntax) else lift(other).as_(Syntax[B, S])
         return other.__or__(self)
 
     def __invert__(self) -> Syntax[Choice[A, Optional[Nothing]], S]:
@@ -515,34 +482,46 @@ class Syntax(Generic[A, S]):
             return m.value if isinstance(m, Marked) else m
 
         return self.bimap(mark_s, imark_s).describe(name=f'mark("{name}")', fixity='postfix', parameter=(self,))
+    
+def when(f: Callable[[], bool], then: Syntax[A, S], otherwise: Syntax[B, S]) -> Syntax[A | B, S]:
+    """
+    Conditionally selects between two syntax branches based on a predicate function.
 
-    def dump_error(self, formatter: Optional[Callable[[Error], None]] = None) -> Syntax[A, S]:
-        def dump_error_run(err: Any) -> Any:
-            if isinstance(err, Error) and formatter is not None:
-                formatter(err)
-            return err
-
-        return self.__class__(lambda cls: self.alg(cls).map_error(dump_error_run))
+    Args:
+        f: A callable returning a boolean to choose the branch.
+        then: Syntax to use if f() is True.
+        otherwise: Syntax to use if f() is False.
 
-    def debug(
-        self,
-        label: str,
-        formatter: Optional[
-            Callable[[Algebra[Any, S], S, Either[Any, Tuple[Any, S]]], None]
-        ] = None,
-    ) -> Syntax[A, S]:
-        return self.__class__(lambda cls: self.alg(cls).debug(label, formatter), meta=self.meta)
+    Returns:
+        A Syntax object representing the chosen branch.
+    """
+    return lazy(lambda: then if f() else otherwise).describe(name='when(?)', fixity='postfix', parameter=(then, otherwise)) # type: ignore
 
+def fail(error: Any) -> Syntax[Any, Any]:
+    """
+    Creates a syntax node that always fails with the given error.
 
-    
-def lazy(thunk: Callable[[], Syntax[A, S]]) -> Syntax[A, S]:
-    return Syntax(lambda cls: cls.lazy(lambda: thunk()(cls))).describe(name='lazy(?)', fixity='postfix') 
+    Args:
+        error: The error to raise or propagate.
 
-def fail(error: Any) -> Syntax[Any, Any]:
-    return Syntax(lambda alg: alg.fail(error)).describe(name=f'fail({error})', fixity='prefix')
+    Returns:
+        A Syntax object that always fails.
+    """
+    return Syntax(lambda alg, cache: alg.fail(error, cache=cache)).describe(name=f'fail({error})', fixity='prefix')
 
 def success(value: Any) -> Syntax[Any, Any]:
-    return Syntax(lambda alg: alg.success(value)).describe(name=f'success({value})', fixity='prefix')
+    """
+    Creates a syntax node that always succeeds with the given value.
+
+    Args:
+        value: The value to return on success.
+
+    Returns:
+        A Syntax object that always succeeds.
+    """
+    return Syntax(lambda alg, cache: alg.success(value, cache=cache)).describe(name=f'success({value})', fixity='prefix')
+
+
 
 def choice(*parsers: Syntax[Any, S]) -> Syntax[Any, S]:
     """
@@ -550,18 +529,126 @@ def choice(*parsers: Syntax[Any, S]) -> Syntax[Any, S]:
     """
     return reduce(lambda a, b: a | b, parsers) if len(parsers) > 0 else success(Nothing())
 
-def run(syntax: Syntax[A, S], alg: Type[Algebra[A, S]], use_cache:bool, *args: Any, **kwargs: Any) -> Tuple[Any, FrozenDict[str, Tuple[Any, ...]]] | Tuple[Any, None]:
+def run(*,
+        syntax: Syntax[A, S], 
+        alg: Type[Algebra[A, S]], 
+        use_cache:bool,         
+        **kwargs: Any) -> Tuple[Any, None | S]:
     """
     Run the syntax over the given algebra, and return the result and bind.
+
+    Args:
+        *args, **kwargs: the arguments passed to alg.state to construct the state object of the algebra.
     """
-    parser = syntax(alg)
-    input: Optional[S] = alg.state(*args, **kwargs)
+    parser = syntax(alg, Cache())
+    input: Optional[S] = alg.state(**kwargs)
     if input:
-        result = parser.run(input, use_cache=use_cache)
-        if isinstance(result, Right):
-            return result.value[0], result.value[1].binding.bound()
-        assert isinstance(result, Left), "Algebra must return Either[E, Tuple[A, S]]"
-        return result.value, None
+        gen = parser.run(input, use_cache=use_cache)
+        try:
+            result = next(gen)
+            while isinstance(result, Incomplete):
+                old_input = result.state
+                result = gen.send(old_input)
+            return Error(this=result, message="Algebra yield data that is not Incomplete"), None 
+        except StopIteration as e:
+            result = e.value                
+            if isinstance(result, Right):
+                return result.value[0], result.value[1]
+            elif isinstance(result, Left):
+                return result.value, None
+            else:
+                return Error(this=result, message="Algebra returned data that is not Left or Right"), None
+    return Error(this=None, message="Algebra failed to create initial state"), None
+
+
+def lazy(thunk: Callable[[], Syntax[A, S]]) -> Syntax[A, S]:
+    syntax: Optional[Syntax[A, S]] = None
+    algebra: Optional[Algebra[A, S]] = None
+    def syntax_lazy_run(cls: Type[Algebra[Any, S]], cache: Cache) -> Algebra[A, S]:
+        nonlocal syntax, algebra
+        # print('==' * 20, 'Syntax.lazy.syntax_lazy_run', '==' * 20)
+        # print('thunk', thunk, id(thunk))
+        # print('syntax', syntax, id(syntax))
+        # print('algebra', algebra, id(algebra))
+        if syntax is None:
+            syntax = thunk()
+        def algebra_lazy_f():
+            if syntax is None:
+                raise SyncraftError("Lazy thunk did not resolve to a Syntax", offending=thunk, expect="a Syntax")
+            return syntax(cls, cache)
+        if algebra is None:
+            algebra = cls.lazy(algebra_lazy_f, cache=cache)  
+        return algebra
+    return Syntax(syntax_lazy_run).describe(name='lazy(?)', fixity='postfix') 
+
+
+# def lazy(thunk: Callable[[], Syntax[A, S]]) -> Syntax[A, S]:
+#     resolved: Optional[Syntax[A, S]] = None
+    
+#     def run_lazy(cls: Type[Algebra[Any, S]], cache: Cache) -> Algebra[A, S]:
+#         nonlocal resolved
+#         if resolved is None:
+#             resolved = thunk()
+#         return resolved(cls, cache)  # reuse the same Algebra instance
+#     return Syntax(run_lazy)
+
+
+
+
+def token(*,
+          text: Optional[str] = None, 
+          token_type: Optional[Enum] = None,           
+          case_sensitive: bool = False,
+          regex: Optional[re.Pattern[str]] = None
+          ) -> Syntax[Any, Any]:
+    """Build a ``Syntax`` that matches a single token.
+
+    Convenience wrapper around ``Parser.token``. You can match by
+    type, exact text, or regex.
+
+    Args:
+        token_type: Expected token enum type.
+        text: Exact token text to match.
+        case_sensitive: Whether text matching respects case.
+        regex: Pattern to match token text.
+
+    Returns:
+        Syntax[Any, Any]: A syntax that matches one token.
+    """
+    token_type_txt = token_type.name if token_type is not None else None
+    token_value_txt = text if text is not None else None
+    msg = 'token(' + ','.join([x for x in [token_type_txt, token_value_txt, str(regex)] if x is not None]) + ')'
+    return Syntax(
+        lambda cls, cache: cls.factory('token', token_type=token_type, text=text, case_sensitive=case_sensitive, regex=regex, cache=cache)
+        ).describe(name=msg, fixity='prefix') 
+
+    
+
+def literal(lit: str) -> Syntax[Any, Any]:
+    """Match an exact literal string (case-sensitive)."""
+    return token(token_type=None, text=lit, case_sensitive=True)
+
+def regex(regex: re.Pattern[str] | str) -> Syntax[Any, Any]:
+    """Match a token whose text satisfies the given regular expression."""
+    if isinstance(regex, str):
+        regex = re.compile(regex)
+    return token(token_type=None, regex=regex, case_sensitive=True)
+
+def lift(value: Any)-> Syntax[Any, Any]:
+    """Lift a Python value into the nearest matching token syntax.
+
+    - ``str`` -> ``literal``
+    - ``re.Pattern`` -> ``token`` with regex
+    - ``Enum`` -> ``token`` with type
+    - otherwise -> succeed with the value
+    """
+    if isinstance(value, str):
+        return literal(value)
+    elif isinstance(value, re.Pattern):
+        return token(regex=value)
+    elif isinstance(value, Enum):
+        return token(token_type=value)
     else:
-        return Error(this=None, message="Algebra failed to create initial state"), None
+        return Syntax(lambda cls, cache: cls.success(value, cache=cache))
+