dbrownell-parserlib 0.10.2__tar.gz → 0.12.0__tar.gz

{dbrownell_parserlib-0.10.2 → dbrownell_parserlib-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dbrownell-parserlib
-Version: 0.10.2
+Version: 0.12.0
 Summary: Functionality useful when creating parsers.
 Author: Dave Brownell
 Author-email: Dave Brownell <github@DavidBrownell.com>
@@ -51,13 +51,14 @@ Description-Content-Type: text/markdown
 
 ### Key Features
 - **ANTLR Integration**: Streamlined wrapper around ANTLR for Python, handling grammar compilation and parser generation
-- **AST Representation**: Expression-based AST nodes with automatic parent-child relationship management
+- **AST Representation**: Element-based AST nodes with automatic parent-child relationship management
 - **Source Location Tracking**: Every AST node tracks its source file location (filename, line, column ranges) for detailed error reporting
 - **Visitor Pattern**: Flexible visitor pattern implementation with fine-grained traversal control
 - **Error Handling**: Rich error objects that associate messages with source locations and extract Python exception tracebacks
 - **Multi-threaded Parsing**: Built-in support for parsing multiple files concurrently
-- **Workspace Support**: Parse entire directory trees with customizable file filtering
-- **Whitespace Handling**: Mixins for both insignificant and significant whitespace grammars (e.g., Python-like indentation)
+- **Workspace Support**: Parse translation units organized across multiple workspace roots
+- **Whitespace Handling**: A single visitor mixin supports both insignificant and significant whitespace grammars (e.g., Python-like indentation); grammars that define `INDENT`/`DEDENT` tokens are detected automatically
+- **Multiline String Extraction**: Extract multiline string content that must be vertically aligned with its opening token, with detailed errors on misalignment
 
 ### How to use `dbrownell_ParserLib`
 
@@ -96,23 +97,23 @@ BuildAntlrGrammar(
 ```
 
 #### 3. Create Custom Visitor
-Implement a visitor that converts ANTLR parse trees to Expression objects:
+Implement a visitor that converts ANTLR parse trees to Element objects:
 
 ```python
 from dataclasses import dataclass
 
-from dbrownell_ParserLib.antlr.antlr_visitor_mixins import InsignificantWhitespaceAntlrVisitorMixin
-from dbrownell_ParserLib.expression import Expression
-from dbrownell_ParserLib.terminal_expression import TerminalExpression
+from dbrownell_ParserLib.antlr.antlr_visitor_mixin import AntlrVisitorMixin
+from dbrownell_ParserLib.element import Element
+from dbrownell_ParserLib.terminal_element import TerminalElement
 
 from CalculatorVisitor import CalculatorVisitor as GeneratedVisitor
 
 
 @dataclass(eq=False)
-class BinaryExpression(Expression):
-    left: Expression
-    operator: TerminalExpression[str]
-    right: Expression
+class BinaryExpression(Element):
+    left: Element
+    operator: TerminalElement[str]
+    right: Element
 
     def _GenerateAcceptDetails(self):
         yield "left", self.left
@@ -120,8 +121,10 @@ class BinaryExpression(Expression):
         yield "right", self.right
 
 
-class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisitor):
-    def visitExpr(self, ctx):
+class CalculatorVisitor(AntlrVisitorMixin, GeneratedVisitor):
+    def visitBinaryOp(self, ctx):
+        operator = TerminalElement[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText())
+
         children = self.GetChildren(ctx)
         assert len(children) == 2, children
 
@@ -129,20 +132,19 @@ class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisit
             BinaryExpression(
                 self.CreateRegion(ctx),
                 children[0],
-                TerminalExpression[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText()),
-
+                operator,
                 children[1],
             )
         )
 
     def visitNumber(self, ctx):
         self._stack.append(
-            TerminalExpression(self.CreateRegion(ctx), int(ctx.getText()))
+            TerminalElement[int](self.CreateRegion(ctx), int(ctx.getText()))
         )
 ```
 
 #### 4. Create Parser Instance
-Use `CreateAntlrParser` to build a callable parser:
+Use `CreateAntlrParser` to build a callable parser. Grammars that define `INDENT` and `DEDENT` tokens (significant whitespace) are detected automatically; no additional configuration is required.
 
 ```python
 from dbrownell_ParserLib.antlr.antlr_parser import CreateAntlrParser
