dbrownell-parserlib 0.7.0__tar.gz → 0.8.0__tar.gz

{dbrownell_parserlib-0.7.0 → dbrownell_parserlib-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dbrownell-parserlib
-Version: 0.7.0
+Version: 0.8.0
 Summary: Functionality useful when creating parsers.
 Author: Dave Brownell
 Author-email: Dave Brownell <github@DavidBrownell.com>

{dbrownell_parserlib-0.7.0 → dbrownell_parserlib-0.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbrownell-parserlib"
-version = "0.7.0"
+version = "0.8.0"
 #          ^^^^^
 # Wheel names will be generated according to this value. Do not manually modify this value; instead
 # update it according to committed changes by running this command from the root of the repository:

{dbrownell_parserlib-0.7.0 → dbrownell_parserlib-0.8.0}/src/dbrownell_ParserLib/__init__.py

@@ -12,8 +12,11 @@ from dbrownell_ParserLib.antlr import (
     SignificantWhitespaceAntlrVisitorMixin,
 )
 from dbrownell_ParserLib.errors import Error, PythonError
+from dbrownell_ParserLib.expression import Expression
 from dbrownell_ParserLib.location import Location
 from dbrownell_ParserLib.region import Region
+from dbrownell_ParserLib.terminal_expression import TerminalExpression
+from dbrownell_ParserLib.visitors import ExpressionVisitor, ExpressionVisitorHelper, VisitResult
 
 
 # ----------------------------------------------------------------------
@@ -24,11 +27,16 @@ __all__ = [
     "BuildAntlrGrammar",
     "CreateAntlrParser",
     "Error",
+    "Expression",
+    "ExpressionVisitor",
+    "ExpressionVisitorHelper",
     "InsignificantWhitespaceAntlrVisitorMixin",
     "Location",
     "PythonError",
     "Region",
     "SignificantWhitespaceAntlrVisitorMixin",
+    "TerminalExpression",
+    "VisitResult",
     "__version__",
 ]
 

{dbrownell_parserlib-0.7.0 → dbrownell_parserlib-0.8.0}/src/dbrownell_ParserLib/antlr/antlr_visitor_mixins.py

@@ -1,7 +1,7 @@
 """Various ANTLR visitor mixins that can be used to add functionality to the generated visitor classes."""
 
 from abc import ABC, abstractmethod
-from typing import cast, TYPE_CHECKING
+from typing import cast, override, TYPE_CHECKING
 
 import antlr4
 
@@ -70,6 +70,7 @@ class InsignificantWhitespaceAntlrVisitorMixin(AntlrVisitorMixinBase):
     """Mixin that adds functionality used for grammars that ignore insignificant whitespace."""
 
     # ----------------------------------------------------------------------
+    @override
     def CreateRegion(
         self,
         ctx: antlr4.ParserRuleContext,
@@ -106,7 +107,8 @@ class SignificantWhitespaceAntlrVisitorMixin(AntlrVisitorMixinBase):
         self._newline_token_string = newline_token_string
 
     # ----------------------------------------------------------------------
-    def CreateRegion(  # noqa: D102
+    @override
+    def CreateRegion(
         self,
         ctx: antlr4.ParserRuleContext,
     ) -> Region:

dbrownell_parserlib-0.8.0/src/dbrownell_ParserLib/expression.py

@@ -0,0 +1,288 @@
+# noqa: D100
+from collections.abc import Generator, Iterable
+from contextlib import contextmanager
+from dataclasses import dataclass, field, fields, InitVar
+from typing import Self, TYPE_CHECKING
+
+from dbrownell_Common.Types import extension, override
+
+from dbrownell_ParserLib.visitors import ExpressionVisitor, ExpressionVisitorHelper, VisitResult
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from dbrownell_ParserLib.region import Region
+
+
+# ----------------------------------------------------------------------
+@dataclass(eq=False)
+class Expression:
+    """Abstract base class for all expressions encountered during the parsing process."""
+
+    # ----------------------------------------------------------------------
+    # |
+    # |  Public Data
+    # |
+    # ----------------------------------------------------------------------
+    region__: Region
+    finalize: InitVar[bool] = field(kw_only=True, default=True)
+
+    parent__: Expression | None = field(init=False)
+
+    _unique_id: tuple[object, ...] | None = field(init=False)
+    _disabled: bool = field(init=False)
+
+    _finalize_func: Callable[[], None] = field(init=False)
+
+    # ----------------------------------------------------------------------
+    # |
+    # |  Public Methods
+    # |
+    # ----------------------------------------------------------------------
+    def __post_init__(
+        self,
+        finalize: bool,
+    ) -> None:
+        self.parent__ = None
+
+        self._unique_id = None
+        self._disabled = False
+
+        # ----------------------------------------------------------------------
+        def Finalize() -> None:
+            visitor = _UniqueIdVisitor(self)
+
+            self.Accept(visitor)
+
+            self._unique_id = visitor.unique_id
+
+        # ----------------------------------------------------------------------
+
+        self._finalize_func = Finalize
+
+        if finalize:
+            self._Finalize()
+
+    # ----------------------------------------------------------------------
+    @property
+    def unique_id__(self) -> tuple[object, ...]:
+        """A unique identifier for this expression, which can be used for caching and other purposes."""
+
+        assert self._unique_id is not None
+        return self._unique_id
+
+    @property
+    def is_disabled__(self) -> bool:
+        """Whether this expression is disabled, which can be used for caching and other purposes."""
+
+        return self._disabled
+
+    # ----------------------------------------------------------------------
+    def __hash__(self) -> int:
+        return hash(self.unique_id__)
+
+    # ----------------------------------------------------------------------
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Expression):
+            return False
+
+        return self.unique_id__ == other.unique_id__
+
+    # ----------------------------------------------------------------------
+    def __ne__(self, other: object) -> bool:
+        if not isinstance(other, Expression):
+            return True
+
+        return self.unique_id__ != other.unique_id__
+
+    # ----------------------------------------------------------------------
+    def Clone(self, **kwargs) -> Self:
+        """Create a copy of this expression, optionally overriding some of its fields."""
+
+        for field_value in fields(self.__class__):
+            if field_value.init and field_value.name != "finalize" and field_value.name not in kwargs:
+                kwargs[field_value.name] = getattr(self, field_value.name)
+
+        return self.__class__(**kwargs)
+
+    # ----------------------------------------------------------------------
+    def Disable(self) -> None:
+        """Disable this expression so that it doesn't participate in visitation."""
+
+        assert self.is_disabled__ is False
+        self._disabled = True
+
+    # ----------------------------------------------------------------------
+    def Accept(  # noqa: C901
+        self,
+        visitor: ExpressionVisitor,
+        *,
+        include_disabled: bool = False,
+    ) -> VisitResult:
+        """Accept a visitor for visitation of this expression and its children (if any)."""
+
+        if self.is_disabled__ and not include_disabled:
+            return VisitResult.Continue
+
+        with visitor.OnExpression(self) as expression_visit_result:
+            if expression_visit_result & VisitResult.Terminate:
+                return expression_visit_result
+
+            if expression_visit_result & VisitResult.SkipAll:
+                return VisitResult.Continue
+
+            method_name = f"On{self.__class__.__name__}"
+
+            method = getattr(visitor, method_name, None)
+            assert method is not None, method_name
+
+            with method(self) as method_visit_result:
+                if method_visit_result & VisitResult.Terminate:
+                    return method_visit_result
+
+                # Details
+                if not method_visit_result & VisitResult.SkipDetails:
+                    all_details = list(self._GenerateAcceptDetails())
+
+                    if all_details:
+                        with visitor.OnExpressionDetails(self) as details_visit_result:
+                            if details_visit_result & VisitResult.Terminate:
+                                return details_visit_result
+
+                            if not details_visit_result & VisitResult.SkipDetails:
+                                method_name_prefix = f"On{self.__class__.__name__}__"
+
+                                for detail_name, detail_value in all_details:
+                                    method_name = f"{method_name_prefix}{detail_name}"
+
+                                    method = getattr(visitor, method_name, None)
+                                    assert method is not None, method_name
+
+                                    detail_visit_result = method(
+                                        detail_value, include_disabled=include_disabled
+                                    )
+
+                                    if detail_visit_result & VisitResult.Terminate:
+                                        return detail_visit_result
+
+                                    if detail_visit_result & VisitResult.SkipDetails:
+                                        break
+
+                # Children
+                if not method_visit_result & VisitResult.SkipChildren:
+                    children_result = self._GetAcceptChildren()
+
+                    if children_result:
+                        children_name, children = children_result
+
+                        with visitor.OnExpressionChildren(
+                            self,
+                            children_name,
+                            children,
+                        ) as children_visit_result:
+                            if children_visit_result & VisitResult.Terminate:
+                                return children_visit_result
+
+                            if not children_visit_result & VisitResult.SkipChildren:
+                                for child in children:
+                                    child_accept_result = child.Accept(
+                                        visitor, include_disabled=include_disabled
+                                    )
+
+                                    if child_accept_result & VisitResult.Terminate:
+                                        return child_accept_result
+
+                                    if child_accept_result & VisitResult.SkipChildren:
+                                        break
+
+        return VisitResult.Continue
+
+    # ----------------------------------------------------------------------
+    # |
+    # |  Protected Types
+    # |
+    # ----------------------------------------------------------------------
+    _GenerateAcceptDetailsResultType = Generator[tuple[str, list[Self]]]
+    _GetAcceptChildrenResultType = tuple[str, Iterable[Self]] | None
+
+    # ----------------------------------------------------------------------
+    # |
+    # |  Protected Methods
+    # |
+    # ----------------------------------------------------------------------
+    def _Finalize(self) -> None:
+        self._finalize_func()
+
+    # ----------------------------------------------------------------------
+    # |
+    # |  Private Methods
+    # |
+    # ----------------------------------------------------------------------
+    @extension
+    def _GetTerminalUniqueId(self) -> tuple[object, ...]:
+        """Get a unique identifier for this expression that doesn't include any of its children."""
+
+        msg = "This functionality should be implemented by a terminal expression (i.e. an expression that doesn't have any children)."
+        raise Exception(msg)
+
+    # ----------------------------------------------------------------------
+    @extension
+    def _GenerateAcceptDetails(self) -> _GenerateAcceptDetailsResultType:
+        # Nothing by default
+        if False:
+            yield
+
+    # ----------------------------------------------------------------------
+    @extension
+    def _GetAcceptChildren(self) -> _GetAcceptChildrenResultType:
+        # Nothing by default
+        return None
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Private Types
+# |
+# ----------------------------------------------------------------------
+class _UniqueIdVisitor(ExpressionVisitorHelper):
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        root_expression: Expression,
+    ) -> None:
+        self._target_expression = root_expression
+
+        self._child_unique_ids: list[tuple[object, ...]] = []
+        self._result: tuple[object, ...] | None = None
+
+    # ----------------------------------------------------------------------
+    @property
+    def unique_id(self) -> tuple[object, ...]:
+        assert self._result is not None
+        return self._result
+
+    # ----------------------------------------------------------------------
+    @override
+    @contextmanager
+    def OnExpression(
+        self,
+        expression: Expression,
+    ) -> Generator[VisitResult]:
+        if expression is self._target_expression:
+            yield VisitResult.Continue
+
+            if not self._child_unique_ids:
+                result = expression._GetTerminalUniqueId()  # noqa: SLF001
+            else:
+                result = tuple(self._child_unique_ids)
+
+            assert self._result is None
+            self._result = (type(expression).__name__, *result)
+
+            return
+
+        self._child_unique_ids.append(expression.unique_id__)
+
+        # Do not parse the children of this expression as its unique id already takes that information
+        # into account.
+        yield VisitResult.SkipChildren

dbrownell_parserlib-0.8.0/src/dbrownell_ParserLib/terminal_expression.py

@@ -0,0 +1,21 @@
+# noqa: D100
+from dataclasses import dataclass
+from typing import override
+
+from dbrownell_ParserLib.expression import Expression
+
+
+# ----------------------------------------------------------------------
+@dataclass(eq=False)
+class TerminalExpression[T](Expression):
+    """Expression with a single value member, typically used with leaves in an abstract syntax tree."""
+
+    # ----------------------------------------------------------------------
+    value: T
+
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    @override
+    def _GetTerminalUniqueId(self) -> tuple[object, ...]:
+        return (self.value,)

dbrownell_parserlib-0.8.0/src/dbrownell_ParserLib/visitors.py

@@ -0,0 +1,160 @@
+"""Contains types related to Expression visitation."""
+
+import types
+
+from abc import ABC, abstractmethod
+from contextlib import contextmanager
+from enum import auto, Flag
+from typing import override, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterable
+
+    from dbrownell_ParserLib.expression import Expression
+
+
+# ----------------------------------------------------------------------
+class VisitResult(Flag):
+    """Result returned during visitation that controls the flow of the visitation process."""
+
+    Continue = 0
+    """Continue visiting the rest of the expressions as normal."""
+
+    SkipDetails = auto()
+    """Skip visiting the details of this expression, but continue visiting the rest of the expressions as normal."""
+
+    SkipChildren = auto()
+    """Skip visiting the children of this expression, but continue visiting the rest of the expressions as normal."""
+
+    Terminate = auto()
+    """Terminate the visitation process immediately."""
+
+    # Amalgamations
+    SkipAll = SkipDetails | SkipChildren
+
+
+# ----------------------------------------------------------------------
+class ExpressionVisitor(ABC):
+    """Abstract base class for a visitor that accepts Expressions."""
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    @contextmanager
+    def OnExpression(
+        self,
+        expression: Expression,
+    ) -> Generator[VisitResult]:
+        """Call for every expression."""
+
+        raise NotImplementedError("Abstract method")  # noqa: EM101  # pragma: no cover
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    @contextmanager
+    def OnExpressionDetails(
+        self,
+        expression: Expression,
+    ) -> Generator[VisitResult]:
+        """Call when visiting the details of an expression."""
+
+        raise NotImplementedError("Abstract method")  # noqa: EM101  # pragma: no cover
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    @contextmanager
+    def OnExpressionChildren(
+        self,
+        expression: Expression,
+        children_name: str,
+        children: Iterable[Expression],
+    ) -> Generator[VisitResult]:
+        """Call when visiting the children of an expression."""
+
+        raise NotImplementedError("Abstract method")  # noqa: EM101  # pragma: no cover
+
+    # ----------------------------------------------------------------------
+    # Derived classes should implement the following methods:
+    #
+    #   @contextmanager
+    #   def On<Expression Name>(self, expression: <Expression Name>) -> Generator[VisitResult]:
+    #       ...
+    #
+    #   def On<Expression Name>__<Detail Name>(self, expression_or_expressions: <Expression Name> | list[<Expression Name>], include_disabled: bool) -> VisitResult:
+    #       ...
+    #
+
+
+# ----------------------------------------------------------------------
+class ExpressionVisitorHelper(ExpressionVisitor):
+    """Base class that makes writing custom visitors easier by providing default behavior for visitation methods."""
+
+    # ----------------------------------------------------------------------
+    @override
+    @contextmanager
+    def OnExpression(
+        self,
+        expression: Expression,
+    ) -> Generator[VisitResult]:
+        yield VisitResult.Continue
+
+    # ----------------------------------------------------------------------
+    @override
+    @contextmanager
+    def OnExpressionDetails(
+        self,
+        expression: Expression,
+    ) -> Generator[VisitResult]:
+        yield VisitResult.Continue
+
+    # ----------------------------------------------------------------------
+    @override
+    @contextmanager
+    def OnExpressionChildren(
+        self,
+        expression: Expression,
+        children_name: str,
+        children: Iterable[Expression],
+    ) -> Generator[VisitResult]:
+        yield VisitResult.Continue
+
+    # ----------------------------------------------------------------------
+    def __getattr__(
+        self,
+        method_name: str,
+    ) -> object:
+        if method_name.endswith("Expression"):
+            return self.__class__._DefaultExpressionMethod  # noqa: SLF001
+
+        index = method_name.find("Expression__")
+        if index != -1 and index + len("Expression__") + 1 < len(method_name):
+            return types.MethodType(self.__class__._DefaultDetailMethod, self)  # noqa: SLF001
+
+        raise AttributeError(method_name)
+
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    @staticmethod
+    @contextmanager
+    def _DefaultExpressionMethod(*args, **kwargs) -> Generator[VisitResult]:  # noqa: ARG004
+        yield VisitResult.Continue
+
+    # ----------------------------------------------------------------------
+    def _DefaultDetailMethod(
+        self,
+        expression_or_expressions: Expression | list[Expression],
+        *,
+        include_disabled: bool,
+    ) -> VisitResult:
+        expressions: list[Expression] = (  # ty: ignore[invalid-assignment]
+            expression_or_expressions
+            if isinstance(expression_or_expressions, list)
+            else [expression_or_expressions]
+        )
+
+        for expression in expressions:
+            result = expression.Accept(self, include_disabled=include_disabled)
+            if result & VisitResult.Terminate:
+                return result
+
+        return VisitResult.Continue