Parser combinators (#80)

* [WIP] Parser combinators

* test: add parser tests

* chore: update pyright

* feat: make parser an object

* refactor: simplify parser

* fix: more parsing and union fixes

* Fix tag names for single case unions

* fix: test

* refactor: call Returns result not ParseResult

- Add run that returns ParseResult

* cleanup

* feat: optimize pchar

- add parser str and repr

* chore: refactor code a bit

Author: dbrattli

.pre-commit-config.yaml

@@ -28,7 +28,7 @@ repos:
         language: node
         pass_filenames: false
         types: [python]
-        additional_dependencies: ["[email protected].243"]
+        additional_dependencies: ["[email protected].246"]
     repo: local
   - hooks:
     - id: jb-to-sphinx

README.md

@@ -114,6 +114,8 @@ on-demand as we go along.
     by [aioreactive](https://github.com/dbrattli/aioreactive).
 - **Data Modelling** - sum and product types
   - **TaggedUnion** - A tagged (discriminated) union type.
+- **Parser Combinators** - A recursive decent string parser combinator
+  library.
 - **Effects**: - lightweight computational expressions for Python. This
   is amazing stuff.
   - **option** - an optional world for working with optional values.
@@ -518,7 +520,7 @@ tagged union cases.
 
 ```python
 from dataclasses import dataclass
-from expression import TaggedUnion, Tag
+from expression import TaggedUnion, tag
 
 @dataclass
 class Rectangle:
@@ -530,8 +532,8 @@ class Circle:
     radius: float
 
 class Shape(TaggedUnion):
-    RECTANGLE = Tag[Rectangle]()
-    CIRCLE = Tag[Circle]()
+    RECTANGLE = tag(Rectangle)
+    CIRCLE = tag(Circle)
 
     @staticmethod
     def rectangle(width: float, length: float) -> Shape:

expression/__init__.py

@@ -56,6 +56,7 @@
     pipe3,
     result,
     snd,
+    tag,
     tailrec,
     tailrec_async,
     try_downcast,
@@ -113,6 +114,7 @@
     "tailrec",
     "tailrec_async",
     "Try",
+    "tag",
     "try_downcast",
     "upcast",
     "__version__",

expression/collections/block.py

@@ -412,6 +412,26 @@ def range(start: int, stop: int, step: int) -> Block[int]:
     def range(*args: int, **kw: int) -> Block[int]:
         return range(*args, **kw)
 
+    def reduce(
+        self,
+        reduction: Callable[[_TSource, _TSource], _TSource],
+    ) -> _TSource:
+        """Apply a function to each element of the collection, threading an
+        accumulator argument through the computation. Apply the function to
+        the first two elements of the list. Then feed this result into the
+        function along with the third element and so on. Return the final
+        result. If the input function is f and the elements are i0...iN then
+        computes f (... (f i0 i1) i2 ...) iN.
+
+        Args:
+            reduction: The function to reduce two list elements to a
+            single element.
+
+        Returns:
+            Returns the final state value.
+        """
+        return reduce(reduction)(self)
+
     @staticmethod
     def singleton(item: _TSource) -> Block[_TSource]:
         return singleton(item)
@@ -646,9 +666,10 @@ def cons(head: _TSource, tail: Block[_TSource]) -> Block[_TSource]:
 """The empty list."""
 
 
+@curry_flipped(1)
 def filter(
-    predicate: Callable[[_TSource], bool]
-) -> Callable[[Block[_TSource]], Block[_TSource]]:
+    source: Block[_TSource], predicate: Callable[[_TSource], bool]
+) -> Block[_TSource]:
     """Returns a new collection containing only the elements of the
     collection for which the given predicate returns `True`
 
@@ -659,20 +680,7 @@ def filter(
         Partially applied filter function.
     """
 
-    def _filter(source: Block[_TSource]) -> Block[_TSource]:
-        """Returns a new collection containing only the elements of the
-        collection for which the given predicate returns `True`
-
-        Args:
-            source: The input list.
-
-        Returns:
-            A list containing only the elements that satisfy the
-            predicate.
-        """
-        return source.filter(predicate)
-
-    return _filter
+    return source.filter(predicate)
 
 
 def fold(
@@ -788,6 +796,34 @@ def _map(source: Block[_TSource]) -> Block[_TResult]:
     return _map
 
 
+@curry_flipped(1)
+def reduce(
+    source: Block[_TSource],
+    reduction: Callable[[_TSource, _TSource], _TSource],
+) -> _TSource:
+    """Apply a function to each element of the collection, threading an
+    accumulator argument through the computation. Apply the function to
+    the first two elements of the list. Then feed this result into the
+    function along with the third element and so on. Return the final
+    result. If the input function is f and the elements are i0...iN then
+    computes f (... (f i0 i1) i2 ...) iN.
+
+    Args:
+        source: The input block (curried flipped)
+        reduction: The function to reduce two list elements to a single
+            element.
+
+    Returns:
+        Partially applied reduce function that takes the source block
+        and returns the final state value.
+    """
+
+    if source.is_empty():
+        raise ValueError("Collection was empty")
+
+    return source.tail().fold(reduction, source.head())
+
+
 @overload
 def starmap(
     mapper: Callable[[_T1, _T2], _TResult]

expression/core/__init__.py

@@ -34,7 +34,7 @@
     try_downcast,
     upcast,
 )
-from .union import SingleCaseUnion, Tag, TaggedUnion
+from .union import SingleCaseUnion, Tag, TaggedUnion, tag
 
 __all__ = [
     "aiotools",
@@ -90,6 +90,7 @@
     "tailrec",
     "tailrec_async",
     "Try",
+    "tag",
     "try_downcast",
     "upcast",
 ]

expression/core/match.py

@@ -142,17 +142,17 @@ def default(self) -> Iterable[_TSource]:
         ...
 
     @overload
-    def default(self, ret: Optional[_TResult]) -> _TResult:
+    def default(self, default_value: _TResult) -> _TResult:
         ...
 
-    def default(self, ret: Optional[Any] = None) -> Any:
+    def default(self, default_value: Any = None) -> Any:
         """Handle default case. Always matches."""
 
         if self.is_matched:
             return []
 
         self.is_matched = True
-        return [ret or self.value]
+        return default_value or [self.value]
 
     def __enter__(self) -> Case[_TSource]:
         """Enter context management."""

expression/core/option.py

@@ -24,6 +24,8 @@
     get_origin,
 )
 
+from typing_extensions import TypeGuard
+
 from .error import EffectError
 from .match import MatchMixin, SupportsMatch
 from .pipe import PipeMixin
@@ -128,12 +130,12 @@ def to_seq(self) -> Seq[_TSource]:
         raise NotImplementedError
 
     @abstractmethod
-    def is_some(self) -> bool:
+    def is_some(self) -> TypeGuard[Some[_TSource]]:
         """Returns true if the option is not Nothing."""
         raise NotImplementedError
 
     @abstractmethod
-    def is_none(self) -> bool:
+    def is_none(self) -> TypeGuard[Nothing_[_TSource]]:
         """Returns true if the option is Nothing."""
         raise NotImplementedError
 
@@ -189,11 +191,11 @@ def default_value(self, value: _TSource) -> _TSource:
         """
         return self._value
 
-    def is_some(self) -> bool:
+    def is_some(self) -> TypeGuard[Some[_TSource]]:
         """Returns `True`."""
         return True
 
-    def is_none(self) -> bool:
+    def is_none(self) -> TypeGuard[Nothing_[_TSource]]:
         """Returns `False`."""
         return False
 
@@ -307,11 +309,11 @@ def default_value(self, value: _TSource) -> _TSource:
         """
         return value
 
-    def is_some(self) -> bool:
+    def is_some(self) -> TypeGuard[Some[_TSource]]:
         """Returns `False`."""
         return False
 
-    def is_none(self) -> bool:
+    def is_none(self) -> TypeGuard[Nothing_[_TSource]]:
         """Returns `True`."""
         return True
 
@@ -447,11 +449,11 @@ def _default_value(option: Option[_TSource]) -> _TSource:
     return _default_value
 
 
-def is_none(option: Option[Any]) -> bool:
+def is_none(option: Option[_TSource]) -> TypeGuard[Nothing_[_TSource]]:
     return option.is_none()
 
 
-def is_some(option: Option[Any]) -> bool:
+def is_some(option: Option[_TSource]) -> TypeGuard[Some[_TSource]]:
     return option.is_some()
 
 

expression/core/result.py

@@ -16,6 +16,7 @@
     Callable,
     Dict,
     Generator,
+    Generic,
     Iterable,
     Iterator,
     List,
@@ -27,6 +28,8 @@
     overload,
 )
 
+from typing_extensions import TypeGuard
+
 from .error import EffectError
 from .match import Case, SupportsMatch
 from .pipe import PipeMixin
@@ -71,8 +74,8 @@ def _validate(result: Any, field: ModelField) -> Result[Any, Any]:
 class Result(
     Iterable[_TSource],
     PipeMixin,
-    SupportsMatch[Union[_TSource, _TError]],
     SupportsValidation["Result[_TSource, _TError]"],
+    Generic[_TSource, _TError],
     ABC,
 ):
     """The result abstract base class."""
@@ -124,13 +127,13 @@ def match(self, pattern: Any) -> Any:
         return case(pattern) if pattern else case
 
     @abstractmethod
-    def is_error(self) -> bool:
+    def is_error(self) -> TypeGuard[Error[_TSource, _TError]]:
         """Returns `True` if the result is an `Error` value."""
 
         raise NotImplementedError
 
     @abstractmethod
-    def is_ok(self) -> bool:
+    def is_ok(self) -> TypeGuard[Ok[_TSource, _TError]]:
         """Returns `True` if the result is an `Ok` value."""
 
         raise NotImplementedError
@@ -182,12 +185,12 @@ def map_error(
         function, or Ok if the input is Ok."""
         return Ok(self._value)
 
-    def is_error(self) -> bool:
+    def is_error(self) -> TypeGuard[Error[_TSource, _TError]]:
         """Returns `True` if the result is an `Ok` value."""
 
         return False
 
-    def is_ok(self) -> bool:
+    def is_ok(self) -> TypeGuard[Ok[_TSource, _TError]]:
         """Returns `True` if the result is an `Ok` value."""
 
         return True
@@ -236,7 +239,11 @@ def __init__(self, message: str):
         self.message = message
 
 
-class Error(ResultException, Result[_TSource, _TError]):
+class Error(
+    ResultException,
+    Result[_TSource, _TError],
+    SupportsMatch[_TError],
+):
     """The Error result case class."""
 
     def __init__(self, error: _TError) -> None:
@@ -262,11 +269,11 @@ def map_error(
         function, or Ok if the input is Ok."""
         return Error(mapper(self._error))
 
-    def is_error(self) -> bool:
+    def is_error(self) -> TypeGuard[Error[_TSource, _TError]]:
         """Returns `True` if the result is an `Ok` value."""
         return True
 
-    def is_ok(self) -> bool:
+    def is_ok(self) -> TypeGuard[Ok[_TSource, _TError]]:
         """Returns `True` if the result is an `Ok` value."""
         return False