@@ -185,12 +187,12 @@ Use the visitor pattern to process your AST:
 ```python
 from contextlib import contextmanager
 
-from dbrownell_ParserLib.visitors import ExpressionVisitorHelper, VisitResult
+from dbrownell_ParserLib.visitors import ElementVisitorHelper, VisitResult
 
 
-class EvaluatorVisitor(ExpressionVisitorHelper):
+class EvaluatorVisitor(ElementVisitorHelper):
     @contextmanager
-    def OnBinaryExpression(self, expression):
+    def OnBinaryExpression(self, element):
         # Process binary expressions
         yield VisitResult.Continue
 

{dbrownell_parserlib-0.10.2 → dbrownell_parserlib-0.12.0}/README.md

@@ -29,13 +29,14 @@
 
 ### Key Features
 - **ANTLR Integration**: Streamlined wrapper around ANTLR for Python, handling grammar compilation and parser generation
-- **AST Representation**: Expression-based AST nodes with automatic parent-child relationship management
+- **AST Representation**: Element-based AST nodes with automatic parent-child relationship management
 - **Source Location Tracking**: Every AST node tracks its source file location (filename, line, column ranges) for detailed error reporting
 - **Visitor Pattern**: Flexible visitor pattern implementation with fine-grained traversal control
 - **Error Handling**: Rich error objects that associate messages with source locations and extract Python exception tracebacks
 - **Multi-threaded Parsing**: Built-in support for parsing multiple files concurrently
-- **Workspace Support**: Parse entire directory trees with customizable file filtering
-- **Whitespace Handling**: Mixins for both insignificant and significant whitespace grammars (e.g., Python-like indentation)
+- **Workspace Support**: Parse translation units organized across multiple workspace roots
+- **Whitespace Handling**: A single visitor mixin supports both insignificant and significant whitespace grammars (e.g., Python-like indentation); grammars that define `INDENT`/`DEDENT` tokens are detected automatically
+- **Multiline String Extraction**: Extract multiline string content that must be vertically aligned with its opening token, with detailed errors on misalignment
 
 ### How to use `dbrownell_ParserLib`
 
@@ -74,23 +75,23 @@ BuildAntlrGrammar(
 ```
 
 #### 3. Create Custom Visitor
-Implement a visitor that converts ANTLR parse trees to Expression objects:
+Implement a visitor that converts ANTLR parse trees to Element objects:
 
 ```python
 from dataclasses import dataclass
 
-from dbrownell_ParserLib.antlr.antlr_visitor_mixins import InsignificantWhitespaceAntlrVisitorMixin
-from dbrownell_ParserLib.expression import Expression
-from dbrownell_ParserLib.terminal_expression import TerminalExpression
+from dbrownell_ParserLib.antlr.antlr_visitor_mixin import AntlrVisitorMixin
+from dbrownell_ParserLib.element import Element
+from dbrownell_ParserLib.terminal_element import TerminalElement
 
 from CalculatorVisitor import CalculatorVisitor as GeneratedVisitor
 
 
 @dataclass(eq=False)
-class BinaryExpression(Expression):
-    left: Expression
-    operator: TerminalExpression[str]
-    right: Expression
+class BinaryExpression(Element):
+    left: Element
+    operator: TerminalElement[str]
+    right: Element
 
     def _GenerateAcceptDetails(self):
         yield "left", self.left
@@ -98,8 +99,10 @@ class BinaryExpression(Expression):
         yield "right", self.right
 
 
-class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisitor):
-    def visitExpr(self, ctx):
+class CalculatorVisitor(AntlrVisitorMixin, GeneratedVisitor):
+    def visitBinaryOp(self, ctx):
+        operator = TerminalElement[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText())
+
         children = self.GetChildren(ctx)
         assert len(children) == 2, children
 
@@ -107,20 +110,19 @@ class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisit
             BinaryExpression(
                 self.CreateRegion(ctx),
                 children[0],
-                TerminalExpression[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText()),
-
+                operator,
                 children[1],
             )
         )
 
     def visitNumber(self, ctx):
         self._stack.append(
-            TerminalExpression(self.CreateRegion(ctx), int(ctx.getText()))
+            TerminalElement[int](self.CreateRegion(ctx), int(ctx.getText()))
         )
 ```
 
 #### 4. Create Parser Instance
