Add files using upload-large-folder tool

lib/python3.12/site-packages/annotated_types/__init__.py

@@ -0,0 +1,432 @@
+import math
+import sys
+import types
+from dataclasses import dataclass
+from datetime import tzinfo
+from typing import TYPE_CHECKING, Any, Callable, Iterator, Optional, SupportsFloat, SupportsIndex, TypeVar, Union
+
+if sys.version_info < (3, 8):
+    from typing_extensions import Protocol, runtime_checkable
+else:
+    from typing import Protocol, runtime_checkable
+
+if sys.version_info < (3, 9):
+    from typing_extensions import Annotated, Literal
+else:
+    from typing import Annotated, Literal
+
+if sys.version_info < (3, 10):
+    EllipsisType = type(Ellipsis)
+    KW_ONLY = {}
+    SLOTS = {}
+else:
+    from types import EllipsisType
+
+    KW_ONLY = {"kw_only": True}
+    SLOTS = {"slots": True}
+
+
+__all__ = (
+    'BaseMetadata',
+    'GroupedMetadata',
+    'Gt',
+    'Ge',
+    'Lt',
+    'Le',
+    'Interval',
+    'MultipleOf',
+    'MinLen',
+    'MaxLen',
+    'Len',
+    'Timezone',
+    'Predicate',
+    'LowerCase',
+    'UpperCase',
+    'IsDigits',
+    'IsFinite',
+    'IsNotFinite',
+    'IsNan',
+    'IsNotNan',
+    'IsInfinite',
+    'IsNotInfinite',
+    'doc',
+    'DocInfo',
+    '__version__',
+)
+
+__version__ = '0.7.0'
+
+
+T = TypeVar('T')
+
+
+# arguments that start with __ are considered
+# positional only
+# see https://peps.python.org/pep-0484/#positional-only-arguments
+
+
+class SupportsGt(Protocol):
+    def __gt__(self: T, __other: T) -> bool:
+        ...
+
+
+class SupportsGe(Protocol):
+    def __ge__(self: T, __other: T) -> bool:
+        ...
+
+
+class SupportsLt(Protocol):
+    def __lt__(self: T, __other: T) -> bool:
+        ...
+
+
+class SupportsLe(Protocol):
+    def __le__(self: T, __other: T) -> bool:
+        ...
+
+
+class SupportsMod(Protocol):
+    def __mod__(self: T, __other: T) -> T:
+        ...
+
+
+class SupportsDiv(Protocol):
+    def __div__(self: T, __other: T) -> T:
+        ...
+
+
+class BaseMetadata:
+    """Base class for all metadata.
+
+    This exists mainly so that implementers
+    can do `isinstance(..., BaseMetadata)` while traversing field annotations.
+    """
+
+    __slots__ = ()
+
+
+@dataclass(frozen=True, **SLOTS)
+class Gt(BaseMetadata):
+    """Gt(gt=x) implies that the value must be greater than x.
+
+    It can be used with any type that supports the ``>`` operator,
+    including numbers, dates and times, strings, sets, and so on.
+    """
+
+    gt: SupportsGt
+
+
+@dataclass(frozen=True, **SLOTS)
+class Ge(BaseMetadata):
+    """Ge(ge=x) implies that the value must be greater than or equal to x.
+
+    It can be used with any type that supports the ``>=`` operator,
+    including numbers, dates and times, strings, sets, and so on.
+    """
+
+    ge: SupportsGe
+
+
+@dataclass(frozen=True, **SLOTS)
+class Lt(BaseMetadata):
+    """Lt(lt=x) implies that the value must be less than x.
+
+    It can be used with any type that supports the ``<`` operator,
+    including numbers, dates and times, strings, sets, and so on.
+    """
+
+    lt: SupportsLt
+
+
+@dataclass(frozen=True, **SLOTS)
+class Le(BaseMetadata):
+    """Le(le=x) implies that the value must be less than or equal to x.
+
+    It can be used with any type that supports the ``<=`` operator,
+    including numbers, dates and times, strings, sets, and so on.
+    """
+
+    le: SupportsLe
+
+
+@runtime_checkable
+class GroupedMetadata(Protocol):
+    """A grouping of multiple objects, like typing.Unpack.
+
+    `GroupedMetadata` on its own is not metadata and has no meaning.
+    All of the constraints and metadata should be fully expressable
+    in terms of the `BaseMetadata`'s returned by `GroupedMetadata.__iter__()`.
+
+    Concrete implementations should override `GroupedMetadata.__iter__()`
+    to add their own metadata.
+    For example:
+
+    >>> @dataclass
+    >>> class Field(GroupedMetadata):
+    >>>     gt: float | None = None
+    >>>     description: str | None = None
+    ...
+    >>>     def __iter__(self) -> Iterable[object]:
+    >>>         if self.gt is not None:
+    >>>             yield Gt(self.gt)
+    >>>         if self.description is not None:
+    >>>             yield Description(self.gt)
+
+    Also see the implementation of `Interval` below for an example.
+
+    Parsers should recognize this and unpack it so that it can be used
+    both with and without unpacking:
+
+    - `Annotated[int, Field(...)]` (parser must unpack Field)
+    - `Annotated[int, *Field(...)]` (PEP-646)
+    """  # noqa: trailing-whitespace
+
+    @property
+    def __is_annotated_types_grouped_metadata__(self) -> Literal[True]:
+        return True
+
+    def __iter__(self) -> Iterator[object]:
+        ...
+
+    if not TYPE_CHECKING:
+        __slots__ = ()  # allow subclasses to use slots
+
+        def __init_subclass__(cls, *args: Any, **kwargs: Any) -> None:
+            # Basic ABC like functionality without the complexity of an ABC
+            super().__init_subclass__(*args, **kwargs)
+            if cls.__iter__ is GroupedMetadata.__iter__:
+                raise TypeError("Can't subclass GroupedMetadata without implementing __iter__")
+
+        def __iter__(self) -> Iterator[object]:  # noqa: F811
+            raise NotImplementedError  # more helpful than "None has no attribute..." type errors
+
+
+@dataclass(frozen=True, **KW_ONLY, **SLOTS)
+class Interval(GroupedMetadata):
+    """Interval can express inclusive or exclusive bounds with a single object.
+
+    It accepts keyword arguments ``gt``, ``ge``, ``lt``, and/or ``le``, which
+    are interpreted the same way as the single-bound constraints.
+    """
+
+    gt: Union[SupportsGt, None] = None
+    ge: Union[SupportsGe, None] = None
+    lt: Union[SupportsLt, None] = None
+    le: Union[SupportsLe, None] = None
+
+    def __iter__(self) -> Iterator[BaseMetadata]:
+        """Unpack an Interval into zero or more single-bounds."""
+        if self.gt is not None:
+            yield Gt(self.gt)
+        if self.ge is not None:
+            yield Ge(self.ge)
+        if self.lt is not None:
+            yield Lt(self.lt)
+        if self.le is not None:
+            yield Le(self.le)
+
+
+@dataclass(frozen=True, **SLOTS)
+class MultipleOf(BaseMetadata):
+    """MultipleOf(multiple_of=x) might be interpreted in two ways:
+
+    1. Python semantics, implying ``value % multiple_of == 0``, or
+    2. JSONschema semantics, where ``int(value / multiple_of) == value / multiple_of``
+
+    We encourage users to be aware of these two common interpretations,
+    and libraries to carefully document which they implement.
+    """
+
+    multiple_of: Union[SupportsDiv, SupportsMod]
+
+
+@dataclass(frozen=True, **SLOTS)
+class MinLen(BaseMetadata):
+    """
+    MinLen() implies minimum inclusive length,
+    e.g. ``len(value) >= min_length``.
+    """
+
+    min_length: Annotated[int, Ge(0)]
+
+
+@dataclass(frozen=True, **SLOTS)
+class MaxLen(BaseMetadata):
+    """
+    MaxLen() implies maximum inclusive length,
+    e.g. ``len(value) <= max_length``.
+    """
+
+    max_length: Annotated[int, Ge(0)]
+
+
+@dataclass(frozen=True, **SLOTS)
+class Len(GroupedMetadata):
+    """
+    Len() implies that ``min_length <= len(value) <= max_length``.
+
+    Upper bound may be omitted or ``None`` to indicate no upper length bound.
+    """
+
+    min_length: Annotated[int, Ge(0)] = 0
+    max_length: Optional[Annotated[int, Ge(0)]] = None
+
+    def __iter__(self) -> Iterator[BaseMetadata]:
+        """Unpack a Len into zone or more single-bounds."""
+        if self.min_length > 0:
+            yield MinLen(self.min_length)
+        if self.max_length is not None:
+            yield MaxLen(self.max_length)
+
+
+@dataclass(frozen=True, **SLOTS)
+class Timezone(BaseMetadata):
+    """Timezone(tz=...) requires a datetime to be aware (or ``tz=None``, naive).
+
+    ``Annotated[datetime, Timezone(None)]`` must be a naive datetime.
+    ``Timezone[...]`` (the ellipsis literal) expresses that the datetime must be
+    tz-aware but any timezone is allowed.
+
+    You may also pass a specific timezone string or tzinfo object such as
+    ``Timezone(timezone.utc)`` or ``Timezone("Africa/Abidjan")`` to express that
+    you only allow a specific timezone, though we note that this is often
+    a symptom of poor design.
+    """
+
+    tz: Union[str, tzinfo, EllipsisType, None]
+
+
+@dataclass(frozen=True, **SLOTS)
+class Unit(BaseMetadata):
+    """Indicates that the value is a physical quantity with the specified unit.
+
+    It is intended for usage with numeric types, where the value represents the
+    magnitude of the quantity. For example, ``distance: Annotated[float, Unit('m')]``
+    or ``speed: Annotated[float, Unit('m/s')]``.
+
+    Interpretation of the unit string is left to the discretion of the consumer.
+    It is suggested to follow conventions established by python libraries that work
+    with physical quantities, such as
+
+    - ``pint`` : <https://pint.readthedocs.io/en/stable/>
+    - ``astropy.units``: <https://docs.astropy.org/en/stable/units/>
+
+    For indicating a quantity with a certain dimensionality but without a specific unit
+    it is recommended to use square brackets, e.g. `Annotated[float, Unit('[time]')]`.
+    Note, however, ``annotated_types`` itself makes no use of the unit string.
+    """
+
+    unit: str
+
+
+@dataclass(frozen=True, **SLOTS)
+class Predicate(BaseMetadata):
+    """``Predicate(func: Callable)`` implies `func(value)` is truthy for valid values.
+
+    Users should prefer statically inspectable metadata, but if you need the full
+    power and flexibility of arbitrary runtime predicates... here it is.
+
+    We provide a few predefined predicates for common string constraints:
+    ``IsLower = Predicate(str.islower)``, ``IsUpper = Predicate(str.isupper)``, and
+    ``IsDigits = Predicate(str.isdigit)``. Users are encouraged to use methods which
+    can be given special handling, and avoid indirection like ``lambda s: s.lower()``.
+
+    Some libraries might have special logic to handle certain predicates, e.g. by
+    checking for `str.isdigit` and using its presence to both call custom logic to
+    enforce digit-only strings, and customise some generated external schema.
+
+    We do not specify what behaviour should be expected for predicates that raise
+    an exception.  For example `Annotated[int, Predicate(str.isdigit)]` might silently
+    skip invalid constraints, or statically raise an error; or it might try calling it
+    and then propagate or discard the resulting exception.
+    """
+
+    func: Callable[[Any], bool]
+
+    def __repr__(self) -> str:
+        if getattr(self.func, "__name__", "<lambda>") == "<lambda>":
+            return f"{self.__class__.__name__}({self.func!r})"
+        if isinstance(self.func, (types.MethodType, types.BuiltinMethodType)) and (
+            namespace := getattr(self.func.__self__, "__name__", None)
+        ):
+            return f"{self.__class__.__name__}({namespace}.{self.func.__name__})"
+        if isinstance(self.func, type(str.isascii)):  # method descriptor
+            return f"{self.__class__.__name__}({self.func.__qualname__})"
+        return f"{self.__class__.__name__}({self.func.__name__})"
+
+
+@dataclass
+class Not:
+    func: Callable[[Any], bool]
+
+    def __call__(self, __v: Any) -> bool:
+        return not self.func(__v)
+
+
+_StrType = TypeVar("_StrType", bound=str)
+
+LowerCase = Annotated[_StrType, Predicate(str.islower)]
+"""
+Return True if the string is a lowercase string, False otherwise.
+
+A string is lowercase if all cased characters in the string are lowercase and there is at least one cased character in the string.
+"""  # noqa: E501
+UpperCase = Annotated[_StrType, Predicate(str.isupper)]
+"""
+Return True if the string is an uppercase string, False otherwise.
+
+A string is uppercase if all cased characters in the string are uppercase and there is at least one cased character in the string.
+"""  # noqa: E501
+IsDigit = Annotated[_StrType, Predicate(str.isdigit)]
+IsDigits = IsDigit  # type: ignore  # plural for backwards compatibility, see #63
+"""
+Return True if the string is a digit string, False otherwise.
+
+A string is a digit string if all characters in the string are digits and there is at least one character in the string.
+"""  # noqa: E501
+IsAscii = Annotated[_StrType, Predicate(str.isascii)]
+"""
+Return True if all characters in the string are ASCII, False otherwise.
+
+ASCII characters have code points in the range U+0000-U+007F. Empty string is ASCII too.
+"""
+
+_NumericType = TypeVar('_NumericType', bound=Union[SupportsFloat, SupportsIndex])
+IsFinite = Annotated[_NumericType, Predicate(math.isfinite)]
+"""Return True if x is neither an infinity nor a NaN, and False otherwise."""
+IsNotFinite = Annotated[_NumericType, Predicate(Not(math.isfinite))]
+"""Return True if x is one of infinity or NaN, and False otherwise"""
+IsNan = Annotated[_NumericType, Predicate(math.isnan)]
+"""Return True if x is a NaN (not a number), and False otherwise."""
+IsNotNan = Annotated[_NumericType, Predicate(Not(math.isnan))]
+"""Return True if x is anything but NaN (not a number), and False otherwise."""
+IsInfinite = Annotated[_NumericType, Predicate(math.isinf)]
+"""Return True if x is a positive or negative infinity, and False otherwise."""
+IsNotInfinite = Annotated[_NumericType, Predicate(Not(math.isinf))]
+"""Return True if x is neither a positive or negative infinity, and False otherwise."""
+
+try:
+    from typing_extensions import DocInfo, doc  # type: ignore [attr-defined]
+except ImportError:
+
+    @dataclass(frozen=True, **SLOTS)
+    class DocInfo:  # type: ignore [no-redef]
+        """ "
+        The return value of doc(), mainly to be used by tools that want to extract the
+        Annotated documentation at runtime.
+        """
+
+        documentation: str
+        """The documentation string passed to doc()."""
+
+    def doc(
+        documentation: str,
+    ) -> DocInfo:
+        """
+        Add documentation to a type annotation inside of Annotated.
+
+        For example:
+
+        >>> def hi(name: Annotated[int, doc("The name of the user")]) -> None: ...
+        """
+        return DocInfo(documentation)

lib/python3.12/site-packages/annotated_types/test_cases.py

