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

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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "dbrownell-parserlib"
-version = "0.6.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.8.0/src/dbrownell_ParserLib/__init__.py

@@ -0,0 +1,44 @@
+# noqa: D104
+
+from importlib.metadata import version
+
+from dbrownell_ParserLib.antlr import (
+    AntlrParser,
+    AntlrParserException,
+    AntlrVisitorMixinBase,
+    BuildAntlrGrammar,
+    CreateAntlrParser,
+    InsignificantWhitespaceAntlrVisitorMixin,
+    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
+
+
+# ----------------------------------------------------------------------
+__all__ = [
+    "AntlrParser",
+    "AntlrParserException",
+    "AntlrVisitorMixinBase",
+    "BuildAntlrGrammar",
+    "CreateAntlrParser",
+    "Error",
+    "Expression",
+    "ExpressionVisitor",
+    "ExpressionVisitorHelper",
+    "InsignificantWhitespaceAntlrVisitorMixin",
+    "Location",
+    "PythonError",
+    "Region",
+    "SignificantWhitespaceAntlrVisitorMixin",
+    "TerminalExpression",
+    "VisitResult",
+    "__version__",
+]
+
+
+__version__ = version("dbrownell_ParserLib")

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

@@ -1,12 +1,20 @@
 # noqa: D104
 from dbrownell_ParserLib.antlr.build_antlr_grammar import BuildAntlrGrammar
 from dbrownell_ParserLib.antlr.antlr_parser import AntlrParser, AntlrParserException, CreateAntlrParser
+from dbrownell_ParserLib.antlr.antlr_visitor_mixins import (
+    AntlrVisitorMixinBase,
+    InsignificantWhitespaceAntlrVisitorMixin,
+    SignificantWhitespaceAntlrVisitorMixin,
+)
 
 
 # ----------------------------------------------------------------------
 __all__ = [
     "AntlrParser",
     "AntlrParserException",
+    "AntlrVisitorMixinBase",
     "BuildAntlrGrammar",
     "CreateAntlrParser",
+    "InsignificantWhitespaceAntlrVisitorMixin",
+    "SignificantWhitespaceAntlrVisitorMixin",
 ]

dbrownell_parserlib-0.8.0/src/dbrownell_ParserLib/antlr/antlr_visitor_mixins.py

@@ -0,0 +1,157 @@
+"""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, override, TYPE_CHECKING
+
+import antlr4
+
+from dbrownell_ParserLib.region import Location, Region
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+
+# ----------------------------------------------------------------------
+class AntlrVisitorMixinBase(ABC):
+    """Base class for visitor mixins. This class is not meant to be used directly, but rather to be inherited by other mixin classes."""
+
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        filename: Path,
+        on_progress_func: Callable[[int], None],
+        *,
+        is_included_file: bool,
+    ) -> None:
+        self.filename = filename
+        self.is_included_file = is_included_file
+
+        # Protected data
+        self._on_progress_func = on_progress_func
+        self._stack: list[object] = []
+
+        # Private data
+        self._current_line: int = 0
+
+    # ----------------------------------------------------------------------
+    @abstractmethod
+    def CreateRegion(
+        self,
+        ctx: antlr4.ParserRuleContext,
+    ) -> Region:
+        """Create a `Region` from the given context."""
+
+        raise NotImplementedError()  # pragma: no cover
+
+    # ----------------------------------------------------------------------
+    def GetChildren(self, ctx: antlr4.ParserRuleContext) -> list[object]:
+        """Return the results of visiting the children of the given context."""
+
+        prev_num_stack_items = len(self._stack)
+
+        cast(antlr4.ParseTreeVisitor, self).visitChildren(ctx)
+
+        results = self._stack[prev_num_stack_items:]
+        del self._stack[prev_num_stack_items:]
+
+        return results
+
+    # ----------------------------------------------------------------------
+    # |  Protected Methods
+    def _OnProgress(self, end_line: int) -> None:
+        if end_line > self._current_line:
+            self._current_line = end_line
+            self._on_progress_func(end_line)
+
+
+# ----------------------------------------------------------------------
+class InsignificantWhitespaceAntlrVisitorMixin(AntlrVisitorMixinBase):
+    """Mixin that adds functionality used for grammars that ignore insignificant whitespace."""
+
+    # ----------------------------------------------------------------------
+    @override
+    def CreateRegion(
+        self,
+        ctx: antlr4.ParserRuleContext,
+    ) -> Region:
+        """Create a `Region` from the given context."""
+
+        start_token = ctx.start
+        stop_token = ctx.stop
+
+        if start_token is None or stop_token is None:
+            msg = "Context does not have start or stop token"
+            raise ValueError(msg)
+
+        return Region(
+            self.filename,
+            Location(start_token.line, start_token.column),
+            Location(stop_token.line, stop_token.column + len(stop_token.text)),
+        )
+
+
+# ----------------------------------------------------------------------
+class SignificantWhitespaceAntlrVisitorMixin(AntlrVisitorMixinBase):
+    """Mixin that adds functionality used for grammars that treat whitespace as significant."""
+
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        dedent_token: int,
+        newline_token: int,
+        newline_token_string: str,
+    ) -> None:
+        self._dedent_token = dedent_token
+        self._newline_token = newline_token
+        self._newline_token_string = newline_token_string
+
+    # ----------------------------------------------------------------------
+    @override
+    def CreateRegion(
+        self,
+        ctx: antlr4.ParserRuleContext,
+    ) -> Region:
+        assert isinstance(ctx.start, antlr4.Token), ctx.start
+        assert isinstance(ctx.stop, antlr4.Token), ctx.stop
+
+        if ctx.stop.type == self._dedent_token:
+            stop_line = ctx.stop.line
+            stop_col = ctx.stop.column
+
+        elif ctx.stop.type == self._newline_token and ctx.stop.text == self._newline_token_string:
+            if ctx.stop.line == ctx.start.line:
+                # This is the scenario where the statement is followed by a dedent followed by another
+                # statement. We don't want the range of this item to overlap with the range of the
+                # next item, so use the values as they are, even though it means that a statement
+                # that terminates with a newline will not have the newline here.
+                stop_line = ctx.stop.line
+                stop_col = ctx.stop.column
+            else:
+                stop_line = ctx.stop.line
+                stop_col = ctx.stop.column if ctx.stop.column == 0 else ctx.start.column
+
+        else:
+            stop_line = ctx.stop.line
+
+            content = ctx.stop.text
+            lines = content.split("\n")
+
+            if ctx.stop.type == self._newline_token:
+                assert content.startswith("\n"), content
+                assert len(lines) == 2, lines  # noqa: PLR2004
+
+            stop_col = len(lines[-1])
+
+            if stop_line == ctx.stop.line:
+                stop_col += ctx.stop.column
+
+            stop_line += len(lines) - 1
+
+        self._OnProgress(stop_line)
+
+        return Region(
+            self.filename,
+            Location(ctx.start.line, ctx.start.column + 1),
+            Location(stop_line, stop_col),
+        )

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

dbrownell_parserlib-0.6.0/src/dbrownell_ParserLib/__init__.py

@@ -1,25 +0,0 @@
-# noqa: D104
-
-from importlib.metadata import version
-
-from dbrownell_ParserLib.antlr import AntlrParser, AntlrParserException, BuildAntlrGrammar, CreateAntlrParser
-from dbrownell_ParserLib.errors import Error, PythonError
-from dbrownell_ParserLib.location import Location
-from dbrownell_ParserLib.region import Region
-
-
-# ----------------------------------------------------------------------
-__all__ = [
-    "AntlrParser",
-    "AntlrParserException",
-    "BuildAntlrGrammar",
-    "CreateAntlrParser",
-    "Error",
-    "Location",
-    "PythonError",
-    "Region",
-    "__version__",
-]
-
-
-__version__ = version("dbrownell_ParserLib")