-Use `CreateAntlrParser` to build a callable parser:
+Use `CreateAntlrParser` to build a callable parser. Grammars that define `INDENT` and `DEDENT` tokens (significant whitespace) are detected automatically; no additional configuration is required.
 
 ```python
 from dbrownell_ParserLib.antlr.antlr_parser import CreateAntlrParser
@@ -163,12 +165,12 @@ Use the visitor pattern to process your AST:
 ```python
 from contextlib import contextmanager
 
-from dbrownell_ParserLib.visitors import ExpressionVisitorHelper, VisitResult
+from dbrownell_ParserLib.visitors import ElementVisitorHelper, VisitResult
 
 
-class EvaluatorVisitor(ExpressionVisitorHelper):
+class EvaluatorVisitor(ElementVisitorHelper):
     @contextmanager
-    def OnBinaryExpression(self, expression):
+    def OnBinaryExpression(self, element):
         # Process binary expressions
         yield VisitResult.Continue
 

{dbrownell_parserlib-0.10.2 → dbrownell_parserlib-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbrownell-parserlib"
-version = "0.10.2"
+version = "0.12.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.10.2 → dbrownell_parserlib-0.12.0}/src/dbrownell_ParserLib/antlr/antlr_parser.py

@@ -102,6 +102,9 @@ class CreateVisitorFuncType(Protocol):
         on_progress_func: Callable[[int], None],
         *,
         is_included_file: bool,
+        parser_newline_string: str | None,
+        indent_token_type: int | None,
+        dedent_token_type: int | None,
     ) -> antlr4.ParseTreeVisitor: ...
 
 
@@ -117,9 +120,18 @@ def CreateAntlrParser(
     get_ast_func: Callable[[antlr4.Parser], antlr4.ParserRuleContext],
     custom_lexer_init_func: Callable[[antlr4.Lexer], None] | None = None,
     custom_parser_init_func: Callable[[antlr4.Parser], None] | None = None,
+    parser_newline_string: str | bool | None = None,  # noqa: FBT001
 ) -> AntlrParser:
     """Create an `AntlrParser` that uses the given code generated by ANTLR."""
 
+    indent_token_type = getattr(antlr_parser, "INDENT", None)
+    dedent_token_type = getattr(antlr_parser, "DEDENT", None)
+
+    if parser_newline_string is None and indent_token_type is not None and dedent_token_type is not None:
+        parser_newline_string = "newLine"
+    elif isinstance(parser_newline_string, bool):
+        parser_newline_string = None
+
     # ----------------------------------------------------------------------
     def CreateLexer(input_stream: antlr4.InputStream) -> antlr4.Lexer:
         lexer = antlr_lexer(input_stream)
@@ -145,6 +157,9 @@ def CreateAntlrParser(
         CreateParser,
         create_visitor_func,
         get_ast_func,
+        indent_token_type,
+        dedent_token_type,
+        parser_newline_string,
     )
 
 
@@ -162,12 +177,19 @@ class _AntlrParser(AntlrParser):
         create_parser_func: Callable[[antlr4.CommonTokenStream], antlr4.Parser],
         create_visitor_func: CreateVisitorFuncType,
         get_ast_func: Callable[[antlr4.Parser], antlr4.ParserRuleContext],
+        indent_token_type: int | None,
+        dedent_token_type: int | None,
+        parser_newline_string: str | None,
     ) -> None:
         self._create_lexer_func = create_lexer_func
         self._create_parser_func = create_parser_func
         self._create_visitor_func = create_visitor_func
         self._get_ast_func = get_ast_func
 
+        self._indent_token_type = indent_token_type
+        self._dedent_token_type = dedent_token_type
+        self._parser_newline_string = parser_newline_string
+
         self._execute_state: _AntlrParser._ExecuteState | None = None
 
     # ----------------------------------------------------------------------
@@ -433,6 +455,9 @@ class _AntlrParser(AntlrParser):
                         fullpath,
                         lambda line: cast(None, status.OnProgress(line, None)),
                         is_included_file=is_included_file,
+                        indent_token_type=self._indent_token_type,
+                        dedent_token_type=self._dedent_token_type,
+                        parser_newline_string=self._parser_newline_string,
                     )
 
                     ast = self._get_ast_func(parser)

