purere2 0.1.0__tar.gz

purere2-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adam2go
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

purere2-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: purere2
+Version: 0.1.0
+Summary: RE2 in pure Python: linear-time, ReDoS-safe regular expressions - no C extension, no backtracking
+Author: adam2go
+License: MIT
+Project-URL: Homepage, https://github.com/adam2go/purere2
+Keywords: regex,re2,redos,linear-time,nfa,pure-python,security,untrusted
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# purere2
+
+[![CI](https://github.com/adam2go/purere2/actions/workflows/ci.yml/badge.svg)](https://github.com/adam2go/purere2/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/purere2)](https://pypi.org/project/purere2/)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.14%20%7C%20PyPy-blue)](.github/workflows/ci.yml)
+[![RE2 conformance](https://img.shields.io/badge/vs%20real%20RE2-99.996%25-brightgreen)](EXPECTED_DIVERGENCES.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**[RE2](https://github.com/google/re2) in pure Python: linear-time,
+ReDoS-safe regular expressions — no C extension, no backtracking.**
+
+Python's built-in `re` (like PCRE and Perl) backtracks, so a pattern like
+`(a+)+$` against a non-matching string can run for years on a few dozen
+characters — the classic **ReDoS** denial-of-service. purere2 compiles every
+pattern to an NFA and runs it with a Pike VM, so **matching is always linear
+in the input** and no pattern can blow up. That guarantee is exactly why
+[RE2 exists](https://github.com/google/re2/wiki/WhyRE2) — and why it has no
+backreferences or lookaround.
+
+```sh
+pip install purere2
+```
+
+```python
+import purere2
+
+# linear time: this returns instantly; re.search would hang for minutes
+purere2.search(r"(a+)+$", "a" * 50 + "!")          # None, in microseconds
+
+purere2.search(r"(\w+)@(\w+)", "x@y").groups()      # ('x', 'y')
+purere2.findall(r"\d{4}-\d\d-\d\d", "2026-06-19")   # ['2026-06-19']
+```
+
+The API mirrors the common subset of the stdlib `re` module
+(`compile`, `search`, `match`, `fullmatch`, `finditer`, `findall`, `sub`,
+`subn`, `split`, flags `I/M/S`, named groups), so it is close to a drop-in
+replacement for **running untrusted or LLM-generated patterns safely**.
+
+## Why pure Python
+
+`google-re2` and `pyre2` already wrap RE2 — but they need the RE2 **C++
+library** (and a compiler, or a matching binary wheel). There was no pure
+Python RE2, even though [RE2/J](https://github.com/google/re2j) (Java) and
+[RE2JS](https://github.com/le0pard/re2js) (JavaScript) have existed for years.
+purere2 is the missing one: zero dependencies, zero binaries, runs anywhere
+Python runs — Pyodide/WASM, AWS Lambda, locked-down sandboxes — exactly where
+you most want to run a pattern you don't trust.
+
+The trade-off, stated honestly: on ordinary patterns purere2 is **slower than
+the C-backed `re`** (a pure-Python NFA can't beat a C engine). Its value is
+**safety and portability**, not raw speed — use it where a pattern is
+untrusted, or where a C extension isn't an option, not as a blanket `re`
+replacement.
+
+## Verified against the real RE2
+
+Conformance is differential, the same way [purefzf](https://github.com/adam2go/purefzf)
+checks itself against the `fzf` binary: random RE2 patterns and inputs are run
+through both purere2 and `google-re2` and compared byte-for-byte. Across
+**150,000+ random checks, agreement is ~99.996%**; the residue is one
+documented edge (a lazy quantifier nested in a greedy loop) — see
+[EXPECTED_DIVERGENCES.md](EXPECTED_DIVERGENCES.md). The conformance test locks
+that level, so any regression fails CI. There is also a ReDoS-safety suite of
+patterns that hang stdlib `re` and must finish in milliseconds here.
+
+## Supported syntax (v0.1)
+
+Literals, `.`, character classes `[...]` with ranges / negation / POSIX
+`[[:alpha:]]`, perl classes `\d \w \s` (ASCII, per RE2) and negations,
+anchors `^ $ \A \z \b \B`, groups `(...)` / `(?:...)` / `(?P<name>...)`,
+alternation `|`, quantifiers `* + ? {m} {m,n}` greedy and lazy, inline flags
+`(?i) (?m) (?s)` and scoped `(?i:...)`, escapes including `\xHH` / `\x{...}`.
+
+**Intentionally absent** (this is what makes it safe): backreferences and
+lookaround. `(a)\1` raises `RegexError`. Deferred to a later version: Unicode
+property classes `\p{...}` and full Unicode case folding.
+
+## License
+
+[MIT](LICENSE)

purere2-0.1.0/README.md

@@ -0,0 +1,80 @@
+# purere2
+
+[![CI](https://github.com/adam2go/purere2/actions/workflows/ci.yml/badge.svg)](https://github.com/adam2go/purere2/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/purere2)](https://pypi.org/project/purere2/)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.14%20%7C%20PyPy-blue)](.github/workflows/ci.yml)
+[![RE2 conformance](https://img.shields.io/badge/vs%20real%20RE2-99.996%25-brightgreen)](EXPECTED_DIVERGENCES.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**[RE2](https://github.com/google/re2) in pure Python: linear-time,
+ReDoS-safe regular expressions — no C extension, no backtracking.**
+
+Python's built-in `re` (like PCRE and Perl) backtracks, so a pattern like
+`(a+)+$` against a non-matching string can run for years on a few dozen
+characters — the classic **ReDoS** denial-of-service. purere2 compiles every
+pattern to an NFA and runs it with a Pike VM, so **matching is always linear
+in the input** and no pattern can blow up. That guarantee is exactly why
+[RE2 exists](https://github.com/google/re2/wiki/WhyRE2) — and why it has no
+backreferences or lookaround.
+
+```sh
+pip install purere2
+```
+
+```python
+import purere2
+
+# linear time: this returns instantly; re.search would hang for minutes
+purere2.search(r"(a+)+$", "a" * 50 + "!")          # None, in microseconds
+
+purere2.search(r"(\w+)@(\w+)", "x@y").groups()      # ('x', 'y')
+purere2.findall(r"\d{4}-\d\d-\d\d", "2026-06-19")   # ['2026-06-19']
+```
+
+The API mirrors the common subset of the stdlib `re` module
+(`compile`, `search`, `match`, `fullmatch`, `finditer`, `findall`, `sub`,
+`subn`, `split`, flags `I/M/S`, named groups), so it is close to a drop-in
+replacement for **running untrusted or LLM-generated patterns safely**.
+
+## Why pure Python
+
+`google-re2` and `pyre2` already wrap RE2 — but they need the RE2 **C++
+library** (and a compiler, or a matching binary wheel). There was no pure
+Python RE2, even though [RE2/J](https://github.com/google/re2j) (Java) and
+[RE2JS](https://github.com/le0pard/re2js) (JavaScript) have existed for years.
+purere2 is the missing one: zero dependencies, zero binaries, runs anywhere
+Python runs — Pyodide/WASM, AWS Lambda, locked-down sandboxes — exactly where
+you most want to run a pattern you don't trust.
+
+The trade-off, stated honestly: on ordinary patterns purere2 is **slower than
+the C-backed `re`** (a pure-Python NFA can't beat a C engine). Its value is
+**safety and portability**, not raw speed — use it where a pattern is
+untrusted, or where a C extension isn't an option, not as a blanket `re`
+replacement.
+
+## Verified against the real RE2
+
+Conformance is differential, the same way [purefzf](https://github.com/adam2go/purefzf)
+checks itself against the `fzf` binary: random RE2 patterns and inputs are run
+through both purere2 and `google-re2` and compared byte-for-byte. Across
+**150,000+ random checks, agreement is ~99.996%**; the residue is one
+documented edge (a lazy quantifier nested in a greedy loop) — see
+[EXPECTED_DIVERGENCES.md](EXPECTED_DIVERGENCES.md). The conformance test locks
+that level, so any regression fails CI. There is also a ReDoS-safety suite of
+patterns that hang stdlib `re` and must finish in milliseconds here.
+
+## Supported syntax (v0.1)
+
+Literals, `.`, character classes `[...]` with ranges / negation / POSIX
+`[[:alpha:]]`, perl classes `\d \w \s` (ASCII, per RE2) and negations,
+anchors `^ $ \A \z \b \B`, groups `(...)` / `(?:...)` / `(?P<name>...)`,
+alternation `|`, quantifiers `* + ? {m} {m,n}` greedy and lazy, inline flags
+`(?i) (?m) (?s)` and scoped `(?i:...)`, escapes including `\xHH` / `\x{...}`.
+
+**Intentionally absent** (this is what makes it safe): backreferences and
+lookaround. `(a)\1` raises `RegexError`. Deferred to a later version: Unicode
+property classes `\p{...}` and full Unicode case folding.
+
+## License
+
+[MIT](LICENSE)

purere2-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "purere2"
+version = "0.1.0"
+description = "RE2 in pure Python: linear-time, ReDoS-safe regular expressions - no C extension, no backtracking"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "adam2go" }]
+keywords = ["regex", "re2", "redos", "linear-time", "nfa", "pure-python",
+            "security", "untrusted"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Programming Language :: Python :: Implementation :: PyPy",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Security",
+    "Topic :: Text Processing",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/adam2go/purere2"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

purere2-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

purere2-0.1.0/src/purere2/__init__.py

@@ -0,0 +1,281 @@
+"""purere2: RE2 in pure Python - linear-time, ReDoS-safe regular expressions.
+
+A pattern compiles to an NFA run by a Pike VM, so matching is always linear in
+the input and no pattern can cause catastrophic backtracking. Like RE2 (and
+unlike Python's `re`), backreferences and lookaround are intentionally absent -
+that absence is exactly what makes the linear-time guarantee possible.
+
+    import purere2
+    purere2.search(r"(\\w+)@(\\w+)", "x@y").groups()      # ('x', 'y')
+    pat = purere2.compile(r"\\d{4}-\\d\\d-\\d\\d")
+    pat.findall("2026-06-19 and 2027-01-01")
+
+The API mirrors the common subset of the stdlib `re` module, so it is close to
+a drop-in replacement for running untrusted or LLM-generated patterns safely.
+"""
+from __future__ import annotations
+
+from .compiler import compile_ast
+from .parser import Anchor, Concat, RegexError, parse
+from .pikevm import Program
+
+__version__ = "0.1.0"
+__all__ = ["compile", "search", "match", "fullmatch", "finditer", "findall",
+           "sub", "subn", "split", "escape", "Pattern", "Match", "RegexError",
+           "error", "I", "IGNORECASE", "M", "MULTILINE", "S", "DOTALL"]
+
+# flag constants (compatible values with re)
+I = IGNORECASE = 2
+M = MULTILINE = 8
+S = DOTALL = 16
+
+error = RegexError
+
+
+def _nslots(ngroups):
+    return 2 * (ngroups + 1)
+
+
+class Match:
+    __slots__ = ("_slots", "string", "_names", "re", "pos", "endpos")
+
+    def __init__(self, slots, string, names, pattern):
+        self._slots = slots
+        self.string = string
+        self._names = names
+        self.re = pattern
+
+    def _idx(self, group):
+        if isinstance(group, str):
+            if group not in self._names:
+                raise IndexError("no such group %r" % group)
+            return self._names[group]
+        return group
+
+    def group(self, *groups):
+        if not groups:
+            groups = (0,)
+        res = tuple(self._one(g) for g in groups)
+        return res[0] if len(res) == 1 else res
+
+    def _one(self, group):
+        g = self._idx(group)
+        a = self._slots[2 * g]
+        b = self._slots[2 * g + 1]
+        if a is None or b is None:
+            return None
+        return self.string[a:b]
+
+    def groups(self, default=None):
+        out = []
+        for g in range(1, len(self._slots) // 2):
+            v = self._one(g)
+            out.append(default if v is None else v)
+        return tuple(out)
+
+    def groupdict(self, default=None):
+        return {name: (self._one(i) if self._one(i) is not None else default)
+                for name, i in self._names.items()}
+
+    def start(self, group=0):
+        s = self._slots[2 * self._idx(group)]
+        return -1 if s is None else s
+
+    def end(self, group=0):
+        e = self._slots[2 * self._idx(group) + 1]
+        return -1 if e is None else e
+
+    def span(self, group=0):
+        return (self.start(group), self.end(group))
+
+    def __getitem__(self, group):
+        return self._one(group)
+
+    def __repr__(self):
+        return "<purere2.Match span=%r match=%r>" % (self.span(), self.group(0))
+
+
+class Pattern:
+    __slots__ = ("pattern", "flags", "groups", "groupindex", "_prog", "_full",
+                 "_ast")
+
+    def __init__(self, pattern, flags=0):
+        self.pattern = pattern
+        self.flags = flags
+        ast, ngroups, names = parse(pattern,
+                                    flags_i=bool(flags & I),
+                                    flags_m=bool(flags & M),
+                                    flags_s=bool(flags & S))
+        self._ast = ast
+        self.groups = ngroups
+        self.groupindex = dict(names)
+        self._prog = Program(compile_ast(ast, ngroups), _nslots(ngroups))
+        self._full = None
+
+    def _fullprog(self):
+        if self._full is None:
+            ast = Concat([self._ast, Anchor("\\z")])
+            self._full = Program(compile_ast(ast, self.groups),
+                                 _nslots(self.groups))
+        return self._full
+
+    def search(self, string, pos=0, endpos=None):
+        return self._run(self._prog, string, pos, endpos, anchored=False)
+
+    def match(self, string, pos=0, endpos=None):
+        return self._run(self._prog, string, pos, endpos, anchored=True)
+
+    def fullmatch(self, string, pos=0, endpos=None):
+        return self._run(self._fullprog(), string, pos, endpos, anchored=True)
+
+    def _run(self, prog, string, pos, endpos, anchored):
+        slots = prog.search(string, pos,
+                            anchored=anchored) if endpos is None else \
+            prog.search(string[:endpos], pos, anchored=anchored)
+        if slots is None:
+            return None
+        return Match(slots, string, self.groupindex, self)
+
+    def finditer(self, string, pos=0, endpos=None):
+        s = string if endpos is None else string[:endpos]
+        n = len(s)
+        while pos <= n:
+            slots = self._prog.search(s, pos, anchored=False)
+            if slots is None:
+                return
+            yield Match(slots, string, self.groupindex, self)
+            a, b = slots[0], slots[1]
+            pos = b + 1 if b == a else b   # avoid stalling on empty matches
+
+    def findall(self, string, pos=0, endpos=None):
+        out = []
+        for m in self.finditer(string, pos, endpos):
+            if self.groups == 0:
+                out.append(m.group(0))
+            elif self.groups == 1:
+                out.append(m.group(1) or "")
+            else:
+                out.append(tuple(g or "" for g in m.groups()))
+        return out
+
+    def sub(self, repl, string, count=0):
+        return self.subn(repl, string, count)[0]
+
+    def subn(self, repl, string, count=0):
+        out = []
+        last = 0
+        n = 0
+        for m in self.finditer(string):
+            if count and n >= count:
+                break
+            out.append(string[last:m.start()])
+            out.append(repl(m) if callable(repl) else _expand(repl, m))
+            last = m.end()
+            n += 1
+        out.append(string[last:])
+        return "".join(out), n
+
+    def split(self, string, maxsplit=0):
+        out = []
+        last = 0
+        n = 0
+        for m in self.finditer(string):
+            if maxsplit and n >= maxsplit:
+                break
+            if m.end() == m.start():
+                continue           # don't split on empty matches (re semantics)
+            out.append(string[last:m.start()])
+            out.extend(m.groups())
+            last = m.end()
+            n += 1
+        out.append(string[last:])
+        return out
+
+    def __repr__(self):
+        return "purere2.compile(%r)" % self.pattern
+
+
+def _expand(template, m):
+    """Expand a replacement template: \\1 \\g<1> \\g<name> and escapes."""
+    out = []
+    i = 0
+    n = len(template)
+    while i < n:
+        c = template[i]
+        if c != "\\":
+            out.append(c)
+            i += 1
+            continue
+        i += 1
+        if i >= n:
+            out.append("\\")
+            break
+        c = template[i]
+        if c == "g":
+            j = template.index(">", i) if ">" in template[i:] else -1
+            assert template[i + 1] == "<" and j != -1, "bad group reference"
+            ref = template[i + 2:j]
+            i = j + 1
+            out.append(m.group(int(ref) if ref.isdigit() else ref) or "")
+        elif c.isdigit():
+            j = i
+            while j < n and template[j].isdigit():
+                j += 1
+            out.append(m.group(int(template[i:j])) or "")
+            i = j
+        else:
+            out.append({"n": "\n", "t": "\t", "r": "\r", "\\": "\\"}.get(c, c))
+            i += 1
+    return "".join(out)
+
+
+_cache = {}
+
+
+def compile(pattern, flags=0):
+    key = (pattern, flags)
+    p = _cache.get(key)
+    if p is None:
+        p = Pattern(pattern, flags)
+        if len(_cache) < 512:
+            _cache[key] = p
+    return p
+
+
+def search(pattern, string, flags=0):
+    return compile(pattern, flags).search(string)
+
+
+def match(pattern, string, flags=0):
+    return compile(pattern, flags).match(string)
+
+
+def fullmatch(pattern, string, flags=0):
+    return compile(pattern, flags).fullmatch(string)
+
+
+def finditer(pattern, string, flags=0):
+    return compile(pattern, flags).finditer(string)
+
+
+def findall(pattern, string, flags=0):
+    return compile(pattern, flags).findall(string)
+
+
+def sub(pattern, repl, string, count=0, flags=0):
+    return compile(pattern, flags).sub(repl, string, count)
+
+
+def subn(pattern, repl, string, count=0, flags=0):
+    return compile(pattern, flags).subn(repl, string, count)
+
+
+def split(pattern, string, maxsplit=0, flags=0):
+    return compile(pattern, flags).split(string, maxsplit)
+
+
+_SPECIAL = set("\\^$.|?*+()[]{}")
+
+
+def escape(s):
+    return "".join("\\" + c if c in _SPECIAL or c.isspace() else c for c in s)

purere2-0.1.0/src/purere2/compiler.py

@@ -0,0 +1,151 @@
+"""Compile an AST into a flat NFA program for the Pike VM.
+
+Instructions (tuples, pc-indexed list):
+    ("char", cp)              consume one codepoint == cp
+    ("set", ranges)           consume one codepoint within ranges
+    ("any", dotall)           consume any codepoint (excl. \\n unless dotall)
+    ("split", x, y)           epsilon-fork; x has priority (greedy preference)
+    ("jmp", x)                epsilon jump
+    ("save", slot)            record current input position into capture slot
+    ("assert", kind, ml)      zero-width assertion (^ $ \\b \\B \\A \\z \\Z)
+    ("match",)                accept
+
+Greedy vs non-greedy is encoded purely by the order of split targets, so the
+VM stays a plain priority-ordered Thompson simulation - linear in input.
+"""
+from __future__ import annotations
+
+from . import parser as P
+
+__all__ = ["compile_ast"]
+
+
+class _Compiler:
+    def __init__(self):
+        self.prog = []
+
+    def emit(self, instr):
+        self.prog.append(instr)
+        return len(self.prog) - 1
+
+    def patch(self, pc, instr):
+        self.prog[pc] = instr
+
+    def compile(self, node, ngroups):
+        self.emit(("save", 0))
+        self._c(node)
+        self.emit(("save", 1))
+        self.emit(("match",))
+        return self.prog
+
+    # emit code for `node`; falls through to the next instruction on success
+    def _c(self, node):
+        t = type(node)
+        if t is P.Empty:
+            return
+        if t is P.Lit:
+            if len(node.cps) == 1:
+                self.emit(("char", node.cps[0]))
+            else:
+                self.emit(("set", tuple((c, c) for c in node.cps)))
+        elif t is P.Dot:
+            self.emit(("any", node.dotall))
+        elif t is P.Class:
+            self.emit(("set", node.ranges))
+        elif t is P.Anchor:
+            self.emit(("assert", node.kind, node.multiline))
+        elif t is P.Concat:
+            for it in node.items:
+                self._c(it)
+        elif t is P.Group:
+            if node.index is not None:
+                self.emit(("save", 2 * node.index))
+                self._c(node.sub)
+                self.emit(("save", 2 * node.index + 1))
+            else:
+                self._c(node.sub)
+        elif t is P.Alt:
+            self._alt(node.opts)
+        elif t is P.Star:
+            self._star(node.sub, node.greedy)
+        elif t is P.Plus:
+            self._plus(node.sub, node.greedy)
+        elif t is P.Quest:
+            self._quest(node.sub, node.greedy)
+        elif t is P.Repeat:
+            self._repeat(node)
+        else:
+            raise AssertionError("unknown node %r" % t)
+
+    def _alt(self, opts):
+        # opt0 | (opt1 | (opt2 | ...)) with priority left-to-right
+        jmps = []
+        for k, opt in enumerate(opts):
+            last = k == len(opts) - 1
+            if not last:
+                sp = self.emit(("split", None, None))
+                a = len(self.prog)
+                self._c(opt)
+                jmps.append(self.emit(("jmp", None)))
+                b = len(self.prog)
+                self.patch(sp, ("split", a, b))
+            else:
+                self._c(opt)
+        end = len(self.prog)
+        for j in jmps:
+            self.patch(j, ("jmp", end))
+
+    def _star(self, sub, greedy):
+        # Compile e* as (e+)? rather than a bare loop. With a plain loop the
+        # exit branch is taken before the body's `save` instructions run, so a
+        # nullable body (e.g. a capturing group that can match empty) would
+        # never record its empty capture. Routing through e+ runs the body's
+        # captures once before the optional exit - matching RE2's submatches.
+        sp = self.emit(("split", None, None))
+        plus = len(self.prog)
+        self._plus(sub, greedy)
+        exit_ = len(self.prog)
+        self.patch(sp, ("split", plus, exit_) if greedy
+                   else ("split", exit_, plus))
+
+    def _plus(self, sub, greedy):
+        body = len(self.prog)
+        self._c(sub)
+        sp = self.emit(("split", None, None))
+        exit_ = len(self.prog)
+        self.patch(sp, ("split", body, exit_) if greedy else ("split", exit_, body))
+
+    def _quest(self, sub, greedy):
+        sp = self.emit(("split", None, None))
+        body = len(self.prog)
+        self._c(sub)
+        exit_ = len(self.prog)
+        self.patch(sp, ("split", body, exit_) if greedy else ("split", exit_, body))
+
+    def _repeat(self, node):
+        lo, hi = node.lo, node.hi
+        for _ in range(lo):
+            self._c(node.sub)
+        if hi is None:
+            if lo == 0:
+                self._star(node.sub, node.greedy)
+            else:
+                self._star(node.sub, node.greedy)
+        else:
+            # (hi - lo) nested optionals: sub(sub(...)?)?  to preserve greedy
+            n_opt = hi - lo
+            self._nested_opt(node.sub, n_opt, node.greedy)
+
+    def _nested_opt(self, sub, k, greedy):
+        if k <= 0:
+            return
+        sp = self.emit(("split", None, None))
+        body = len(self.prog)
+        self._c(sub)
+        self._nested_opt(sub, k - 1, greedy)
+        exit_ = len(self.prog)
+        self.patch(sp, ("split", body, exit_) if greedy else ("split", exit_, body))
+
+
+def compile_ast(node, ngroups):
+    return _Compiler().compile(node, ngroups)