Module regex/parser

Regex pattern parser — parses a regex pattern string into an AST of RegexNode objects. Uses an iterative stack-based approach.

Internal to std/regex. Nothing here is public API: import std/regex and use Regex. This module's shape changes freely — the one piece of it users see is RegexError, which std/regex re-exports.

Why iterative

Nesting in a pattern is unbounded (((((a))))), and a recursive-descent parser turns that into unbounded native stack. parse keeps an explicit ArrayList(ParseFrame) instead: ( pushes the enclosing frame and starts a fresh one, ) pops and folds the finished group into its parent's current sequence. So pattern depth costs heap, not stack, and a deeply nested pattern from untrusted input cannot overflow.

Alternation is handled by the same frames rather than by precedence: | closes the current sequence into the frame's alternatives list and starts a new one, and the frame is folded into right-nested binary RegexNode.alternation nodes when it closes. That is why a|b|c becomes alternation(a, alternation(b, c)) and not a three-child node.

Positions are BYTE offsets into the pattern throughout — _pos indexes _bytes — and every RegexError reports one. Bytes outside ASCII are decoded as runes only where the grammar cares (literals, class members); the structural scan is byte-wise, which is safe because every metacharacter is ASCII and UTF-8 is self-synchronising.

Stability

unstable, and deliberately not public. Its output type (RegexNode) is internal and its input grammar is still growing — every construct added (inline (?i) flag groups, \Q...\E, atomic groups, named-class shorthands) changes both NodeKind and RegexError. RegexError is the one piece that escapes, and its own ## Stability section explains why an exhaustively-matched error enum cannot be frozen while the grammar moves.