dbrownell_parserlib-0.12.0/src/dbrownell_ParserLib/antlr/antlr_visitor_mixin.py

@@ -0,0 +1,150 @@
+# noqa: D100
+import re
+
+from typing import cast, TYPE_CHECKING
+
+import antlr4
+
+from dbrownell_ParserLib.region import Location, Region
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+
+# ----------------------------------------------------------------------
+class AntlrVisitorMixin:
+    """Mixin that provides common visitation functionality; it is used along side ANTLR-generated visitors."""
+
+    # ----------------------------------------------------------------------
+    def __init__(
+        self,
+        filename: Path,
+        on_progress_func: Callable[[int], None],
+        *,
+        is_included_file: bool,
+        parser_newline_string: str | None,
+        indent_token_type: int | None,
+        dedent_token_type: int | None,
+    ) -> None:
+        self.filename = filename
+        self.is_included_file = is_included_file
+
+        # Protected data
+        self._on_progress_func = on_progress_func
+        self._parser_newline_string = parser_newline_string
+        self._indent_token_type = indent_token_type
+        self._dedent_token_type = dedent_token_type
+        self._stack: list[object] = []
+
+        # Private data
+        self._current_line: int = 0
+        self._stop_token_regex = re.compile(r"^\r?\n[ \t]*$")
+
+    # ----------------------------------------------------------------------
+    def CreateRegion(
+        self,
+        ctx: antlr4.TerminalNode | antlr4.ParserRuleContext,
+    ) -> Region:
+        """Create a `Region` from the given context."""
+
+        if isinstance(ctx, antlr4.TerminalNode):
+            start_token = cast(antlr4.Token, ctx.symbol)  # ty: ignore[unresolved-attribute]
+            end_location = self._CreateEndLocation(start_token)
+        else:
+            start_token = ctx.start
+            stop_token = ctx.stop
+
+            assert ctx.children is not None
+            assert start_token is not None
+            assert stop_token is not None
+
+            end_location: Location | None = None
+
+            if self._parser_newline_string is not None:
+                if self._IsStopToken(stop_token):
+                    assert len(ctx.children) == 2, ctx.children  # noqa: PLR2004
+                    end_location = self._CreateEndLocation(start_token)
+                elif stop_token.type == self._dedent_token_type:
+                    end_location = Location(stop_token.line, stop_token.column + 1)
+
+            if end_location is None:
+                end_location = self._CreateEndLocation(stop_token)
+
+        assert start_token.line is not None
+        assert start_token.column is not None
+
+        region = Region(
+            self.filename,
+            Location(start_token.line, start_token.column + 1),
+            end_location,
+        )
+
+        self._OnProgress(region.end.line)
+
+        return region
+
+    # ----------------------------------------------------------------------
+    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)
+
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    @staticmethod
+    def _CreateEndLocation(token: antlr4.Token) -> Location:
+        assert token.text is not None
+        assert token.line is not None
+        assert token.column is not None
+
+        return CreateEndLocation(token.text, token.line, token.column + 1)
+
+    # ----------------------------------------------------------------------
+    def _IsStopToken(self, token: antlr4.Token) -> bool:
+        assert token.text is not None
+
+        return (
+            token.text == self._parser_newline_string or self._stop_token_regex.match(token.text) is not None
+        )
+
+
+# ----------------------------------------------------------------------
+def CreateEndLocation(text: str, line: int, column: int) -> Location:
+    """Create a `Location` based on the text and current line and column."""
+
+    # Note that this function will not be invoked outside of this file; it is implemented as a
+    # function so that it can be exercised by automated tests.
+
+    assert line > 0, line
+    assert column > 0, column
+
+    lines = text.splitlines()
+
+    last_nonblank_line = None
+
+    for line_index, line_text in enumerate(lines):
+        if line_text.strip():
+            last_nonblank_line = line_index
+
+    assert last_nonblank_line is not None
+
+    if last_nonblank_line == 0:
+        return Location(line, column + len(lines[0]))
+
+    return Location(line + last_nonblank_line, len(lines[last_nonblank_line]) + 1)

dbrownell_parserlib-0.10.2/src/dbrownell_ParserLib/expression.py → dbrownell_parserlib-0.12.0/src/dbrownell_ParserLib/element.py

@@ -8,7 +8,7 @@ from typing import Self, TYPE_CHECKING
 
 from dbrownell_Common.Types import extension, override
 
