simplibs-regex 0.1.0__py3-none-any.whl

simplibs/regex/__init__.py

@@ -0,0 +1,171 @@
+# ======================================================================
+# Base Class
+# ======================================================================
+from .base_class.Regex import Regex
+
+# ======================================================================
+# Compiler
+# ======================================================================
+from .compiler.RegexPattern import RegexPattern
+
+# ======================================================================
+# Elements & Enums
+# ======================================================================
+from .elements.Anchor import Anchor
+from .elements.enums.AnchorKind import AnchorKind
+from .elements.CharacterClass import CharacterClass
+from .elements.CharacterRange import CharacterRange
+from .elements.CharacterType import CharacterType
+from .elements.enums.CharacterTypeKind import CharacterTypeKind
+from .elements.CharCode import CharCode
+from .elements.enums.CharCodeKind import CharCodeKind
+from .elements.GroupReference import GroupReference
+from .elements.Literal import Literal
+from .elements.RawPattern import RawPattern
+
+# ======================================================================
+# Containers & Enums
+# ======================================================================
+from .containers.Alternation import Alternation
+from .containers.Conditional import Conditional
+from .containers.Group import Group
+from .containers.Lookaround import Lookaround
+from .containers.enums.LookaroundDirection import LookaroundDirection
+from .containers.Repeat import Repeat
+from .containers.enums.RepeatMode import RepeatMode
+from .containers.Sequence import Sequence
+
+# ======================================================================
+# Flags
+# ======================================================================
+from .flags.Flag import Flag
+
+# ======================================================================
+# Presets (Anchors)
+# ======================================================================
+from .presets.anchors.END import END
+from .presets.anchors.END_STRING import END_STRING
+from .presets.anchors.NON_WORD_BOUNDARY import NON_WORD_BOUNDARY
+from .presets.anchors.START import START
+from .presets.anchors.START_STRING import START_STRING
+from .presets.anchors.WORD_BOUNDARY import WORD_BOUNDARY
+
+# ======================================================================
+# Presets (Character Types)
+# ======================================================================
+from .presets.character_types.DIGIT import DIGIT
+from .presets.character_types.NON_DIGIT import NON_DIGIT
+from .presets.character_types.NON_WHITESPACE import NON_WHITESPACE
+from .presets.character_types.NON_WORD import NON_WORD
+from .presets.character_types.WHITESPACE import WHITESPACE
+from .presets.character_types.WORD import WORD
+
+# ======================================================================
+# Presets (Groups)
+# ======================================================================
+from .presets.groups.ATOMIC_GROUP import ATOMIC_GROUP
+from .presets.groups.NAMED_GROUP import NAMED_GROUP
+from .presets.groups.NON_CAPTURING import NON_CAPTURING
+
+# ======================================================================
+# Presets (Lookaround)
+# ======================================================================
+from .presets.lookaround.LOOKAHEAD import LOOKAHEAD
+from .presets.lookaround.LOOKBEHIND import LOOKBEHIND
+from .presets.lookaround.NEGATIVE_LOOKAHEAD import NEGATIVE_LOOKAHEAD
+from .presets.lookaround.NEGATIVE_LOOKBEHIND import NEGATIVE_LOOKBEHIND
+
+# ======================================================================
+# Presets (Quantifiers)
+# ======================================================================
+from .presets.quantifiers.AT_LEAST import AT_LEAST
+from .presets.quantifiers.BETWEEN import BETWEEN
+from .presets.quantifiers.EXACTLY import EXACTLY
+from .presets.quantifiers.ONE_OR_MORE import ONE_OR_MORE
+from .presets.quantifiers.OPTIONAL import OPTIONAL
+from .presets.quantifiers.ZERO_OR_MORE import ZERO_OR_MORE
+
+
+__all__ = [
+    # Base Class
+    "Regex",
+    # Compiler
+    "RegexPattern",
+    # Elements & Enums
+    "Anchor",
+    "AnchorKind",
+    "CharacterClass",
+    "CharacterRange",
+    "CharacterType",
+    "CharacterTypeKind",
+    "CharCode",
+    "CharCodeKind",
+    "GroupReference",
+    "Literal",
+    "RawPattern",
+    # Containers & Enums
+    "Alternation",
+    "Conditional",
+    "Group",
+    "Lookaround",
+    "LookaroundDirection",
+    "Repeat",
+    "RepeatMode",
+    "Sequence",
+    # Flags
+    "Flag",
+    # Presets - Anchors
+    "END",
+    "END_STRING",
+    "NON_WORD_BOUNDARY",
+    "START",
+    "START_STRING",
+    "WORD_BOUNDARY",
+    # Presets - Character Types
+    "DIGIT",
+    "NON_DIGIT",
+    "NON_WHITESPACE",
+    "NON_WORD",
+    "WHITESPACE",
+    "WORD",
+    # Presets - Groups
+    "ATOMIC_GROUP",
+    "NAMED_GROUP",
+    "NON_CAPTURING",
+    # Presets - Lookaround
+    "LOOKAHEAD",
+    "LOOKBEHIND",
+    "NEGATIVE_LOOKAHEAD",
+    "NEGATIVE_LOOKBEHIND",
+    # Presets - Quantifiers",
+    "AT_LEAST",
+    "BETWEEN",
+    "EXACTLY",
+    "ONE_OR_MORE",
+    "OPTIONAL",
+    "ZERO_OR_MORE",
+]
+
+
+_DESIGN_NOTES = """
+# Simplibs Regex Library — Main Package Root
+
+## Purpose
+The `simplibs-regex` root package provides a clean, expressive, 
+and type-safe Domain Specific Language (DSL) for constructing, 
+composing, and compiling regular expressions in Python. 
+It decouples primitive AST nodes from structural containers 
+and ergonomic presets, ensuring robust IDE support 
+and fail-fast validation.
+
+## Core Architecture & Root Packages Registry
+
+| Sub-Package / Module | Type             | Description                                                                         |
+| :------------------- | :--------------- | :---------------------------------------------------------------------------------- |
+| `base_class`         | Foundation       | Provides the root abstract AST node class (`Regex`) and precedence management.      |
+| `compiler`           | Compilation      | Handles expression compilation, pattern generation, and execution (`RegexPattern`). |
+| `elements`           | Atomic AST Nodes | Foundational building blocks like literals, anchors, character classes, and codes.  |
+| `containers`         | Higher-Order AST | Structural combinators like sequences, alternations, groups, and quantifiers.       |
+| `flags`              | Configuration    | Regular expression compilation flags (`Flag`).                                      |
+| `presets`            | DSL Shortcuts    | Ready-to-use syntactic helpers and atomic aliases for clean expression building.    |
+"""