@@ -0,0 +1,151 @@
+import math
+import sys
+from datetime import date, datetime, timedelta, timezone
+from decimal import Decimal
+from typing import Any, Dict, Iterable, Iterator, List, NamedTuple, Set, Tuple
+
+if sys.version_info < (3, 9):
+    from typing_extensions import Annotated
+else:
+    from typing import Annotated
+
+import annotated_types as at
+
+
+class Case(NamedTuple):
+    """
+    A test case for `annotated_types`.
+    """
+
+    annotation: Any
+    valid_cases: Iterable[Any]
+    invalid_cases: Iterable[Any]
+
+
+def cases() -> Iterable[Case]:
+    # Gt, Ge, Lt, Le
+    yield Case(Annotated[int, at.Gt(4)], (5, 6, 1000), (4, 0, -1))
+    yield Case(Annotated[float, at.Gt(0.5)], (0.6, 0.7, 0.8, 0.9), (0.5, 0.0, -0.1))
+    yield Case(
+        Annotated[datetime, at.Gt(datetime(2000, 1, 1))],
+        [datetime(2000, 1, 2), datetime(2000, 1, 3)],
+        [datetime(2000, 1, 1), datetime(1999, 12, 31)],
+    )
+    yield Case(
+        Annotated[datetime, at.Gt(date(2000, 1, 1))],
+        [date(2000, 1, 2), date(2000, 1, 3)],
+        [date(2000, 1, 1), date(1999, 12, 31)],
+    )
+    yield Case(
+        Annotated[datetime, at.Gt(Decimal('1.123'))],
+        [Decimal('1.1231'), Decimal('123')],
+        [Decimal('1.123'), Decimal('0')],
+    )
+
+    yield Case(Annotated[int, at.Ge(4)], (4, 5, 6, 1000, 4), (0, -1))
+    yield Case(Annotated[float, at.Ge(0.5)], (0.5, 0.6, 0.7, 0.8, 0.9), (0.4, 0.0, -0.1))
+    yield Case(
+        Annotated[datetime, at.Ge(datetime(2000, 1, 1))],
+        [datetime(2000, 1, 2), datetime(2000, 1, 3)],
+        [datetime(1998, 1, 1), datetime(1999, 12, 31)],
+    )
+
+    yield Case(Annotated[int, at.Lt(4)], (0, -1), (4, 5, 6, 1000, 4))
+    yield Case(Annotated[float, at.Lt(0.5)], (0.4, 0.0, -0.1), (0.5, 0.6, 0.7, 0.8, 0.9))
+    yield Case(
+        Annotated[datetime, at.Lt(datetime(2000, 1, 1))],
+        [datetime(1999, 12, 31), datetime(1999, 12, 31)],
+        [datetime(2000, 1, 2), datetime(2000, 1, 3)],
+    )
+
+    yield Case(Annotated[int, at.Le(4)], (4, 0, -1), (5, 6, 1000))
+    yield Case(Annotated[float, at.Le(0.5)], (0.5, 0.0, -0.1), (0.6, 0.7, 0.8, 0.9))
+    yield Case(
+        Annotated[datetime, at.Le(datetime(2000, 1, 1))],
+        [datetime(2000, 1, 1), datetime(1999, 12, 31)],
+        [datetime(2000, 1, 2), datetime(2000, 1, 3)],
+    )
+
+    # Interval
+    yield Case(Annotated[int, at.Interval(gt=4)], (5, 6, 1000), (4, 0, -1))
+    yield Case(Annotated[int, at.Interval(gt=4, lt=10)], (5, 6), (4, 10, 1000, 0, -1))
+    yield Case(Annotated[float, at.Interval(ge=0.5, le=1)], (0.5, 0.9, 1), (0.49, 1.1))
+    yield Case(
+        Annotated[datetime, at.Interval(gt=datetime(2000, 1, 1), le=datetime(2000, 1, 3))],
+        [datetime(2000, 1, 2), datetime(2000, 1, 3)],
+        [datetime(2000, 1, 1), datetime(2000, 1, 4)],
+    )
+
+    yield Case(Annotated[int, at.MultipleOf(multiple_of=3)], (0, 3, 9), (1, 2, 4))
+    yield Case(Annotated[float, at.MultipleOf(multiple_of=0.5)], (0, 0.5, 1, 1.5), (0.4, 1.1))
+
+    # lengths
+
+    yield Case(Annotated[str, at.MinLen(3)], ('123', '1234', 'x' * 10), ('', '1', '12'))
+    yield Case(Annotated[str, at.Len(3)], ('123', '1234', 'x' * 10), ('', '1', '12'))
+    yield Case(Annotated[List[int], at.MinLen(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
+    yield Case(Annotated[List[int], at.Len(3)], ([1, 2, 3], [1, 2, 3, 4], [1] * 10), ([], [1], [1, 2]))
+
+    yield Case(Annotated[str, at.MaxLen(4)], ('', '1234'), ('12345', 'x' * 10))
+    yield Case(Annotated[str, at.Len(0, 4)], ('', '1234'), ('12345', 'x' * 10))
+    yield Case(Annotated[List[str], at.MaxLen(4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 5, ['b'] * 10))
+    yield Case(Annotated[List[str], at.Len(0, 4)], ([], ['a', 'bcdef'], ['a', 'b', 'c']), (['a'] * 5, ['b'] * 10))
+
+    yield Case(Annotated[str, at.Len(3, 5)], ('123', '12345'), ('', '1', '12', '123456', 'x' * 10))
+    yield Case(Annotated[str, at.Len(3, 3)], ('123',), ('12', '1234'))
+
+    yield Case(Annotated[Dict[int, int], at.Len(2, 3)], [{1: 1, 2: 2}], [{}, {1: 1}, {1: 1, 2: 2, 3: 3, 4: 4}])
+    yield Case(Annotated[Set[int], at.Len(2, 3)], ({1, 2}, {1, 2, 3}), (set(), {1}, {1, 2, 3, 4}))
+    yield Case(Annotated[Tuple[int, ...], at.Len(2, 3)], ((1, 2), (1, 2, 3)), ((), (1,), (1, 2, 3, 4)))
+
+    # Timezone
+
+    yield Case(
+        Annotated[datetime, at.Timezone(None)], [datetime(2000, 1, 1)], [datetime(2000, 1, 1, tzinfo=timezone.utc)]
+    )
+    yield Case(
+        Annotated[datetime, at.Timezone(...)], [datetime(2000, 1, 1, tzinfo=timezone.utc)], [datetime(2000, 1, 1)]
+    )
+    yield Case(
+        Annotated[datetime, at.Timezone(timezone.utc)],
+        [datetime(2000, 1, 1, tzinfo=timezone.utc)],
+        [datetime(2000, 1, 1), datetime(2000, 1, 1, tzinfo=timezone(timedelta(hours=6)))],
+    )
+    yield Case(
+        Annotated[datetime, at.Timezone('Europe/London')],
+        [datetime(2000, 1, 1, tzinfo=timezone(timedelta(0), name='Europe/London'))],
+        [datetime(2000, 1, 1), datetime(2000, 1, 1, tzinfo=timezone(timedelta(hours=6)))],
+    )
+
+    # Quantity
+
+    yield Case(Annotated[float, at.Unit(unit='m')], (5, 4.2), ('5m', '4.2m'))
+
+    # predicate types
+
+    yield Case(at.LowerCase[str], ['abc', 'foobar'], ['', 'A', 'Boom'])
+    yield Case(at.UpperCase[str], ['ABC', 'DEFO'], ['', 'a', 'abc', 'AbC'])
+    yield Case(at.IsDigit[str], ['123'], ['', 'ab', 'a1b2'])
+    yield Case(at.IsAscii[str], ['123', 'foo bar'], ['£100', '😊', 'whatever 👀'])
+
+    yield Case(Annotated[int, at.Predicate(lambda x: x % 2 == 0)], [0, 2, 4], [1, 3, 5])
+
+    yield Case(at.IsFinite[float], [1.23], [math.nan, math.inf, -math.inf])
+    yield Case(at.IsNotFinite[float], [math.nan, math.inf], [1.23])
+    yield Case(at.IsNan[float], [math.nan], [1.23, math.inf])
+    yield Case(at.IsNotNan[float], [1.23, math.inf], [math.nan])
+    yield Case(at.IsInfinite[float], [math.inf], [math.nan, 1.23])
+    yield Case(at.IsNotInfinite[float], [math.nan, 1.23], [math.inf])
+
+    # check stacked predicates
+    yield Case(at.IsInfinite[Annotated[float, at.Predicate(lambda x: x > 0)]], [math.inf], [-math.inf, 1.23, math.nan])
+
+    # doc
+    yield Case(Annotated[int, at.doc("A number")], [1, 2], [])
+
+    # custom GroupedMetadata
+    class MyCustomGroupedMetadata(at.GroupedMetadata):
+        def __iter__(self) -> Iterator[at.Predicate]:
+            yield at.Predicate(lambda x: float(x).is_integer())
+
+    yield Case(Annotated[float, MyCustomGroupedMetadata()], [0, 2.0], [0.01, 1.5])

lib/python3.12/site-packages/antlr4/BufferedTokenStream.py

@@ -0,0 +1,302 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+
+# This implementation of {@link TokenStream} loads tokens from a
+# {@link TokenSource} on-demand, and places the tokens in a buffer to provide
+# access to any previous token by index.
+#
+# <p>
+# This token stream ignores the value of {@link Token#getChannel}. If your
+# parser requires the token stream filter tokens to only those on a particular
+# channel, such as {@link Token#DEFAULT_CHANNEL} or
+# {@link Token#HIDDEN_CHANNEL}, use a filtering token stream such a
+# {@link CommonTokenStream}.</p>
+from io import StringIO
+from antlr4.Token import Token
+from antlr4.error.Errors import IllegalStateException
+
+# need forward declaration
+Lexer = None
+
+# this is just to keep meaningful parameter types to Parser
+class TokenStream(object):
+
+    pass
+
+
+class BufferedTokenStream(TokenStream):
+    __slots__ = ('tokenSource', 'tokens', 'index', 'fetchedEOF')
+
+    def __init__(self, tokenSource:Lexer):
+        # The {@link TokenSource} from which tokens for this stream are fetched.
+        self.tokenSource = tokenSource
+
+        # A collection of all tokens fetched from the token source. The list is
+        # considered a complete view of the input once {@link #fetchedEOF} is set
+        # to {@code true}.
+        self.tokens = []
+
+        # The index into {@link #tokens} of the current token (next token to
+        # {@link #consume}). {@link #tokens}{@code [}{@link #p}{@code ]} should be
+        # {@link #LT LT(1)}.
+        #
+        # <p>This field is set to -1 when the stream is first constructed or when
+        # {@link #setTokenSource} is called, indicating that the first token has
+        # not yet been fetched from the token source. For additional information,
+        # see the documentation of {@link IntStream} for a description of
+        # Initializing Methods.</p>
+        self.index = -1
+
+        # Indicates whether the {@link Token#EOF} token has been fetched from
+        # {@link #tokenSource} and added to {@link #tokens}. This field improves
+        # performance for the following cases:
+        #
+        # <ul>
+        # <li>{@link #consume}: The lookahead check in {@link #consume} to prevent
+        # consuming the EOF symbol is optimized by checking the values of
+        # {@link #fetchedEOF} and {@link #p} instead of calling {@link #LA}.</li>
+        # <li>{@link #fetch}: The check to prevent adding multiple EOF symbols into
+        # {@link #tokens} is trivial with this field.</li>
+        # <ul>
+        self.fetchedEOF = False
+
+    def mark(self):
+        return 0
+
+    def release(self, marker:int):
+        # no resources to release
+        pass
+
+    def reset(self):
+        self.seek(0)
+
+    def seek(self, index:int):
+        self.lazyInit()
+        self.index = self.adjustSeekIndex(index)
+
+    def get(self, index:int):
+        self.lazyInit()
+        return self.tokens[index]
+
+    def consume(self):
+        skipEofCheck = False
+        if self.index >= 0:
+            if self.fetchedEOF:
+                # the last token in tokens is EOF. skip check if p indexes any
+                # fetched token except the last.
+                skipEofCheck = self.index < len(self.tokens) - 1
+            else:
+               # no EOF token in tokens. skip check if p indexes a fetched token.
+                skipEofCheck = self.index < len(self.tokens)
+        else:
+            # not yet initialized
+            skipEofCheck = False
+
+        if not skipEofCheck and self.LA(1) == Token.EOF:
+            raise IllegalStateException("cannot consume EOF")
+
+        if self.sync(self.index + 1):
+            self.index = self.adjustSeekIndex(self.index + 1)
+
+    # Make sure index {@code i} in tokens has a token.
+    #
+    # @return {@code true} if a token is located at index {@code i}, otherwise
+    #    {@code false}.
+    # @see #get(int i)
+    #/
+    def sync(self, i:int):
+        n = i - len(self.tokens) + 1 # how many more elements we need?
+        if n > 0 :
+            fetched = self.fetch(n)
+            return fetched >= n
+        return True
+
+    # Add {@code n} elements to buffer.
+    #
+    # @return The actual number of elements added to the buffer.
+    #/
+    def fetch(self, n:int):
+        if self.fetchedEOF:
+            return 0
+        for i in range(0, n):
+            t = self.tokenSource.nextToken()
+            t.tokenIndex = len(self.tokens)
+            self.tokens.append(t)
+            if t.type==Token.EOF:
+                self.fetchedEOF = True
+                return i + 1
+        return n
+
+
+    # Get all tokens from start..stop inclusively#/
+    def getTokens(self, start:int, stop:int, types:set=None):
+        if start<0 or stop<0:
+            return None
+        self.lazyInit()
+        subset = []
+        if stop >= len(self.tokens):
+            stop = len(self.tokens)-1
+        for i in range(start, stop):
+            t = self.tokens[i]
+            if t.type==Token.EOF:
+                break
+            if types is None or t.type in types:
+                subset.append(t)
+        return subset
+
+    def LA(self, i:int):
+        return self.LT(i).type
+
+    def LB(self, k:int):
+        if (self.index-k) < 0:
+            return None
+        return self.tokens[self.index-k]
+
+    def LT(self, k:int):
+        self.lazyInit()
+        if k==0:
+            return None
+        if k < 0:
+            return self.LB(-k)
+        i = self.index + k - 1
+        self.sync(i)
+        if i >= len(self.tokens): # return EOF token
+            # EOF must be last token
+            return self.tokens[len(self.tokens)-1]
+        return self.tokens[i]
+
+    # Allowed derived classes to modify the behavior of operations which change
+    # the current stream position by adjusting the target token index of a seek
+    # operation. The default implementation simply returns {@code i}. If an
+    # exception is thrown in this method, the current stream index should not be
+    # changed.
+    #
+    # <p>For example, {@link CommonTokenStream} overrides this method to ensure that
+    # the seek target is always an on-channel token.</p>
+    #
+    # @param i The target token index.
+    # @return The adjusted target token index.
+
+    def adjustSeekIndex(self, i:int):
+        return i
+
+    def lazyInit(self):
+        if self.index == -1:
+            self.setup()
+
+    def setup(self):
+        self.sync(0)
+        self.index = self.adjustSeekIndex(0)
+
+    # Reset this token stream by setting its token source.#/
+    def setTokenSource(self, tokenSource:Lexer):
+        self.tokenSource = tokenSource
+        self.tokens = []
+        self.index = -1
+        self.fetchedEOF = False
+
+
+    # Given a starting index, return the index of the next token on channel.
+    #  Return i if tokens[i] is on channel.  Return the index of the EOF token
+    # if there are no tokens on channel between i and EOF.
+    #/
+    def nextTokenOnChannel(self, i:int, channel:int):
+        self.sync(i)
+        if i>=len(self.tokens):
+            return len(self.tokens) - 1
+        token = self.tokens[i]
+        while token.channel!=channel:
+            if token.type==Token.EOF:
+                return i
+            i += 1
+            self.sync(i)
+            token = self.tokens[i]
+        return i
+
+    # Given a starting index, return the index of the previous token on channel.
+    #  Return i if tokens[i] is on channel. Return -1 if there are no tokens
+    #  on channel between i and 0.
+    def previousTokenOnChannel(self, i:int, channel:int):
+        while i>=0 and self.tokens[i].channel!=channel:
+            i -= 1
+        return i
+
+    # Collect all tokens on specified channel to the right of
+    #  the current token up until we see a token on DEFAULT_TOKEN_CHANNEL or
+    #  EOF. If channel is -1, find any non default channel token.
+    def getHiddenTokensToRight(self, tokenIndex:int, channel:int=-1):
+        self.lazyInit()
+        if tokenIndex<0 or tokenIndex>=len(self.tokens):
+            raise Exception(str(tokenIndex) + " not in 0.." + str(len(self.tokens)-1))
+        from antlr4.Lexer import Lexer
+        nextOnChannel = self.nextTokenOnChannel(tokenIndex + 1, Lexer.DEFAULT_TOKEN_CHANNEL)
+        from_ = tokenIndex+1
+        # if none onchannel to right, nextOnChannel=-1 so set to = last token
+        to = (len(self.tokens)-1) if nextOnChannel==-1 else nextOnChannel
+        return self.filterForChannel(from_, to, channel)
+
+
+    # Collect all tokens on specified channel to the left of
+    #  the current token up until we see a token on DEFAULT_TOKEN_CHANNEL.
+    #  If channel is -1, find any non default channel token.
+    def getHiddenTokensToLeft(self, tokenIndex:int, channel:int=-1):
+        self.lazyInit()
+        if tokenIndex<0 or tokenIndex>=len(self.tokens):
+            raise Exception(str(tokenIndex) + " not in 0.." + str(len(self.tokens)-1))
+        from antlr4.Lexer import Lexer
+        prevOnChannel = self.previousTokenOnChannel(tokenIndex - 1, Lexer.DEFAULT_TOKEN_CHANNEL)
+        if prevOnChannel == tokenIndex - 1:
+            return None
+        # if none on channel to left, prevOnChannel=-1 then from=0
+        from_ = prevOnChannel+1
+        to = tokenIndex-1
+        return self.filterForChannel(from_, to, channel)
+
+
+    def filterForChannel(self, left:int, right:int, channel:int):
+        hidden = []
+        for i in range(left, right+1):
+            t = self.tokens[i]
+            if channel==-1:
+                from antlr4.Lexer import Lexer
+                if t.channel!= Lexer.DEFAULT_TOKEN_CHANNEL:
+                    hidden.append(t)
+            elif t.channel==channel:
+                    hidden.append(t)
+        if len(hidden)==0:
+            return None
+        return hidden
+
+    def getSourceName(self):
+        return self.tokenSource.getSourceName()
+
+    # Get the text of all tokens in this buffer.#/
+    def getText(self, start:int=None, stop:int=None):
+        self.lazyInit()
+        self.fill()
+        if isinstance(start, Token):
+            start = start.tokenIndex
+        elif start is None:
+            start = 0
+        if isinstance(stop, Token):
+            stop = stop.tokenIndex
+        elif stop is None or stop >= len(self.tokens):
+            stop = len(self.tokens) - 1
+        if start < 0 or stop < 0 or stop < start:
+            return ""
+        with StringIO() as buf:
+            for i in range(start, stop+1):
+                t = self.tokens[i]
+                if t.type==Token.EOF:
+                    break
+                buf.write(t.text)
+            return buf.getvalue()
+
+
+    # Get all tokens from lexer until EOF#/
+    def fill(self):
+        self.lazyInit()
+        while self.fetch(1000)==1000:
+            pass

lib/python3.12/site-packages/antlr4/CommonTokenFactory.py

@@ -0,0 +1,61 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+#
+# This default implementation of {@link TokenFactory} creates
+# {@link CommonToken} objects.
+#
+from antlr4.Token import CommonToken
+
+class TokenFactory(object):
+
+    pass
+
+class CommonTokenFactory(TokenFactory):
+    __slots__ = 'copyText'
+
+    #
+    # The default {@link CommonTokenFactory} instance.
+    #
+    # <p>
+    # This token factory does not explicitly copy token text when constructing
+    # tokens.</p>
+    #
+    DEFAULT = None
+
+    def __init__(self, copyText:bool=False):
+        # Indicates whether {@link CommonToken#setText} should be called after
+        # constructing tokens to explicitly set the text. This is useful for cases
+        # where the input stream might not be able to provide arbitrary substrings
+        # of text from the input after the lexer creates a token (e.g. the
+        # implementation of {@link CharStream#getText} in
+        # {@link UnbufferedCharStream} throws an
+        # {@link UnsupportedOperationException}). Explicitly setting the token text
+        # allows {@link Token#getText} to be called at any time regardless of the
+        # input stream implementation.
+        #
+        # <p>
+        # The default value is {@code false} to avoid the performance and memory
+        # overhead of copying text for every token unless explicitly requested.</p>
+        #
+        self.copyText = copyText
+
+    def create(self, source, type:int, text:str, channel:int, start:int, stop:int, line:int, column:int):
+        t = CommonToken(source, type, channel, start, stop)
+        t.line = line
+        t.column = column
+        if text is not None:
+            t.text = text
+        elif self.copyText and source[1] is not None:
+            t.text = source[1].getText(start,stop)
+        return t
+
+    def createThin(self, type:int, text:str):
+        t = CommonToken(type=type)
+        t.text = text
+        return t
+
+CommonTokenFactory.DEFAULT = CommonTokenFactory()

lib/python3.12/site-packages/antlr4/CommonTokenStream.py

@@ -0,0 +1,87 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+
+#
+# This class extends {@link BufferedTokenStream} with functionality to filter
+# token streams to tokens on a particular channel (tokens where
+# {@link Token#getChannel} returns a particular value).
+#
+# <p>
+# This token stream provides access to all tokens by index or when calling
+# methods like {@link #getText}. The channel filtering is only used for code
+# accessing tokens via the lookahead methods {@link #LA}, {@link #LT}, and
+# {@link #LB}.</p>
+#
+# <p>
+# By default, tokens are placed on the default channel
+# ({@link Token#DEFAULT_CHANNEL}), but may be reassigned by using the
+# {@code ->channel(HIDDEN)} lexer command, or by using an embedded action to
+# call {@link Lexer#setChannel}.
+# </p>
+#
+# <p>
+# Note: lexer rules which use the {@code ->skip} lexer command or call
+# {@link Lexer#skip} do not produce tokens at all, so input text matched by
+# such a rule will not be available as part of the token stream, regardless of
+# channel.</p>
+#/
+
+from antlr4.BufferedTokenStream import BufferedTokenStream
+from antlr4.Lexer import Lexer
+from antlr4.Token import Token
+
+
+class CommonTokenStream(BufferedTokenStream):
+    __slots__ = 'channel'
+
+    def __init__(self, lexer:Lexer, channel:int=Token.DEFAULT_CHANNEL):
+        super().__init__(lexer)
+        self.channel = channel
+
+    def adjustSeekIndex(self, i:int):
+        return self.nextTokenOnChannel(i, self.channel)
+
+    def LB(self, k:int):
+        if k==0 or (self.index-k)<0:
+            return None
+        i = self.index
+        n = 1
+        # find k good tokens looking backwards
+        while n <= k:
+            # skip off-channel tokens
+            i = self.previousTokenOnChannel(i - 1, self.channel)
+            n += 1
+        if i < 0:
+            return None
+        return self.tokens[i]
+
+    def LT(self, k:int):
+        self.lazyInit()
+        if k == 0:
+            return None
+        if k < 0:
+            return self.LB(-k)
+        i = self.index
+        n = 1 # we know tokens[pos] is a good one
+        # find k good tokens
+        while n < k:
+            # skip off-channel tokens, but make sure to not look past EOF
+            if self.sync(i + 1):
+                i = self.nextTokenOnChannel(i + 1, self.channel)
+            n += 1
+        return self.tokens[i]
+
+    # Count EOF just once.#/
+    def getNumberOfOnChannelTokens(self):
+        n = 0
+        self.fill()
+        for i in range(0, len(self.tokens)):
+            t = self.tokens[i]
+            if t.channel==self.channel:
+                n += 1
+            if t.type==Token.EOF:
+                break
+        return n

lib/python3.12/site-packages/antlr4/FileStream.py

@@ -0,0 +1,27 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+#
+#  This is an InputStream that is loaded from a file all at once
+#  when you construct the object.
+#
+
+import codecs
+from antlr4.InputStream import InputStream
+
+
+class FileStream(InputStream):
+    __slots__ = 'fileName'
+
+    def __init__(self, fileName:str, encoding:str='ascii', errors:str='strict'):
+        super().__init__(self.readDataFrom(fileName, encoding, errors))
+        self.fileName = fileName
+
+    def readDataFrom(self, fileName:str, encoding:str, errors:str='strict'):
+        # read binary to avoid line ending conversion
+        with open(fileName, 'rb') as file:
+            bytes = file.read()
+            return codecs.decode(bytes, encoding, errors)

lib/python3.12/site-packages/antlr4/InputStream.py

@@ -0,0 +1,87 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+
+#
+#  Vacuum all input from a string and then treat it like a buffer.
+#
+from antlr4.Token import Token
+
+
+class InputStream (object):
+    __slots__ = ('name', 'strdata', '_index', 'data', '_size')
+
+    def __init__(self, data: str):
+        self.name = "<empty>"
+        self.strdata = data
+        self._loadString()
+
+    def _loadString(self):
+        self._index = 0
+        self.data = [ord(c) for c in self.strdata]
+        self._size = len(self.data)
+
+    @property
+    def index(self):
+        return self._index
+
+    @property
+    def size(self):
+        return self._size
+
+    # Reset the stream so that it's in the same state it was
+    #  when the object was created *except* the data array is not
+    #  touched.
+    #
+    def reset(self):
+        self._index = 0
+
+    def consume(self):
+        if self._index >= self._size:
+            assert self.LA(1) == Token.EOF
+            raise Exception("cannot consume EOF")
+        self._index += 1
+
+    def LA(self, offset: int):
+        if offset==0:
+            return 0 # undefined
+        if offset<0:
+            offset += 1 # e.g., translate LA(-1) to use offset=0
+        pos = self._index + offset - 1
+        if pos < 0 or pos >= self._size: # invalid
+            return Token.EOF
+        return self.data[pos]
+
+    def LT(self, offset: int):
+        return self.LA(offset)
+
+    # mark/release do nothing; we have entire buffer
+    def mark(self):
+        return -1
+
+    def release(self, marker: int):
+        pass
+
+    # consume() ahead until p==_index; can't just set p=_index as we must
+    # update line and column. If we seek backwards, just set p
+    #
+    def seek(self, _index: int):
+        if _index<=self._index:
+            self._index = _index # just jump; don't update stream state (line, ...)
+            return
+        # seek forward
+        self._index = min(_index, self._size)
+
+    def getText(self, start :int, stop: int):
+        if stop >= self._size:
+            stop = self._size-1
+        if start >= self._size:
+            return ""
+        else:
+            return self.strdata[start:stop+1]
+
+    def __str__(self):
+        return self.strdata

lib/python3.12/site-packages/antlr4/IntervalSet.py

@@ -0,0 +1,180 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+from io import StringIO
+from antlr4.Token import Token
+
+# need forward declarations
+IntervalSet = None
+
+class IntervalSet(object):
+    __slots__ = ('intervals', 'readonly')
+
+    def __init__(self):
+        self.intervals = None
+        self.readonly = False
+
+    def __iter__(self):
+        if self.intervals is not None:
+            for i in self.intervals:
+                for c in i:
+                    yield c
+
+    def __getitem__(self, item):
+        i = 0
+        for k in self:
+            if i==item:
+                return k
+            else:
+                i += 1
+        return Token.INVALID_TYPE
+
+    def addOne(self, v:int):
+        self.addRange(range(v, v+1))
+
+    def addRange(self, v:range):
+        if self.intervals is None:
+            self.intervals = list()
+            self.intervals.append(v)
+        else:
+            # find insert pos
+            k = 0
+            for i in self.intervals:
+                # distinct range -> insert
+                if v.stop<i.start:
+                    self.intervals.insert(k, v)
+                    return
+                # contiguous range -> adjust
+                elif v.stop==i.start:
+                    self.intervals[k] = range(v.start, i.stop)
+                    return
+                # overlapping range -> adjust and reduce
+                elif v.start<=i.stop:
+                    self.intervals[k] = range(min(i.start,v.start), max(i.stop,v.stop))
+                    self.reduce(k)
+                    return
+                k += 1
+            # greater than any existing
+            self.intervals.append(v)
+
+    def addSet(self, other:IntervalSet):
+        if other.intervals is not None:
+            for i in other.intervals:
+                self.addRange(i)
+        return self
+
+    def reduce(self, k:int):
+        # only need to reduce if k is not the last
+        if k<len(self.intervals)-1:
+            l = self.intervals[k]
+            r = self.intervals[k+1]
+            # if r contained in l
+            if l.stop >= r.stop:
+                self.intervals.pop(k+1)
+                self.reduce(k)
+            elif l.stop >= r.start:
+                self.intervals[k] = range(l.start, r.stop)
+                self.intervals.pop(k+1)
+
+    def complement(self, start, stop):
+        result = IntervalSet()
+        result.addRange(range(start,stop+1))
+        for i in self.intervals:
+            result.removeRange(i)
+        return result
+
+    def __contains__(self, item):
+        if self.intervals is None:
+            return False
+        else:
+            return any(item in i for i in self.intervals)
+
+    def __len__(self):
+        return sum(len(i) for i in self.intervals)
+
+    def removeRange(self, v):
+        if v.start==v.stop-1:
+            self.removeOne(v.start)
+        elif self.intervals is not None:
+            k = 0
+            for i in self.intervals:
+                # intervals are ordered
+                if v.stop<=i.start:
+                    return
+                # check for including range, split it
+                elif v.start>i.start and v.stop<i.stop:
+                    self.intervals[k] = range(i.start, v.start)
+                    x = range(v.stop, i.stop)
+                    self.intervals.insert(k, x)
+                    return
+                # check for included range, remove it
+                elif v.start<=i.start and v.stop>=i.stop:
+                    self.intervals.pop(k)
+                    k -= 1  # need another pass
+                # check for lower boundary
+                elif v.start<i.stop:
+                    self.intervals[k] = range(i.start, v.start)
+                # check for upper boundary
+                elif v.stop<i.stop:
+                    self.intervals[k] = range(v.stop, i.stop)
+                k += 1
+
+    def removeOne(self, v):
+        if self.intervals is not None:
+            k = 0
+            for i in self.intervals:
+                # intervals is ordered
+                if v<i.start:
+                    return
+                # check for single value range
+                elif v==i.start and v==i.stop-1:
+                    self.intervals.pop(k)
+                    return
+                # check for lower boundary
+                elif v==i.start:
+                    self.intervals[k] = range(i.start+1, i.stop)
+                    return
+                # check for upper boundary
+                elif v==i.stop-1:
+                    self.intervals[k] = range(i.start, i.stop-1)
+                    return
+                # split existing range
+                elif v<i.stop-1:
+                    x = range(i.start, v)
+                    self.intervals[k] = range(v + 1, i.stop)
+                    self.intervals.insert(k, x)
+                    return
+                k += 1
+
+
+    def toString(self, literalNames:list, symbolicNames:list):
+        if self.intervals is None:
+            return "{}"
+        with StringIO() as buf:
+            if len(self)>1:
+                buf.write("{")
+            first = True
+            for i in self.intervals:
+                for j in i:
+                    if not first:
+                        buf.write(", ")
+                    buf.write(self.elementName(literalNames, symbolicNames, j))
+                    first = False
+            if len(self)>1:
+                buf.write("}")
+            return buf.getvalue()
+
+    def elementName(self, literalNames:list, symbolicNames:list, a:int):
+        if a==Token.EOF:
+            return "<EOF>"
+        elif a==Token.EPSILON:
+            return "<EPSILON>"
+        else:
+            if a<len(literalNames) and literalNames[a] != "<INVALID>":
+                return literalNames[a]
+            if a<len(symbolicNames):
+                return symbolicNames[a]
+            return "<UNKNOWN>"

lib/python3.12/site-packages/antlr4/LL1Analyzer.py

@@ -0,0 +1,173 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+from antlr4.IntervalSet import IntervalSet
+from antlr4.Token import Token
+from antlr4.PredictionContext import PredictionContext, SingletonPredictionContext, PredictionContextFromRuleContext
+from antlr4.RuleContext import RuleContext
+from antlr4.atn.ATN import ATN
+from antlr4.atn.ATNConfig import ATNConfig
+from antlr4.atn.ATNState import ATNState, RuleStopState
+from antlr4.atn.Transition import WildcardTransition, NotSetTransition, AbstractPredicateTransition, RuleTransition
+
+
+class LL1Analyzer (object):
+    __slots__ = 'atn'
+
+    #* Special value added to the lookahead sets to indicate that we hit
+    #  a predicate during analysis if {@code seeThruPreds==false}.
+    #/
+    HIT_PRED = Token.INVALID_TYPE
+
+    def __init__(self, atn:ATN):
+        self.atn = atn
+
+    #*
+    # Calculates the SLL(1) expected lookahead set for each outgoing transition
+    # of an {@link ATNState}. The returned array has one element for each
+    # outgoing transition in {@code s}. If the closure from transition
+    # <em>i</em> leads to a semantic predicate before matching a symbol, the
+    # element at index <em>i</em> of the result will be {@code null}.
+    #
+    # @param s the ATN state
+    # @return the expected symbols for each outgoing transition of {@code s}.
+    #/
+    def getDecisionLookahead(self, s:ATNState):
+        if s is None:
+            return None
+
+        count = len(s.transitions)
+        look = [] * count
+        for alt in range(0, count):
+            look[alt] = set()
+            lookBusy = set()
+            seeThruPreds = False # fail to get lookahead upon pred
+            self._LOOK(s.transition(alt).target, None, PredictionContext.EMPTY,
+                  look[alt], lookBusy, set(), seeThruPreds, False)
+            # Wipe out lookahead for this alternative if we found nothing
+            # or we had a predicate when we !seeThruPreds
+            if len(look[alt])==0 or self.HIT_PRED in look[alt]:
+                look[alt] = None
+        return look
+
+    #*
+    # Compute set of tokens that can follow {@code s} in the ATN in the
+    # specified {@code ctx}.
+    #
+    # <p>If {@code ctx} is {@code null} and the end of the rule containing
+    # {@code s} is reached, {@link Token#EPSILON} is added to the result set.
+    # If {@code ctx} is not {@code null} and the end of the outermost rule is
+    # reached, {@link Token#EOF} is added to the result set.</p>
+    #
+    # @param s the ATN state
+    # @param stopState the ATN state to stop at. This can be a
+    # {@link BlockEndState} to detect epsilon paths through a closure.
+    # @param ctx the complete parser context, or {@code null} if the context
+    # should be ignored
+    #
+    # @return The set of tokens that can follow {@code s} in the ATN in the
+    # specified {@code ctx}.
+    #/
+    def LOOK(self, s:ATNState, stopState:ATNState=None, ctx:RuleContext=None):
+        r = IntervalSet()
+        seeThruPreds = True # ignore preds; get all lookahead
+        lookContext = PredictionContextFromRuleContext(s.atn, ctx) if ctx is not None else None
+        self._LOOK(s, stopState, lookContext, r, set(), set(), seeThruPreds, True)
+        return r
+
+    #*
+    # Compute set of tokens that can follow {@code s} in the ATN in the
+    # specified {@code ctx}.
+    #
+    # <p>If {@code ctx} is {@code null} and {@code stopState} or the end of the
+    # rule containing {@code s} is reached, {@link Token#EPSILON} is added to
+    # the result set. If {@code ctx} is not {@code null} and {@code addEOF} is
+    # {@code true} and {@code stopState} or the end of the outermost rule is
+    # reached, {@link Token#EOF} is added to the result set.</p>
+    #
+    # @param s the ATN state.
+    # @param stopState the ATN state to stop at. This can be a
+    # {@link BlockEndState} to detect epsilon paths through a closure.
+    # @param ctx The outer context, or {@code null} if the outer context should
+    # not be used.
+    # @param look The result lookahead set.
+    # @param lookBusy A set used for preventing epsilon closures in the ATN
+    # from causing a stack overflow. Outside code should pass
+    # {@code new HashSet<ATNConfig>} for this argument.
+    # @param calledRuleStack A set used for preventing left recursion in the
+    # ATN from causing a stack overflow. Outside code should pass
+    # {@code new BitSet()} for this argument.
+    # @param seeThruPreds {@code true} to true semantic predicates as
+    # implicitly {@code true} and "see through them", otherwise {@code false}
+    # to treat semantic predicates as opaque and add {@link #HIT_PRED} to the
+    # result if one is encountered.
+    # @param addEOF Add {@link Token#EOF} to the result if the end of the
+    # outermost context is reached. This parameter has no effect if {@code ctx}
+    # is {@code null}.
+    #/
+    def _LOOK(self, s:ATNState, stopState:ATNState , ctx:PredictionContext, look:IntervalSet, lookBusy:set,
+                     calledRuleStack:set, seeThruPreds:bool, addEOF:bool):
+        c = ATNConfig(s, 0, ctx)
+
+        if c in lookBusy:
+            return
+        lookBusy.add(c)
+
+        if s == stopState:
+            if ctx is None:
+                look.addOne(Token.EPSILON)
+                return
+            elif ctx.isEmpty() and addEOF:
+                look.addOne(Token.EOF)
+                return
+
+        if isinstance(s, RuleStopState ):
+            if ctx is None:
+                look.addOne(Token.EPSILON)
+                return
+            elif ctx.isEmpty() and addEOF:
+                look.addOne(Token.EOF)
+                return
+
+            if ctx != PredictionContext.EMPTY:
+                removed = s.ruleIndex in calledRuleStack
+                try:
+                    calledRuleStack.discard(s.ruleIndex)
+                    # run thru all possible stack tops in ctx
+                    for i in range(0, len(ctx)):
+                        returnState = self.atn.states[ctx.getReturnState(i)]
+                        self._LOOK(returnState, stopState, ctx.getParent(i), look, lookBusy, calledRuleStack, seeThruPreds, addEOF)
+                finally:
+                    if removed:
+                        calledRuleStack.add(s.ruleIndex)
+                return
+
+        for t in s.transitions:
+            if type(t) == RuleTransition:
+                if t.target.ruleIndex in calledRuleStack:
+                    continue
+
+                newContext = SingletonPredictionContext.create(ctx, t.followState.stateNumber)
+
+                try:
+                    calledRuleStack.add(t.target.ruleIndex)
+                    self._LOOK(t.target, stopState, newContext, look, lookBusy, calledRuleStack, seeThruPreds, addEOF)
+                finally:
+                    calledRuleStack.remove(t.target.ruleIndex)
+            elif isinstance(t, AbstractPredicateTransition ):
+                if seeThruPreds:
+                    self._LOOK(t.target, stopState, ctx, look, lookBusy, calledRuleStack, seeThruPreds, addEOF)
+                else:
+                    look.addOne(self.HIT_PRED)
+            elif t.isEpsilon:
+                self._LOOK(t.target, stopState, ctx, look, lookBusy, calledRuleStack, seeThruPreds, addEOF)
+            elif type(t) == WildcardTransition:
+                look.addRange( range(Token.MIN_USER_TOKEN_TYPE, self.atn.maxTokenType + 1) )
+            else:
+                set_ = t.label
+                if set_ is not None:
+                    if isinstance(t, NotSetTransition):
+                        set_ = set_.complement(Token.MIN_USER_TOKEN_TYPE, self.atn.maxTokenType)
+                    look.addSet(set_)

lib/python3.12/site-packages/antlr4/Lexer.py

@@ -0,0 +1,329 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+
+# A lexer is recognizer that draws input symbols from a character stream.
+#  lexer grammars result in a subclass of self object. A Lexer object
+#  uses simplified match() and error recovery mechanisms in the interest
+#  of speed.
+#/
+from io import StringIO
+
+import sys
+if sys.version_info[1] > 5:
+    from typing import TextIO
+else:
+    from typing.io import TextIO
+from antlr4.CommonTokenFactory import CommonTokenFactory
+from antlr4.atn.LexerATNSimulator import LexerATNSimulator
+from antlr4.InputStream import InputStream
+from antlr4.Recognizer import Recognizer
+from antlr4.Token import Token
+from antlr4.error.Errors import IllegalStateException, LexerNoViableAltException, RecognitionException
+
+class TokenSource(object):
+
+    pass
+
+
+class Lexer(Recognizer, TokenSource):
+    __slots__ = (
+        '_input', '_output', '_factory', '_tokenFactorySourcePair', '_token',
+        '_tokenStartCharIndex', '_tokenStartLine', '_tokenStartColumn',
+        '_hitEOF', '_channel', '_type', '_modeStack', '_mode', '_text'
+    )
+
+    DEFAULT_MODE = 0
+    MORE = -2
+    SKIP = -3
+
+    DEFAULT_TOKEN_CHANNEL = Token.DEFAULT_CHANNEL
+    HIDDEN = Token.HIDDEN_CHANNEL
+    MIN_CHAR_VALUE = 0x0000
+    MAX_CHAR_VALUE = 0x10FFFF
+
+    def __init__(self, input:InputStream, output:TextIO = sys.stdout):
+        super().__init__()
+        self._input = input
+        self._output = output
+        self._factory = CommonTokenFactory.DEFAULT
+        self._tokenFactorySourcePair = (self, input)
+
+        self._interp = None # child classes must populate this
+
+        # The goal of all lexer rules/methods is to create a token object.
+        #  self is an instance variable as multiple rules may collaborate to
+        #  create a single token.  nextToken will return self object after
+        #  matching lexer rule(s).  If you subclass to allow multiple token
+        #  emissions, then set self to the last token to be matched or
+        #  something nonnull so that the auto token emit mechanism will not
+        #  emit another token.
+        self._token = None
+
+        # What character index in the stream did the current token start at?
+        #  Needed, for example, to get the text for current token.  Set at
+        #  the start of nextToken.
+        self._tokenStartCharIndex = -1
+
+        # The line on which the first character of the token resides#/
+        self._tokenStartLine = -1
+
+        # The character position of first character within the line#/
+        self._tokenStartColumn = -1
+
+        # Once we see EOF on char stream, next token will be EOF.
+        #  If you have DONE : EOF ; then you see DONE EOF.
+        self._hitEOF = False
+
+        # The channel number for the current token#/
+        self._channel = Token.DEFAULT_CHANNEL
+
+        # The token type for the current token#/
+        self._type = Token.INVALID_TYPE
+
+        self._modeStack = []
+        self._mode = self.DEFAULT_MODE
+
+        # You can set the text for the current token to override what is in
+        #  the input char buffer.  Use setText() or can set self instance var.
+        #/
+        self._text = None
+
+
+    def reset(self):
+        # wack Lexer state variables
+        if self._input is not None:
+            self._input.seek(0) # rewind the input
+        self._token = None
+        self._type = Token.INVALID_TYPE
+        self._channel = Token.DEFAULT_CHANNEL
+        self._tokenStartCharIndex = -1
+        self._tokenStartColumn = -1
+        self._tokenStartLine = -1
+        self._text = None
+
+        self._hitEOF = False
+        self._mode = Lexer.DEFAULT_MODE
+        self._modeStack = []
+
+        self._interp.reset()
+
+    # Return a token from self source; i.e., match a token on the char
+    #  stream.
+    def nextToken(self):
+        if self._input is None:
+            raise IllegalStateException("nextToken requires a non-null input stream.")
+
+        # Mark start location in char stream so unbuffered streams are
+        # guaranteed at least have text of current token
+        tokenStartMarker = self._input.mark()
+        try:
+            while True:
+                if self._hitEOF:
+                    self.emitEOF()
+                    return self._token
+                self._token = None
+                self._channel = Token.DEFAULT_CHANNEL
+                self._tokenStartCharIndex = self._input.index
+                self._tokenStartColumn = self._interp.column
+                self._tokenStartLine = self._interp.line
+                self._text = None
+                continueOuter = False
+                while True:
+                    self._type = Token.INVALID_TYPE
+                    ttype = self.SKIP
+                    try:
+                        ttype = self._interp.match(self._input, self._mode)
+                    except LexerNoViableAltException as e:
+                        self.notifyListeners(e)		# report error
+                        self.recover(e)
+                    if self._input.LA(1)==Token.EOF:
+                        self._hitEOF = True
+                    if self._type == Token.INVALID_TYPE:
+                        self._type = ttype
+                    if self._type == self.SKIP:
+                        continueOuter = True
+                        break
+                    if self._type!=self.MORE:
+                        break
+                if continueOuter:
+                    continue
+                if self._token is None:
+                    self.emit()
+                return self._token
+        finally:
+            # make sure we release marker after match or
+            # unbuffered char stream will keep buffering
+            self._input.release(tokenStartMarker)
+
+    # Instruct the lexer to skip creating a token for current lexer rule
+    #  and look for another token.  nextToken() knows to keep looking when
+    #  a lexer rule finishes with token set to SKIP_TOKEN.  Recall that
+    #  if token==null at end of any token rule, it creates one for you
+    #  and emits it.
+    #/
+    def skip(self):
+        self._type = self.SKIP
+
+    def more(self):
+        self._type = self.MORE
+
+    def mode(self, m:int):
+        self._mode = m
+
+    def pushMode(self, m:int):
+        if self._interp.debug:
+            print("pushMode " + str(m), file=self._output)
+        self._modeStack.append(self._mode)
+        self.mode(m)
+
+    def popMode(self):
+        if len(self._modeStack)==0:
+            raise Exception("Empty Stack")
+        if self._interp.debug:
+            print("popMode back to "+ self._modeStack[:-1], file=self._output)
+        self.mode( self._modeStack.pop() )
+        return self._mode
+
+    # Set the char stream and reset the lexer#/
+    @property
+    def inputStream(self):
+        return self._input
+
+    @inputStream.setter
+    def inputStream(self, input:InputStream):
+        self._input = None
+        self._tokenFactorySourcePair = (self, self._input)
+        self.reset()
+        self._input = input
+        self._tokenFactorySourcePair = (self, self._input)
+
+    @property
+    def sourceName(self):
+        return self._input.sourceName
+
+    # By default does not support multiple emits per nextToken invocation
+    #  for efficiency reasons.  Subclass and override self method, nextToken,
+    #  and getToken (to push tokens into a list and pull from that list
+    #  rather than a single variable as self implementation does).
+    #/
+    def emitToken(self, token:Token):
+        self._token = token
+
+    # The standard method called to automatically emit a token at the
+    #  outermost lexical rule.  The token object should point into the
+    #  char buffer start..stop.  If there is a text override in 'text',
+    #  use that to set the token's text.  Override self method to emit
+    #  custom Token objects or provide a new factory.
+    #/
+    def emit(self):
+        t = self._factory.create(self._tokenFactorySourcePair, self._type, self._text, self._channel, self._tokenStartCharIndex,
+                                 self.getCharIndex()-1, self._tokenStartLine, self._tokenStartColumn)
+        self.emitToken(t)
+        return t
+
+    def emitEOF(self):
+        cpos = self.column
+        lpos = self.line
+        eof = self._factory.create(self._tokenFactorySourcePair, Token.EOF, None, Token.DEFAULT_CHANNEL, self._input.index,
+                                   self._input.index-1, lpos, cpos)
+        self.emitToken(eof)
+        return eof
+
+    @property
+    def type(self):
+        return self._type
+
+    @type.setter
+    def type(self, type:int):
+        self._type = type
+
+    @property
+    def line(self):
+        return self._interp.line
+
+    @line.setter
+    def line(self, line:int):
+        self._interp.line = line
+
+    @property
+    def column(self):
+        return self._interp.column
+
+    @column.setter
+    def column(self, column:int):
+        self._interp.column = column
+
+    # What is the index of the current character of lookahead?#/
+    def getCharIndex(self):
+        return self._input.index
+
+    # Return the text matched so far for the current token or any
+    #  text override.
+    @property
+    def text(self):
+        if self._text is not None:
+            return self._text
+        else:
+            return self._interp.getText(self._input)
+
+    # Set the complete text of self token; it wipes any previous
+    #  changes to the text.
+    @text.setter
+    def text(self, txt:str):
+        self._text = txt
+
+    # Return a list of all Token objects in input char stream.
+    #  Forces load of all tokens. Does not include EOF token.
+    #/
+    def getAllTokens(self):
+        tokens = []
+        t = self.nextToken()
+        while t.type!=Token.EOF:
+            tokens.append(t)
+            t = self.nextToken()
+        return tokens
+
+    def notifyListeners(self, e:LexerNoViableAltException):
+        start = self._tokenStartCharIndex
+        stop = self._input.index
+        text = self._input.getText(start, stop)
+        msg = "token recognition error at: '" + self.getErrorDisplay(text) + "'"
+        listener = self.getErrorListenerDispatch()
+        listener.syntaxError(self, None, self._tokenStartLine, self._tokenStartColumn, msg, e)
+
+    def getErrorDisplay(self, s:str):
+        with StringIO() as buf:
+            for c in s:
+                buf.write(self.getErrorDisplayForChar(c))
+            return buf.getvalue()
+
+    def getErrorDisplayForChar(self, c:str):
+        if ord(c[0])==Token.EOF:
+            return "<EOF>"
+        elif c=='\n':
+            return "\\n"
+        elif c=='\t':
+            return "\\t"
+        elif c=='\r':
+            return "\\r"
+        else:
+            return c
+
+    def getCharErrorDisplay(self, c:str):
+        return "'" + self.getErrorDisplayForChar(c) + "'"
+
+    # Lexers can normally match any char in it's vocabulary after matching
+    #  a token, so do the easy thing and just kill a character and hope
+    #  it all works out.  You can instead use the rule invocation stack
+    #  to do sophisticated error recovery if you are in a fragment rule.
+    #/
+    def recover(self, re:RecognitionException):
+        if self._input.LA(1) != Token.EOF:
+            if isinstance(re, LexerNoViableAltException):
+                    # skip a char and try again
+                    self._interp.consume(self._input)
+            else:
+                # TODO: Do we lose character or line position information?
+                self._input.consume()

lib/python3.12/site-packages/antlr4/ListTokenSource.py

@@ -0,0 +1,144 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+#
+# Provides an implementation of {@link TokenSource} as a wrapper around a list
+# of {@link Token} objects.
+#
+# <p>If the final token in the list is an {@link Token#EOF} token, it will be used
+# as the EOF token for every call to {@link #nextToken} after the end of the
+# list is reached. Otherwise, an EOF token will be created.</p>
+#
+from antlr4.CommonTokenFactory import CommonTokenFactory
+from antlr4.Lexer import TokenSource
+from antlr4.Token import Token
+
+
+class ListTokenSource(TokenSource):
+    __slots__ = ('tokens', 'sourceName', 'pos', 'eofToken', '_factory')
+
+    # Constructs a new {@link ListTokenSource} instance from the specified
+    # collection of {@link Token} objects and source name.
+    #
+    # @param tokens The collection of {@link Token} objects to provide as a
+    # {@link TokenSource}.
+    # @param sourceName The name of the {@link TokenSource}. If this value is
+    # {@code null}, {@link #getSourceName} will attempt to infer the name from
+    # the next {@link Token} (or the previous token if the end of the input has
+    # been reached).
+    #
+    # @exception NullPointerException if {@code tokens} is {@code null}
+    #
+    def __init__(self, tokens:list, sourceName:str=None):
+        if tokens is None:
+            raise ReferenceError("tokens cannot be null")
+        self.tokens = tokens
+        self.sourceName = sourceName
+        # The index into {@link #tokens} of token to return by the next call to
+        # {@link #nextToken}. The end of the input is indicated by this value
+        # being greater than or equal to the number of items in {@link #tokens}.
+        self.pos = 0
+        # This field caches the EOF token for the token source.
+        self.eofToken = None
+        # This is the backing field for {@link #getTokenFactory} and
+        self._factory = CommonTokenFactory.DEFAULT
+
+
+    #
+    # {@inheritDoc}
+    #
+    @property
+    def column(self):
+        if self.pos < len(self.tokens):
+            return self.tokens[self.pos].column
+        elif self.eofToken is not None:
+            return self.eofToken.column
+        elif len(self.tokens) > 0:
+            # have to calculate the result from the line/column of the previous
+            # token, along with the text of the token.
+            lastToken = self.tokens[len(self.tokens) - 1]
+            tokenText = lastToken.text
+            if tokenText is not None:
+                lastNewLine = tokenText.rfind('\n')
+                if lastNewLine >= 0:
+                    return len(tokenText) - lastNewLine - 1
+            return lastToken.column + lastToken.stop - lastToken.start + 1
+
+        # only reach this if tokens is empty, meaning EOF occurs at the first
+        # position in the input
+        return 0
+
+    #
+    # {@inheritDoc}
+    #
+    def nextToken(self):
+        if self.pos >= len(self.tokens):
+            if self.eofToken is None:
+                start = -1
+                if len(self.tokens) > 0:
+                    previousStop = self.tokens[len(self.tokens) - 1].stop
+                    if previousStop != -1:
+                        start = previousStop + 1
+                stop = max(-1, start - 1)
+                self.eofToken = self._factory.create((self, self.getInputStream()),
+                            Token.EOF, "EOF", Token.DEFAULT_CHANNEL, start, stop, self.line, self.column)
+            return self.eofToken
+        t = self.tokens[self.pos]
+        if self.pos == len(self.tokens) - 1 and t.type == Token.EOF:
+            self.eofToken = t
+        self.pos += 1
+        return t
+
+    #
+    # {@inheritDoc}
+    #
+    @property
+    def line(self):
+        if self.pos < len(self.tokens):
+            return self.tokens[self.pos].line
+        elif self.eofToken is not None:
+            return self.eofToken.line
+        elif len(self.tokens) > 0:
+            # have to calculate the result from the line/column of the previous
+            # token, along with the text of the token.
+            lastToken = self.tokens[len(self.tokens) - 1]
+            line = lastToken.line
+            tokenText = lastToken.text
+            if tokenText is not None:
+                line += tokenText.count('\n')
+
+            # if no text is available, assume the token did not contain any newline characters.
+            return line
+
+        # only reach this if tokens is empty, meaning EOF occurs at the first
+        # position in the input
+        return 1
+
+    #
+    # {@inheritDoc}
+    #
+    def getInputStream(self):
+        if self.pos < len(self.tokens):
+            return self.tokens[self.pos].getInputStream()
+        elif self.eofToken is not None:
+            return self.eofToken.getInputStream()
+        elif len(self.tokens) > 0:
+            return self.tokens[len(self.tokens) - 1].getInputStream()
+        else:
+            # no input stream information is available
+            return None
+
+    #
+    # {@inheritDoc}
+    #
+    def getSourceName(self):
+        if self.sourceName is not None:
+            return self.sourceName
+        inputStream = self.getInputStream()
+        if inputStream is not None:
+            return inputStream.getSourceName()
+        else:
+            return "List"

lib/python3.12/site-packages/antlr4/Parser.py

@@ -0,0 +1,580 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+import sys
+if sys.version_info[1] > 5:
+    from typing import TextIO
+else:
+    from typing.io import TextIO
+from antlr4.BufferedTokenStream import TokenStream
+from antlr4.CommonTokenFactory import TokenFactory
+from antlr4.error.ErrorStrategy import DefaultErrorStrategy
+from antlr4.InputStream import InputStream
+from antlr4.Recognizer import Recognizer
+from antlr4.RuleContext import RuleContext
+from antlr4.ParserRuleContext import ParserRuleContext
+from antlr4.Token import Token
+from antlr4.Lexer import Lexer
+from antlr4.atn.ATNDeserializer import ATNDeserializer
+from antlr4.atn.ATNDeserializationOptions import ATNDeserializationOptions
+from antlr4.error.Errors import UnsupportedOperationException, RecognitionException
+from antlr4.tree.ParseTreePatternMatcher import ParseTreePatternMatcher
+from antlr4.tree.Tree import ParseTreeListener, TerminalNode, ErrorNode
+
+class TraceListener(ParseTreeListener):
+    __slots__ = '_parser'
+
+    def __init__(self, parser):
+        self._parser = parser
+
+    def enterEveryRule(self, ctx):
+        print("enter   " + self._parser.ruleNames[ctx.getRuleIndex()] + ", LT(1)=" + self._parser._input.LT(1).text, file=self._parser._output)
+
+    def visitTerminal(self, node):
+
+        print("consume " + str(node.symbol) + " rule " + self._parser.ruleNames[self._parser._ctx.getRuleIndex()], file=self._parser._output)
+
+    def visitErrorNode(self, node):
+        pass
+
+
+    def exitEveryRule(self, ctx):
+        print("exit    " + self._parser.ruleNames[ctx.getRuleIndex()] + ", LT(1)=" + self._parser._input.LT(1).text, file=self._parser._output)
+
+
+# self is all the parsing support code essentially; most of it is error recovery stuff.#
+class Parser (Recognizer):
+    __slots__ = (
+        '_input', '_output', '_errHandler', '_precedenceStack', '_ctx',
+        'buildParseTrees', '_tracer', '_parseListeners', '_syntaxErrors'
+
+    )
+    # self field maps from the serialized ATN string to the deserialized {@link ATN} with
+    # bypass alternatives.
+    #
+    # @see ATNDeserializationOptions#isGenerateRuleBypassTransitions()
+    #
+    bypassAltsAtnCache = dict()
+
+    def __init__(self, input:TokenStream, output:TextIO = sys.stdout):
+        super().__init__()
+        # The input stream.
+        self._input = None
+        self._output = output
+        # The error handling strategy for the parser. The default value is a new
+        # instance of {@link DefaultErrorStrategy}.
+        self._errHandler = DefaultErrorStrategy()
+        self._precedenceStack = list()
+        self._precedenceStack.append(0)
+        # The {@link ParserRuleContext} object for the currently executing rule.
+        # self is always non-null during the parsing process.
+        self._ctx = None
+        # Specifies whether or not the parser should construct a parse tree during
+        # the parsing process. The default value is {@code true}.
+        self.buildParseTrees = True
+        # When {@link #setTrace}{@code (true)} is called, a reference to the
+        # {@link TraceListener} is stored here so it can be easily removed in a
+        # later call to {@link #setTrace}{@code (false)}. The listener itself is
+        # implemented as a parser listener so self field is not directly used by
+        # other parser methods.
+        self._tracer = None
+        # The list of {@link ParseTreeListener} listeners registered to receive
+        # events during the parse.
+        self._parseListeners = None
+        # The number of syntax errors reported during parsing. self value is
+        # incremented each time {@link #notifyErrorListeners} is called.
+        self._syntaxErrors = 0
+        self.setInputStream(input)
+
+    # reset the parser's state#
+    def reset(self):
+        if self._input is not None:
+            self._input.seek(0)
+        self._errHandler.reset(self)
+        self._ctx = None
+        self._syntaxErrors = 0
+        self.setTrace(False)
+        self._precedenceStack = list()
+        self._precedenceStack.append(0)
+        if self._interp is not None:
+            self._interp.reset()
+
+    # Match current input symbol against {@code ttype}. If the symbol type
+    # matches, {@link ANTLRErrorStrategy#reportMatch} and {@link #consume} are
+    # called to complete the match process.
+    #
+    # <p>If the symbol type does not match,
+    # {@link ANTLRErrorStrategy#recoverInline} is called on the current error
+    # strategy to attempt recovery. If {@link #getBuildParseTree} is
+    # {@code true} and the token index of the symbol returned by
+    # {@link ANTLRErrorStrategy#recoverInline} is -1, the symbol is added to
+    # the parse tree by calling {@link ParserRuleContext#addErrorNode}.</p>
+    #
+    # @param ttype the token type to match
+    # @return the matched symbol
+    # @throws RecognitionException if the current input symbol did not match
+    # {@code ttype} and the error strategy could not recover from the
+    # mismatched symbol
+
+    def match(self, ttype:int):
+        t = self.getCurrentToken()
+        if t.type==ttype:
+            self._errHandler.reportMatch(self)
+            self.consume()
+        else:
+            t = self._errHandler.recoverInline(self)
+            if self.buildParseTrees and t.tokenIndex==-1:
+                # we must have conjured up a new token during single token insertion
+                # if it's not the current symbol
+                self._ctx.addErrorNode(t)
+        return t
+
+    # Match current input symbol as a wildcard. If the symbol type matches
+    # (i.e. has a value greater than 0), {@link ANTLRErrorStrategy#reportMatch}
+    # and {@link #consume} are called to complete the match process.
+    #
+    # <p>If the symbol type does not match,
+    # {@link ANTLRErrorStrategy#recoverInline} is called on the current error
+    # strategy to attempt recovery. If {@link #getBuildParseTree} is
+    # {@code true} and the token index of the symbol returned by
+    # {@link ANTLRErrorStrategy#recoverInline} is -1, the symbol is added to
+    # the parse tree by calling {@link ParserRuleContext#addErrorNode}.</p>
+    #
+    # @return the matched symbol
+    # @throws RecognitionException if the current input symbol did not match
+    # a wildcard and the error strategy could not recover from the mismatched
+    # symbol
+
+    def matchWildcard(self):
+        t = self.getCurrentToken()
+        if t.type > 0:
+            self._errHandler.reportMatch(self)
+            self.consume()
+        else:
+            t = self._errHandler.recoverInline(self)
+            if self.buildParseTrees and t.tokenIndex == -1:
+                # we must have conjured up a new token during single token insertion
+                # if it's not the current symbol
+                self._ctx.addErrorNode(t)
+
+        return t
+
+    def getParseListeners(self):
+        return list() if self._parseListeners is None else self._parseListeners
+
+    # Registers {@code listener} to receive events during the parsing process.
+    #
+    # <p>To support output-preserving grammar transformations (including but not
+    # limited to left-recursion removal, automated left-factoring, and
+    # optimized code generation), calls to listener methods during the parse
+    # may differ substantially from calls made by
+    # {@link ParseTreeWalker#DEFAULT} used after the parse is complete. In
+    # particular, rule entry and exit events may occur in a different order
+    # during the parse than after the parser. In addition, calls to certain
+    # rule entry methods may be omitted.</p>
+    #
+    # <p>With the following specific exceptions, calls to listener events are
+    # <em>deterministic</em>, i.e. for identical input the calls to listener
+    # methods will be the same.</p>
+    #
+    # <ul>
+    # <li>Alterations to the grammar used to generate code may change the
+    # behavior of the listener calls.</li>
+    # <li>Alterations to the command line options passed to ANTLR 4 when
+    # generating the parser may change the behavior of the listener calls.</li>
+    # <li>Changing the version of the ANTLR Tool used to generate the parser
+    # may change the behavior of the listener calls.</li>
+    # </ul>
+    #
+    # @param listener the listener to add
+    #
+    # @throws NullPointerException if {@code} listener is {@code null}
+    #
+    def addParseListener(self, listener:ParseTreeListener):
+        if listener is None:
+            raise ReferenceError("listener")
+        if self._parseListeners is None:
+            self._parseListeners = []
+        self._parseListeners.append(listener)
+
+    #
+    # Remove {@code listener} from the list of parse listeners.
+    #
+    # <p>If {@code listener} is {@code null} or has not been added as a parse
+    # listener, self method does nothing.</p>
+    # @param listener the listener to remove
+    #
+    def removeParseListener(self, listener:ParseTreeListener):
+        if self._parseListeners is not None:
+            self._parseListeners.remove(listener)
+            if len(self._parseListeners)==0:
+                    self._parseListeners = None
+
+    # Remove all parse listeners.
+    def removeParseListeners(self):
+        self._parseListeners = None
+
+    # Notify any parse listeners of an enter rule event.
+    def triggerEnterRuleEvent(self):
+        if self._parseListeners is not None:
+            for listener in self._parseListeners:
+                listener.enterEveryRule(self._ctx)
+                self._ctx.enterRule(listener)
+
+    #
+    # Notify any parse listeners of an exit rule event.
+    #
+    # @see #addParseListener
+    #
+    def triggerExitRuleEvent(self):
+        if self._parseListeners is not None:
+            # reverse order walk of listeners
+            for listener in reversed(self._parseListeners):
+                self._ctx.exitRule(listener)
+                listener.exitEveryRule(self._ctx)
+
+
+    # Gets the number of syntax errors reported during parsing. This value is
+    # incremented each time {@link #notifyErrorListeners} is called.
+    #
+    # @see #notifyErrorListeners
+    #
+    def getNumberOfSyntaxErrors(self):
+        return self._syntaxErrors
+
+    def getTokenFactory(self):
+        return self._input.tokenSource._factory
+
+    # Tell our token source and error strategy about a new way to create tokens.#
+    def setTokenFactory(self, factory:TokenFactory):
+        self._input.tokenSource._factory = factory
+
+    # The ATN with bypass alternatives is expensive to create so we create it
+    # lazily.
+    #
+    # @throws UnsupportedOperationException if the current parser does not
+    # implement the {@link #getSerializedATN()} method.
+    #
+    def getATNWithBypassAlts(self):
+        serializedAtn = self.getSerializedATN()
+        if serializedAtn is None:
+            raise UnsupportedOperationException("The current parser does not support an ATN with bypass alternatives.")
+        result = self.bypassAltsAtnCache.get(serializedAtn, None)
+        if result is None:
+            deserializationOptions = ATNDeserializationOptions()
+            deserializationOptions.generateRuleBypassTransitions = True
+            result = ATNDeserializer(deserializationOptions).deserialize(serializedAtn)
+            self.bypassAltsAtnCache[serializedAtn] = result
+        return result
+
+    # The preferred method of getting a tree pattern. For example, here's a
+    # sample use:
+    #
+    # <pre>
+    # ParseTree t = parser.expr();
+    # ParseTreePattern p = parser.compileParseTreePattern("&lt;ID&gt;+0", MyParser.RULE_expr);
+    # ParseTreeMatch m = p.match(t);
+    # String id = m.get("ID");
+    # </pre>
+    #
+    def compileParseTreePattern(self, pattern:str, patternRuleIndex:int, lexer:Lexer = None):
+        if lexer is None:
+            if self.getTokenStream() is not None:
+                tokenSource = self.getTokenStream().tokenSource
+                if isinstance( tokenSource, Lexer ):
+                    lexer = tokenSource
+        if lexer is None:
+            raise UnsupportedOperationException("Parser can't discover a lexer to use")
+
+        m = ParseTreePatternMatcher(lexer, self)
+        return m.compile(pattern, patternRuleIndex)
+
+
+    def getInputStream(self):
+        return self.getTokenStream()
+
+    def setInputStream(self, input:InputStream):
+        self.setTokenStream(input)
+
+    def getTokenStream(self):
+        return self._input
+
+    # Set the token stream and reset the parser.#
+    def setTokenStream(self, input:TokenStream):
+        self._input = None
+        self.reset()
+        self._input = input
+
+    # Match needs to return the current input symbol, which gets put
+    #  into the label for the associated token ref; e.g., x=ID.
+    #
+    def getCurrentToken(self):
+        return self._input.LT(1)
+
+    def notifyErrorListeners(self, msg:str, offendingToken:Token = None, e:RecognitionException = None):
+        if offendingToken is None:
+            offendingToken = self.getCurrentToken()
+        self._syntaxErrors += 1
+        line = offendingToken.line
+        column = offendingToken.column
+        listener = self.getErrorListenerDispatch()
+        listener.syntaxError(self, offendingToken, line, column, msg, e)
+
+    #
+    # Consume and return the {@linkplain #getCurrentToken current symbol}.
+    #
+    # <p>E.g., given the following input with {@code A} being the current
+    # lookahead symbol, self function moves the cursor to {@code B} and returns
+    # {@code A}.</p>
+    #
+    # <pre>
+    #  A B
+    #  ^
+    # </pre>
+    #
+    # If the parser is not in error recovery mode, the consumed symbol is added
+    # to the parse tree using {@link ParserRuleContext#addChild(Token)}, and
+    # {@link ParseTreeListener#visitTerminal} is called on any parse listeners.
+    # If the parser <em>is</em> in error recovery mode, the consumed symbol is
+    # added to the parse tree using
+    # {@link ParserRuleContext#addErrorNode(Token)}, and
+    # {@link ParseTreeListener#visitErrorNode} is called on any parse
+    # listeners.
+    #
+    def consume(self):
+        o = self.getCurrentToken()
+        if o.type != Token.EOF:
+            self.getInputStream().consume()
+        hasListener = self._parseListeners is not None and len(self._parseListeners)>0
+        if self.buildParseTrees or hasListener:
+            if self._errHandler.inErrorRecoveryMode(self):
+                node = self._ctx.addErrorNode(o)
+            else:
+                node = self._ctx.addTokenNode(o)
+            if hasListener:
+                for listener in self._parseListeners:
+                    if isinstance(node, ErrorNode):
+                        listener.visitErrorNode(node)
+                    elif isinstance(node, TerminalNode):
+                        listener.visitTerminal(node)
+        return o
+
+    def addContextToParseTree(self):
+        # add current context to parent if we have a parent
+        if self._ctx.parentCtx is not None:
+            self._ctx.parentCtx.addChild(self._ctx)
+
+    # Always called by generated parsers upon entry to a rule. Access field
+    # {@link #_ctx} get the current context.
+    #
+    def enterRule(self, localctx:ParserRuleContext , state:int , ruleIndex:int):
+        self.state = state
+        self._ctx = localctx
+        self._ctx.start = self._input.LT(1)
+        if self.buildParseTrees:
+            self.addContextToParseTree()
+        if self._parseListeners  is not None:
+            self.triggerEnterRuleEvent()
+
+    def exitRule(self):
+        self._ctx.stop = self._input.LT(-1)
+        # trigger event on _ctx, before it reverts to parent
+        if self._parseListeners is not None:
+            self.triggerExitRuleEvent()
+        self.state = self._ctx.invokingState
+        self._ctx = self._ctx.parentCtx
+
+    def enterOuterAlt(self, localctx:ParserRuleContext, altNum:int):
+        localctx.setAltNumber(altNum)
+        # if we have new localctx, make sure we replace existing ctx
+        # that is previous child of parse tree
+        if self.buildParseTrees and self._ctx != localctx:
+            if self._ctx.parentCtx is not None:
+                self._ctx.parentCtx.removeLastChild()
+                self._ctx.parentCtx.addChild(localctx)
+        self._ctx = localctx
+
+    # Get the precedence level for the top-most precedence rule.
+    #
+    # @return The precedence level for the top-most precedence rule, or -1 if
+    # the parser context is not nested within a precedence rule.
+    #
+    def getPrecedence(self):
+        if len(self._precedenceStack)==0:
+            return -1
+        else:
+            return self._precedenceStack[-1]
+
+    def enterRecursionRule(self, localctx:ParserRuleContext, state:int, ruleIndex:int, precedence:int):
+        self.state = state
+        self._precedenceStack.append(precedence)
+        self._ctx = localctx
+        self._ctx.start = self._input.LT(1)
+        if self._parseListeners is not None:
+            self.triggerEnterRuleEvent() # simulates rule entry for left-recursive rules
+
+    #
+    # Like {@link #enterRule} but for recursive rules.
+    #
+    def pushNewRecursionContext(self, localctx:ParserRuleContext, state:int, ruleIndex:int):
+        previous = self._ctx
+        previous.parentCtx = localctx
+        previous.invokingState = state
+        previous.stop = self._input.LT(-1)
+
+        self._ctx = localctx
+        self._ctx.start = previous.start
+        if self.buildParseTrees:
+            self._ctx.addChild(previous)
+
+        if self._parseListeners is not None:
+            self.triggerEnterRuleEvent() # simulates rule entry for left-recursive rules
+
+    def unrollRecursionContexts(self, parentCtx:ParserRuleContext):
+        self._precedenceStack.pop()
+        self._ctx.stop = self._input.LT(-1)
+        retCtx = self._ctx # save current ctx (return value)
+        # unroll so _ctx is as it was before call to recursive method
+        if self._parseListeners is not None:
+            while self._ctx is not parentCtx:
+                self.triggerExitRuleEvent()
+                self._ctx = self._ctx.parentCtx
+        else:
+            self._ctx = parentCtx
+
+        # hook into tree
+        retCtx.parentCtx = parentCtx
+
+        if self.buildParseTrees and parentCtx is not None:
+            # add return ctx into invoking rule's tree
+            parentCtx.addChild(retCtx)
+
+    def getInvokingContext(self, ruleIndex:int):
+        ctx = self._ctx
+        while ctx is not None:
+            if ctx.getRuleIndex() == ruleIndex:
+                return ctx
+            ctx = ctx.parentCtx
+        return None
+
+
+    def precpred(self, localctx:RuleContext , precedence:int):
+        return precedence >= self._precedenceStack[-1]
+
+    def inContext(self, context:str):
+        # TODO: useful in parser?
+        return False
+
+    #
+    # Checks whether or not {@code symbol} can follow the current state in the
+    # ATN. The behavior of self method is equivalent to the following, but is
+    # implemented such that the complete context-sensitive follow set does not
+    # need to be explicitly constructed.
+    #
+    # <pre>
+    # return getExpectedTokens().contains(symbol);
+    # </pre>
+    #
+    # @param symbol the symbol type to check
+    # @return {@code true} if {@code symbol} can follow the current state in
+    # the ATN, otherwise {@code false}.
+    #
+    def isExpectedToken(self, symbol:int):
+        atn = self._interp.atn
+        ctx = self._ctx
+        s = atn.states[self.state]
+        following = atn.nextTokens(s)
+        if symbol in following:
+            return True
+        if not Token.EPSILON in following:
+            return False
+
+        while ctx is not None and ctx.invokingState>=0 and Token.EPSILON in following:
+            invokingState = atn.states[ctx.invokingState]
+            rt = invokingState.transitions[0]
+            following = atn.nextTokens(rt.followState)
+            if symbol in following:
+                return True
+            ctx = ctx.parentCtx
+
+        if Token.EPSILON in following and symbol == Token.EOF:
+            return True
+        else:
+            return False
+
+    # Computes the set of input symbols which could follow the current parser
+    # state and context, as given by {@link #getState} and {@link #getContext},
+    # respectively.
+    #
+    # @see ATN#getExpectedTokens(int, RuleContext)
+    #
+    def getExpectedTokens(self):
+        return self._interp.atn.getExpectedTokens(self.state, self._ctx)
+
+    def getExpectedTokensWithinCurrentRule(self):
+        atn = self._interp.atn
+        s = atn.states[self.state]
+        return atn.nextTokens(s)
+
+    # Get a rule's index (i.e., {@code RULE_ruleName} field) or -1 if not found.#
+    def getRuleIndex(self, ruleName:str):
+        ruleIndex = self.getRuleIndexMap().get(ruleName, None)
+        if ruleIndex is not None:
+            return ruleIndex
+        else:
+            return -1
+
+    # Return List&lt;String&gt; of the rule names in your parser instance
+    #  leading up to a call to the current rule.  You could override if
+    #  you want more details such as the file/line info of where
+    #  in the ATN a rule is invoked.
+    #
+    #  this is very useful for error messages.
+    #
+    def getRuleInvocationStack(self, p:RuleContext=None):
+        if p is None:
+            p = self._ctx
+        stack = list()
+        while p is not None:
+            # compute what follows who invoked us
+            ruleIndex = p.getRuleIndex()
+            if ruleIndex<0:
+                stack.append("n/a")
+            else:
+                stack.append(self.ruleNames[ruleIndex])
+            p = p.parentCtx
+        return stack
+
+    # For debugging and other purposes.#
+    def getDFAStrings(self):
+        return [ str(dfa) for dfa in self._interp.decisionToDFA]
+
+    # For debugging and other purposes.#
+    def dumpDFA(self):
+        seenOne = False
+        for i in range(0, len(self._interp.decisionToDFA)):
+            dfa = self._interp.decisionToDFA[i]
+            if len(dfa.states)>0:
+                if seenOne:
+                    print(file=self._output)
+                print("Decision " + str(dfa.decision) + ":", file=self._output)
+                print(dfa.toString(self.literalNames, self.symbolicNames), end='', file=self._output)
+                seenOne = True
+
+
+    def getSourceName(self):
+        return self._input.sourceName
+
+    # During a parse is sometimes useful to listen in on the rule entry and exit
+    #  events as well as token matches. self is for quick and dirty debugging.
+    #
+    def setTrace(self, trace:bool):
+        if not trace:
+            self.removeParseListener(self._tracer)
+            self._tracer = None
+        else:
+            if self._tracer is not None:
+                self.removeParseListener(self._tracer)
+            self._tracer = TraceListener(self)
+            self.addParseListener(self._tracer)

lib/python3.12/site-packages/antlr4/ParserInterpreter.py

@@ -0,0 +1,170 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+# A parser simulator that mimics what ANTLR's generated
+#  parser code does. A ParserATNSimulator is used to make
+#  predictions via adaptivePredict but this class moves a pointer through the
+#  ATN to simulate parsing. ParserATNSimulator just
+#  makes us efficient rather than having to backtrack, for example.
+#
+#  This properly creates parse trees even for left recursive rules.
+#
+#  We rely on the left recursive rule invocation and special predicate
+#  transitions to make left recursive rules work.
+#
+#  See TestParserInterpreter for examples.
+#
+from antlr4.dfa.DFA import DFA
+from antlr4.BufferedTokenStream import TokenStream
+from antlr4.Lexer import Lexer
+from antlr4.Parser import Parser
+from antlr4.ParserRuleContext import InterpreterRuleContext, ParserRuleContext
+from antlr4.Token import Token
+from antlr4.atn.ATN import ATN
+from antlr4.atn.ATNState import StarLoopEntryState, ATNState, LoopEndState
+from antlr4.atn.ParserATNSimulator import ParserATNSimulator
+from antlr4.PredictionContext import PredictionContextCache
+from antlr4.atn.Transition import Transition
+from antlr4.error.Errors import RecognitionException, UnsupportedOperationException, FailedPredicateException
+
+
+class ParserInterpreter(Parser):
+    __slots__ = (
+        'grammarFileName', 'atn', 'tokenNames', 'ruleNames', 'decisionToDFA',
+        'sharedContextCache', '_parentContextStack',
+        'pushRecursionContextStates'
+    )
+
+    def __init__(self, grammarFileName:str, tokenNames:list, ruleNames:list, atn:ATN, input:TokenStream):
+        super().__init__(input)
+        self.grammarFileName = grammarFileName
+        self.atn = atn
+        self.tokenNames = tokenNames
+        self.ruleNames = ruleNames
+        self.decisionToDFA = [ DFA(state) for state in atn.decisionToState ]
+        self.sharedContextCache = PredictionContextCache()
+        self._parentContextStack = list()
+        # identify the ATN states where pushNewRecursionContext must be called
+        self.pushRecursionContextStates = set()
+        for state in atn.states:
+            if not isinstance(state, StarLoopEntryState):
+                continue
+            if state.isPrecedenceDecision:
+                self.pushRecursionContextStates.add(state.stateNumber)
+        # get atn simulator that knows how to do predictions
+        self._interp = ParserATNSimulator(self, atn, self.decisionToDFA, self.sharedContextCache)
+
+    # Begin parsing at startRuleIndex#
+    def parse(self, startRuleIndex:int):
+        startRuleStartState = self.atn.ruleToStartState[startRuleIndex]
+        rootContext = InterpreterRuleContext(None, ATNState.INVALID_STATE_NUMBER, startRuleIndex)
+        if startRuleStartState.isPrecedenceRule:
+            self.enterRecursionRule(rootContext, startRuleStartState.stateNumber, startRuleIndex, 0)
+        else:
+            self.enterRule(rootContext, startRuleStartState.stateNumber, startRuleIndex)
+        while True:
+            p = self.getATNState()
+            if p.stateType==ATNState.RULE_STOP :
+                # pop; return from rule
+                if len(self._ctx)==0:
+                    if startRuleStartState.isPrecedenceRule:
+                        result = self._ctx
+                        parentContext = self._parentContextStack.pop()
+                        self.unrollRecursionContexts(parentContext.a)
+                        return result
+                    else:
+                        self.exitRule()
+                        return rootContext
+                self.visitRuleStopState(p)
+
+            else:
+                try:
+                    self.visitState(p)
+                except RecognitionException as e:
+                    self.state = self.atn.ruleToStopState[p.ruleIndex].stateNumber
+                    self._ctx.exception = e
+                    self._errHandler.reportError(self, e)
+                    self._errHandler.recover(self, e)
+
+    def enterRecursionRule(self, localctx:ParserRuleContext, state:int, ruleIndex:int, precedence:int):
+        self._parentContextStack.append((self._ctx, localctx.invokingState))
+        super().enterRecursionRule(localctx, state, ruleIndex, precedence)
+
+    def getATNState(self):
+        return self.atn.states[self.state]
+
+    def visitState(self, p:ATNState):
+        edge = 0
+        if len(p.transitions) > 1:
+            self._errHandler.sync(self)
+            edge = self._interp.adaptivePredict(self._input, p.decision, self._ctx)
+        else:
+            edge = 1
+
+        transition = p.transitions[edge - 1]
+        tt = transition.serializationType
+        if tt==Transition.EPSILON:
+
+            if self.pushRecursionContextStates[p.stateNumber] and not isinstance(transition.target, LoopEndState):
+                t = self._parentContextStack[-1]
+                ctx = InterpreterRuleContext(t[0], t[1], self._ctx.ruleIndex)
+                self.pushNewRecursionContext(ctx, self.atn.ruleToStartState[p.ruleIndex].stateNumber, self._ctx.ruleIndex)
+
+        elif tt==Transition.ATOM:
+
+            self.match(transition.label)
+
+        elif tt in [ Transition.RANGE, Transition.SET, Transition.NOT_SET]:
+
+            if not transition.matches(self._input.LA(1), Token.MIN_USER_TOKEN_TYPE, Lexer.MAX_CHAR_VALUE):
+                self._errHandler.recoverInline(self)
+            self.matchWildcard()
+
+        elif tt==Transition.WILDCARD:
+
+            self.matchWildcard()
+
+        elif tt==Transition.RULE:
+
+            ruleStartState = transition.target
+            ruleIndex = ruleStartState.ruleIndex
+            ctx = InterpreterRuleContext(self._ctx, p.stateNumber, ruleIndex)
+            if ruleStartState.isPrecedenceRule:
+                self.enterRecursionRule(ctx, ruleStartState.stateNumber, ruleIndex, transition.precedence)
+            else:
+                self.enterRule(ctx, transition.target.stateNumber, ruleIndex)
+
+        elif tt==Transition.PREDICATE:
+
+            if not self.sempred(self._ctx, transition.ruleIndex, transition.predIndex):
+                raise FailedPredicateException(self)
+
+        elif tt==Transition.ACTION:
+
+            self.action(self._ctx, transition.ruleIndex, transition.actionIndex)
+
+        elif tt==Transition.PRECEDENCE:
+
+            if not self.precpred(self._ctx, transition.precedence):
+                msg = "precpred(_ctx, " + str(transition.precedence) + ")"
+                raise FailedPredicateException(self, msg)
+
+        else:
+            raise UnsupportedOperationException("Unrecognized ATN transition type.")
+
+        self.state = transition.target.stateNumber
+
+    def visitRuleStopState(self, p:ATNState):
+        ruleStartState = self.atn.ruleToStartState[p.ruleIndex]
+        if ruleStartState.isPrecedenceRule:
+            parentContext = self._parentContextStack.pop()
+            self.unrollRecursionContexts(parentContext.a)
+            self.state = parentContext[1]
+        else:
+            self.exitRule()
+
+        ruleTransition = self.atn.states[self.state].transitions[0]
+        self.state = ruleTransition.followState.stateNumber

lib/python3.12/site-packages/antlr4/ParserRuleContext.py

@@ -0,0 +1,186 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+
+#* A rule invocation record for parsing.
+#
+#  Contains all of the information about the current rule not stored in the
+#  RuleContext. It handles parse tree children list, Any ATN state
+#  tracing, and the default values available for rule indications:
+#  start, stop, rule index, current alt number, current
+#  ATN state.
+#
+#  Subclasses made for each rule and grammar track the parameters,
+#  return values, locals, and labels specific to that rule. These
+#  are the objects that are returned from rules.
+#
+#  Note text is not an actual field of a rule return value; it is computed
+#  from start and stop using the input stream's toString() method.  I
+#  could add a ctor to this so that we can pass in and store the input
+#  stream, but I'm not sure we want to do that.  It would seem to be undefined
+#  to get the .text property anyway if the rule matches tokens from multiple
+#  input streams.
+#
+#  I do not use getters for fields of objects that are used simply to
+#  group values such as this aggregate.  The getters/setters are there to
+#  satisfy the superclass interface.
+
+from antlr4.RuleContext import RuleContext
+from antlr4.Token import Token
+from antlr4.tree.Tree import ParseTreeListener, ParseTree, TerminalNodeImpl, ErrorNodeImpl, TerminalNode, \
+    INVALID_INTERVAL
+
+# need forward declaration
+ParserRuleContext = None
+
+class ParserRuleContext(RuleContext):
+    __slots__ = ('children', 'start', 'stop', 'exception')
+    def __init__(self, parent:ParserRuleContext = None, invokingStateNumber:int = None ):
+        super().__init__(parent, invokingStateNumber)
+        #* If we are debugging or building a parse tree for a visitor,
+        #  we need to track all of the tokens and rule invocations associated
+        #  with this rule's context. This is empty for parsing w/o tree constr.
+        #  operation because we don't the need to track the details about
+        #  how we parse this rule.
+        #/
+        self.children = None
+        self.start = None
+        self.stop = None
+        # The exception that forced this rule to return. If the rule successfully
+        # completed, this is {@code null}.
+        self.exception = None
+
+    #* COPY a ctx (I'm deliberately not using copy constructor)#/
+    #
+    # This is used in the generated parser code to flip a generic XContext
+    # node for rule X to a YContext for alt label Y. In that sense, it is
+    # not really a generic copy function.
+    #
+    # If we do an error sync() at start of a rule, we might add error nodes
+    # to the generic XContext so this function must copy those nodes to
+    # the YContext as well else they are lost!
+    #/
+    def copyFrom(self, ctx:ParserRuleContext):
+        # from RuleContext
+        self.parentCtx = ctx.parentCtx
+        self.invokingState = ctx.invokingState
+        self.children = None
+        self.start = ctx.start
+        self.stop = ctx.stop
+
+        # copy any error nodes to alt label node
+        if ctx.children is not None:
+            self.children = []
+            # reset parent pointer for any error nodes
+            for child in ctx.children:
+                if isinstance(child, ErrorNodeImpl):
+                    self.children.append(child)
+                    child.parentCtx = self
+
+    # Double dispatch methods for listeners
+    def enterRule(self, listener:ParseTreeListener):
+        pass
+
+    def exitRule(self, listener:ParseTreeListener):
+        pass
+
+    #* Does not set parent link; other add methods do that#/
+    def addChild(self, child:ParseTree):
+        if self.children is None:
+            self.children = []
+        self.children.append(child)
+        return child
+
+    #* Used by enterOuterAlt to toss out a RuleContext previously added as
+    #  we entered a rule. If we have # label, we will need to remove
+    #  generic ruleContext object.
+    #/
+    def removeLastChild(self):
+        if self.children is not None:
+            del self.children[len(self.children)-1]
+
+    def addTokenNode(self, token:Token):
+        node = TerminalNodeImpl(token)
+        self.addChild(node)
+        node.parentCtx = self
+        return node
+
+    def addErrorNode(self, badToken:Token):
+        node = ErrorNodeImpl(badToken)
+        self.addChild(node)
+        node.parentCtx = self
+        return node
+
+    def getChild(self, i:int, ttype:type = None):
+        if ttype is None:
+            return self.children[i] if len(self.children)>i else None
+        else:
+            for child in self.getChildren():
+                if not isinstance(child, ttype):
+                    continue
+                if i==0:
+                    return child
+                i -= 1
+            return None
+
+    def getChildren(self, predicate = None):
+        if self.children is not None:
+            for child in self.children:
+                if predicate is not None and not predicate(child):
+                    continue
+                yield child
+
+    def getToken(self, ttype:int, i:int):
+        for child in self.getChildren():
+            if not isinstance(child, TerminalNode):
+                continue
+            if child.symbol.type != ttype:
+                continue
+            if i==0:
+                return child
+            i -= 1
+        return None
+
+    def getTokens(self, ttype:int ):
+        if self.getChildren() is None:
+            return []
+        tokens = []
+        for child in self.getChildren():
+            if not isinstance(child, TerminalNode):
+                continue
+            if child.symbol.type != ttype:
+                continue
+            tokens.append(child)
+        return tokens
+
+    def getTypedRuleContext(self, ctxType:type, i:int):
+        return self.getChild(i, ctxType)
+
+    def getTypedRuleContexts(self, ctxType:type):
+        children = self.getChildren()
+        if children is None:
+            return []
+        contexts = []
+        for child in children:
+            if not isinstance(child, ctxType):
+                continue
+            contexts.append(child)
+        return contexts
+
+    def getChildCount(self):
+        return len(self.children) if self.children else 0
+
+    def getSourceInterval(self):
+        if self.start is None or self.stop is None:
+            return INVALID_INTERVAL
+        else:
+            return (self.start.tokenIndex, self.stop.tokenIndex)
+
+
+RuleContext.EMPTY = ParserRuleContext()
+
+class InterpreterRuleContext(ParserRuleContext):
+
+    def __init__(self, parent:ParserRuleContext, invokingStateNumber:int, ruleIndex:int):
+        super().__init__(parent, invokingStateNumber)
+        self.ruleIndex = ruleIndex

lib/python3.12/site-packages/antlr4/PredictionContext.py

@@ -0,0 +1,623 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+from io import StringIO
+
+from antlr4.error.Errors import IllegalStateException
+
+from antlr4.RuleContext import RuleContext
+from antlr4.atn.ATN import ATN
+from antlr4.atn.ATNState import ATNState
+
+
+class PredictionContext(object):
+
+    # Represents {@code $} in local context prediction, which means wildcard.
+    # {@code#+x =#}.
+    #/
+    EMPTY = None
+
+    # Represents {@code $} in an array in full context mode, when {@code $}
+    # doesn't mean wildcard: {@code $ + x = [$,x]}. Here,
+    # {@code $} = {@link #EMPTY_RETURN_STATE}.
+    #/
+    EMPTY_RETURN_STATE = 0x7FFFFFFF
+
+    globalNodeCount = 1
+    id = globalNodeCount
+
+    # Stores the computed hash code of this {@link PredictionContext}. The hash
+    # code is computed in parts to match the following reference algorithm.
+    #
+    # <pre>
+    #  private int referenceHashCode() {
+    #      int hash = {@link MurmurHash#initialize MurmurHash.initialize}({@link #INITIAL_HASH});
+    #
+    #      for (int i = 0; i &lt; {@link #size()}; i++) {
+    #          hash = {@link MurmurHash#update MurmurHash.update}(hash, {@link #getParent getParent}(i));
+    #      }
+    #
+    #      for (int i = 0; i &lt; {@link #size()}; i++) {
+    #          hash = {@link MurmurHash#update MurmurHash.update}(hash, {@link #getReturnState getReturnState}(i));
+    #      }
+    #
+    #      hash = {@link MurmurHash#finish MurmurHash.finish}(hash, 2# {@link #size()});
+    #      return hash;
+    #  }
+    # </pre>
+    #/
+
+    def __init__(self, cachedHashCode:int):
+        self.cachedHashCode = cachedHashCode
+
+    def __len__(self):
+        return 0
+
+    # This means only the {@link #EMPTY} context is in set.
+    def isEmpty(self):
+        return self is self.EMPTY
+
+    def hasEmptyPath(self):
+        return self.getReturnState(len(self) - 1) == self.EMPTY_RETURN_STATE
+
+    def getReturnState(self, index:int):
+        raise IllegalStateException("illegal!")
+
+    def __hash__(self):
+        return self.cachedHashCode
+
+def calculateHashCode(parent:PredictionContext, returnState:int):
+    return hash("") if parent is None else hash((hash(parent), returnState))
+
+def calculateListsHashCode(parents:[], returnStates:[] ):
+    h = 0
+    for parent, returnState in zip(parents, returnStates):
+        h = hash((h, calculateHashCode(parent, returnState)))
+    return h
+
+#  Used to cache {@link PredictionContext} objects. Its used for the shared
+#  context cash associated with contexts in DFA states. This cache
+#  can be used for both lexers and parsers.
+
+class PredictionContextCache(object):
+
+    def __init__(self):
+        self.cache = dict()
+
+    #  Add a context to the cache and return it. If the context already exists,
+    #  return that one instead and do not add a new context to the cache.
+    #  Protect shared cache from unsafe thread access.
+    #
+    def add(self, ctx:PredictionContext):
+        if ctx==PredictionContext.EMPTY:
+            return PredictionContext.EMPTY
+        existing = self.cache.get(ctx, None)
+        if existing is not None:
+            return existing
+        self.cache[ctx] = ctx
+        return ctx
+
+    def get(self, ctx:PredictionContext):
+        return self.cache.get(ctx, None)
+
+    def __len__(self):
+        return len(self.cache)
+
+
+class SingletonPredictionContext(PredictionContext):
+
+    @staticmethod
+    def create(parent:PredictionContext , returnState:int ):
+        if returnState == PredictionContext.EMPTY_RETURN_STATE and parent is None:
+            # someone can pass in the bits of an array ctx that mean $
+            return SingletonPredictionContext.EMPTY
+        else:
+            return SingletonPredictionContext(parent, returnState)
+
+    def __init__(self, parent:PredictionContext, returnState:int):
+        hashCode = calculateHashCode(parent, returnState)
+        super().__init__(hashCode)
+        self.parentCtx = parent
+        self.returnState = returnState
+
+    def __len__(self):
+        return 1
+
+    def getParent(self, index:int):
+        return self.parentCtx
+
+    def getReturnState(self, index:int):
+        return self.returnState
+
+    def __eq__(self, other):
+        if self is other:
+            return True
+        elif other is None:
+            return False
+        elif not isinstance(other, SingletonPredictionContext):
+            return False
+        else:
+            return self.returnState == other.returnState and self.parentCtx == other.parentCtx
+
+    def __hash__(self):
+        return self.cachedHashCode
+
+    def __str__(self):
+        up = "" if self.parentCtx is None else str(self.parentCtx)
+        if len(up)==0:
+            if self.returnState == self.EMPTY_RETURN_STATE:
+                return "$"
+            else:
+                return str(self.returnState)
+        else:
+            return str(self.returnState) + " " + up
+
+
+class EmptyPredictionContext(SingletonPredictionContext):
+
+    def __init__(self):
+        super().__init__(None, PredictionContext.EMPTY_RETURN_STATE)
+
+    def isEmpty(self):
+        return True
+
+    def __eq__(self, other):
+        return self is other
+
+    def __hash__(self):
+        return self.cachedHashCode
+
+    def __str__(self):
+        return "$"
+
+
+PredictionContext.EMPTY = EmptyPredictionContext()
+
+class ArrayPredictionContext(PredictionContext):
+    # Parent can be null only if full ctx mode and we make an array
+    #  from {@link #EMPTY} and non-empty. We merge {@link #EMPTY} by using null parent and
+    #  returnState == {@link #EMPTY_RETURN_STATE}.
+
+    def __init__(self, parents:list, returnStates:list):
+        super().__init__(calculateListsHashCode(parents, returnStates))
+        self.parents = parents
+        self.returnStates = returnStates
+
+    def isEmpty(self):
+        # since EMPTY_RETURN_STATE can only appear in the last position, we
+        # don't need to verify that size==1
+        return self.returnStates[0]==PredictionContext.EMPTY_RETURN_STATE
+
+    def __len__(self):
+        return len(self.returnStates)
+
+    def getParent(self, index:int):
+        return self.parents[index]
+
+    def getReturnState(self, index:int):
+        return self.returnStates[index]
+
+    def __eq__(self, other):
+        if self is other:
+            return True
+        elif not isinstance(other, ArrayPredictionContext):
+            return False
+        elif hash(self) != hash(other):
+            return False # can't be same if hash is different
+        else:
+            return self.returnStates==other.returnStates and self.parents==other.parents
+
+    def __str__(self):
+        if self.isEmpty():
+            return "[]"
+        with StringIO() as buf:
+            buf.write("[")
+            for i in range(0,len(self.returnStates)):
+                if i>0:
+                    buf.write(", ")
+                if self.returnStates[i]==PredictionContext.EMPTY_RETURN_STATE:
+                    buf.write("$")
+                    continue
+                buf.write(str(self.returnStates[i]))
+                if self.parents[i] is not None:
+                    buf.write(' ')
+                    buf.write(str(self.parents[i]))
+                else:
+                    buf.write("null")
+            buf.write("]")
+            return buf.getvalue()
+
+    def __hash__(self):
+        return self.cachedHashCode
+
+
+
+#  Convert a {@link RuleContext} tree to a {@link PredictionContext} graph.
+#  Return {@link #EMPTY} if {@code outerContext} is empty or null.
+#/
+def PredictionContextFromRuleContext(atn:ATN, outerContext:RuleContext=None):
+    if outerContext is None:
+        outerContext = RuleContext.EMPTY
+
+    # if we are in RuleContext of start rule, s, then PredictionContext
+    # is EMPTY. Nobody called us. (if we are empty, return empty)
+    if outerContext.parentCtx is None or outerContext is RuleContext.EMPTY:
+        return PredictionContext.EMPTY
+
+    # If we have a parent, convert it to a PredictionContext graph
+    parent = PredictionContextFromRuleContext(atn, outerContext.parentCtx)
+    state = atn.states[outerContext.invokingState]
+    transition = state.transitions[0]
+    return SingletonPredictionContext.create(parent, transition.followState.stateNumber)
+
+
+def merge(a:PredictionContext, b:PredictionContext, rootIsWildcard:bool, mergeCache:dict):
+
+    # share same graph if both same
+    if a==b:
+        return a
+
+    if isinstance(a, SingletonPredictionContext) and isinstance(b, SingletonPredictionContext):
+        return mergeSingletons(a, b, rootIsWildcard, mergeCache)
+
+    # At least one of a or b is array
+    # If one is $ and rootIsWildcard, return $ as# wildcard
+    if rootIsWildcard:
+        if isinstance( a, EmptyPredictionContext ):
+            return a
+        if isinstance( b, EmptyPredictionContext ):
+            return b
+
+    # convert singleton so both are arrays to normalize
+    if isinstance( a, SingletonPredictionContext ):
+        a = ArrayPredictionContext([a.parentCtx], [a.returnState])
+    if isinstance( b, SingletonPredictionContext):
+        b = ArrayPredictionContext([b.parentCtx], [b.returnState])
+    return mergeArrays(a, b, rootIsWildcard, mergeCache)
+
+
+#
+# Merge two {@link SingletonPredictionContext} instances.
+#
+# <p>Stack tops equal, parents merge is same; return left graph.<br>
+# <embed src="images/SingletonMerge_SameRootSamePar.svg" type="image/svg+xml"/></p>
+#
+# <p>Same stack top, parents differ; merge parents giving array node, then
+# remainders of those graphs. A new root node is created to point to the
+# merged parents.<br>
+# <embed src="images/SingletonMerge_SameRootDiffPar.svg" type="image/svg+xml"/></p>
+#
+# <p>Different stack tops pointing to same parent. Make array node for the
+# root where both element in the root point to the same (original)
+# parent.<br>
+# <embed src="images/SingletonMerge_DiffRootSamePar.svg" type="image/svg+xml"/></p>
+#
+# <p>Different stack tops pointing to different parents. Make array node for
+# the root where each element points to the corresponding original
+# parent.<br>
+# <embed src="images/SingletonMerge_DiffRootDiffPar.svg" type="image/svg+xml"/></p>
+#
+# @param a the first {@link SingletonPredictionContext}
+# @param b the second {@link SingletonPredictionContext}
+# @param rootIsWildcard {@code true} if this is a local-context merge,
+# otherwise false to indicate a full-context merge
+# @param mergeCache
+#/
+def mergeSingletons(a:SingletonPredictionContext, b:SingletonPredictionContext, rootIsWildcard:bool, mergeCache:dict):
+    if mergeCache is not None:
+        previous = mergeCache.get((a,b), None)
+        if previous is not None:
+            return previous
+        previous = mergeCache.get((b,a), None)
+        if previous is not None:
+            return previous
+
+    merged = mergeRoot(a, b, rootIsWildcard)
+    if merged is not None:
+        if mergeCache is not None:
+            mergeCache[(a, b)] = merged
+        return merged
+
+    if a.returnState==b.returnState:
+        parent = merge(a.parentCtx, b.parentCtx, rootIsWildcard, mergeCache)
+        # if parent is same as existing a or b parent or reduced to a parent, return it
+        if parent == a.parentCtx:
+            return a # ax + bx = ax, if a=b
+        if parent == b.parentCtx:
+            return b # ax + bx = bx, if a=b
+        # else: ax + ay = a'[x,y]
+        # merge parents x and y, giving array node with x,y then remainders
+        # of those graphs.  dup a, a' points at merged array
+        # new joined parent so create new singleton pointing to it, a'
+        merged = SingletonPredictionContext.create(parent, a.returnState)
+        if mergeCache is not None:
+            mergeCache[(a, b)] = merged
+        return merged
+    else: # a != b payloads differ
+        # see if we can collapse parents due to $+x parents if local ctx
+        singleParent = None
+        if a is b or (a.parentCtx is not None and a.parentCtx==b.parentCtx): # ax + bx = [a,b]x
+            singleParent = a.parentCtx
+        if singleParent is not None:	# parents are same
+            # sort payloads and use same parent
+            payloads = [ a.returnState, b.returnState ]
+            if a.returnState > b.returnState:
+                payloads = [ b.returnState, a.returnState ]
+            parents = [singleParent, singleParent]
+            merged = ArrayPredictionContext(parents, payloads)
+            if mergeCache is not None:
+                mergeCache[(a, b)] = merged
+            return merged
+        # parents differ and can't merge them. Just pack together
+        # into array; can't merge.
+        # ax + by = [ax,by]
+        payloads = [ a.returnState, b.returnState ]
+        parents = [ a.parentCtx, b.parentCtx ]
+        if a.returnState > b.returnState: # sort by payload
+            payloads = [ b.returnState, a.returnState ]
+            parents = [ b.parentCtx, a.parentCtx ]
+        merged = ArrayPredictionContext(parents, payloads)
+        if mergeCache is not None:
+            mergeCache[(a, b)] = merged
+        return merged
+
+
+#
+# Handle case where at least one of {@code a} or {@code b} is
+# {@link #EMPTY}. In the following diagrams, the symbol {@code $} is used
+# to represent {@link #EMPTY}.
+#
+# <h2>Local-Context Merges</h2>
+#
+# <p>These local-context merge operations are used when {@code rootIsWildcard}
+# is true.</p>
+#
+# <p>{@link #EMPTY} is superset of any graph; return {@link #EMPTY}.<br>
+# <embed src="images/LocalMerge_EmptyRoot.svg" type="image/svg+xml"/></p>
+#
+# <p>{@link #EMPTY} and anything is {@code #EMPTY}, so merged parent is
+# {@code #EMPTY}; return left graph.<br>
+# <embed src="images/LocalMerge_EmptyParent.svg" type="image/svg+xml"/></p>
+#
+# <p>Special case of last merge if local context.<br>
+# <embed src="images/LocalMerge_DiffRoots.svg" type="image/svg+xml"/></p>
+#
+# <h2>Full-Context Merges</h2>
+#
+# <p>These full-context merge operations are used when {@code rootIsWildcard}
+# is false.</p>
+#
+# <p><embed src="images/FullMerge_EmptyRoots.svg" type="image/svg+xml"/></p>
+#
+# <p>Must keep all contexts; {@link #EMPTY} in array is a special value (and
+# null parent).<br>
+# <embed src="images/FullMerge_EmptyRoot.svg" type="image/svg+xml"/></p>
+#
+# <p><embed src="images/FullMerge_SameRoot.svg" type="image/svg+xml"/></p>
+#
+# @param a the first {@link SingletonPredictionContext}
+# @param b the second {@link SingletonPredictionContext}
+# @param rootIsWildcard {@code true} if this is a local-context merge,
+# otherwise false to indicate a full-context merge
+#/
+def mergeRoot(a:SingletonPredictionContext, b:SingletonPredictionContext, rootIsWildcard:bool):
+    if rootIsWildcard:
+        if a == PredictionContext.EMPTY:
+            return PredictionContext.EMPTY  ## + b =#
+        if b == PredictionContext.EMPTY:
+            return PredictionContext.EMPTY  # a +# =#
+    else:
+        if a == PredictionContext.EMPTY and b == PredictionContext.EMPTY:
+            return PredictionContext.EMPTY # $ + $ = $
+        elif a == PredictionContext.EMPTY: # $ + x = [$,x]
+            payloads = [ b.returnState, PredictionContext.EMPTY_RETURN_STATE ]
+            parents = [ b.parentCtx, None ]
+            return ArrayPredictionContext(parents, payloads)
+        elif b == PredictionContext.EMPTY: # x + $ = [$,x] ($ is always first if present)
+            payloads = [ a.returnState, PredictionContext.EMPTY_RETURN_STATE ]
+            parents = [ a.parentCtx, None ]
+            return ArrayPredictionContext(parents, payloads)
+    return None
+
+
+#
+# Merge two {@link ArrayPredictionContext} instances.
+#
+# <p>Different tops, different parents.<br>
+# <embed src="images/ArrayMerge_DiffTopDiffPar.svg" type="image/svg+xml"/></p>
+#
+# <p>Shared top, same parents.<br>
+# <embed src="images/ArrayMerge_ShareTopSamePar.svg" type="image/svg+xml"/></p>
+#
+# <p>Shared top, different parents.<br>
+# <embed src="images/ArrayMerge_ShareTopDiffPar.svg" type="image/svg+xml"/></p>
+#
+# <p>Shared top, all shared parents.<br>
+# <embed src="images/ArrayMerge_ShareTopSharePar.svg" type="image/svg+xml"/></p>
+#
+# <p>Equal tops, merge parents and reduce top to
+# {@link SingletonPredictionContext}.<br>
+# <embed src="images/ArrayMerge_EqualTop.svg" type="image/svg+xml"/></p>
+#/
+def mergeArrays(a:ArrayPredictionContext, b:ArrayPredictionContext, rootIsWildcard:bool, mergeCache:dict):
+    if mergeCache is not None:
+        previous = mergeCache.get((a,b), None)
+        if previous is not None:
+            return previous
+        previous = mergeCache.get((b,a), None)
+        if previous is not None:
+            return previous
+
+    # merge sorted payloads a + b => M
+    i = 0 # walks a
+    j = 0 # walks b
+    k = 0 # walks target M array
+
+    mergedReturnStates = [None] * (len(a.returnStates) + len( b.returnStates))
+    mergedParents = [None] * len(mergedReturnStates)
+    # walk and merge to yield mergedParents, mergedReturnStates
+    while i<len(a.returnStates) and j<len(b.returnStates):
+        a_parent = a.parents[i]
+        b_parent = b.parents[j]
+        if a.returnStates[i]==b.returnStates[j]:
+            # same payload (stack tops are equal), must yield merged singleton
+            payload = a.returnStates[i]
+            # $+$ = $
+            bothDollars = payload == PredictionContext.EMPTY_RETURN_STATE and \
+                            a_parent is None and b_parent is None
+            ax_ax = (a_parent is not None and b_parent is not None) and a_parent==b_parent # ax+ax -> ax
+            if bothDollars or ax_ax:
+                mergedParents[k] = a_parent # choose left
+                mergedReturnStates[k] = payload
+            else: # ax+ay -> a'[x,y]
+                mergedParent = merge(a_parent, b_parent, rootIsWildcard, mergeCache)
+                mergedParents[k] = mergedParent
+                mergedReturnStates[k] = payload
+            i += 1 # hop over left one as usual
+            j += 1 # but also skip one in right side since we merge
+        elif a.returnStates[i]<b.returnStates[j]: # copy a[i] to M
+            mergedParents[k] = a_parent
+            mergedReturnStates[k] = a.returnStates[i]
+            i += 1
+        else: # b > a, copy b[j] to M
+            mergedParents[k] = b_parent
+            mergedReturnStates[k] = b.returnStates[j]
+            j += 1
+        k += 1
+
+    # copy over any payloads remaining in either array
+    if i < len(a.returnStates):
+        for p in range(i, len(a.returnStates)):
+            mergedParents[k] = a.parents[p]
+            mergedReturnStates[k] = a.returnStates[p]
+            k += 1
+    else:
+        for p in range(j, len(b.returnStates)):
+            mergedParents[k] = b.parents[p]
+            mergedReturnStates[k] = b.returnStates[p]
+            k += 1
+
+    # trim merged if we combined a few that had same stack tops
+    if k < len(mergedParents): # write index < last position; trim
+        if k == 1: # for just one merged element, return singleton top
+            merged = SingletonPredictionContext.create(mergedParents[0], mergedReturnStates[0])
+            if mergeCache is not None:
+                mergeCache[(a,b)] = merged
+            return merged
+        mergedParents = mergedParents[0:k]
+        mergedReturnStates = mergedReturnStates[0:k]
+
+    merged = ArrayPredictionContext(mergedParents, mergedReturnStates)
+
+    # if we created same array as a or b, return that instead
+    # TODO: track whether this is possible above during merge sort for speed
+    if merged==a:
+        if mergeCache is not None:
+            mergeCache[(a,b)] = a
+        return a
+    if merged==b:
+        if mergeCache is not None:
+            mergeCache[(a,b)] = b
+        return b
+    combineCommonParents(mergedParents)
+
+    if mergeCache is not None:
+        mergeCache[(a,b)] = merged
+    return merged
+
+
+#
+# Make pass over all <em>M</em> {@code parents}; merge any {@code equals()}
+# ones.
+#/
+def combineCommonParents(parents:list):
+    uniqueParents = dict()
+
+    for p in range(0, len(parents)):
+        parent = parents[p]
+        if uniqueParents.get(parent, None) is None:
+            uniqueParents[parent] = parent
+
+    for p in range(0, len(parents)):
+        parents[p] = uniqueParents[parents[p]]
+
+def getCachedPredictionContext(context:PredictionContext, contextCache:PredictionContextCache, visited:dict):
+    if context.isEmpty():
+        return context
+    existing = visited.get(context)
+    if existing is not None:
+        return existing
+    existing = contextCache.get(context)
+    if existing is not None:
+        visited[context] = existing
+        return existing
+    changed = False
+    parents = [None] * len(context)
+    for i in range(0, len(parents)):
+        parent = getCachedPredictionContext(context.getParent(i), contextCache, visited)
+        if changed or parent is not context.getParent(i):
+            if not changed:
+                parents = [context.getParent(j) for j in range(len(context))]
+                changed = True
+            parents[i] = parent
+    if not changed:
+        contextCache.add(context)
+        visited[context] = context
+        return context
+
+    updated = None
+    if len(parents) == 0:
+        updated = PredictionContext.EMPTY
+    elif len(parents) == 1:
+        updated = SingletonPredictionContext.create(parents[0], context.getReturnState(0))
+    else:
+        updated = ArrayPredictionContext(parents, context.returnStates)
+
+    contextCache.add(updated)
+    visited[updated] = updated
+    visited[context] = updated
+
+    return updated
+
+
+#	# extra structures, but cut/paste/morphed works, so leave it.
+#	# seems to do a breadth-first walk
+#	public static List<PredictionContext> getAllNodes(PredictionContext context) {
+#		Map<PredictionContext, PredictionContext> visited =
+#			new IdentityHashMap<PredictionContext, PredictionContext>();
+#		Deque<PredictionContext> workList = new ArrayDeque<PredictionContext>();
+#		workList.add(context);
+#		visited.put(context, context);
+#		List<PredictionContext> nodes = new ArrayList<PredictionContext>();
+#		while (!workList.isEmpty()) {
+#			PredictionContext current = workList.pop();
+#			nodes.add(current);
+#			for (int i = 0; i < current.size(); i++) {
+#				PredictionContext parent = current.getParent(i);
+#				if ( parent!=null && visited.put(parent, parent) == null) {
+#					workList.push(parent);
+#				}
+#			}
+#		}
+#		return nodes;
+#	}
+
+# ter's recursive version of Sam's getAllNodes()
+def getAllContextNodes(context:PredictionContext, nodes:list=None, visited:dict=None):
+    if nodes is None:
+        nodes = list()
+        return getAllContextNodes(context, nodes, visited)
+    elif visited is None:
+        visited = dict()
+        return getAllContextNodes(context, nodes, visited)
+    else:
+        if context is None or visited.get(context, None) is not None:
+            return nodes
+        visited.put(context, context)
+        nodes.add(context)
+        for i in range(0, len(context)):
+            getAllContextNodes(context.getParent(i), nodes, visited)
+        return nodes
+

lib/python3.12/site-packages/antlr4/Recognizer.py

@@ -0,0 +1,147 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+from antlr4.RuleContext import RuleContext
+from antlr4.Token import Token
+from antlr4.error.ErrorListener import ProxyErrorListener, ConsoleErrorListener
+
+# need forward delcaration
+RecognitionException = None
+
+class Recognizer(object):
+    __slots__ = ('_listeners', '_interp', '_stateNumber')
+
+    tokenTypeMapCache = dict()
+    ruleIndexMapCache = dict()
+
+    def __init__(self):
+        self._listeners = [ ConsoleErrorListener.INSTANCE ]
+        self._interp = None
+        self._stateNumber = -1
+
+    def extractVersion(self, version):
+        pos = version.find(".")
+        major = version[0:pos]
+        version = version[pos+1:]
+        pos = version.find(".")
+        if pos==-1:
+            pos = version.find("-")
+        if pos==-1:
+            pos = len(version)
+        minor = version[0:pos]
+        return major, minor
+
+    def checkVersion(self, toolVersion):
+        runtimeVersion = "4.9.3"
+        rvmajor, rvminor = self.extractVersion(runtimeVersion)
+        tvmajor, tvminor = self.extractVersion(toolVersion)
+        if rvmajor!=tvmajor or rvminor!=tvminor:
+            print("ANTLR runtime and generated code versions disagree: "+runtimeVersion+"!="+toolVersion)
+
+    def addErrorListener(self, listener):
+        self._listeners.append(listener)
+
+    def removeErrorListener(self, listener):
+        self._listeners.remove(listener)
+
+    def removeErrorListeners(self):
+        self._listeners = []
+
+    def getTokenTypeMap(self):
+        tokenNames = self.getTokenNames()
+        if tokenNames is None:
+            from antlr4.error.Errors import UnsupportedOperationException
+            raise UnsupportedOperationException("The current recognizer does not provide a list of token names.")
+        result = self.tokenTypeMapCache.get(tokenNames, None)
+        if result is None:
+            result = zip( tokenNames, range(0, len(tokenNames)))
+            result["EOF"] = Token.EOF
+            self.tokenTypeMapCache[tokenNames] = result
+        return result
+
+    # Get a map from rule names to rule indexes.
+    #
+    # <p>Used for XPath and tree pattern compilation.</p>
+    #
+    def getRuleIndexMap(self):
+        ruleNames = self.getRuleNames()
+        if ruleNames is None:
+            from antlr4.error.Errors import UnsupportedOperationException
+            raise UnsupportedOperationException("The current recognizer does not provide a list of rule names.")
+        result = self.ruleIndexMapCache.get(ruleNames, None)
+        if result is None:
+            result = zip( ruleNames, range(0, len(ruleNames)))
+            self.ruleIndexMapCache[ruleNames] = result
+        return result
+
+    def getTokenType(self, tokenName:str):
+        ttype = self.getTokenTypeMap().get(tokenName, None)
+        if ttype is not None:
+            return ttype
+        else:
+            return Token.INVALID_TYPE
+
+
+    # What is the error header, normally line/character position information?#
+    def getErrorHeader(self, e:RecognitionException):
+        line = e.getOffendingToken().line
+        column = e.getOffendingToken().column
+        return "line "+line+":"+column
+
+
+    # How should a token be displayed in an error message? The default
+    #  is to display just the text, but during development you might
+    #  want to have a lot of information spit out.  Override in that case
+    #  to use t.toString() (which, for CommonToken, dumps everything about
+    #  the token). This is better than forcing you to override a method in
+    #  your token objects because you don't have to go modify your lexer
+    #  so that it creates a new Java type.
+    #
+    # @deprecated This method is not called by the ANTLR 4 Runtime. Specific
+    # implementations of {@link ANTLRErrorStrategy} may provide a similar
+    # feature when necessary. For example, see
+    # {@link DefaultErrorStrategy#getTokenErrorDisplay}.
+    #
+    def getTokenErrorDisplay(self, t:Token):
+        if t is None:
+            return "<no token>"
+        s = t.text
+        if s is None:
+            if t.type==Token.EOF:
+                s = "<EOF>"
+            else:
+                s = "<" + str(t.type) + ">"
+        s = s.replace("\n","\\n")
+        s = s.replace("\r","\\r")
+        s = s.replace("\t","\\t")
+        return "'" + s + "'"
+
+    def getErrorListenerDispatch(self):
+        return ProxyErrorListener(self._listeners)
+
+    # subclass needs to override these if there are sempreds or actions
+    # that the ATN interp needs to execute
+    def sempred(self, localctx:RuleContext, ruleIndex:int, actionIndex:int):
+        return True
+
+    def precpred(self, localctx:RuleContext , precedence:int):
+        return True
+
+    @property
+    def state(self):
+        return self._stateNumber
+
+    # Indicate that the recognizer has changed internal state that is
+    #  consistent with the ATN state passed in.  This way we always know
+    #  where we are in the ATN as the parser goes along. The rule
+    #  context objects form a stack that lets us see the stack of
+    #  invoking rules. Combine this and we have complete ATN
+    #  configuration information.
+
+    @state.setter
+    def state(self, atnState:int):
+        self._stateNumber = atnState
+
+del RecognitionException

lib/python3.12/site-packages/antlr4/RuleContext.py

@@ -0,0 +1,227 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+
+
+#  A rule context is a record of a single rule invocation. It knows
+#  which context invoked it, if any. If there is no parent context, then
+#  naturally the invoking state is not valid.  The parent link
+#  provides a chain upwards from the current rule invocation to the root
+#  of the invocation tree, forming a stack. We actually carry no
+#  information about the rule associated with this context (except
+#  when parsing). We keep only the state number of the invoking state from
+#  the ATN submachine that invoked this. Contrast this with the s
+#  pointer inside ParserRuleContext that tracks the current state
+#  being "executed" for the current rule.
+#
+#  The parent contexts are useful for computing lookahead sets and
+#  getting error information.
+#
+#  These objects are used during parsing and prediction.
+#  For the special case of parsers, we use the subclass
+#  ParserRuleContext.
+#
+#  @see ParserRuleContext
+#/
+from io import StringIO
+from antlr4.tree.Tree import RuleNode, INVALID_INTERVAL, ParseTreeVisitor
+from antlr4.tree.Trees import Trees
+
+# need forward declarations
+RuleContext = None
+Parser = None
+
+class RuleContext(RuleNode):
+    __slots__ = ('parentCtx', 'invokingState')
+    EMPTY = None
+
+    def __init__(self, parent:RuleContext=None, invokingState:int=-1):
+        super().__init__()
+        # What context invoked this rule?
+        self.parentCtx = parent
+        # What state invoked the rule associated with this context?
+        #  The "return address" is the followState of invokingState
+        #  If parent is null, this should be -1.
+        self.invokingState = invokingState
+
+
+    def depth(self):
+        n = 0
+        p = self
+        while p is not None:
+            p = p.parentCtx
+            n += 1
+        return n
+
+    # A context is empty if there is no invoking state; meaning nobody call
+    #  current context.
+    def isEmpty(self):
+        return self.invokingState == -1
+
+    # satisfy the ParseTree / SyntaxTree interface
+
+    def getSourceInterval(self):
+        return INVALID_INTERVAL
+
+    def getRuleContext(self):
+        return self
+
+    def getPayload(self):
+        return self
+
+   # Return the combined text of all child nodes. This method only considers
+    #  tokens which have been added to the parse tree.
+    #  <p>
+    #  Since tokens on hidden channels (e.g. whitespace or comments) are not
+    #  added to the parse trees, they will not appear in the output of this
+    #  method.
+    #/
+    def getText(self):
+        if self.getChildCount() == 0:
+            return ""
+        with StringIO() as builder:
+            for child in self.getChildren():
+                builder.write(child.getText())
+            return builder.getvalue()
+
+    def getRuleIndex(self):
+        return -1
+
+    # For rule associated with this parse tree internal node, return
+    # the outer alternative number used to match the input. Default
+    # implementation does not compute nor store this alt num. Create
+    # a subclass of ParserRuleContext with backing field and set
+    # option contextSuperClass.
+    # to set it.
+    def getAltNumber(self):
+        return 0 # should use ATN.INVALID_ALT_NUMBER but won't compile
+
+    # Set the outer alternative number for this context node. Default
+    # implementation does nothing to avoid backing field overhead for
+    # trees that don't need it.  Create
+    # a subclass of ParserRuleContext with backing field and set
+    # option contextSuperClass.
+    def setAltNumber(self, altNumber:int):
+        pass
+
+    def getChild(self, i:int):
+        return None
+
+    def getChildCount(self):
+        return 0
+
+    def getChildren(self):
+        for c in []:
+            yield c
+
+    def accept(self, visitor:ParseTreeVisitor):
+        return visitor.visitChildren(self)
+
+   # # Call this method to view a parse tree in a dialog box visually.#/
+   #  public Future<JDialog> inspect(@Nullable Parser parser) {
+   #      List<String> ruleNames = parser != null ? Arrays.asList(parser.getRuleNames()) : null;
+   #      return inspect(ruleNames);
+   #  }
+   #
+   #  public Future<JDialog> inspect(@Nullable List<String> ruleNames) {
+   #      TreeViewer viewer = new TreeViewer(ruleNames, this);
+   #      return viewer.open();
+   #  }
+   #
+   # # Save this tree in a postscript file#/
+   #  public void save(@Nullable Parser parser, String fileName)
+   #      throws IOException, PrintException
+   #  {
+   #      List<String> ruleNames = parser != null ? Arrays.asList(parser.getRuleNames()) : null;
+   #      save(ruleNames, fileName);
+   #  }
+   #
+   # # Save this tree in a postscript file using a particular font name and size#/
+   #  public void save(@Nullable Parser parser, String fileName,
+   #                   String fontName, int fontSize)
+   #      throws IOException
+   #  {
+   #      List<String> ruleNames = parser != null ? Arrays.asList(parser.getRuleNames()) : null;
+   #      save(ruleNames, fileName, fontName, fontSize);
+   #  }
+   #
+   # # Save this tree in a postscript file#/
+   #  public void save(@Nullable List<String> ruleNames, String fileName)
+   #      throws IOException, PrintException
+   #  {
+   #      Trees.writePS(this, ruleNames, fileName);
+   #  }
+   #
+   # # Save this tree in a postscript file using a particular font name and size#/
+   #  public void save(@Nullable List<String> ruleNames, String fileName,
+   #                   String fontName, int fontSize)
+   #      throws IOException
+   #  {
+   #      Trees.writePS(this, ruleNames, fileName, fontName, fontSize);
+   #  }
+   #
+   # # Print out a whole tree, not just a node, in LISP format
+   #  #  (root child1 .. childN). Print just a node if this is a leaf.
+   #  #  We have to know the recognizer so we can get rule names.
+   #  #/
+   #  @Override
+   #  public String toStringTree(@Nullable Parser recog) {
+   #      return Trees.toStringTree(this, recog);
+   #  }
+   #
+   # Print out a whole tree, not just a node, in LISP format
+   #  (root child1 .. childN). Print just a node if this is a leaf.
+   #
+    def toStringTree(self, ruleNames:list=None, recog:Parser=None):
+        return Trees.toStringTree(self, ruleNames=ruleNames, recog=recog)
+   #  }
+   #
+   #  @Override
+   #  public String toStringTree() {
+   #      return toStringTree((List<String>)null);
+   #  }
+   #
+    def __str__(self):
+        return self.toString(None, None)
+
+   #  @Override
+   #  public String toString() {
+   #      return toString((List<String>)null, (RuleContext)null);
+   #  }
+   #
+   #  public final String toString(@Nullable Recognizer<?,?> recog) {
+   #      return toString(recog, ParserRuleContext.EMPTY);
+   #  }
+   #
+   #  public final String toString(@Nullable List<String> ruleNames) {
+   #      return toString(ruleNames, null);
+   #  }
+   #
+   #  // recog null unless ParserRuleContext, in which case we use subclass toString(...)
+   #  public String toString(@Nullable Recognizer<?,?> recog, @Nullable RuleContext stop) {
+   #      String[] ruleNames = recog != null ? recog.getRuleNames() : null;
+   #      List<String> ruleNamesList = ruleNames != null ? Arrays.asList(ruleNames) : null;
+   #      return toString(ruleNamesList, stop);
+   #  }
+
+    def toString(self, ruleNames:list, stop:RuleContext)->str:
+        with StringIO() as buf:
+            p = self
+            buf.write("[")
+            while p is not None and p is not stop:
+                if ruleNames is None:
+                    if not p.isEmpty():
+                        buf.write(str(p.invokingState))
+                else:
+                    ri = p.getRuleIndex()
+                    ruleName = ruleNames[ri] if ri >= 0 and ri < len(ruleNames) else str(ri)
+                    buf.write(ruleName)
+
+                if p.parentCtx is not None and (ruleNames is not None or not p.parentCtx.isEmpty()):
+                    buf.write(" ")
+
+                p = p.parentCtx
+
+            buf.write("]")
+            return buf.getvalue()

lib/python3.12/site-packages/antlr4/StdinStream.py

@@ -0,0 +1,11 @@
+import codecs
+import sys
+
+from antlr4.InputStream import InputStream
+
+
+class StdinStream(InputStream):
+    def __init__(self, encoding:str='ascii', errors:str='strict') -> None:
+        bytes = sys.stdin.buffer.read()
+        data = codecs.decode(bytes, encoding, errors)
+        super().__init__(data)

lib/python3.12/site-packages/antlr4/Token.py

@@ -0,0 +1,155 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+# A token has properties: text, type, line, character position in the line
+# (so we can ignore tabs), token channel, index, and source from which
+# we obtained this token.
+from io import StringIO
+
+
+class Token (object):
+    __slots__ = ('source', 'type', 'channel', 'start', 'stop', 'tokenIndex', 'line', 'column', '_text')
+
+    INVALID_TYPE = 0
+
+    # During lookahead operations, this "token" signifies we hit rule end ATN state
+    # and did not follow it despite needing to.
+    EPSILON = -2
+
+    MIN_USER_TOKEN_TYPE = 1
+
+    EOF = -1
+
+    # All tokens go to the parser (unless skip() is called in that rule)
+    # on a particular "channel".  The parser tunes to a particular channel
+    # so that whitespace etc... can go to the parser on a "hidden" channel.
+
+    DEFAULT_CHANNEL = 0
+
+    # Anything on different channel than DEFAULT_CHANNEL is not parsed
+    # by parser.
+
+    HIDDEN_CHANNEL = 1
+
+    def __init__(self):
+        self.source = None
+        self.type = None # token type of the token
+        self.channel = None # The parser ignores everything not on DEFAULT_CHANNEL
+        self.start = None # optional; return -1 if not implemented.
+        self.stop = None  # optional; return -1 if not implemented.
+        self.tokenIndex = None # from 0..n-1 of the token object in the input stream
+        self.line = None # line=1..n of the 1st character
+        self.column = None # beginning of the line at which it occurs, 0..n-1
+        self._text = None # text of the token.
+
+    @property
+    def text(self):
+        return self._text
+
+    # Explicitly set the text for this token. If {code text} is not
+    # {@code null}, then {@link #getText} will return this value rather than
+    # extracting the text from the input.
+    #
+    # @param text The explicit text of the token, or {@code null} if the text
+    # should be obtained from the input along with the start and stop indexes
+    # of the token.
+
+    @text.setter
+    def text(self, text:str):
+        self._text = text
+
+
+    def getTokenSource(self):
+        return self.source[0]
+
+    def getInputStream(self):
+        return self.source[1]
+
+class CommonToken(Token):
+
+    # An empty {@link Pair} which is used as the default value of
+    # {@link #source} for tokens that do not have a source.
+    EMPTY_SOURCE = (None, None)
+
+    def __init__(self, source:tuple = EMPTY_SOURCE, type:int = None, channel:int=Token.DEFAULT_CHANNEL, start:int=-1, stop:int=-1):
+        super().__init__()
+        self.source = source
+        self.type = type
+        self.channel = channel
+        self.start = start
+        self.stop = stop
+        self.tokenIndex = -1
+        if source[0] is not None:
+            self.line = source[0].line
+            self.column = source[0].column
+        else:
+            self.column = -1
+
+    # Constructs a new {@link CommonToken} as a copy of another {@link Token}.
+    #
+    # <p>
+    # If {@code oldToken} is also a {@link CommonToken} instance, the newly
+    # constructed token will share a reference to the {@link #text} field and
+    # the {@link Pair} stored in {@link #source}. Otherwise, {@link #text} will
+    # be assigned the result of calling {@link #getText}, and {@link #source}
+    # will be constructed from the result of {@link Token#getTokenSource} and
+    # {@link Token#getInputStream}.</p>
+    #
+    # @param oldToken The token to copy.
+     #
+    def clone(self):
+        t = CommonToken(self.source, self.type, self.channel, self.start, self.stop)
+        t.tokenIndex = self.tokenIndex
+        t.line = self.line
+        t.column = self.column
+        t.text = self.text
+        return t
+
+    @property
+    def text(self):
+        if self._text is not None:
+            return self._text
+        input = self.getInputStream()
+        if input is None:
+            return None
+        n = input.size
+        if self.start < n and self.stop < n:
+            return input.getText(self.start, self.stop)
+        else:
+            return "<EOF>"
+
+    @text.setter
+    def text(self, text:str):
+        self._text = text
+
+    def __str__(self):
+        with StringIO() as buf:
+            buf.write("[@")
+            buf.write(str(self.tokenIndex))
+            buf.write(",")
+            buf.write(str(self.start))
+            buf.write(":")
+            buf.write(str(self.stop))
+            buf.write("='")
+            txt = self.text
+            if txt is not None:
+                txt = txt.replace("\n","\\n")
+                txt = txt.replace("\r","\\r")
+                txt = txt.replace("\t","\\t")
+            else:
+                txt = "<no text>"
+            buf.write(txt)
+            buf.write("',<")
+            buf.write(str(self.type))
+            buf.write(">")
+            if self.channel > 0:
+                buf.write(",channel=")
+                buf.write(str(self.channel))
+            buf.write(",")
+            buf.write(str(self.line))
+            buf.write(":")
+            buf.write(str(self.column))
+            buf.write("]")
+            return buf.getvalue()

lib/python3.12/site-packages/antlr4/TokenStreamRewriter.py

@@ -0,0 +1,255 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+from io import StringIO
+from antlr4.Token import Token
+
+from antlr4.CommonTokenStream import CommonTokenStream
+
+
+class TokenStreamRewriter(object):
+    __slots__ = ('tokens', 'programs', 'lastRewriteTokenIndexes')
+
+    DEFAULT_PROGRAM_NAME = "default"
+    PROGRAM_INIT_SIZE = 100
+    MIN_TOKEN_INDEX = 0
+
+    def __init__(self, tokens):
+        """
+        :type  tokens: antlr4.BufferedTokenStream.BufferedTokenStream
+        :param tokens:
+        :return:
+        """
+        super(TokenStreamRewriter, self).__init__()
+        self.tokens = tokens
+        self.programs = {self.DEFAULT_PROGRAM_NAME: []}
+        self.lastRewriteTokenIndexes = {}
+
+    def getTokenStream(self):
+        return self.tokens
+
+    def rollback(self, instruction_index, program_name):
+        ins = self.programs.get(program_name, None)
+        if ins:
+            self.programs[program_name] = ins[self.MIN_TOKEN_INDEX: instruction_index]
+
+    def deleteProgram(self, program_name=DEFAULT_PROGRAM_NAME):
+        self.rollback(self.MIN_TOKEN_INDEX, program_name)
+
+    def insertAfterToken(self, token, text, program_name=DEFAULT_PROGRAM_NAME):
+        self.insertAfter(token.tokenIndex, text, program_name)
+
+    def insertAfter(self, index, text, program_name=DEFAULT_PROGRAM_NAME):
+        op = self.InsertAfterOp(self.tokens, index + 1, text)
+        rewrites = self.getProgram(program_name)
+        op.instructionIndex = len(rewrites)
+        rewrites.append(op)
+
+    def insertBeforeIndex(self, index, text):
+        self.insertBefore(self.DEFAULT_PROGRAM_NAME, index, text)
+
+    def insertBeforeToken(self, token, text, program_name=DEFAULT_PROGRAM_NAME):
+        self.insertBefore(program_name, token.tokenIndex, text)
+
+    def insertBefore(self, program_name, index, text):
+        op = self.InsertBeforeOp(self.tokens, index, text)
+        rewrites = self.getProgram(program_name)
+        op.instructionIndex = len(rewrites)
+        rewrites.append(op)
+
+    def replaceIndex(self, index, text):
+        self.replace(self.DEFAULT_PROGRAM_NAME, index, index, text)
+
+    def replaceRange(self, from_idx, to_idx, text):
+        self.replace(self.DEFAULT_PROGRAM_NAME, from_idx, to_idx, text)
+
+    def replaceSingleToken(self, token, text):
+        self.replace(self.DEFAULT_PROGRAM_NAME, token.tokenIndex, token.tokenIndex, text)
+
+    def replaceRangeTokens(self, from_token, to_token, text, program_name=DEFAULT_PROGRAM_NAME):
+        self.replace(program_name, from_token.tokenIndex, to_token.tokenIndex, text)
+
+    def replace(self, program_name, from_idx, to_idx, text):
+        if any((from_idx > to_idx, from_idx < 0, to_idx < 0, to_idx >= len(self.tokens.tokens))):
+            raise ValueError(
+                'replace: range invalid: {}..{}(size={})'.format(from_idx, to_idx, len(self.tokens.tokens)))
+        op = self.ReplaceOp(from_idx, to_idx, self.tokens, text)
+        rewrites = self.getProgram(program_name)
+        op.instructionIndex = len(rewrites)
+        rewrites.append(op)
+
+    def deleteToken(self, token):
+        self.delete(self.DEFAULT_PROGRAM_NAME, token, token)
+
+    def deleteIndex(self, index):
+        self.delete(self.DEFAULT_PROGRAM_NAME, index, index)
+
+    def delete(self, program_name, from_idx, to_idx):
+        if isinstance(from_idx, Token):
+            self.replace(program_name, from_idx.tokenIndex, to_idx.tokenIndex, "")
+        else:
+            self.replace(program_name, from_idx, to_idx, "")
+
+    def lastRewriteTokenIndex(self, program_name=DEFAULT_PROGRAM_NAME):
+        return self.lastRewriteTokenIndexes.get(program_name, -1)
+
+    def setLastRewriteTokenIndex(self, program_name, i):
+        self.lastRewriteTokenIndexes[program_name] = i
+
+    def getProgram(self, program_name):
+        return self.programs.setdefault(program_name, [])
+
+    def getDefaultText(self):
+        return self.getText(self.DEFAULT_PROGRAM_NAME, 0, len(self.tokens.tokens) - 1)
+
+    def getText(self, program_name, start:int, stop:int):
+        """
+        :return: the text in tokens[start, stop](closed interval)
+        """
+        rewrites = self.programs.get(program_name)
+
+        # ensure start/end are in range
+        if stop > len(self.tokens.tokens) - 1:
+            stop = len(self.tokens.tokens) - 1
+        if start < 0:
+            start = 0
+
+        # if no instructions to execute
+        if not rewrites: return self.tokens.getText(start, stop)
+        buf = StringIO()
+        indexToOp = self._reduceToSingleOperationPerIndex(rewrites)
+        i = start
+        while all((i <= stop, i < len(self.tokens.tokens))):
+            op = indexToOp.pop(i, None)
+            token = self.tokens.get(i)
+            if op is None:
+                if token.type != Token.EOF: buf.write(token.text)
+                i += 1
+            else:
+                i = op.execute(buf)
+
+        if stop == len(self.tokens.tokens)-1:
+            for op in indexToOp.values():
+                if op.index >= len(self.tokens.tokens)-1: buf.write(op.text)
+
+        return buf.getvalue()
+
+    def _reduceToSingleOperationPerIndex(self, rewrites):
+        # Walk replaces
+        for i, rop in enumerate(rewrites):
+            if any((rop is None, not isinstance(rop, TokenStreamRewriter.ReplaceOp))):
+                continue
+            # Wipe prior inserts within range
+            inserts = [op for op in rewrites[:i] if isinstance(op, TokenStreamRewriter.InsertBeforeOp)]
+            for iop in inserts:
+                if iop.index == rop.index:
+                    rewrites[iop.instructionIndex] = None
+                    rop.text = '{}{}'.format(iop.text, rop.text)
+                elif all((iop.index > rop.index, iop.index <= rop.last_index)):
+                    rewrites[iop.instructionIndex] = None
+
+            # Drop any prior replaces contained within
+            prevReplaces = [op for op in rewrites[:i] if isinstance(op, TokenStreamRewriter.ReplaceOp)]
+            for prevRop in prevReplaces:
+                if all((prevRop.index >= rop.index, prevRop.last_index <= rop.last_index)):
+                    rewrites[prevRop.instructionIndex] = None
+                    continue
+                isDisjoint = any((prevRop.last_index<rop.index, prevRop.index>rop.last_index))
+                if all((prevRop.text is None, rop.text is None, not isDisjoint)):
+                    rewrites[prevRop.instructionIndex] = None
+                    rop.index = min(prevRop.index, rop.index)
+                    rop.last_index = min(prevRop.last_index, rop.last_index)
+                    print('New rop {}'.format(rop))
+                elif (not(isDisjoint)):
+                    raise ValueError("replace op boundaries of {} overlap with previous {}".format(rop, prevRop))
+
+        # Walk inserts
+        for i, iop in enumerate(rewrites):
+            if any((iop is None, not isinstance(iop, TokenStreamRewriter.InsertBeforeOp))):
+                continue
+            prevInserts = [op for op in rewrites[:i] if isinstance(op, TokenStreamRewriter.InsertBeforeOp)]
+            for prev_index, prevIop in enumerate(prevInserts):
+                if prevIop.index == iop.index and type(prevIop) is TokenStreamRewriter.InsertBeforeOp:
+                    iop.text += prevIop.text
+                    rewrites[prev_index] = None
+                elif prevIop.index == iop.index and type(prevIop) is TokenStreamRewriter.InsertAfterOp:
+                    iop.text = prevIop.text + iop.text
+                    rewrites[prev_index] = None
+            # look for replaces where iop.index is in range; error
+            prevReplaces = [op for op in rewrites[:i] if isinstance(op, TokenStreamRewriter.ReplaceOp)]
+            for rop in prevReplaces:
+                if iop.index == rop.index:
+                    rop.text = iop.text + rop.text
+                    rewrites[i] = None
+                    continue
+                if all((iop.index >= rop.index, iop.index <= rop.last_index)):
+                    raise ValueError("insert op {} within boundaries of previous {}".format(iop, rop))
+
+        reduced = {}
+        for i, op in enumerate(rewrites):
+            if op is None: continue
+            if reduced.get(op.index): raise ValueError('should be only one op per index')
+            reduced[op.index] = op
+
+        return reduced
+
+    class RewriteOperation(object):
+        __slots__ = ('tokens', 'index', 'text', 'instructionIndex')
+
+        def __init__(self, tokens, index, text=""):
+            """
+            :type tokens: CommonTokenStream
+            :param tokens:
+            :param index:
+            :param text:
+            :return:
+            """
+            self.tokens = tokens
+            self.index = index
+            self.text = text
+            self.instructionIndex = 0
+
+        def execute(self, buf):
+            """
+            :type buf: StringIO.StringIO
+            :param buf:
+            :return:
+            """
+            return self.index
+
+        def __str__(self):
+            return '<{}@{}:"{}">'.format(self.__class__.__name__, self.tokens.get(self.index), self.text)
+
+    class InsertBeforeOp(RewriteOperation):
+
+        def __init__(self, tokens, index, text=""):
+            super(TokenStreamRewriter.InsertBeforeOp, self).__init__(tokens, index, text)
+
+        def execute(self, buf):
+            buf.write(self.text)
+            if self.tokens.get(self.index).type != Token.EOF:
+                buf.write(self.tokens.get(self.index).text)
+            return self.index + 1
+
+    class InsertAfterOp(InsertBeforeOp):
+        pass
+
+    class ReplaceOp(RewriteOperation):
+        __slots__ = 'last_index'
+
+        def __init__(self, from_idx, to_idx, tokens, text):
+            super(TokenStreamRewriter.ReplaceOp, self).__init__(tokens, from_idx, text)
+            self.last_index = to_idx
+
+        def execute(self, buf):
+            if self.text:
+                buf.write(self.text)
+            return self.last_index + 1
+
+        def __str__(self):
+            if self.text:
+                return '<ReplaceOp@{}..{}:"{}">'.format(self.tokens.get(self.index), self.tokens.get(self.last_index),
+                                                        self.text)

lib/python3.12/site-packages/antlr4/Utils.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#
+
+from io import StringIO
+
+def str_list(val):
+    with StringIO() as buf:
+        buf.write('[')
+        first = True
+        for item in val:
+            if not first:
+                buf.write(', ')
+            buf.write(str(item))
+            first = False
+        buf.write(']')
+        return buf.getvalue()
+
+def escapeWhitespace(s:str, escapeSpaces:bool):
+    with StringIO() as buf:
+        for c in s:
+            if c==' ' and escapeSpaces:
+                buf.write('\u00B7')
+            elif c=='\t':
+                buf.write("\\t")
+            elif c=='\n':
+                buf.write("\\n")
+            elif c=='\r':
+                buf.write("\\r")
+            else:
+                buf.write(c)
+        return buf.getvalue()

lib/python3.12/site-packages/antlr4/__init__.py

@@ -0,0 +1,21 @@
+from antlr4.Token import Token
+from antlr4.InputStream import InputStream
+from antlr4.FileStream import FileStream
+from antlr4.StdinStream import StdinStream
+from antlr4.BufferedTokenStream import TokenStream
+from antlr4.CommonTokenStream import CommonTokenStream
+from antlr4.Lexer import Lexer
+from antlr4.Parser import Parser
+from antlr4.dfa.DFA import DFA
+from antlr4.atn.ATN import ATN
+from antlr4.atn.ATNDeserializer import ATNDeserializer
+from antlr4.atn.LexerATNSimulator import LexerATNSimulator
+from antlr4.atn.ParserATNSimulator import ParserATNSimulator
+from antlr4.atn.PredictionMode import PredictionMode
+from antlr4.PredictionContext import PredictionContextCache
+from antlr4.ParserRuleContext import RuleContext, ParserRuleContext
+from antlr4.tree.Tree import ParseTreeListener, ParseTreeVisitor, ParseTreeWalker, TerminalNode, ErrorNode, RuleNode
+from antlr4.error.Errors import RecognitionException, IllegalStateException, NoViableAltException
+from antlr4.error.ErrorStrategy import BailErrorStrategy
+from antlr4.error.DiagnosticErrorListener import DiagnosticErrorListener
+from antlr4.Utils import str_list

lib/python3.12/site-packages/antlr4/atn/ATN.py

@@ -0,0 +1,132 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+from antlr4.IntervalSet import IntervalSet
+
+from antlr4.RuleContext import RuleContext
+
+from antlr4.Token import Token
+from antlr4.atn.ATNType import ATNType
+from antlr4.atn.ATNState import ATNState, DecisionState
+
+
+class ATN(object):
+    __slots__ = (
+        'grammarType', 'maxTokenType', 'states', 'decisionToState',
+        'ruleToStartState', 'ruleToStopState', 'modeNameToStartState',
+        'ruleToTokenType', 'lexerActions', 'modeToStartState'
+    )
+
+    INVALID_ALT_NUMBER = 0
+
+    # Used for runtime deserialization of ATNs from strings#/
+    def __init__(self, grammarType:ATNType , maxTokenType:int ):
+        # The type of the ATN.
+        self.grammarType = grammarType
+        # The maximum value for any symbol recognized by a transition in the ATN.
+        self.maxTokenType = maxTokenType
+        self.states = []
+        # Each subrule/rule is a decision point and we must track them so we
+        #  can go back later and build DFA predictors for them.  This includes
+        #  all the rules, subrules, optional blocks, ()+, ()* etc...
+        self.decisionToState = []
+        # Maps from rule index to starting state number.
+        self.ruleToStartState = []
+        # Maps from rule index to stop state number.
+        self.ruleToStopState = None
+        self.modeNameToStartState = dict()
+        # For lexer ATNs, this maps the rule index to the resulting token type.
+        # For parser ATNs, this maps the rule index to the generated bypass token
+        # type if the
+        # {@link ATNDeserializationOptions#isGenerateRuleBypassTransitions}
+        # deserialization option was specified; otherwise, this is {@code null}.
+        self.ruleToTokenType = None
+        # For lexer ATNs, this is an array of {@link LexerAction} objects which may
+        # be referenced by action transitions in the ATN.
+        self.lexerActions = None
+        self.modeToStartState = []
+
+    # Compute the set of valid tokens that can occur starting in state {@code s}.
+    #  If {@code ctx} is null, the set of tokens will not include what can follow
+    #  the rule surrounding {@code s}. In other words, the set will be
+    #  restricted to tokens reachable staying within {@code s}'s rule.
+    def nextTokensInContext(self, s:ATNState, ctx:RuleContext):
+        from antlr4.LL1Analyzer import LL1Analyzer
+        anal = LL1Analyzer(self)
+        return anal.LOOK(s, ctx=ctx)
+
+    # Compute the set of valid tokens that can occur starting in {@code s} and
+    # staying in same rule. {@link Token#EPSILON} is in set if we reach end of
+    # rule.
+    def nextTokensNoContext(self, s:ATNState):
+        if s.nextTokenWithinRule is not None:
+            return s.nextTokenWithinRule
+        s.nextTokenWithinRule = self.nextTokensInContext(s, None)
+        s.nextTokenWithinRule.readonly = True
+        return s.nextTokenWithinRule
+
+    def nextTokens(self, s:ATNState, ctx:RuleContext = None):
+        if ctx==None:
+            return self.nextTokensNoContext(s)
+        else:
+            return self.nextTokensInContext(s, ctx)
+
+    def addState(self, state:ATNState):
+        if state is not None:
+            state.atn = self
+            state.stateNumber = len(self.states)
+        self.states.append(state)
+
+    def removeState(self, state:ATNState):
+        self.states[state.stateNumber] = None # just free mem, don't shift states in list
+
+    def defineDecisionState(self, s:DecisionState):
+        self.decisionToState.append(s)
+        s.decision = len(self.decisionToState)-1
+        return s.decision
+
+    def getDecisionState(self, decision:int):
+        if len(self.decisionToState)==0:
+            return None
+        else:
+            return self.decisionToState[decision]
+
+    # Computes the set of input symbols which could follow ATN state number
+    # {@code stateNumber} in the specified full {@code context}. This method
+    # considers the complete parser context, but does not evaluate semantic
+    # predicates (i.e. all predicates encountered during the calculation are
+    # assumed true). If a path in the ATN exists from the starting state to the
+    # {@link RuleStopState} of the outermost context without matching any
+    # symbols, {@link Token#EOF} is added to the returned set.
+    #
+    # <p>If {@code context} is {@code null}, it is treated as
+    # {@link ParserRuleContext#EMPTY}.</p>
+    #
+    # @param stateNumber the ATN state number
+    # @param context the full parse context
+    # @return The set of potentially valid input symbols which could follow the
+    # specified state in the specified context.
+    # @throws IllegalArgumentException if the ATN does not contain a state with
+    # number {@code stateNumber}
+    #/
+    def getExpectedTokens(self, stateNumber:int, ctx:RuleContext ):
+        if stateNumber < 0 or stateNumber >= len(self.states):
+            raise Exception("Invalid state number.")
+        s = self.states[stateNumber]
+        following = self.nextTokens(s)
+        if Token.EPSILON not in following:
+            return following
+        expected = IntervalSet()
+        expected.addSet(following)
+        expected.removeOne(Token.EPSILON)
+        while (ctx != None and ctx.invokingState >= 0 and Token.EPSILON in following):
+            invokingState = self.states[ctx.invokingState]
+            rt = invokingState.transitions[0]
+            following = self.nextTokens(rt.followState)
+            expected.addSet(following)
+            expected.removeOne(Token.EPSILON)
+            ctx = ctx.parentCtx
+        if Token.EPSILON in following:
+            expected.addOne(Token.EOF)
+        return expected

lib/python3.12/site-packages/antlr4/atn/ATNConfig.py

@@ -0,0 +1,159 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+
+# A tuple: (ATN state, predicted alt, syntactic, semantic context).
+#  The syntactic context is a graph-structured stack node whose
+#  path(s) to the root is the rule invocation(s)
+#  chain used to arrive at the state.  The semantic context is
+#  the tree of semantic predicates encountered before reaching
+#  an ATN state.
+#/
+from io import StringIO
+from antlr4.PredictionContext import PredictionContext
+from antlr4.atn.ATNState import ATNState, DecisionState
+from antlr4.atn.LexerActionExecutor import LexerActionExecutor
+from antlr4.atn.SemanticContext import SemanticContext
+
+# need a forward declaration
+ATNConfig = None
+
+class ATNConfig(object):
+    __slots__ = (
+        'state', 'alt', 'context', 'semanticContext', 'reachesIntoOuterContext',
+        'precedenceFilterSuppressed'
+    )
+
+    def __init__(self, state:ATNState=None, alt:int=None, context:PredictionContext=None, semantic:SemanticContext=None, config:ATNConfig=None):
+        if config is not None:
+            if state is None:
+                state = config.state
+            if alt is None:
+                alt = config.alt
+            if context is None:
+                context = config.context
+            if semantic is None:
+                semantic = config.semanticContext
+        if semantic is None:
+            semantic = SemanticContext.NONE
+        # The ATN state associated with this configuration#/
+        self.state = state
+        # What alt (or lexer rule) is predicted by this configuration#/
+        self.alt = alt
+        # The stack of invoking states leading to the rule/states associated
+        #  with this config.  We track only those contexts pushed during
+        #  execution of the ATN simulator.
+        self.context = context
+        self.semanticContext = semantic
+        # We cannot execute predicates dependent upon local context unless
+        # we know for sure we are in the correct context. Because there is
+        # no way to do this efficiently, we simply cannot evaluate
+        # dependent predicates unless we are in the rule that initially
+        # invokes the ATN simulator.
+        #
+        # closure() tracks the depth of how far we dip into the
+        # outer context: depth > 0.  Note that it may not be totally
+        # accurate depth since I don't ever decrement. TODO: make it a boolean then
+        self.reachesIntoOuterContext = 0 if config is None else config.reachesIntoOuterContext
+        self.precedenceFilterSuppressed = False if config is None else config.precedenceFilterSuppressed
+
+    # An ATN configuration is equal to another if both have
+    #  the same state, they predict the same alternative, and
+    #  syntactic/semantic contexts are the same.
+    #/
+    def __eq__(self, other):
+        if self is other:
+            return True
+        elif not isinstance(other, ATNConfig):
+            return False
+        else:
+            return self.state.stateNumber==other.state.stateNumber \
+                and self.alt==other.alt \
+                and ((self.context is other.context) or (self.context==other.context)) \
+                and self.semanticContext==other.semanticContext \
+                and self.precedenceFilterSuppressed==other.precedenceFilterSuppressed
+
+    def __hash__(self):
+        return hash((self.state.stateNumber, self.alt, self.context, self.semanticContext))
+
+    def hashCodeForConfigSet(self):
+        return hash((self.state.stateNumber, self.alt, hash(self.semanticContext)))
+
+    def equalsForConfigSet(self, other):
+        if self is other:
+            return True
+        elif not isinstance(other, ATNConfig):
+            return False
+        else:
+            return self.state.stateNumber==other.state.stateNumber \
+                and self.alt==other.alt \
+                and self.semanticContext==other.semanticContext
+
+    def __str__(self):
+        with StringIO() as buf:
+            buf.write('(')
+            buf.write(str(self.state))
+            buf.write(",")
+            buf.write(str(self.alt))
+            if self.context is not None:
+                buf.write(",[")
+                buf.write(str(self.context))
+                buf.write("]")
+            if self.semanticContext is not None and self.semanticContext is not SemanticContext.NONE:
+                buf.write(",")
+                buf.write(str(self.semanticContext))
+            if self.reachesIntoOuterContext>0:
+                buf.write(",up=")
+                buf.write(str(self.reachesIntoOuterContext))
+            buf.write(')')
+            return buf.getvalue()
+
+# need a forward declaration
+LexerATNConfig = None
+
+class LexerATNConfig(ATNConfig):
+    __slots__ = ('lexerActionExecutor', 'passedThroughNonGreedyDecision')
+
+    def __init__(self, state:ATNState, alt:int=None, context:PredictionContext=None, semantic:SemanticContext=SemanticContext.NONE,
+                 lexerActionExecutor:LexerActionExecutor=None, config:LexerATNConfig=None):
+        super().__init__(state=state, alt=alt, context=context, semantic=semantic, config=config)
+        if config is not None:
+            if lexerActionExecutor is None:
+                lexerActionExecutor = config.lexerActionExecutor
+        # This is the backing field for {@link #getLexerActionExecutor}.
+        self.lexerActionExecutor = lexerActionExecutor
+        self.passedThroughNonGreedyDecision = False if config is None else self.checkNonGreedyDecision(config, state)
+
+    def __hash__(self):
+        return hash((self.state.stateNumber, self.alt, self.context,
+                self.semanticContext, self.passedThroughNonGreedyDecision,
+                self.lexerActionExecutor))
+
+    def __eq__(self, other):
+        if self is other:
+            return True
+        elif not isinstance(other, LexerATNConfig):
+            return False
+        if self.passedThroughNonGreedyDecision != other.passedThroughNonGreedyDecision:
+            return False
+        if not(self.lexerActionExecutor == other.lexerActionExecutor):
+            return False
+        return super().__eq__(other)
+
+
+
+    def hashCodeForConfigSet(self):
+        return hash(self)
+
+
+
+    def equalsForConfigSet(self, other):
+        return self==other
+
+
+
+    def checkNonGreedyDecision(self, source:LexerATNConfig, target:ATNState):
+        return source.passedThroughNonGreedyDecision \
+            or isinstance(target, DecisionState) and target.nonGreedy

lib/python3.12/site-packages/antlr4/atn/ATNConfigSet.py

@@ -0,0 +1,212 @@
+#
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+
+#
+# Specialized {@link Set}{@code <}{@link ATNConfig}{@code >} that can track
+# info about the set, with support for combining similar configurations using a
+# graph-structured stack.
+#/
+from io import StringIO
+from functools import reduce
+from antlr4.PredictionContext import PredictionContext, merge
+from antlr4.Utils import str_list
+from antlr4.atn.ATN import ATN
+from antlr4.atn.ATNConfig import ATNConfig
+from antlr4.atn.SemanticContext import SemanticContext
+from antlr4.error.Errors import UnsupportedOperationException, IllegalStateException
+
+ATNSimulator = None
+
+class ATNConfigSet(object):
+    __slots__ = (
+        'configLookup', 'fullCtx', 'readonly', 'configs', 'uniqueAlt',
+        'conflictingAlts', 'hasSemanticContext', 'dipsIntoOuterContext',
+        'cachedHashCode'
+    )
+
+    #
+    # The reason that we need this is because we don't want the hash map to use
+    # the standard hash code and equals. We need all configurations with the same
+    # {@code (s,i,_,semctx)} to be equal. Unfortunately, this key effectively doubles
+    # the number of objects associated with ATNConfigs. The other solution is to
+    # use a hash table that lets us specify the equals/hashcode operation.
+
+    def __init__(self, fullCtx:bool=True):
+        # All configs but hashed by (s, i, _, pi) not including context. Wiped out
+        # when we go readonly as this set becomes a DFA state.
+        self.configLookup = dict()
+        # Indicates that this configuration set is part of a full context
+        #  LL prediction. It will be used to determine how to merge $. With SLL
+        #  it's a wildcard whereas it is not for LL context merge.
+        self.fullCtx = fullCtx
+        # Indicates that the set of configurations is read-only. Do not
+        #  allow any code to manipulate the set; DFA states will point at
+        #  the sets and they must not change. This does not protect the other
+        #  fields; in particular, conflictingAlts is set after
+        #  we've made this readonly.
+        self.readonly = False
+        # Track the elements as they are added to the set; supports get(i)#/
+        self.configs = []
+
+        # TODO: these fields make me pretty uncomfortable but nice to pack up info together, saves recomputation
+        # TODO: can we track conflicts as they are added to save scanning configs later?
+        self.uniqueAlt = 0
+        self.conflictingAlts = None
+
+        # Used in parser and lexer. In lexer, it indicates we hit a pred
+        # while computing a closure operation.  Don't make a DFA state from this.
+        self.hasSemanticContext = False
+        self.dipsIntoOuterContext = False
+
+        self.cachedHashCode = -1
+
+    def __iter__(self):
+        return self.configs.__iter__()
+
+    # Adding a new config means merging contexts with existing configs for
+    # {@code (s, i, pi, _)}, where {@code s} is the
+    # {@link ATNConfig#state}, {@code i} is the {@link ATNConfig#alt}, and
+    # {@code pi} is the {@link ATNConfig#semanticContext}. We use
+    # {@code (s,i,pi)} as key.
+    #
+    # <p>This method updates {@link #dipsIntoOuterContext} and
+    # {@link #hasSemanticContext} when necessary.</p>
+    #/
+    def add(self, config:ATNConfig, mergeCache=None):
+        if self.readonly:
+            raise Exception("This set is readonly")
+        if config.semanticContext is not SemanticContext.NONE:
+            self.hasSemanticContext = True
+        if config.reachesIntoOuterContext > 0:
+            self.dipsIntoOuterContext = True
+        existing = self.getOrAdd(config)
+        if existing is config:
+            self.cachedHashCode = -1
+            self.configs.append(config)  # track order here
+            return True
+        # a previous (s,i,pi,_), merge with it and save result
+        rootIsWildcard = not self.fullCtx
+        merged = merge(existing.context, config.context, rootIsWildcard, mergeCache)
+        # no need to check for existing.context, config.context in cache
+        # since only way to create new graphs is "call rule" and here.
+        # We cache at both places.
+        existing.reachesIntoOuterContext = max(existing.reachesIntoOuterContext, config.reachesIntoOuterContext)
+        # make sure to preserve the precedence filter suppression during the merge
+        if config.precedenceFilterSuppressed:
+            existing.precedenceFilterSuppressed = True
+        existing.context = merged # replace context; no need to alt mapping
+        return True
+
+    def getOrAdd(self, config:ATNConfig):
+        h = config.hashCodeForConfigSet()
+        l = self.configLookup.get(h, None)
+        if l is not None:
+            r = next((cfg for cfg in l if config.equalsForConfigSet(cfg)), None)
+            if r is not None:
+                return r
+        if l is None:
+            l = [config]
+            self.configLookup[h] = l
+        else:
+            l.append(config)
+        return config
+
+    def getStates(self):
+        return set(c.state for c in self.configs)
+
+    def getPredicates(self):
+        return list(cfg.semanticContext for cfg in self.configs if cfg.semanticContext!=SemanticContext.NONE)
+
+    def get(self, i:int):
+        return self.configs[i]
+
+    def optimizeConfigs(self, interpreter:ATNSimulator):
+        if self.readonly:
+            raise IllegalStateException("This set is readonly")
+        if len(self.configs)==0:
+            return
+        for config in self.configs:
+            config.context = interpreter.getCachedContext(config.context)
+
+    def addAll(self, coll:list):
+        for c in coll:
+            self.add(c)
+        return False
+
+    def __eq__(self, other):
+        if self is other:
+            return True
+        elif not isinstance(other, ATNConfigSet):
+            return False
+
+        same = self.configs is not None and \
+            self.configs==other.configs and \
+            self.fullCtx == other.fullCtx and \
+            self.uniqueAlt == other.uniqueAlt and \
+            self.conflictingAlts == other.conflictingAlts and \
+            self.hasSemanticContext == other.hasSemanticContext and \
+            self.dipsIntoOuterContext == other.dipsIntoOuterContext
+
+        return same
+
+    def __hash__(self):
+        if self.readonly:
+            if self.cachedHashCode == -1:
+                self.cachedHashCode = self.hashConfigs()
+            return self.cachedHashCode
+        return self.hashConfigs()
+
+    def hashConfigs(self):
+        return reduce(lambda h, cfg: hash((h, cfg)), self.configs, 0)
+
+    def __len__(self):
+        return len(self.configs)
+
+    def isEmpty(self):
+        return len(self.configs)==0
+
+    def __contains__(self, config):
+        if self.configLookup is None:
+            raise UnsupportedOperationException("This method is not implemented for readonly sets.")
+        h = config.hashCodeForConfigSet()
+        l = self.configLookup.get(h, None)
+        if l is not None:
+            for c in l:
+                if config.equalsForConfigSet(c):
+                    return True
+        return False
+
+    def clear(self):
+        if self.readonly:
+            raise IllegalStateException("This set is readonly")
+        self.configs.clear()
+        self.cachedHashCode = -1
+        self.configLookup.clear()
+
+    def setReadonly(self, readonly:bool):
+        self.readonly = readonly
+        self.configLookup = None # can't mod, no need for lookup cache
+
+    def __str__(self):
+        with StringIO() as buf:
+            buf.write(str_list(self.configs))
+            if self.hasSemanticContext:
+                buf.write(",hasSemanticContext=")
+                buf.write(str(self.hasSemanticContext))
+            if self.uniqueAlt!=ATN.INVALID_ALT_NUMBER:
+                buf.write(",uniqueAlt=")
+                buf.write(str(self.uniqueAlt))
+            if self.conflictingAlts is not None:
+                buf.write(",conflictingAlts=")
+                buf.write(str(self.conflictingAlts))
+            if self.dipsIntoOuterContext:
+                buf.write(",dipsIntoOuterContext")
+            return buf.getvalue()
+
+
+class OrderedATNConfigSet(ATNConfigSet):
+
+    def __init__(self):
+        super().__init__()

lib/python3.12/site-packages/antlr4/atn/ATNDeserializationOptions.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+
+# need a forward declaration
+ATNDeserializationOptions = None
+
+class ATNDeserializationOptions(object):
+    __slots__ = ('readonly', 'verifyATN', 'generateRuleBypassTransitions')
+
+    defaultOptions = None
+
+    def __init__(self, copyFrom:ATNDeserializationOptions = None):
+        self.readonly = False
+        self.verifyATN = True if copyFrom is None else copyFrom.verifyATN
+        self.generateRuleBypassTransitions = False if copyFrom is None else copyFrom.generateRuleBypassTransitions
+
+    def __setattr__(self, key, value):
+        if key!="readonly" and self.readonly:
+            raise Exception("The object is read only.")
+        super(type(self), self).__setattr__(key,value)
+
+ATNDeserializationOptions.defaultOptions = ATNDeserializationOptions()
+ATNDeserializationOptions.defaultOptions.readonly = True

lib/python3.12/site-packages/antlr4/atn/ATNDeserializer.py

@@ -0,0 +1,529 @@
+# Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
+# Use of this file is governed by the BSD 3-clause license that
+# can be found in the LICENSE.txt file in the project root.
+#/
+from uuid import UUID
+from io import StringIO
+from typing import Callable
+from antlr4.Token import Token
+from antlr4.atn.ATN import ATN
+from antlr4.atn.ATNType import ATNType
+from antlr4.atn.ATNState import *
+from antlr4.atn.Transition import *
+from antlr4.atn.LexerAction import *
+from antlr4.atn.ATNDeserializationOptions import ATNDeserializationOptions
+
+# This is the earliest supported serialized UUID.
+BASE_SERIALIZED_UUID = UUID("AADB8D7E-AEEF-4415-AD2B-8204D6CF042E")
+
+# This UUID indicates the serialized ATN contains two sets of
+# IntervalSets, where the second set's values are encoded as
+# 32-bit integers to support the full Unicode SMP range up to U+10FFFF.
+ADDED_UNICODE_SMP = UUID("59627784-3BE5-417A-B9EB-8131A7286089")
+
+# This list contains all of the currently supported UUIDs, ordered by when
+# the feature first appeared in this branch.
+SUPPORTED_UUIDS = [ BASE_SERIALIZED_UUID, ADDED_UNICODE_SMP ]
+
+SERIALIZED_VERSION = 3
+
+# This is the current serialized UUID.
+SERIALIZED_UUID = ADDED_UNICODE_SMP
+
+class ATNDeserializer (object):
+    __slots__ = ('deserializationOptions', 'data', 'pos', 'uuid')
+
+    def __init__(self, options : ATNDeserializationOptions = None):
+        if options is None:
+            options = ATNDeserializationOptions.defaultOptions
+        self.deserializationOptions = options
+
+    # Determines if a particular serialized representation of an ATN supports
+    # a particular feature, identified by the {@link UUID} used for serializing
+    # the ATN at the time the feature was first introduced.
+    #
+    # @param feature The {@link UUID} marking the first time the feature was
+    # supported in the serialized ATN.
+    # @param actualUuid The {@link UUID} of the actual serialized ATN which is
+    # currently being deserialized.
+    # @return {@code true} if the {@code actualUuid} value represents a
+    # serialized ATN at or after the feature identified by {@code feature} was
+    # introduced; otherwise, {@code false}.
+
+    def isFeatureSupported(self, feature : UUID , actualUuid : UUID ):
+        idx1 = SUPPORTED_UUIDS.index(feature)
+        if idx1<0:
+            return False
+        idx2 = SUPPORTED_UUIDS.index(actualUuid)
+        return idx2 >= idx1
+
+    def deserialize(self, data : str):
+        self.reset(data)
+        self.checkVersion()
+        self.checkUUID()
+        atn = self.readATN()
+        self.readStates(atn)
+        self.readRules(atn)
+        self.readModes(atn)
+        sets = []
+        # First, read all sets with 16-bit Unicode code points <= U+FFFF.
+        self.readSets(atn, sets, self.readInt)
+        # Next, if the ATN was serialized with the Unicode SMP feature,
+        # deserialize sets with 32-bit arguments <= U+10FFFF.
+        if self.isFeatureSupported(ADDED_UNICODE_SMP, self.uuid):
+            self.readSets(atn, sets, self.readInt32)
+        self.readEdges(atn, sets)
+        self.readDecisions(atn)
+        self.readLexerActions(atn)
+        self.markPrecedenceDecisions(atn)
+        self.verifyATN(atn)
+        if self.deserializationOptions.generateRuleBypassTransitions \
+                and atn.grammarType == ATNType.PARSER:
+            self.generateRuleBypassTransitions(atn)
+            # re-verify after modification
+            self.verifyATN(atn)
+        return atn
+
+    def reset(self, data:str):
+        def adjust(c):
+            v = ord(c)
+            return v-2 if v>1 else v + 65533
+        temp = [ adjust(c) for c in data ]
+        # don't adjust the first value since that's the version number
+        temp[0] = ord(data[0])
+        self.data = temp
+        self.pos = 0
+
+    def checkVersion(self):
+        version = self.readInt()
+        if version != SERIALIZED_VERSION:
+            raise Exception("Could not deserialize ATN with version " + str(version) + " (expected " + str(SERIALIZED_VERSION) + ").")
+
+    def checkUUID(self):
+        uuid = self.readUUID()
+        if not uuid in SUPPORTED_UUIDS:
+            raise Exception("Could not deserialize ATN with UUID: " + str(uuid) + \
+                            " (expected " + str(SERIALIZED_UUID) + " or a legacy UUID).", uuid, SERIALIZED_UUID)
+        self.uuid = uuid
+
+    def readATN(self):
+        idx = self.readInt()
+        grammarType = ATNType.fromOrdinal(idx)
+        maxTokenType = self.readInt()
+        return ATN(grammarType, maxTokenType)
+
+    def readStates(self, atn:ATN):
+        loopBackStateNumbers = []
+        endStateNumbers = []
+        nstates = self.readInt()
+        for i in range(0, nstates):
+            stype = self.readInt()
+            # ignore bad type of states
+            if stype==ATNState.INVALID_TYPE:
+                atn.addState(None)
+                continue
+            ruleIndex = self.readInt()
+            if ruleIndex == 0xFFFF:
+                ruleIndex = -1
+
+            s = self.stateFactory(stype, ruleIndex)
+            if stype == ATNState.LOOP_END: # special case
+                loopBackStateNumber = self.readInt()
+                loopBackStateNumbers.append((s, loopBackStateNumber))
+            elif isinstance(s, BlockStartState):
+                endStateNumber = self.readInt()
+                endStateNumbers.append((s, endStateNumber))
+
+            atn.addState(s)
+
+        # delay the assignment of loop back and end states until we know all the state instances have been initialized
+        for pair in loopBackStateNumbers:
+            pair[0].loopBackState = atn.states[pair[1]]
+
+        for pair in endStateNumbers:
+            pair[0].endState = atn.states[pair[1]]
+
+        numNonGreedyStates = self.readInt()
+        for i in range(0, numNonGreedyStates):
+            stateNumber = self.readInt()
+            atn.states[stateNumber].nonGreedy = True
+
+        numPrecedenceStates = self.readInt()
+        for i in range(0, numPrecedenceStates):
+            stateNumber = self.readInt()
+            atn.states[stateNumber].isPrecedenceRule = True
+
+    def readRules(self, atn:ATN):
+        nrules = self.readInt()
+        if atn.grammarType == ATNType.LEXER:
+            atn.ruleToTokenType = [0] * nrules
+
+        atn.ruleToStartState = [0] * nrules
+        for i in range(0, nrules):
+            s = self.readInt()
+            startState = atn.states[s]
+            atn.ruleToStartState[i] = startState
+            if atn.grammarType == ATNType.LEXER:
+                tokenType = self.readInt()
+                if tokenType == 0xFFFF:
+                    tokenType = Token.EOF
+
+                atn.ruleToTokenType[i] = tokenType
+
+        atn.ruleToStopState = [0] * nrules
+        for state in atn.states:
+            if not isinstance(state, RuleStopState):
+                continue
+            atn.ruleToStopState[state.ruleIndex] = state
+            atn.ruleToStartState[state.ruleIndex].stopState = state
+
+    def readModes(self, atn:ATN):
+        nmodes = self.readInt()
+        for i in range(0, nmodes):
+            s = self.readInt()
+            atn.modeToStartState.append(atn.states[s])
+
+    def readSets(self, atn:ATN, sets:list, readUnicode:Callable[[], int]):
+        m = self.readInt()
+        for i in range(0, m):
+            iset = IntervalSet()
+            sets.append(iset)
+            n = self.readInt()
+            containsEof = self.readInt()
+            if containsEof!=0:
+                iset.addOne(-1)
+            for j in range(0, n):
+                i1 = readUnicode()
+                i2 = readUnicode()
+                iset.addRange(range(i1, i2 + 1)) # range upper limit is exclusive
+
+    def readEdges(self, atn:ATN, sets:list):
+        nedges = self.readInt()
+        for i in range(0, nedges):
+            src = self.readInt()
+            trg = self.readInt()
+            ttype = self.readInt()
+            arg1 = self.readInt()
+            arg2 = self.readInt()
+            arg3 = self.readInt()
+            trans = self.edgeFactory(atn, ttype, src, trg, arg1, arg2, arg3, sets)
+            srcState = atn.states[src]
+            srcState.addTransition(trans)
+
+        # edges for rule stop states can be derived, so they aren't serialized
+        for state in atn.states:
+            for i in range(0, len(state.transitions)):
+                t = state.transitions[i]
+                if not isinstance(t, RuleTransition):
+                    continue
+                outermostPrecedenceReturn = -1
+                if atn.ruleToStartState[t.target.ruleIndex].isPrecedenceRule:
+                    if t.precedence == 0:
+                        outermostPrecedenceReturn = t.target.ruleIndex
+                trans = EpsilonTransition(t.followState, outermostPrecedenceReturn)
+                atn.ruleToStopState[t.target.ruleIndex].addTransition(trans)
+
+        for state in atn.states:
+            if isinstance(state, BlockStartState):
+                # we need to know the end state to set its start state
+                if state.endState is None:
+                    raise Exception("IllegalState")
+                # block end states can only be associated to a single block start state
+                if state.endState.startState is not None:
+                    raise Exception("IllegalState")
+                state.endState.startState = state
+
+            if isinstance(state, PlusLoopbackState):
+                for i in range(0, len(state.transitions)):
+                    target = state.transitions[i].target
+                    if isinstance(target, PlusBlockStartState):
+                        target.loopBackState = state
+            elif isinstance(state, StarLoopbackState):
+                for i in range(0, len(state.transitions)):
+                    target = state.transitions[i].target
+                    if isinstance(target, StarLoopEntryState):
+                        target.loopBackState = state
+
+    def readDecisions(self, atn:ATN):
+        ndecisions = self.readInt()
+        for i in range(0, ndecisions):
+            s = self.readInt()
+            decState = atn.states[s]
+            atn.decisionToState.append(decState)
+            decState.decision = i
+
+    def readLexerActions(self, atn:ATN):
+        if atn.grammarType == ATNType.LEXER:
+            count = self.readInt()
+            atn.lexerActions = [ None ] * count
+            for i in range(0, count):
+                actionType = self.readInt()
+                data1 = self.readInt()
+                if data1 == 0xFFFF:
+                    data1 = -1
+                data2 = self.readInt()
+                if data2 == 0xFFFF:
+                    data2 = -1
+                lexerAction = self.lexerActionFactory(actionType, data1, data2)
+                atn.lexerActions[i] = lexerAction
+
+    def generateRuleBypassTransitions(self, atn:ATN):
+
+        count = len(atn.ruleToStartState)
+        atn.ruleToTokenType = [ 0 ] * count
+        for i in range(0, count):
+            atn.ruleToTokenType[i] = atn.maxTokenType + i + 1
+
+        for i in range(0, count):
+            self.generateRuleBypassTransition(atn, i)
+
+    def generateRuleBypassTransition(self, atn:ATN, idx:int):
+
+        bypassStart = BasicBlockStartState()
+        bypassStart.ruleIndex = idx
+        atn.addState(bypassStart)
+
+        bypassStop = BlockEndState()
+        bypassStop.ruleIndex = idx
+        atn.addState(bypassStop)
+
+        bypassStart.endState = bypassStop
+        atn.defineDecisionState(bypassStart)
+
+        bypassStop.startState = bypassStart
+
+        excludeTransition = None
+
+        if atn.ruleToStartState[idx].isPrecedenceRule:
+            # wrap from the beginning of the rule to the StarLoopEntryState
+            endState = None
+            for state in atn.states:
+                if self.stateIsEndStateFor(state, idx):
+                    endState = state
+                    excludeTransition = state.loopBackState.transitions[0]
+                    break
+
+            if excludeTransition is None:
+                raise Exception("Couldn't identify final state of the precedence rule prefix section.")
+
+        else:
+
+            endState = atn.ruleToStopState[idx]
+
+        # all non-excluded transitions that currently target end state need to target blockEnd instead
+        for state in atn.states:
+            for transition in state.transitions:
+                if transition == excludeTransition:
+                    continue
+                if transition.target == endState:
+                    transition.target = bypassStop
+
+        # all transitions leaving the rule start state need to leave blockStart instead
+        ruleToStartState = atn.ruleToStartState[idx]
+        count = len(ruleToStartState.transitions)
+        while count > 0:
+            bypassStart.addTransition(ruleToStartState.transitions[count-1])
+            del ruleToStartState.transitions[-1]
+
+        # link the new states
+        atn.ruleToStartState[idx].addTransition(EpsilonTransition(bypassStart))
+        bypassStop.addTransition(EpsilonTransition(endState))
+
+        matchState = BasicState()
+        atn.addState(matchState)
+        matchState.addTransition(AtomTransition(bypassStop, atn.ruleToTokenType[idx]))
+        bypassStart.addTransition(EpsilonTransition(matchState))
+
+
+    def stateIsEndStateFor(self, state:ATNState, idx:int):
+        if state.ruleIndex != idx:
+            return None
+        if not isinstance(state, StarLoopEntryState):
+            return None
+
+        maybeLoopEndState = state.transitions[len(state.transitions) - 1].target
+        if not isinstance(maybeLoopEndState, LoopEndState):
+            return None
+
+        if maybeLoopEndState.epsilonOnlyTransitions and \
+                isinstance(maybeLoopEndState.transitions[0].target, RuleStopState):
+            return state
+        else:
+            return None
+
+
+    #
+    # Analyze the {@link StarLoopEntryState} states in the specified ATN to set
+    # the {@link StarLoopEntryState#isPrecedenceDecision} field to the
+    # correct value.
+    #
+    # @param atn The ATN.
+    #
+    def markPrecedenceDecisions(self, atn:ATN):
+        for state in atn.states:
+            if not isinstance(state, StarLoopEntryState):
+                continue
+
+            # We analyze the ATN to determine if this ATN decision state is the
+            # decision for the closure block that determines whether a
+            # precedence rule should continue or complete.
+            #
+            if atn.ruleToStartState[state.ruleIndex].isPrecedenceRule:
+                maybeLoopEndState = state.transitions[len(state.transitions) - 1].target
+                if isinstance(maybeLoopEndState, LoopEndState):
+                    if maybeLoopEndState.epsilonOnlyTransitions and \
+                            isinstance(maybeLoopEndState.transitions[0].target, RuleStopState):
+                        state.isPrecedenceDecision = True
+
+    def verifyATN(self, atn:ATN):
+        if not self.deserializationOptions.verifyATN:
+            return
+        # verify assumptions
+        for state in atn.states:
+            if state is None:
+                continue
+
+            self.checkCondition(state.epsilonOnlyTransitions or len(state.transitions) <= 1)
+
+            if isinstance(state, PlusBlockStartState):
+                self.checkCondition(state.loopBackState is not None)
+
+            if isinstance(state, StarLoopEntryState):
+                self.checkCondition(state.loopBackState is not None)
+                self.checkCondition(len(state.transitions) == 2)
+
+                if isinstance(state.transitions[0].target, StarBlockStartState):
+                    self.checkCondition(isinstance(state.transitions[1].target, LoopEndState))
+                    self.checkCondition(not state.nonGreedy)
+                elif isinstance(state.transitions[0].target, LoopEndState):
+                    self.checkCondition(isinstance(state.transitions[1].target, StarBlockStartState))
+                    self.checkCondition(state.nonGreedy)
+                else:
+                    raise Exception("IllegalState")
+
+            if isinstance(state, StarLoopbackState):
+                self.checkCondition(len(state.transitions) == 1)
+                self.checkCondition(isinstance(state.transitions[0].target, StarLoopEntryState))
+
+            if isinstance(state, LoopEndState):
+                self.checkCondition(state.loopBackState is not None)
+
+            if isinstance(state, RuleStartState):
+                self.checkCondition(state.stopState is not None)
+
+            if isinstance(state, BlockStartState):
+                self.checkCondition(state.endState is not None)
+
+            if isinstance(state, BlockEndState):
+                self.checkCondition(state.startState is not None)
+
+            if isinstance(state, DecisionState):
+                self.checkCondition(len(state.transitions) <= 1 or state.decision >= 0)
+            else:
+                self.checkCondition(len(state.transitions) <= 1 or isinstance(state, RuleStopState))
+
+    def checkCondition(self, condition:bool, message=None):
+        if not condition:
+            if message is None:
+                message = "IllegalState"
+            raise Exception(message)
+
+    def readInt(self):
+        i = self.data[self.pos]
+        self.pos += 1
+        return i
+
+    def readInt32(self):
+        low = self.readInt()
+        high = self.readInt()
+        return low | (high << 16)
+
+    def readLong(self):
+        low = self.readInt32()
+        high = self.readInt32()
+        return (low & 0x00000000FFFFFFFF) | (high << 32)
+
+    def readUUID(self):
+        low = self.readLong()
+        high = self.readLong()
+        allBits = (low & 0xFFFFFFFFFFFFFFFF) | (high << 64)
+        return UUID(int=allBits)
+
+    edgeFactories = [ lambda args : None,
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : EpsilonTransition(target),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        RangeTransition(target, Token.EOF, arg2) if arg3 != 0 else RangeTransition(target, arg1, arg2),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        RuleTransition(atn.states[arg1], arg2, arg3, target),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        PredicateTransition(target, arg1, arg2, arg3 != 0),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        AtomTransition(target, Token.EOF) if arg3 != 0 else AtomTransition(target, arg1),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        ActionTransition(target, arg1, arg2, arg3 != 0),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        SetTransition(target, sets[arg1]),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        NotSetTransition(target, sets[arg1]),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        WildcardTransition(target),
+                      lambda atn, src, trg, arg1, arg2, arg3, sets, target : \
+                        PrecedencePredicateTransition(target, arg1)
+                      ]
+
+    def edgeFactory(self, atn:ATN, type:int, src:int, trg:int, arg1:int, arg2:int, arg3:int, sets:list):
+        target = atn.states[trg]
+        if type > len(self.edgeFactories) or self.edgeFactories[type] is None:
+            raise Exception("The specified transition type: " + str(type) + " is not valid.")
+        else:
+            return self.edgeFactories[type](atn, src, trg, arg1, arg2, arg3, sets, target)
+
+    stateFactories = [  lambda : None,
+                        lambda : BasicState(),
+                        lambda : RuleStartState(),
+                        lambda : BasicBlockStartState(),
+                        lambda : PlusBlockStartState(),
+                        lambda : StarBlockStartState(),
+                        lambda : TokensStartState(),
+                        lambda : RuleStopState(),
+                        lambda : BlockEndState(),
+                        lambda : StarLoopbackState(),
+                        lambda : StarLoopEntryState(),
+                        lambda : PlusLoopbackState(),
+                        lambda : LoopEndState()
+                    ]
+
+    def stateFactory(self, type:int, ruleIndex:int):
+        if type> len(self.stateFactories) or self.stateFactories[type] is None:
+            raise Exception("The specified state type " + str(type) + " is not valid.")
+        else:
+            s = self.stateFactories[type]()
+            if s is not None:
+                s.ruleIndex = ruleIndex
+        return s
+
+    CHANNEL = 0     #The type of a {@link LexerChannelAction} action.
+    CUSTOM = 1      #The type of a {@link LexerCustomAction} action.
+    MODE = 2        #The type of a {@link LexerModeAction} action.
+    MORE = 3        #The type of a {@link LexerMoreAction} action.
+    POP_MODE = 4    #The type of a {@link LexerPopModeAction} action.
+    PUSH_MODE = 5   #The type of a {@link LexerPushModeAction} action.
+    SKIP = 6        #The type of a {@link LexerSkipAction} action.
+    TYPE = 7        #The type of a {@link LexerTypeAction} action.
+
+    actionFactories = [ lambda data1, data2: LexerChannelAction(data1),
+                        lambda data1, data2: LexerCustomAction(data1, data2),
+                        lambda data1, data2: LexerModeAction(data1),
+                        lambda data1, data2: LexerMoreAction.INSTANCE,
+                        lambda data1, data2: LexerPopModeAction.INSTANCE,
+                        lambda data1, data2: LexerPushModeAction(data1),
+                        lambda data1, data2: LexerSkipAction.INSTANCE,
+                        lambda data1, data2: LexerTypeAction(data1)
+                      ]
+
+    def lexerActionFactory(self, type:int, data1:int, data2:int):
+
+        if type > len(self.actionFactories) or self.actionFactories[type] is None:
+            raise Exception("The specified lexer action type " + str(type) + " is not valid.")
+        else:
+            return self.actionFactories[type](data1, data2)