-from dbrownell_ParserLib.visitors import ExpressionVisitor, ExpressionVisitorHelper, VisitResult
+from dbrownell_ParserLib.visitors import ElementVisitor, ElementVisitorHelper, VisitResult
 
 if TYPE_CHECKING:
     from dbrownell_ParserLib.region import Region
@@ -16,8 +16,8 @@ if TYPE_CHECKING:
 
 # ----------------------------------------------------------------------
 @dataclass(eq=False)
-class Expression:
-    """Abstract base class for all expressions encountered during the parsing process."""
+class Element:
+    """Abstract base class for all elements encountered during the parsing process."""
 
     # ----------------------------------------------------------------------
     # |
@@ -27,7 +27,7 @@ class Expression:
     region__: Region
     finalize: InitVar[bool] = field(kw_only=True, default=True)
 
-    parent__: weakref.ref[Expression] | None = field(init=False)
+    parent__: weakref.ref[Element] | None = field(init=False)
 
     _unique_id: tuple[object, ...] | None = field(init=False)
     _disabled: bool = field(init=False)
@@ -52,14 +52,14 @@ class Expression:
     # ----------------------------------------------------------------------
     @property
     def unique_id__(self) -> tuple[object, ...]:
-        """A unique identifier for this expression, which can be used for caching and other purposes."""
+        """A unique identifier for this element, 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."""
+        """Whether this element is disabled, which can be used for caching and other purposes."""
 
         return self._disabled
 
@@ -69,21 +69,21 @@ class Expression:
 
     # ----------------------------------------------------------------------
     def __eq__(self, other: object) -> bool:
-        if not isinstance(other, Expression):
+        if not isinstance(other, Element):
             return False
 
         return self.unique_id__ == other.unique_id__
 
     # ----------------------------------------------------------------------
     def __ne__(self, other: object) -> bool:
-        if not isinstance(other, Expression):
+        if not isinstance(other, Element):
             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."""
+        """Create a copy of this element, 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:
@@ -93,7 +93,7 @@ class Expression:
 
     # ----------------------------------------------------------------------
     def Disable(self) -> None:
-        """Disable this expression so that it doesn't participate in visitation."""
+        """Disable this element so that it doesn't participate in visitation."""
 
         assert self.is_disabled__ is False
         self._disabled = True
@@ -101,20 +101,20 @@ class Expression:
     # ----------------------------------------------------------------------
     def Accept(  # noqa: C901
         self,
-        visitor: ExpressionVisitor,
+        visitor: ElementVisitor,
         *,
         include_disabled: bool = False,
     ) -> VisitResult:
-        """Accept a visitor for visitation of this expression and its children (if any)."""
+        """Accept a visitor for visitation of this element 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
+        with visitor.OnElement(self) as element_visit_result:
+            if element_visit_result & VisitResult.Terminate:
+                return element_visit_result
 
-            if expression_visit_result & VisitResult.SkipAll:
+            if element_visit_result & VisitResult.SkipAll:
                 return VisitResult.Continue
 
             method_name = f"On{self.__class__.__name__}"
@@ -131,7 +131,7 @@ class Expression:
                     all_details = list(self._GenerateAcceptDetails())
 
                     if all_details:
-                        with visitor.OnExpressionDetails(self) as details_visit_result:
+                        with visitor.OnElementDetails(self) as details_visit_result:
                             if details_visit_result & VisitResult.Terminate:
                                 return details_visit_result
 
@@ -161,7 +161,7 @@ class Expression:
                     if children_result:
                         children_name, children = children_result
 
-                        with visitor.OnExpressionChildren(
+                        with visitor.OnElementChildren(
                             self,
                             children_name,
                             children,
@@ -210,9 +210,9 @@ class Expression:
     # ----------------------------------------------------------------------
     @extension
     def _GetTerminalUniqueId(self) -> tuple[object, ...]:
-        """Get a unique identifier for this expression that doesn't include any of its children."""
+        """Get a unique identifier for this element that doesn't include any of its children."""
 
-        msg = f"This functionality should be implemented by a terminal expression (i.e. an expression that doesn't have any children or expression details) [{self.__class__.__name__}]"
+        msg = f"This functionality should be implemented by a terminal element (i.e. an element that doesn't have any children or element details) [{self.__class__.__name__}]"
         raise Exception(msg)
 
     # ----------------------------------------------------------------------