simplibs/regex/base_class/Regex.py

@@ -0,0 +1,328 @@
+from abc import ABC, abstractmethod
+from typing import Any
+# Inners
+from ._Precedence import _Precedence
+
+
+class Regex(ABC):
+    """Abstract base class for every node of the regex DSL.
+
+    Every concrete node (container or atom) inherits from this class and
+    implements `to_pattern` and, where a fixed length is knowable,
+    `fixed_length`. The class provides precedence-aware rendering via
+    `render` (Point 1), fixed-length introspection for lookbehind
+    validation (Point 3), a character-class-item opt-in marker (Point 4),
+    and `+`/`|` composition operators mirroring `Rule`'s `&`/`|`.
+    """
+
+    # ----------------------------------------------------------------------
+    # Class-level contract every subclass declares
+    # ----------------------------------------------------------------------
+
+    # Point 1 — binding power of THIS node's own top-level syntax, used by
+    # a parent's `render()` to decide whether this node needs wrapping.
+    # Defaults to ATOM (self-delimiting) — the loosest-binding containers
+    # (Sequence, Alternation) explicitly override this to a lower value.
+    _precedence: _Precedence = _Precedence.ATOM
+
+    # Point 4 — opt-in marker: True on nodes that are legal standalone
+    # items inside a CharacterClass (`[...]`), where escape semantics
+    # differ from the rest of the pattern (see CharacterClass's own
+    # validation, which checks this flag rather than a broad isinstance
+    # check against the whole Regex hierarchy). Defaults to False; only
+    # CharacterType, CharacterRange, CharCode and single-character
+    # Literal override it to True.
+    _usable_in_char_class: bool = False
+
+    # ----------------------------------------------------------------------
+    # 1) Abstract Interface (mandatory for subclasses)
+    # ----------------------------------------------------------------------
+
+    @abstractmethod
+    def to_pattern(self) -> str:
+        """Return this node's own regex fragment, WITHOUT any wrapping
+        that depends on where it is embedded.
+
+        Containers call `child.render(self._precedence)` on their
+        children instead of `child.to_pattern()` directly, so that
+        wrapping decisions are made once, in one place (`render`), never
+        duplicated per-container. Implementations of `to_pattern` should
+        therefore never wrap their own output in `(?:...)` for precedence
+        reasons — only for syntax that is mandatory regardless of context
+        (e.g. `Group` always emits its own parentheses; that is not a
+        precedence wrap, it is the node's literal syntax).
+        """
+        raise NotImplementedError
+
+    # ----------------------------------------------------------------------
+    # 2) Fixed-Length Introspection (Point 3 — lookbehind validation)
+    # ----------------------------------------------------------------------
+
+    def fixed_length(self) -> int | None:
+        """Return this node's match length in characters if — and only
+        if — it is fixed regardless of input, otherwise `None`.
+
+        Used by `Lookaround` (direction=BEHIND) to fail fast at
+        construction time when Python's `re` would otherwise reject a
+        variable-length lookbehind, instead of surfacing that failure
+        only later at `re.compile()`.
+
+        Default: `None` (unknown / variable). A node that CAN determine
+        a fixed length overrides this:
+        * `Literal` -> `len(text)`
+        * `CharacterType` / `CharacterClass` / `Anchor` (non-empty-width
+          anchors return 0) -> a constant
+        * `Sequence` -> sum of children's fixed lengths, or `None` if any
+          child is `None`
+        * `Repeat` -> `min * inner_length` when `min == max` and inner has
+          a fixed length, else `None`
+        * `Alternation` -> the shared length if every branch has the SAME
+          fixed length, else `None` (Python's `re` does support
+          same-length alternation inside a lookbehind)
+
+        Never guess: returning a wrong non-`None` value here would let an
+        invalid lookbehind slip past construction-time validation only to
+        fail confusingly later, or (worse) silently compile something
+        other than what the user intended.
+        """
+        return None
+
+    def needs_wrap_for_repeat(self) -> bool:
+        """Return True if this node, despite rendering at ATOM precedence
+        (no wrap from `render`'s ordinary precedence comparison), still
+        needs an explicit `(?:...)` wrap before a `Repeat` quantifier can
+        be applied to it as a single unit.
+
+        Exists for exactly one case in the whole hierarchy: a
+        multi-character `Literal`. Quantifiers in `re` bind to the single
+        preceding token — a character, an escape sequence, a character
+        class, or a group — never to more than one character of plain
+        text. `Literal`'s own `_precedence` correctly stays at ATOM (it
+        needs no wrap when embedded in a `Sequence` or `Alternation`),
+        so `_precedence` alone cannot express this narrower,
+        repeat-specific constraint; this separate hook does.
+
+        Default: `False` — every other ATOM-precedence node (`Anchor`,
+        `CharacterType`, `CharacterClass`, `Group`, `Lookaround`,
+        `GroupReference`, `CharCode`) is already exactly one token by
+        construction and never needs this.
+        """
+        return False
+
+    def to_char_class_fragment(self) -> str:
+        """Return this node's representation for use as a standalone item
+        inside a `CharacterClass` (`[...]`), where escaping rules differ
+        from the rest of a pattern (Point 4).
+
+        Default: identical to `to_pattern()` — correct for every node
+        whose escape syntax is genuinely the same inside and outside a
+        character class (`CharacterType`, `CharCode`). Only `Literal`
+        overrides this, since a character class only ever needs to
+        escape `] ^ - \\`, a different and much smaller set than the
+        general-purpose `re.escape` used by `Literal.to_pattern`.
+
+        Only ever called on nodes where `_usable_in_char_class` is
+        `True` — `CharacterClass.__init__` is responsible for that
+        check; this method itself does not re-validate it.
+        """
+        return self.to_pattern()
+
+    # ----------------------------------------------------------------------
+    # 3) Precedence-Aware Rendering (Point 1)
+    # ----------------------------------------------------------------------
+
+    def render(self, parent_precedence: "_Precedence") -> str:
+        """Render this node for embedding inside a parent whose own
+        binding power is `parent_precedence`.
+
+        Wraps `to_pattern()`'s output in a non-capturing group exactly
+        when this node's own `_precedence` is strictly lower than the
+        parent's — e.g. an `Alternation` embedded inside a `Sequence`
+        gets wrapped, because ALTERNATION < SEQUENCE. A node whose
+        precedence is ATOM (the default) is never wrapped, since it is
+        already self-delimiting.
+
+        This is the ONLY place precedence wrapping happens. Containers
+        (`Sequence`, `Repeat`, ...) must call `child.render(self._precedence)`
+        on every child instead of `child.to_pattern()` directly.
+        """
+        fragment = self.to_pattern()
+
+        if self._precedence < parent_precedence:
+            return f"(?:{fragment})"
+
+        return fragment
+
+    # ----------------------------------------------------------------------
+    # 4) Public Interface
+    # ----------------------------------------------------------------------
+
+    def compile(self, flags: int = 0) -> Any:
+        """Compile this node's top-level pattern via `re.compile`.
+
+        Top-level rendering always uses `to_pattern()` directly (never
+        `render()`) — there is no parent context to wrap against at the
+        root of the tree.
+        """
+        import re
+
+        return re.compile(self.to_pattern(), flags)
+
+    # ----------------------------------------------------------------------
+    # 5) Operator-Based Composition (+, |)
+    # ----------------------------------------------------------------------
+    #
+    # `+` builds Sequence, `|` builds Alternation — deliberately different
+    # operators from Rule's `&`/`|`, since regex composition has no
+    # boolean AND: two nodes next to each other in a pattern concatenate,
+    # they do not both have to "pass". `|` is the one operator that keeps
+    # its meaning from Rule/Action, since regex alternation IS a direct
+    # analogue of logical OR.
+
+    def __add__(self, other: "Regex") -> "Regex":
+        """Concatenate with another node via `node1 + node2`.
+
+        Equivalent to `Sequence(self, other)`. Returns `NotImplemented`
+        for anything that is not a `Regex` instance, letting Python fall
+        back to `other.__radd__(self)` or raise `TypeError` as usual.
+        """
+        if isinstance(other, Regex):
+            from ..containers.Sequence import Sequence
+
+            return Sequence(self, other)
+        return NotImplemented
+
+    def __radd__(self, other: "Regex") -> "Regex":
+        """Support `other + node` when `other` has no (or a declining) `__add__`."""
+        if isinstance(other, Regex):
+            from ..containers.Sequence import Sequence
+
+            return Sequence(other, self)
+        return NotImplemented
+
+    def __or__(self, other: "Regex") -> "Regex":
+        """Combine with another node via alternation: `node1 | node2`.
+
+        Equivalent to `Alternation(self, other)`.
+        """
+        if isinstance(other, Regex):
+            from ..containers.Alternation import Alternation
+
+            return Alternation(self, other)
+        return NotImplemented
+
+    def __ror__(self, other: "Regex") -> "Regex":
+        """Support `other | node` when `other` has no (or a declining) `__or__`."""
+        if isinstance(other, Regex):
+            from ..containers.Alternation import Alternation
+
+            return Alternation(other, self)
+        return NotImplemented
+
+    def __repr__(self) -> str:
+        """Return a concise unambiguous representation of the Regex node."""
+        return f"{self.__class__.__name__}({self.to_pattern()!r})"
+
+_DESIGN_NOTES = """
+# Regex — Base Abstract Class for the Regex DSL
+
+## Relationship to Rule / Action
+Same three-part shape: (1) an abstract production method every subclass
+must implement (`to_pattern`, mirroring `is_valid`/`__call__`), (2) a
+public convenience surface (`render`, `compile`), (3) operator-based
+composition delegating to lazily-imported containers, exactly like
+`Rule.__and__`/`Action.__and__` deferring to `AllOf`/`ParallelCompose`.
+
+The one new piece with no Rule/Action equivalent is `fixed_length` —
+regex composition has no analogue to "does this predicate pass", but it
+does have "how wide is this fragment", and that question only exists
+because `Lookaround(direction=BEHIND)` needs an answer to it at
+construction time.
+
+## Why `render()` lives on the base class, not repeated per container
+Every container (`Sequence`, `Alternation`, `Repeat`, `Group`, ...) needs
+the exact same decision procedure for wrapping a child: compare
+precedences, wrap or don't. Putting that once on `Regex.render()` and
+having containers call `child.render(self._precedence)` means the
+wrapping RULE has exactly one implementation in the whole library — a
+container never decides FOR ITSELF whether to wrap a child, it just
+states its own precedence and asks the child to render into that
+context. This mirrors how `AllOf.build_exception` doesn't reimplement
+diagnostic formatting — it delegates to `build_child_exception`.
+
+## Why `_precedence` defaults to ATOM rather than being abstract
+Most nodes in the tree (`Literal`, `CharacterType`, `Anchor`,
+`GroupReference`, `CharCode`, and every container that already emits its
+own delimiters — `Group`, `CharacterClass`, `Lookaround`, `Conditional`)
+are self-delimiting and never need wrapping. Only `Sequence`,
+`Alternation`, and `Repeat` have a real precedence below ATOM and must
+override the class attribute. Making ATOM the default means the large,
+common case (leaf nodes) declares nothing extra — only the few
+containers where it actually matters opt out of the default.
+
+## Why `fixed_length` is a concrete method with a safe default, not abstract
+Unlike `to_pattern` (every node MUST be renderable) or `is_valid` on
+`Rule` (every rule MUST be evaluable), most nodes genuinely don't need an
+exact answer to "how long am I" — only `Lookaround` ever asks the
+question. Defaulting to `None` ("unknown/variable") is always SAFE: a
+node that fails to override this when it actually has a fixed length
+only loses the ability to be used inside a lookbehind directly (it can
+still always be wrapped in an explicit, hand-verified way) — it can
+never cause a wrong pattern to compile, because `None` is
+construction-time-rejected by `Lookaround`, never silently accepted.
+
+## Point 4 — `_usable_in_char_class` is a flag, not a separate hierarchy
+Chosen deliberately over fully separate `CharacterClassItem`/`Atom` class
+hierarchies (the alternative discussed as "variant 1" in the design
+review): a single `Regex` hierarchy stays consistent with `Rule`'s own
+single-hierarchy shape, and `CharacterClass.__init__` enforces the
+restriction procedurally — via `isinstance(item, Regex) and
+item._usable_in_char_class` — the same procedural-check pattern
+`Rule.__and__` already uses for `__not_rule__`. This is intentionally
+closer to variant 2 of the original write-up (runtime marker, not a
+type-level split) — full static separation would require either
+duplicating `CharacterType`/`CharCode` under two class hierarchies or
+introducing a shared mixin/Protocol layer whose benefit (catching a
+`CharacterClass(WordBoundary())` mistake at type-check time instead of
+at construction time) did not outweigh the added structural complexity
+for this first pass. `CharacterClass`'s own design notes will document
+this decision again alongside its actual constructor.
+
+## `compile()` uses `to_pattern()` directly, never `render()`
+There is no parent node at the root of a tree, so there is no
+`parent_precedence` to render against. Calling `render()` at the root
+would require inventing a fake top-level precedence — `to_pattern()` is
+the honest choice: the root always emits its own fragment unwrapped.
+
+## `needs_wrap_for_repeat` — a narrower hook than `_precedence`, added for Point 2
+`Repeat` needs to know something `_precedence` genuinely cannot express:
+not "does this need parentheses to avoid changing meaning in a larger
+expression" (that's precedence), but "is this exactly one quantifiable
+token". Those two questions have the same answer for every ATOM node
+except a multi-character `Literal`, which is why this is a separate
+method with a safe default (`False`) rather than a new `_Precedence`
+level — inventing a level for a single-class exception would have
+forced every other atom to reason about a distinction that, for them,
+never varies.
+
+## `to_char_class_fragment` — a narrower rendering hook, added for Point 4
+Same shape of decision as `needs_wrap_for_repeat`: the DEFAULT
+implementation (delegate straight to `to_pattern`) is correct for the
+common case (`CharacterType`, `CharCode` — genuinely the same escape
+syntax either side of `[...]`), and only the one node where the two
+contexts actually diverge (`Literal`) overrides it. Kept as a separate
+method rather than a branch inside `to_pattern` itself, because
+`to_pattern`'s job is "render me as a normal fragment" — conflating
+that with "render me as a character-class item" would make every node
+that never appears inside a class carry dead branching for a context
+that can never apply to it.
+
+## Why `+` for Sequence instead of reusing `&`
+`Rule.__and__` means "both predicates must hold" — a genuine boolean AND.
+Two regex nodes placed next to each other don't "both have to hold" in
+that sense; they concatenate. Using `&` for that would silently imply a
+semantics this DSL does not have (and `&` is already claimed by
+`Action` for a different, execution-parallel meaning) — `+` reads
+correctly as "these go one after another" and has no prior claimed
+meaning in either sibling library.
+"""

