dbrownell-parserlib 0.8.3__tar.gz → 0.9.0__tar.gz

{dbrownell_parserlib-0.8.3 → dbrownell_parserlib-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dbrownell-parserlib
-Version: 0.8.3
+Version: 0.9.0
 Summary: Functionality useful when creating parsers.
 Author: Dave Brownell
 Author-email: Dave Brownell <github@DavidBrownell.com>
@@ -61,16 +61,18 @@ Description-Content-Type: text/markdown
 
 ### How to use `dbrownell_ParserLib`
 
-The typical workflow for creating a parser with this library involves:
+The typical workflow for creating a parser with this library involves the following steps. For detailed examples, see the test files in the repository, particularly the end-to-end tests that demonstrate complete parsing workflows.
+
 
 #### 1. Define an ANTLR Grammar
 Create a `.g4` grammar file defining your language syntax:
+
 ```antlr
 grammar Calculator;
 
-expr : expr op=('*'|'/') expr   # BinaryOp
-     | expr op=('+'|'-') expr   # BinaryOp
-     | INT                       # Number
+expr : expr ('*'|'/') expr   # BinaryOp
+     | expr ('+'|'-') expr   # BinaryOp
+     | INT                   # Number
      ;
 
 INT : [0-9]+ ;
@@ -79,10 +81,13 @@ WS : [ \t\n\r]+ -> skip ;
 
 #### 2. Build the Grammar
 Use `BuildAntlrGrammar` to generate the lexer and parser:
+
 ```python
-from dbrownell_ParserLib import BuildAntlrGrammar
 from pathlib import Path
 
+from dbrownell_ParserLib import BuildAntlrGrammar
+
+
 BuildAntlrGrammar(
     dm,  # DoneManager instance
     Path("Calculator.g4"),
@@ -92,18 +97,19 @@ BuildAntlrGrammar(
 
 #### 3. Create Custom Visitor
 Implement a visitor that converts ANTLR parse trees to Expression objects:
+
 ```python
+from dataclasses import dataclass
+
 from dbrownell_ParserLib import (
     Expression,
     InsignificantWhitespaceAntlrVisitorMixin,
     TerminalExpression,
 )
-from dataclasses import dataclass
 
 from CalculatorVisitor import CalculatorVisitor as GeneratedVisitor
 
 
-
 @dataclass(eq=False)
 class BinaryExpression(Expression):
     left: Expression
@@ -115,30 +121,35 @@ class BinaryExpression(Expression):
         yield "operator", self.operator
         yield "right", self.right
 
-class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisitor):
 
-    def visitBinaryOp(self, ctx):
+class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisitor):
+    def visitExpr(self, ctx):
         children = self.GetChildren(ctx)
+        assert len(children) == 2, children
+
         self._stack.append(
             BinaryExpression(
                 self.CreateRegion(ctx),
                 children[0],
-                TerminalExpression[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText()),
+                TerminalExpression[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText()),
+
                 children[1],
             )
         )
 
     def visitNumber(self, ctx):
         self._stack.append(
-            TerminalExpression(self.CreateRegion(ctx), int(ctx.INT().getText()))
+            TerminalExpression(self.CreateRegion(ctx), int(ctx.getText()))
         )
 ```
 
 #### 4. Create Parser Instance
 Use `CreateAntlrParser` to build a callable parser:
+
 ```python
 from dbrownell_ParserLib import CreateAntlrParser
 
+
 parser = CreateAntlrParser(
     CalculatorLexer,
     CalculatorParser,
@@ -146,15 +157,14 @@ parser = CreateAntlrParser(
     lambda p: p.expr(),  # Entry point rule
 )
 ```
-from pathlib import Path
-
-from dbrownell_ParserLib import Error
-
-
 
 #### 5. Parse Files
 Parse single files, multiple files, or entire workspaces:
+
 ```python
+from dbrownell_ParserLib import Error
+
+
 # Parse a single file
 results = parser(dm, Path("input.txt"), None)
 
@@ -171,30 +181,25 @@ for filepath, result in results.items():
         # Process the AST
 ```
 
-from contextlib import contextmanager
-
 #### 6. Traverse the AST
 Use the visitor pattern to process your AST:
+
 ```python
-    @contextmanager
+from contextlib import contextmanager
 
 from dbrownell_ParserLib import ExpressionVisitorHelper, VisitResult
 
+
 class EvaluatorVisitor(ExpressionVisitorHelper):
-    def OnBinaryExpression(self, expression):
     @contextmanager
-
+    def OnBinaryExpression(self, expression):
         # Process binary expressions
         yield VisitResult.Continue
 
-        # Process terminal values
-        yield VisitResult.Continue
 
 ast.Accept(EvaluatorVisitor())
 ```
 
-For detailed examples, see the test files in the repository, particularly the end-to-end tests that demonstrate complete parsing workflows.
-
 <!-- Content below this delimiter will be copied to the generated README.md file. DO NOT REMOVE THIS COMMENT, as it will cause regeneration to fail. -->
 
 ## Installation

{dbrownell_parserlib-0.8.3 → dbrownell_parserlib-0.9.0}/README.md

@@ -39,16 +39,18 @@
 
 ### How to use `dbrownell_ParserLib`
 
-The typical workflow for creating a parser with this library involves:
+The typical workflow for creating a parser with this library involves the following steps. For detailed examples, see the test files in the repository, particularly the end-to-end tests that demonstrate complete parsing workflows.
+
 
 #### 1. Define an ANTLR Grammar
 Create a `.g4` grammar file defining your language syntax:
+
 ```antlr
 grammar Calculator;
 
-expr : expr op=('*'|'/') expr   # BinaryOp
-     | expr op=('+'|'-') expr   # BinaryOp
-     | INT                       # Number
+expr : expr ('*'|'/') expr   # BinaryOp
+     | expr ('+'|'-') expr   # BinaryOp
+     | INT                   # Number
      ;
 
 INT : [0-9]+ ;
@@ -57,10 +59,13 @@ WS : [ \t\n\r]+ -> skip ;
 
 #### 2. Build the Grammar
 Use `BuildAntlrGrammar` to generate the lexer and parser:
+
 ```python
-from dbrownell_ParserLib import BuildAntlrGrammar
 from pathlib import Path
 
+from dbrownell_ParserLib import BuildAntlrGrammar
+
+
 BuildAntlrGrammar(
     dm,  # DoneManager instance
     Path("Calculator.g4"),
@@ -70,18 +75,19 @@ BuildAntlrGrammar(
 
 #### 3. Create Custom Visitor
 Implement a visitor that converts ANTLR parse trees to Expression objects:
+
 ```python
+from dataclasses import dataclass
+
 from dbrownell_ParserLib import (
     Expression,
     InsignificantWhitespaceAntlrVisitorMixin,
     TerminalExpression,
 )
-from dataclasses import dataclass
 
 from CalculatorVisitor import CalculatorVisitor as GeneratedVisitor
 
 
-
 @dataclass(eq=False)
 class BinaryExpression(Expression):
     left: Expression
@@ -93,30 +99,35 @@ class BinaryExpression(Expression):
         yield "operator", self.operator
         yield "right", self.right
 
-class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisitor):
 
-    def visitBinaryOp(self, ctx):
+class CalculatorVisitor(InsignificantWhitespaceAntlrVisitorMixin, GeneratedVisitor):
+    def visitExpr(self, ctx):
         children = self.GetChildren(ctx)
+        assert len(children) == 2, children
+
         self._stack.append(
             BinaryExpression(
                 self.CreateRegion(ctx),
                 children[0],
-                TerminalExpression[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText()),
+                TerminalExpression[str](self.CreateRegion(ctx.children[1]), ctx.children[1].getText()),
+
                 children[1],
             )
         )
 
     def visitNumber(self, ctx):
         self._stack.append(
-            TerminalExpression(self.CreateRegion(ctx), int(ctx.INT().getText()))
+            TerminalExpression(self.CreateRegion(ctx), int(ctx.getText()))
         )
 ```
 
 #### 4. Create Parser Instance
 Use `CreateAntlrParser` to build a callable parser:
+
 ```python
 from dbrownell_ParserLib import CreateAntlrParser
 
+
 parser = CreateAntlrParser(
     CalculatorLexer,
     CalculatorParser,
@@ -124,15 +135,14 @@ parser = CreateAntlrParser(
     lambda p: p.expr(),  # Entry point rule
 )
 ```
-from pathlib import Path
-
-from dbrownell_ParserLib import Error
-
-
 
 #### 5. Parse Files
 Parse single files, multiple files, or entire workspaces:
+
 ```python
+from dbrownell_ParserLib import Error
+
+
 # Parse a single file
 results = parser(dm, Path("input.txt"), None)
 
@@ -149,30 +159,25 @@ for filepath, result in results.items():
         # Process the AST
 ```
 
-from contextlib import contextmanager
-
 #### 6. Traverse the AST
 Use the visitor pattern to process your AST:
+
 ```python
-    @contextmanager
+from contextlib import contextmanager
 
 from dbrownell_ParserLib import ExpressionVisitorHelper, VisitResult
 
+
 class EvaluatorVisitor(ExpressionVisitorHelper):
-    def OnBinaryExpression(self, expression):
     @contextmanager
-
+    def OnBinaryExpression(self, expression):
         # Process binary expressions
         yield VisitResult.Continue
 
-        # Process terminal values
-        yield VisitResult.Continue
 
 ast.Accept(EvaluatorVisitor())
 ```
 
-For detailed examples, see the test files in the repository, particularly the end-to-end tests that demonstrate complete parsing workflows.
-
 <!-- Content below this delimiter will be copied to the generated README.md file. DO NOT REMOVE THIS COMMENT, as it will cause regeneration to fail. -->
 
 ## Installation

{dbrownell_parserlib-0.8.3 → dbrownell_parserlib-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbrownell-parserlib"
-version = "0.8.3"
+version = "0.9.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.3 → dbrownell_parserlib-0.9.0}/src/dbrownell_ParserLib/__init__.py

@@ -4,14 +4,13 @@ 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.errors import CreateErrorType, Error, ErrorException, PythonError
 from dbrownell_ParserLib.expression import Expression
 from dbrownell_ParserLib.location import Location
 from dbrownell_ParserLib.region import Region
@@ -22,11 +21,12 @@ from dbrownell_ParserLib.visitors import ExpressionVisitor, ExpressionVisitorHel
 # ----------------------------------------------------------------------
 __all__ = [
     "AntlrParser",
-    "AntlrParserException",
     "AntlrVisitorMixinBase",
     "BuildAntlrGrammar",
     "CreateAntlrParser",
+    "CreateErrorType",
     "Error",
+    "ErrorException",
     "Expression",
     "ExpressionVisitor",
     "ExpressionVisitorHelper",

{dbrownell_parserlib-0.8.3 → dbrownell_parserlib-0.9.0}/src/dbrownell_ParserLib/antlr/__init__.py

@@ -1,6 +1,6 @@
 # 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_parser import AntlrParser, CreateAntlrParser
 from dbrownell_ParserLib.antlr.antlr_visitor_mixins import (
     AntlrVisitorMixinBase,
     InsignificantWhitespaceAntlrVisitorMixin,
@@ -11,7 +11,6 @@ from dbrownell_ParserLib.antlr.antlr_visitor_mixins import (
 # ----------------------------------------------------------------------
 __all__ = [
     "AntlrParser",
-    "AntlrParserException",
     "AntlrVisitorMixinBase",
     "BuildAntlrGrammar",
     "CreateAntlrParser",

{dbrownell_parserlib-0.8.3 → dbrownell_parserlib-0.9.0}/src/dbrownell_ParserLib/antlr/antlr_parser.py

@@ -17,7 +17,7 @@ from dbrownell_Common import ExecuteTasks
 from dbrownell_Common.Streams.DoneManager import DoneManager  # noqa: TC002
 from plum import dispatch, overload
 
-from dbrownell_ParserLib.errors import Error, PythonError
+from dbrownell_ParserLib.errors import Error, ErrorException, PythonError
 from dbrownell_ParserLib.region import Location, Region
 
 
@@ -25,17 +25,6 @@ from dbrownell_ParserLib.region import Location, Region
 # |
 # |  Public Types
 # |
-# ----------------------------------------------------------------------
-class AntlrParserException(Exception):  # noqa: N818
-    """Exception raised by the ANTLR parser or a visitor processing the AST."""
-
-    # ----------------------------------------------------------------------
-    def __init__(self, error: Error) -> None:
-        super().__init__(str(error))
-
-        self.error = error
-
-
 # ----------------------------------------------------------------------
 class AntlrParser(ABC):
     """Abstract base class for parsers created with `CreateAntlrParser`."""
@@ -451,7 +440,7 @@ class _AntlrParser(AntlrParser):
 
                     result = visitor
 
-                except AntlrParserException as ex:
+                except ErrorException as ex:
                     result = ex.error
                 except Exception as ex:
                     result = PythonError.Create(ex)
@@ -486,7 +475,7 @@ class _ErrorListener(antlr4.DiagnosticErrorListener):
 
         location = Location(line, column + 1)
         error = Error(f"Syntax error: {msg}", Region(self._source, location, location))
-        ex = AntlrParserException(error)
+        ex = ErrorException(error)
 
         if e is None:
             raise ex

dbrownell_parserlib-0.9.0/src/dbrownell_ParserLib/errors.py

@@ -0,0 +1,232 @@
+"""Contains functionality associated with errors and exceptions."""
+
+import re
+import textwrap
+import traceback
+
+from abc import abstractmethod
+from dataclasses import dataclass, field, InitVar, make_dataclass
+from enum import Enum
+from functools import cached_property, singledispatch
+from io import StringIO
+from pathlib import Path
+from typing import Self
+
+from dbrownell_ParserLib.region import Location, Region
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Public Types
+# |
+# ----------------------------------------------------------------------
+@dataclass(frozen=True)
+class Error:
+    """Base class for all errors generated by this library."""
+
+    # ----------------------------------------------------------------------
+    message: str
+
+    region_or_regions: InitVar[Region | list[Region]]
+    regions: list[Region] = field(init=False)
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    def CreateAsException(cls, *args, **kwargs) -> ErrorException:
+        """Create an `ErrorException` with an `Error` based on the provided arguments."""
+
+        return ErrorException(cls(*args, **kwargs))
+
+    # ----------------------------------------------------------------------
+    def __post_init__(self, region_or_regions: Region | list[Region]) -> None:
+        regions = [region_or_regions] if isinstance(region_or_regions, Region) else region_or_regions
+
+        if not regions:
+            msg = "At least one region must be provided"
+            raise ValueError(msg)
+
+        object.__setattr__(self, "regions", regions)
+
+    # ----------------------------------------------------------------------
+    def __str__(self) -> str:
+        return self._string
+
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    # ----------------------------------------------------------------------
+    @cached_property
+    def _string(self) -> str:
+        if len(self.regions) == 1 and "\n" not in self.message:
+            return f"{self.message} ({self.regions[0]})"
+
+        return textwrap.dedent(
+            """\
+            {}
+
+            {}
+            """,
+        ).format(self.message.rstrip(), "\n".join(f"    - {region}" for region in self.regions))
+
+
+# ----------------------------------------------------------------------
+@dataclass(frozen=True)
+class PythonError(Error):
+    """An `Error` based on a Python exception."""
+
+    # ----------------------------------------------------------------------
+    ex: Exception
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    def Create(
+        cls,
+        ex: Exception,
+    ) -> Self:
+        """Create a `PythonError` from a Python exception."""
+
+        regions: list[Region] = []
+
+        # I haven't been able to find a reliable way to get the exception's callstack so it is being
+        # parsed manually here. There has got to be a better way to do this.
+        sink = StringIO()
+
+        traceback.print_exception(ex, file=sink)
+        sink_str = sink.getvalue()
+
+        regex = re.compile(r"^\s*File \"(?P<filename>.+?)\", line (?P<line>\d+),.+$", re.MULTILINE)
+
+        for line in sink_str.splitlines():
+            match = regex.match(line)
+            if not match:
+                continue
+
+            line_number = int(match.group("line"))
+
+            regions.append(
+                Region(
+                    Path(match.group("filename")),
+                    Location(line_number, 1),
+                    Location(line_number, 1),
+                ),
+            )
+
+        regions.reverse()
+
+        return cls(
+            textwrap.dedent(
+                """\
+                Python Exception
+                ----------------
+                {}
+                """,
+            ).format(str(ex)),
+            regions,
+            ex,
+        )
+
+
+# ----------------------------------------------------------------------
+class ErrorException(Exception):  # noqa: N818
+    """Python exception that contains an `Error` object."""
+
+    # ----------------------------------------------------------------------
+    def __init__(self, error: Error) -> None:
+        super().__init__(str(error))
+        self.error = error
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Public Functions
+# |
+# ----------------------------------------------------------------------
+class _CreatedError(Error):
+    """Abstract base class for errors created via `CreateErrorType`."""
+
+    # ----------------------------------------------------------------------
+    @classmethod
+    @abstractmethod
+    def Create(cls, region_or_regions: Region | list[Region], *args, **kwargs) -> Self: ...
+
+
+# ----------------------------------------------------------------------
+def CreateErrorType(
+    message_template: str,
+    **error_attributes: type,
+) -> type[_CreatedError]:
+    """Create a new `Error` type with the provided message template and attributes.
+
+    Example:
+        MyError = CreateErrorType(
+            "This is an error with attribute {attr1} and {attr2}",
+            attr1=str,
+            attr2=int,
+        )
+
+    """
+
+    dynamic_fields_class = make_dataclass(
+        "DynamicFields",
+        error_attributes.items(),
+        bases=(_CreatedError,),
+        frozen=True,
+    )
+
+    # ----------------------------------------------------------------------
+    @dataclass(frozen=True)
+    class NewError(dynamic_fields_class):  # ty: ignore[unsupported-base]
+        # ----------------------------------------------------------------------
+        @classmethod
+        def Create(
+            cls,
+            region_or_regions: Region | list[Region],
+            *args,
+            **kwargs,
+        ) -> Self:
+            """Create a new instance of this error type."""
+
+            kvps = {k: _ArgToString(v) for k, v in zip(error_attributes.keys(), args, strict=False)}
+
+            for k, v in kwargs.items():
+                kvps[k] = _ArgToString(v)
+
+            return cls(
+                message_template.format(**kvps),  # ty: ignore[too-many-positional-arguments]
+                region_or_regions,
+                *args,
+                **kwargs,
+            )
+
+        # ----------------------------------------------------------------------
+        @classmethod
+        def CreateAsException(cls, *args, **kwargs) -> ErrorException:
+            return ErrorException(cls.Create(*args, **kwargs))
+
+    # ----------------------------------------------------------------------
+
+    return NewError
+
+
+# ----------------------------------------------------------------------
+# |
+# |  Private Functions
+# |
+# ----------------------------------------------------------------------
+@singledispatch
+def _ArgToString(value: object) -> str:
+    return str(value)
+
+
+@_ArgToString.register
+def _(value: str) -> str:
+    return value
+
+
+@_ArgToString.register
+def _(value: Enum) -> str:
+    return value.name
+
+
+@_ArgToString.register
+def _(value: list) -> str:
+    return "[{}]".format(", ".join("'{}'".format(_ArgToString(v)) for v in value))

dbrownell_parserlib-0.8.3/src/dbrownell_ParserLib/errors.py

@@ -1,112 +0,0 @@
-"""Contains functionality associated with errors and exceptions."""
-
-import re
-import textwrap
-import traceback
-
-from dataclasses import dataclass, field, InitVar
-from functools import cached_property
-from io import StringIO
-from pathlib import Path
-from typing import Self
-
-from dbrownell_ParserLib.region import Location, Region
-
-
-# ----------------------------------------------------------------------
-@dataclass(frozen=True)
-class Error:
-    """Base class for all errors generated by this library."""
-
-    # ----------------------------------------------------------------------
-    message: str
-
-    region_or_regions: InitVar[Region | list[Region]]
-    regions: list[Region] = field(init=False)
-
-    # ----------------------------------------------------------------------
-    def __post_init__(self, region_or_regions: Region | list[Region]) -> None:
-        regions = [region_or_regions] if isinstance(region_or_regions, Region) else region_or_regions
-
-        if not regions:
-            msg = "At least one region must be provided"
-            raise ValueError(msg)
-
-        object.__setattr__(self, "regions", regions)
-
-    # ----------------------------------------------------------------------
-    def __str__(self) -> str:
-        return self._string
-
-    # ----------------------------------------------------------------------
-    # ----------------------------------------------------------------------
-    # ----------------------------------------------------------------------
-    @cached_property
-    def _string(self) -> str:
-        if len(self.regions) == 1 and "\n" not in self.message:
-            return f"{self.message} ({self.regions[0]})"
-
-        return textwrap.dedent(
-            """\
-            {}
-
-            {}
-            """,
-        ).format(self.message.rstrip(), "\n".join(f"    - {region}" for region in self.regions))
-
-
-# ----------------------------------------------------------------------
-@dataclass(frozen=True)
-class PythonError(Error):
-    """An `Error` based on a Python exception."""
-
-    # ----------------------------------------------------------------------
-    ex: Exception
-
-    # ----------------------------------------------------------------------
-    @classmethod
-    def Create(
-        cls,
-        ex: Exception,
-    ) -> Self:
-        """Create a `PythonError` from a Python exception."""
-
-        regions: list[Region] = []
-
-        # I haven't been able to find a reliable way to get the exception's callstack so it is being
-        # parsed manually here. There has got to be a better way to do this.
-        sink = StringIO()
-
-        traceback.print_exception(ex, file=sink)
-        sink_str = sink.getvalue()
-
-        regex = re.compile(r"^\s*File \"(?P<filename>.+?)\", line (?P<line>\d+),.+$", re.MULTILINE)
-
-        for line in sink_str.splitlines():
-            match = regex.match(line)
-            if not match:
-                continue
-
-            line_number = int(match.group("line"))
-
-            regions.append(
-                Region(
-                    Path(match.group("filename")),
-                    Location(line_number, 1),
-                    Location(line_number, 1),
-                ),
-            )
-
-        regions.reverse()
-
-        return cls(
-            textwrap.dedent(
-                """\
-                Python Exception
-                ----------------
-                {}
-                """,
-            ).format(str(ex)),
-            regions,
-            ex,
-        )