@@ -234,15 +234,15 @@ class Expression:
 # |  Private Types
 # |
 # ----------------------------------------------------------------------
-class _FinalizeVisitor(ExpressionVisitorHelper):
-    """Visitor that visits the children of an expression, but not anything below that; it sets the unique_id__ of the target expression and sets its children's parent attribute to the correct value."""
+class _FinalizeVisitor(ElementVisitorHelper):
+    """Visitor that visits the children of an element, but not anything below that; it sets the unique_id__ of the target element and sets its children's parent attribute to the correct value."""
 
     # ----------------------------------------------------------------------
     def __init__(
         self,
-        root_expression: Expression,
+        root_element: Element,
     ) -> None:
-        self._target_expression = root_expression
+        self._target_element = root_element
 
         self._child_unique_ids: list[tuple[object, ...]] = []
         self._result: tuple[object, ...] | None = None
@@ -256,27 +256,27 @@ class _FinalizeVisitor(ExpressionVisitorHelper):
     # ----------------------------------------------------------------------
     @override
     @contextmanager
-    def OnExpression(
+    def OnElement(
         self,
-        expression: Expression,
+        element: Element,
     ) -> Generator[VisitResult]:
-        # This code will visit the children of the target expression, but not anything below that.
-        if expression is self._target_expression:
+        # This code will visit the children of the target element, but not anything below that.
+        if element is self._target_element:
             yield VisitResult.Continue
 
             if not self._child_unique_ids:
-                result = expression._GetTerminalUniqueId()  # noqa: SLF001
+                result = element._GetTerminalUniqueId()  # noqa: SLF001
             else:
                 result = tuple(self._child_unique_ids)
 
             assert self._result is None
-            self._result = (type(expression).__name__, *result)
+            self._result = (type(element).__name__, *result)
 
             return
 
-        expression.parent__ = weakref.ref(self._target_expression)
+        element.parent__ = weakref.ref(self._target_element)
 
-        self._child_unique_ids.append(expression.unique_id__)
+        self._child_unique_ids.append(element.unique_id__)
 
-        # Do not parse the grandchildren of the original target expression
+        # Do not parse the grandchildren of the original target element
         yield VisitResult.SkipChildren

dbrownell_parserlib-0.10.2/src/dbrownell_ParserLib/terminal_expression.py → dbrownell_parserlib-0.12.0/src/dbrownell_ParserLib/terminal_element.py

@@ -2,13 +2,13 @@
 from dataclasses import dataclass
 from typing import override
 
-from dbrownell_ParserLib.expression import Expression
+from dbrownell_ParserLib.element import Element
 
 
 # ----------------------------------------------------------------------
 @dataclass(eq=False)
-class TerminalExpression[T](Expression):
-    """Expression with a single value member, typically used with leaves in an abstract syntax tree."""
+class TerminalElement[T](Element):
+    """Element with a single value member, typically used with leaves in an abstract syntax tree."""
 
     # ----------------------------------------------------------------------
     value: T

{dbrownell_parserlib-0.10.2 → dbrownell_parserlib-0.12.0}/src/dbrownell_ParserLib/visitors.py

@@ -1,4 +1,4 @@
-"""Contains types related to Expression visitation."""
+"""Contains types related to Element visitation."""
 
 import types
 
@@ -10,7 +10,7 @@ from typing import override, TYPE_CHECKING
 if TYPE_CHECKING:
     from collections.abc import Generator, Iterable
 
-    from dbrownell_ParserLib.expression import Expression
+    from dbrownell_ParserLib.element import Element
 
 
 # ----------------------------------------------------------------------
@@ -18,13 +18,13 @@ 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."""
+    """Continue visiting the rest of the elements as normal."""
 
     SkipDetails = auto()
-    """Skip visiting the details of this expression, but continue visiting the rest of the expressions as normal."""
+    """Skip visiting the details of this element, but continue visiting the rest of the elements as normal."""
 
     SkipChildren = auto()
-    """Skip visiting the children of this expression, but continue visiting the rest of the expressions as normal."""
+    """Skip visiting the children of this element, but continue visiting the rest of the elements as normal."""
 
     Terminate = auto()
     """Terminate the visitation process immediately."""
@@ -34,41 +34,41 @@ class VisitResult(Flag):
 
 
 # ----------------------------------------------------------------------
-class ExpressionVisitor(ABC):
-    """Abstract base class for a visitor that accepts Expressions."""
+class ElementVisitor(ABC):
+    """Abstract base class for a visitor that accepts Elements."""
 
     # ----------------------------------------------------------------------
     @abstractmethod
     @contextmanager
-    def OnExpression(
+    def OnElement(
         self,
-        expression: Expression,
+        element: Element,
     ) -> Generator[VisitResult]:
-        """Call for every expression."""
+        """Call for every element."""
 
         raise NotImplementedError("Abstract method")  # noqa: EM101  # pragma: no cover
 
     # ----------------------------------------------------------------------
     @abstractmethod
     @contextmanager
-    def OnExpressionDetails(
+    def OnElementDetails(
         self,
-        expression: Expression,
+        element: Element,
     ) -> Generator[VisitResult]:
-        """Call when visiting the details of an expression."""
+        """Call when visiting the details of an element."""
 
         raise NotImplementedError("Abstract method")  # noqa: EM101  # pragma: no cover
 
     # ----------------------------------------------------------------------
     @abstractmethod
     @contextmanager
-    def OnExpressionChildren(
+    def OnElementChildren(
         self,
-        expression: Expression,
+        element: Element,
         children_name: str,
-        children: Iterable[Expression],
+        children: Iterable[Element],
     ) -> Generator[VisitResult]:
-        """Call when visiting the children of an expression."""
+        """Call when visiting the children of an element."""
 
         raise NotImplementedError("Abstract method")  # noqa: EM101  # pragma: no cover
 
@@ -76,44 +76,44 @@ class ExpressionVisitor(ABC):
     # Derived classes should implement the following methods:
     #
     #   @contextmanager
-    #   def On<Expression Name>(self, expression: <Expression Name>) -> Generator[VisitResult]:
+    #   def On<Element Name>(self, element: <Element Name>) -> Generator[VisitResult]:
     #       ...
     #
-    #   def On<Expression Name>__<Detail Name>(self, expression_or_expressions: <Expression Name> | list[<Expression Name>], include_disabled: bool) -> VisitResult:
+    #   def On<Element Name>__<Detail Name>(self, element_or_elements: <Element Name> | list[<Element Name>], include_disabled: bool) -> VisitResult:
     #       ...
     #
 
 
 # ----------------------------------------------------------------------
-class ExpressionVisitorHelper(ExpressionVisitor):
+class ElementVisitorHelper(ElementVisitor):
     """Base class that makes writing custom visitors easier by providing default behavior for visitation methods."""
 
     # ----------------------------------------------------------------------
     @override
     @contextmanager
-    def OnExpression(
+    def OnElement(
         self,
-        expression: Expression,
+        element: Element,
     ) -> Generator[VisitResult]:
         yield VisitResult.Continue
 
     # ----------------------------------------------------------------------
     @override
     @contextmanager
-    def OnExpressionDetails(
+    def OnElementDetails(
         self,
-        expression: Expression,
+        element: Element,
     ) -> Generator[VisitResult]:
         yield VisitResult.Continue
 
     # ----------------------------------------------------------------------
     @override
     @contextmanager
-    def OnExpressionChildren(
+    def OnElementChildren(
         self,
-        expression: Expression,
+        element: Element,
         children_name: str,
-        children: Iterable[Expression],
+        children: Iterable[Element],
     ) -> Generator[VisitResult]:
         yield VisitResult.Continue
 
@@ -128,7 +128,7 @@ class ExpressionVisitorHelper(ExpressionVisitor):
                 return types.MethodType(self.__class__._DefaultDetailMethod, self)  # noqa: SLF001
 
             if index == -1:
-                return self.__class__._DefaultExpressionMethod  # noqa: SLF001
+                return self.__class__._DefaultElementMethod  # noqa: SLF001
 
         raise AttributeError(method_name)
 
@@ -137,24 +137,22 @@ class ExpressionVisitorHelper(ExpressionVisitor):
     # ----------------------------------------------------------------------
     @staticmethod
     @contextmanager
-    def _DefaultExpressionMethod(*args, **kwargs) -> Generator[VisitResult]:  # noqa: ARG004
+    def _DefaultElementMethod(*args, **kwargs) -> Generator[VisitResult]:  # noqa: ARG004
         yield VisitResult.Continue
 
     # ----------------------------------------------------------------------
     def _DefaultDetailMethod(
         self,
-        expression_or_expressions: Expression | list[Expression],
+        element_or_elements: Element | list[Element],
         *,
         include_disabled: bool,
     ) -> VisitResult:
-        expressions: list[Expression] = (  # ty: ignore[invalid-assignment]
-            expression_or_expressions
-            if isinstance(expression_or_expressions, list)
-            else [expression_or_expressions]
+        elements: list[Element] = (  # ty: ignore[invalid-assignment]
+            element_or_elements if isinstance(element_or_elements, list) else [element_or_elements]
         )
 
-        for expression in expressions:
-            result = expression.Accept(self, include_disabled=include_disabled)
+        for element in elements:
+            result = element.Accept(self, include_disabled=include_disabled)
             if result & VisitResult.Terminate:
                 return result
 

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

@@ -1,169 +0,0 @@
-"""Various ANTLR visitor mixins that can be used to add functionality to the generated visitor classes."""
-
-import re
-
-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
-
-    # ----------------------------------------------------------------------
-    def CreateRegion(
-        self,
-        ctx: antlr4.TerminalNode | antlr4.ParserRuleContext,
-    ) -> Region:
-        """Create a `Region` from the given context."""
-
-        if isinstance(ctx, antlr4.TerminalNode):
-            token = cast(antlr4.Token, ctx.symbol)  # ty: ignore[unresolved-attribute]
-
-            assert token.column is not None
-
-            start_line = token.line
-            start_col = token.column + 1
-            end_line = token.line
-            end_col = token.column + 1 + len(token.text)
-
-            assert start_line is not None
-            assert end_line is not None
-
-            region = Region(
-                self.filename,
-                Location(start_line, start_col),
-                Location(end_line, end_col),
-            )
-        else:
-            region = self._CreateRegionFromRule(ctx)
-
-        self._OnProgress(region.end.line)
-
-        return region
-
-    # ----------------------------------------------------------------------
-    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)
-
-    # ----------------------------------------------------------------------
-    @abstractmethod
-    def _CreateRegionFromRule(self, ctx: antlr4.ParserRuleContext) -> Region: ...
-
-
-# ----------------------------------------------------------------------
-class InsignificantWhitespaceAntlrVisitorMixin(AntlrVisitorMixinBase):
-    """Mixin that adds functionality used for grammars that ignore insignificant whitespace."""
-
-    # ----------------------------------------------------------------------
-    def _CreateRegionFromRule(self, ctx: antlr4.ParserRuleContext) -> Region:
-        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)
-
-        start_line = start_token.line
-        start_col = start_token.column + 1
-        end_line = stop_token.line
-        end_col = stop_token.column + 1 + len(stop_token.text)
-
-        assert start_line is not None
-        assert end_line is not None
-
-        return Region(
-            self.filename,
-            Location(start_line, start_col),
-            Location(end_line, end_col),
-        )
-
-
-# ----------------------------------------------------------------------
-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
-
-        self._newline_indent_regex = re.compile(r"^\r?\n[ \t]*$")
-
-    # ----------------------------------------------------------------------
-    @override
-    def _CreateRegionFromRule(
-        self,
-        ctx: antlr4.ParserRuleContext,
-    ) -> Region:
-        assert isinstance(ctx.start, antlr4.Token), ctx.start
-        assert isinstance(ctx.stop, antlr4.Token), ctx.stop
-
-        if ctx.stop.text == self._newline_token_string or self._newline_indent_regex.match(ctx.stop.text):
-            assert ctx.stop.line == ctx.start.line or ctx.stop.line - 1 == ctx.start.line, (
-                ctx.start.line,
-                ctx.stop.line,
-            )
-
-            stop_line = ctx.start.line
-            stop_column = ctx.start.column + 1 + len(ctx.start.text)
-
-            return Region(
-                self.filename,
-                Location(ctx.start.line, ctx.start.column + 1),
-                Location(stop_line, stop_column),
-            )
-
-        return Region(
-            self.filename,
-            Location(ctx.start.line, ctx.start.column + 1),
-            Location(ctx.stop.line, ctx.stop.column + 1),
-        )