simplibs/regex/base_class/_Precedence.py

@@ -0,0 +1,43 @@
+from enum import IntEnum
+
+
+class _Precedence(IntEnum):
+    """Binding-power levels used by `Regex.render()` to decide whether a
+    child node must be wrapped in a non-capturing group before being
+    embedded inside a parent node.
+
+    Ordering matches regex operator precedence, from loosest-binding to
+    tightest-binding. A child is wrapped whenever its own precedence is
+    STRICTLY LOWER than the precedence the parent renders it at — e.g. an
+    `Alternation` (ALTERNATION) embedded inside a `Sequence` (SEQUENCE)
+    gets wrapped, because ALTERNATION < SEQUENCE.
+
+    ATOM is intentionally the ceiling: anything already self-delimiting
+    (a single character, a `Group`, a `CharacterClass`, a `Lookaround`)
+    never needs an extra wrap, regardless of where it is embedded.
+    """
+
+    ALTERNATION = 0   # A|B  — loosest: spreads across the entire pattern if unwrapped
+    SEQUENCE = 1      # AB   — concatenation
+    REPEAT = 2        # A*, A{m,n}, ...  — binds to exactly one preceding unit
+    ATOM = 3          # single char, Group(...), CharacterClass, Lookaround, Anchor, ...
+
+
+_DESIGN_NOTES = """
+# _Precedence — Operator Binding Power
+
+## Purpose
+Defines binding-power levels for `Regex.render()` to determine when a child 
+node requires wrapping in a non-capturing group.
+
+## Precedence Hierarchy (Loosest to Tightest)
+1. `ALTERNATION = 0` (`A|B`) — loosest binding.
+2. `SEQUENCE = 1` (`AB`) — concatenation.
+3. `REPEAT = 2` (`A*`, `A{m,n}`) — binds to one preceding unit.
+4. `ATOM = 3` — ceiling (self-delimiting nodes like groups, character classes, 
+anchors, never need wrapping).
+
+## Wrapping Rule
+A child is wrapped if its precedence is strictly lower than the parent's 
+rendering context (`child_precedence < parent_precedence`).
+"""

simplibs/regex/base_class/__init__.py

@@ -0,0 +1,18 @@
+from ._Precedence import _Precedence
+from .Regex import Regex
+
+
+_DESIGN_NOTES = """
+# Regex Base Class Sub-Package
+
+## Purpose
+The `base_class` package provides the foundational abstract syntax tree (AST) building blocks 
+for the regex library, including operator overloading, precedence levels, and fragment generation hooks.
+
+## Internal Components Registry
+
+| Component     | Type             | Description                                                                        |
+| :------------ | :--------------- | :--------------------------------------------------------------------------------- |
+| `Regex`       | Abstract Class   | The root abstract class for all regex AST nodes, defining operators and hooks.     |
+| `_Precedence` | Internal Enum    | Precedence levels used to determine when parentheses are required during rendering.|
+"""