Regex.pcode

/* This class is a port and enhancement of the ASF regex engine: https://github.com/ECP-Solutions/ASF/blob/main/src/ASF_RegexEngine.cls */
/* Original ASF source license: 

MIT License

Copyright (c) 2025 ECP Solutions

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.


*/
class Regex
   method Regex();
   property Hash LastNamedCaptures get;
   property boolean DEBUG_TRACE;
   
   /* Optional Parameters for Init */
   property string Pattern get;
   property boolean IgnoreCase;
   property number MaxSteps;
   property boolean Multiline;
   property boolean DotAll;
   property number SnapshotCount;
   property number SnapshotRestoreCount;
   property boolean EnableSurrogatePairs;
   property array of array of number CaptureRanges get;
   /* Public API */
   method Init(&pattern As string);
   method Split(&subj As string) Returns array of string;
   method SplitWithCaptures(&subj As string) Returns array of string;
   method Escape(&aInput As string) Returns string;
   method Replace(&subj As string, &replacement As string) Returns string;
   method Exec(&subj As string) Returns array of string;
   method ExecAt(&subj As string, &startPos As number) Returns array of string;
   /* Add to the Public API section of the class declaration */
   method ExecAll(&subj As string) Returns array of array of string;
   method ReplaceFirst(&subj As string, &replacement As string) Returns string;
   method Test(&subj As string) Returns boolean;
private
   /* Config */
   Constant &DEFAULT_MAX_STEPS = 200000;
   Constant &MAX_EXEC_TIME = 5;
   
   instance time &execStartTime;
   
   /* State */
   instance string &pPattern;
   instance boolean &pIgnoreCase;
   instance number &pMaxMatchSteps;
   instance Hash &pAST;
   instance number &pGroupCount;
   instance boolean &pMultiline;
   instance boolean &pDotAll;
   /* Current subject & captures */
   instance string &CurSubject;
   instance array of number &capsStart;
   instance array of number &capsEnd;
   instance array of boolean &atomicLocks;
   instance number &MatchSteps;
   instance Hash &pNamedCaptures;
   
   /* Core Infrastructure */
   method SafeMid(&aStr As string, &aStart As number, &aLength As number) Returns string;
   method newNode(&typ As string) Returns Hash;
   
   /* Parsing Helpers */
   method DetectUnsupportedCommentSyntax(&pat As string);
   method ParseEscapeChar(&ch As string) Returns string;
   method ParseEscapeNode(&ch As string) Returns Hash;
   method FindClassEnd(&pat As string, &startPos As number, &pEnd As number) Returns number;
   method FindGroupEnd(&pat As string, &startPos As number, &pEnd As number) Returns number;
   method ParseClass(&pat As string, &pStart As number, &pEnd As number) Returns Hash;
   method ParseClassFromSimple(&spec As string) Returns Hash;
   
   /* Parser Core */
   method ParseSequence(&pat As string, &p As number out, &pEnd As number, &groupCounter As number out, &stopAtPipeOrParen As boolean) Returns Hash;
   method ParseAlternation(&pat As string, &p As number out, &pEnd As number, &groupCounter As number out) Returns Hash;
   method CompilePattern(&pat As string) Returns Hash;
   
   /* AST Post Processing */
   method PropagateFlags(&node As any, &flags As string);
   rem method GetGroupCount(&ast As Hash) Returns number;
   method TraverseForGroups(&node As any, &maxIdx As number out);
   method CollectGroupNodesRecursive(&node As any, &outColl As array of array of any out);
   method BuildGroupNodesFromAST(&ast As Hash) Returns array of array of any;
   method ComputeMinLen(&node As Hash) Returns number;
   method ComputeMaxLen(&node As Hash) Returns number;
   method ComputeFixedWidth(&node As Hash) Returns number;
   method EnforceFixedWidthLookbehinds(&ast As Hash);
   method TraverseEnforce(&node As Hash);
   <* method AnnotateLookbehinds(&node As Hash); NOT IMPLEMENTED SINCE WIDTHS ARE SET DURING ENFORCE *>
   
   /* Match Engine Core */
   method MatchCharClassNode(&node As Hash, &ch As string) Returns boolean;
   method CopyCaps() Returns array of array of number;
   method RestoreCaps(&snapshot As array of array of number);
   method MatchNode(&node As Hash, &subj As string, &pos As number, &outEnd As number out) Returns boolean;
   method MatchSequence(&children As array of any, &subj As string, &pos As number, &outEnd As any out) Returns boolean;
   method MatchSeqFrom(&children As array of any, &subj As string, &pos As number, &childIdx As number, &outEnd As any out) Returns boolean;
   method FindGroupIndexByName(&ast As Hash, &name As string) Returns number;
   method FindGroupIndexByOrdinal(&ast As Hash, &ord As number) Returns number;
   method BuildCaptureCollection() Returns array of string;
   method ExpandReplacement(&caps As array of string, &repl As string, &namedColl As Hash) Returns string;
   method UpdateNamedCapturesFromAST();
   method EnsureGroupNodes(&ast As Hash) Returns array of array of any;
   /* Operations */
   method ReplaceInternal(&subj As string, &replacement As string, &allMatches As boolean) Returns string;
   
   /* Memoization */
   instance Hash &failCache;
   instance number &nodeIdCounter;
   method MarkMemoSafe(&node As any) Returns boolean;
   
   /* AST Optimization */
   instance boolean &optDeadNodeElim;
   instance boolean &optSingleChildElim;
   instance boolean &optQuantSimplify;
   instance boolean &optClassSimplify;
   instance boolean &optGroupFlatten;
   instance boolean &optLitConcat;
   instance boolean &optAltFactor;
   instance boolean &optAnchoredStart;
   instance boolean &optPrefixExtract;
   
   method OptimizeAST(&ast As Hash);
   method OptimizeNode(&node As Hash) Returns Hash;
   method GetLeadingChar(&node As Hash) Returns string;
   method StripLeadingChar(&node As Hash) Returns Hash;
   method FlushLitBuffer(&outArr As array of any out, &buf As string, &flags As string);
   
   
   /* Full unicode surrogate support */
   Constant &PUA_START = 57344; /* U+E000 */
   Constant &PUA_END = 63743; /* U+F8FF */
   Constant &HIGH_SURROGATE_START = 55296; /* U+D800 */
   Constant &HIGH_SURROGATE_END = 56319; /* U+DBFF */
   Constant &LOW_SURROGATE_START = 56320; /* U+DC00 */
   Constant &LOW_SURROGATE_END = 57343; /* U+DFFF */
   instance Hash &surrogateToPua;
   instance Hash &puaToSurrogate;
   instance number &nextPuaCode;
   method NormalizeString(&str As string) Returns string;
   method DenormalizeString(&str As string) Returns string;
   method DenormalizeArray(&arr As array of string) Returns array of string;
   
   method PrintAST(&astNode As any, &indent As string);
   method PrintASTCompact(&astNode As any) Returns string;
   method DebugTrace(&msg As string);
end-class;

get CaptureRanges
   /+ Returns Array2 of Number +/
   Local array of array of number &ranges = CreateArrayRept(CreateArrayRept(0, 0), 0);
   Local integer &x;
   
   If &capsStart [1] >= 1 And
         &capsEnd [1] >= &capsStart [1] Then
      &ranges.Push(CreateArray(&capsStart [1], &capsEnd [1]));
   Else
      If &ranges.Len = 0 Then
         &ranges.Push(CreateArray(0, 0));
      End-If;
   End-If;
   
   Local number &i;
   /* Weird here because we want groups 1..N but they are in array slots (1+1)..(N+1) */
   For &i = 2 To &pGroupCount + 1
      If &capsStart [&i] >= 1 And
            &capsEnd [&i] >= &capsStart [&i] Then
         &ranges.Push(CreateArray(&capsStart [&i], &capsEnd [&i]));
      Else
         /* push empty for the group that wasn't used */
         &ranges.Push(CreateArray(0, 0));
      End-If;
   End-For;
   
   Return &ranges;
end-get;

method Regex
   %This.IgnoreCase = False;
   %This.MaxSteps = &DEFAULT_MAX_STEPS;
   %This.Multiline = False;
   %This.DotAll = False;
   %This.DEBUG_TRACE = False;
   %This.EnableSurrogatePairs = True;
   
   /* optimizations */
   &optDeadNodeElim = True;
   &optSingleChildElim = True;
   &optQuantSimplify = True;
   &optClassSimplify = True;
   &optGroupFlatten = True;
   &optLitConcat = True;
   &optAltFactor = True;
   &optAnchoredStart = True;
   &optPrefixExtract = True;
   
end-method;

method Init
   /+ &pattern as String +/
   &pPattern = &pattern;
   &pIgnoreCase = %This.IgnoreCase;
   &pMultiline = %This.Multiline;
   &pDotAll = %This.DotAll;
   &nodeIdCounter = 0;
   
   If (%This.MaxSteps <= 0) Then
      &pMaxMatchSteps = &DEFAULT_MAX_STEPS;
   Else
      &pMaxMatchSteps = %This.MaxSteps;
   End-If;
   
   /* ── NEW: Initialize normalization state ── */
   &surrogateToPua = CreateHash();
   &puaToSurrogate = CreateHash();
   &nextPuaCode = &PUA_START;
   
   /* ── NEW: Normalize pattern if FullUnicodeSupport is on ── */
   Local string &compilePat = &pPattern;
   If %This.EnableSurrogatePairs Then
      &compilePat = %This.NormalizeString(&pPattern);
   End-If;
   
   &pAST = %This.CompilePattern(&compilePat);
   
   If (&pAST <> Null) Then
      If ( Not &pAST.Exists("groupNodes")) Then
         Local array of array of any &groupNodes = %This.BuildGroupNodesFromAST(&pAST);
      End-If;
   End-If;
   If &DEBUG_TRACE Then
      %Response.Write("<br />");
      %Response.Write("AST After Optimizations: <br />");
      rem %This.PrintAST(&pAST, "");
      %Response.Write(%This.PrintASTCompact(&pAST.GetValue("body", True)));
   End-If;
   %This.EnforceFixedWidthLookbehinds(&pAST);
   rem &pGroupCount = %This.GetGroupCount(&pAST);
   &pGroupCount = &pAST.GetValue("groupCount", True);
   
   rem %Response.WriteLine("GetGroupCount = " | &pGroupCount);
end-method;


get LastNamedCaptures
   /+ Returns Hash +/
   
   If %This.EnableSurrogatePairs Then
      Local string &k;
      Local array of string &v;
      
      &pNamedCaptures.IterStart();
      While &pNamedCaptures.IterNext(&k, &v)
         &v [2] = %This.DenormalizeString(&v [2]);
      End-While;
   End-If;
   
   
   Return &pNamedCaptures;
end-get;

get Pattern
   /+ Returns String +/
   Return &pPattern;
end-get;

/* Node helpers - We can probably optimize these out after the port. */
method newNode
   /+ &typ as String +/
   /+ Returns Hash +/
   Local Hash &h = CreateHash();
   &h.SetValue("type", &typ);
   &nodeIdCounter = &nodeIdCounter + 1;
   &h.SetValue("nodeId", &nodeIdCounter);
   Return &h;
end-method;

method CompilePattern
   /+ &pat as String +/
   /+ Returns Hash +/
   
   %This.DetectUnsupportedCommentSyntax(&pat);
   
   Local Hash &ast = CreateHash();
   &ast.SetValue("raw", &pat);
   
   Local number &pos = 1;
   Local number &groupCounter = 0;
   Local Hash &body = %This.ParseAlternation(&pat, &pos, Len(&pat), &groupCounter);
   
   &ast.SetValue("body", &body);
   
   If &DEBUG_TRACE Then
      %Response.Write("<br />");
      %Response.Write("Original AST: <br />");
      %This.PrintAST(&ast, "");
   End-If;
   
   If &DEBUG_TRACE Then
      %Response.Write("<br />");
      %Response.Write("AST Before Optimizations: <br />");
      rem %This.PrintAST(&pAST, "");
      %Response.Write(%This.PrintASTCompact(&ast.GetValue("body", True)));
   End-If;
   
   /* Store group count BEFORE optimization can eliminate group nodes */
   &ast.SetValue("groupCount", &groupCounter);
   
   %This.OptimizeAST(&ast);
   
   /* ── Ensure body is always a seq ──
      This guarantees quantifiers always route through 
      MatchSeqFrom which has proper cross-occurrence 
      backtracking, rather than MatchNode's simpler path. */
   &body = &ast.GetValue("body", True);
   If &body.GetValue("type", True) <> "seq" Then
      Local Hash &wrapSeq = %This.newNode("seq");
      Local array of any &wrapKids = CreateArrayAny();
      &wrapKids.Push(&body);
      &wrapSeq.SetValue("child", &wrapKids);
      &ast.SetValue("body", &wrapSeq);
   End-If;
   
   Local boolean &_ = %This.MarkMemoSafe(&ast.GetValue("body", True));
   
   Local number &mlen = %This.ComputeMinLen(&body);
   &ast.SetValue("minLen", &mlen);
   
   Return &ast;
end-method;


method ParseAlternation
   /+ &pat as String, +/
   /+ &p as Number out, +/
   /+ &pEnd as Number, +/
   /+ &groupCounter as Number out +/
   /+ Returns Hash +/
   Local Hash &firstSeq = %This.ParseSequence(&pat, &p, &pEnd, &groupCounter, False);
   If ( Not (&p <= &pEnd And
         %This.SafeMid(&pat, &p, 1) = "|")) Then
      Return &firstSeq;
   End-If;
   
   Local Hash &altNode = %This.newNode("alt");
   Local array of any &alts = CreateArrayAny();
   &alts.Push(&firstSeq);
   While &p <= &pEnd And
         %This.SafeMid(&pat, &p, 1) = "|"
      &p = &p + 1;
      Local Hash &nextSeq = %This.ParseSequence(&pat, &p, &pEnd, &groupCounter, False);
      &alts.Push(&nextSeq);
   End-While;
   
   &altNode.SetValue("child", &alts);
   Return &altNode;
end-method;


method ParseSequence
   /+ &pat as String, +/
   /+ &p as Number out, +/
   /+ &pEnd as Number, +/
   /+ &groupCounter as Number out, +/
   /+ &stopAtPipeOrParen as Boolean +/
   /+ Returns Hash +/
   Local Hash &seq = %This.newNode("seq");
   Local array of any &children = CreateArrayAny();
   Local number &thisIdx;
   Local string &ch;
   Local Hash &node;
   
   While &p <= &pEnd
      &ch = %This.SafeMid(&pat, &p, 1);
      If (&ch = ")" Or
            &ch = "|") Then
         Break;
      End-If;
      
      &node = Null;
      
      
      Evaluate &ch
      When = "\"
         &p = &p + 1;
         If &p > &pEnd Then
            Break;
         End-If;
         
         Local string &escCh = %This.SafeMid(&pat, &p, 1);
         Local number &escCode = Code(&escCh);
         
         /* ── Numeric backreference: \1 through \99 ── */
         If &escCode >= 49 And
               &escCode <= 57 Then
            /* Digit 1-9: collect all following digits */
            Local string &refDigits = &escCh;
            Local number &peekPos = &p + 1;
            While &peekPos <= &pEnd
               Local string &peekCh = %This.SafeMid(&pat, &peekPos, 1);
               Local number &peekCode = Code(&peekCh);
               If &peekCode >= 48 And
                     &peekCode <= 57 Then
                  &refDigits = &refDigits | &peekCh;
                  &peekPos = &peekPos + 1;
               Else
                  Break;
               End-If;
            End-While;
            
            /* Greedy two-digit resolution: if two+ digits collected,
               try the full number first. If only valid as smaller,
               we resolve at match time — store the largest number. 
               At match time, if the index exceeds group count, 
               fall back to first digit only. */
            Local number &refNum = Value(&refDigits);
            &node = %This.newNode("backref");
            &node.SetValue("idx", &refNum);
            /* Store raw digits so match-time can do fallback */
            &node.SetValue("raw", &refDigits);
            &p = &p + Len(&refDigits);
         Else
            If &escCh = "k" Then
               /* ── Named backreference: \k<name> or \k'name' ── */
               &p = &p + 1;
               If &p <= &pEnd Then
                  Local string &kDelim = %This.SafeMid(&pat, &p, 1);
                  Local string &kClose = "";
                  If &kDelim = "<" Then
                     &kClose = ">";
                  Else
                     If &kDelim = "'" Then
                        &kClose = "'";
                     Else
                        /* Not a valid \k sequence — treat \k as literal "k" */
                        &node = %This.newNode("lit");
                        &node.SetValue("ch", "k");
                        /* &p already advanced past 'k' */
                     End-If;
                  End-If;
                  
                  If &kClose <> "" And
                        Len(&kClose) > 0 Then
                     &p = &p + 1;
                     Local string &kName = "";
                     While &p <= &pEnd
                        Local string &kc = %This.SafeMid(&pat, &p, 1);
                        If &kc = &kClose Then
                           &p = &p + 1;
                           Break;
                        End-If;
                        &kName = &kName | &kc;
                        &p = &p + 1;
                     End-While;
                     
                     If Len(&kName) > 0 Then
                        &node = %This.newNode("backref");
                        &node.SetValue("name", &kName);
                     Else
                        /* Empty name — treat as literal */
                        &node = %This.newNode("lit");
                        &node.SetValue("ch", "k");
                     End-If;
                  End-If;
               Else
                  /* \k at end of pattern — literal */
                  &node = %This.newNode("lit");
                  &node.SetValue("ch", "k");
               End-If;
            Else
               /* ── All other escapes: delegate to existing handler ── */
               &node = %This.ParseEscapeNode(&escCh);
               &p = &p + 1;
            End-If;
         End-If;
         Break;
      When = "."
         &node = %This.newNode("dot");
         &p = &p + 1;
         Break;
      When = "["
         Local number &clsEnd = %This.FindClassEnd(&pat, &p, &pEnd);
         If &clsEnd = - 1 Then
            &node = %This.newNode("lit");
            &node.SetValue("ch", "[");
            &p = &p + 1;
         Else
            &node = %This.ParseClass(&pat, &p + 1, &clsEnd - 1);
            &p = &clsEnd + 1;
         End-If;
         Break;
      When = "^"
         &node = %This.newNode("anchor_start");
         &p = &p + 1;
         Break;
      When = "$"
         &node = %This.newNode("anchor_end");
         &p = &p + 1;
         Break;
      When = "("
         /* Locate matching ')' deterministically */
         Local number &foundClose = %This.FindGroupEnd(&pat, &p, &pEnd);
         If (&foundClose = - 1) Then
            &node = %This.newNode("lit");
            &node.SetValue("ch", "(");
            &p = &p + 1;
         Else
            /* Consume '(' */
            &p = &p + 1;
            
            If (&p <= &pEnd) And
                  %This.SafeMid(&pat, &p, 1) = "?" Then
               &p = &p + 1;
               
               /* Support for (?P<name> named groups */
               If (&p + 1 <= &pEnd And
                     %This.SafeMid(&pat, &p, 1) = "P" And
                     %This.SafeMid(&pat, &p + 1, 1) = "<") Then
                  &p = &p + 1;
               End-If;
               
               If (&p > &pEnd) Then
                  &node = %This.newNode("lit");
                  &node.SetValue("ch", "(");
               Else
                  Local string &nextCh = %This.SafeMid(&pat, &p, 1);
                  Evaluate &nextCh
                  When "="
                     &p = &p + 1;
                     Local Hash &innerLA = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                     If (&p <= &pEnd And
                           %This.SafeMid(&pat, &p, 1) = ")") Then
                        &p = &p + 1;
                     End-If;
                     Local Hash &laNode = %This.newNode("lookahead_pos");
                     &laNode.SetValue("child", &innerLA);
                     &node = &laNode;
                     Break;
                  When "!"
                     &p = &p + 1;
                     Local Hash &innerNL = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                     If (&p <= &pEnd And
                           %This.SafeMid(&pat, &p, 1) = ")") Then
                        &p = &p + 1;
                     End-If;
                     Local Hash &nlaNode = %This.newNode("lookahead_neg");
                     &nlaNode.SetValue("child", &innerNL);
                     &node = &nlaNode;
                     Break;
                  When "<"
                     &p = &p + 1;
                     If &p <= &pEnd Then
                        Local string &sbch = %This.SafeMid(&pat, &p, 1);
                        Evaluate &sbch
                        When = "="
                           &p = &p + 1;
                           Local Hash &innerLB = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                           If (&p < &pEnd And
                                 %This.SafeMid(&pat, &p, 1) = ")") Then
                              &p = &p + 1;
                           End-If;
                           Local Hash &lbNode = %This.newNode("lookbehind_pos");
                           &lbNode.SetValue("child", &innerLB);
                           &node = &lbNode;
                           Break;
                        When = "!"
                           &p = &p + 1;
                           Local Hash &innerLBN = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                           If (&p < &pEnd And
                                 %This.SafeMid(&pat, &p, 1) = ")") Then
                              &p = &p + 1;
                           End-If;
                           Local Hash &lbnNode = %This.newNode("lookbehind_neg");
                           &lbnNode.SetValue("child", &innerLBN);
                           &node = &lbnNode;
                           Break;
                        When-Other
                           /* Named capture form (?<name>...) */
                           Local string &nameBuf = "";
                           While &p <= &pEnd
                              Local string &nc = %This.SafeMid(&pat, &p, 1);
                              Local number &ncC = Code(&nc);
                              If (&nc = ">") Then
                                 Break;
                              End-If;
                              /* First char: a-z A-Z _ only (no digits) */
                              If Len(&nameBuf) = 0 Then
                                 If (&ncC >= 97 And
                                       &ncC <= 122) Or
                                       (&ncC >= 65 And
                                          &ncC <= 90) Or
                                       (&ncC = 95) Then
                                    &nameBuf = &nameBuf | &nc;
                                    &p = &p + 1;
                                 Else
                                    Break;
                                 End-If;
                              Else
                                 /* Subsequent chars: a-z A-Z 0-9 _ - */
                                 If (&ncC >= 97 And
                                       &ncC <= 122) Or
                                       (&ncC >= 65 And
                                          &ncC <= 90) Or
                                       (&ncC >= 48 And
                                          &ncC <= 57) Or
                                       (&ncC = 95) Or
                                       (&ncC = 45) Then
                                    &nameBuf = &nameBuf | &nc;
                                    &p = &p + 1;
                                 Else
                                    Break;
                                 End-If;
                              End-If;
                           End-While;
                           
                           If &p < &pEnd And
                                 %This.SafeMid(&pat, &p, 1) = ">" And
                                 Len(&nameBuf) > 0 Then
                              &p = &p + 1;
                              &groupCounter = &groupCounter + 1;
                              &thisIdx = &groupCounter;
                              Local Hash &innerNamed = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                              If (&p <= &pEnd And
                                    %This.SafeMid(&pat, &p, 1) = ")") Then
                                 &p = &p + 1;
                              End-If;
                              Local Hash &gnodeNamed = %This.newNode("group");
                              &gnodeNamed.SetValue("idx", &thisIdx);
                              &gnodeNamed.SetValue("child", &innerNamed);
                              &gnodeNamed.SetValue("name", &nameBuf);
                              &node = &gnodeNamed;
                              If &DEBUG_TRACE Then
                                 MessageBox(0, "", 0, 0, "TRACE PARSE named-group -> name=" | &nameBuf | " idx=" | &thisIdx);
                              End-If;
                           Else
                              &node = %This.newNode("lit");
                              &node.SetValue("ch", "(");
                           End-If;
                           
                           Break;
                        End-Evaluate;
                     Else
                        &node = %This.newNode("lit");
                        &node.SetValue("ch", "(");
                     End-If;
                     Break;
                  When ">"
                     &p = &p + 1;
                     Local Hash &innerAtomic = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                     If (&p <= &pEnd And
                           %This.SafeMid(&pat, &p, 1) = ")") Then
                        &p = &p + 1;
                     End-If;
                     Local Hash &atomicNode = %This.newNode("atomic");
                     &atomicNode.SetValue("child", &innerAtomic);
                     &node = &atomicNode;
                     Break;
                  When ":"
                     &p = &p + 1;
                     Local Hash &innerNC = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                     If (&p <= &pEnd And
                           %This.SafeMid(&pat, &p, 1) = ")") Then
                        &p = &p + 1;
                     End-If;
                     Local Hash &ncNode = %This.newNode("group");
                     &ncNode.SetValue("child", &innerNC);
                     &ncNode.SetValue("noncap_syntax", True);
                     &node = &ncNode;
                     Break;
                  When "R"
                     &p = &p + 1;
                     If (&p <= &pEnd And
                           %This.SafeMid(&pat, &p, 1) = ")") Then
                        &p = &p + 1;
                     End-If;
                     Local Hash &rnode = %This.newNode("recurse");
                     &rnode.SetValue("target", 0);
                     &node = &rnode;
                     Break;
                  When "("
                     &p = &p + 1;
                     Local number &condStart = &p;
                     Local number &condEnd = - 1;
                     While &p <= &pEnd
                        If %This.SafeMid(&pat, &p, 1) = ")" Then
                           &condEnd = &p - 1;
                           Break;
                        End-If;
                        &p = &p + 1;
                     End-While;
                     
                     If &condEnd = - 1 Then
                        &node = %This.newNode("lit");
                        &node.SetValue("ch", "(");
                     Else
                        Local string &condText = Substring(&pat, &condStart, &condEnd - &condStart + 1);
                        &p = &p + 1;
                        Local Hash &yesNode = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, True);
                        Local Hash &noNode = Null;
                        If (&p <= &pEnd And
                              %This.SafeMid(&pat, &p, 1) = "|") Then
                           &p = &p + 1;
                           &noNode = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, True);
                        End-If;
                        
                        If &foundClose <= &pEnd Then
                           &p = &foundClose + 1;
                        End-If;
                        
                        Local Hash &condNode = %This.newNode("cond");
                        &condNode.SetValue("cond", &condText);
                        &condNode.SetValue("yes", &yesNode);
                        If (&noNode <> Null) Then
                           &condNode.SetValue("no", &noNode);
                        End-If;
                        &node = &condNode;
                     End-If;
                     
                     Break;
                  When-Other
                     /* recursion by number or inline flags */
                     /* Char is >= "0" and <= "9" */
                     If (Code(%This.SafeMid(&pat, &p, 1)) >= 48 And
                           Code(%This.SafeMid(&pat, &p, 1)) <= 57) Then
                        Local string &ds = "";
                        While &p <= &pEnd
                           Local string &dc = %This.SafeMid(&pat, &p, 1);
                           If (Code(&dc) >= 48 And
                                 Code(&dc) <= 57) Then
                              &ds = &ds | &dc;
                              &p = &p + 1;
                           Else
                              Break;
                           End-If;
                        End-While;
                        If (&p <= &pEnd And
                              %This.SafeMid(&pat, &p, 1) = ")") Then
                           &p = &p + 1;
                        End-If;
                        Local Hash &rn = %This.newNode("recurse");
                        &rn.SetValue("target", Value(&ds));
                        &node = &rn;
                     Else
                        Local string &flagsStr = "";
                        While &p <= &pEnd
                           Local string &fch = %This.SafeMid(&pat, &p, 1);
                           Local number &fchC = Code(&fch);
                           /* a-z A-Z - */
                           If (&fchC >= 97 And
                                 &fchC <= 122) Or
                                 (&fchC >= 65 And
                                    &fchC <= 90) Or
                                 (&fchC = 45) Then
                              &flagsStr = &flagsStr | &fch;
                              &p = &p + 1;
                           Else
                              Break;
                           End-If;
                        End-While;
                        If (&p <= &pEnd And
                              %This.SafeMid(&pat, &p, 1) = ":") Then
                           &p = &p + 1;
                           Local Hash &innerFlagged = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
                           If (&p <= &pEnd And
                                 %This.SafeMid(&pat, &p, 1) = ")") Then
                              &p = &p + 1;
                           End-If;
                           Local Hash &gnodeF = %This.newNode("group");
                           &gnodeF.SetValue("noncap_syntax", True);
                           Local string &normFlags = "";
                           Local number &kch;
                           For &kch = 1 To Len(&flagsStr);
                              Local string &fc = Lower(Substring(&flagsStr, &kch, 1));
                              If (&fc = "i" Or
                                    &fc = "m" Or
                                    &fc = "s" Or
                                    &fc = "-") Then
                                 &normFlags = &normFlags | &fc;
                              End-If;
                           End-For;
                           If (Len(&normFlags) > 0) Then
                              &gnodeF.SetValue("flags_on", &normFlags);
                              %This.PropagateFlags(&innerFlagged, &normFlags);
                           End-If;
                           &gnodeF.SetValue("child", &innerFlagged);
                           &node = &gnodeF;
                        Else
                           throw CreateException(0, 0, "Inline flags without ':' are not supported at compile time (use (?i:...) for group-scoped flags).");
                        End-If;
                     End-If;
                     
                     Break;
                  End-Evaluate;
               End-If;
            Else
               /* normal capturing group */
               &groupCounter = &groupCounter + 1;
               &thisIdx = &groupCounter;
               Local Hash &inner = %This.ParseSequence(&pat, &p, &foundClose - 1, &groupCounter, False);
               If (&p <= &pEnd And
                     %This.SafeMid(&pat, &p, 1) = ")") Then
                  &p = &p + 1;
               End-If;
               Local Hash &gnode = %This.newNode("group");
               &gnode.SetValue("idx", &thisIdx);
               &gnode.SetValue("child", &inner);
               &node = &gnode;
            End-If;
            
            /* defensive: if inner parsing didn't advance to foundClose, jump past it */
            If (&foundClose <> - 1) Then
               If (&p <= &foundClose And
                     %This.SafeMid(&pat, &p, 1) <> ")") Then
                  &p = &foundClose + 1;
               End-If;
            End-If;
            
         End-If;
         Break;
      When-Other
         &node = %This.newNode("lit");
         &node.SetValue("ch", &ch);
         &p = &p + 1;
         Break;
      End-Evaluate;
      
      /* quantifier (same semantics as original) */
      If (&node <> Null And
            &p <= &pEnd) Then
         Local string &qch = %This.SafeMid(&pat, &p, 1);
         If (&qch = "*" Or
               &qch = "+" Or
               &qch = "?" Or
               &qch = "{") Then
            Local Hash &qnode = %This.newNode("quant");
            &qnode.SetValue("child", &node);
            &qnode.SetValue("possessive", False);
            Evaluate &qch
            When = "*"
               &qnode.SetValue("min", 0);
               &qnode.SetValue("max", - 1);
               &p = &p + 1;
               Break;
            When = "+"
               &qnode.SetValue("min", 1);
               &qnode.SetValue("max", - 1);
               &p = &p + 1;
               Break;
            When = "?"
               &qnode.SetValue("min", 0);
               &qnode.SetValue("max", 1);
               &p = &p + 1;
               Break;
            When = "{"
               Local number &closePos = Find("}", &pat, &p);
               If (&closePos > 0) Then
                  Local string &content = %This.SafeMid(&pat, &p + 1, &closePos - &p - 1);
                  Local array of string &parts = Split(&content, ",");
                  Local number &mi, &ma;
                  If (&parts.Len = 1) Then
                     If (Len(RTrim(LTrim(&parts [1]))) = 0) Then
                        &mi = 0;
                        &ma = - 1;
                     Else
                        &mi = Value(RTrim(LTrim(&parts [1])));
                        
                        /* {1,} produces only 1 element in the split, so we need to see if the , was at the end */
                        If (Right(RTrim(&content), 1) = ",") Then
                           &ma = - 1; /* Unbounded max */
                        Else
                           &ma = &mi;
                        End-If;
                        
                     End-If;
                  Else
                     
                     &mi = Value(RTrim(LTrim(&parts [1])));
                     &ma = Value(RTrim(LTrim(&parts [2])));
                  End-If;
                  &qnode.SetValue("min", &mi);
                  &qnode.SetValue("max", &ma);
                  &p = &closePos + 1;
               Else
                  &qnode.SetValue("min", 0);
                  &qnode.SetValue("max", 1);
                  &p = &p + 1;
               End-If;
               Break;
            End-Evaluate;
            
            If (&p <= &pEnd) Then
               Local string &nextQ = %This.SafeMid(&pat, &p, 1);
               Evaluate &nextQ
               When = "?"
                  &qnode.SetValue("lazy", True);
                  &p = &p + 1;
                  Break;
               When = "+"
                  &qnode.SetValue("possessive", True);
                  &qnode.SetValue("lazy", False);
                  &p = &p + 1;
                  Break;
               When-Other
                  &qnode.SetValue("lazy", False);
                  Break;
               End-Evaluate;
            Else
               &qnode.SetValue("lazy", False);
            End-If;
            &node = &qnode;
         End-If;
      End-If;
      If &node <> Null Then
         &children.Push(&node);
      End-If;
   End-While;
   
   &seq.SetValue("child", &children);
   
   If Not &stopAtPipeOrParen Then
      If (&p < &pEnd And
            %This.SafeMid(&pat, &p, 1) = "|") Then
         Local Hash &altNode = %This.newNode("alt");
         Local array of any &alts = CreateArrayAny();
         &alts.Push(&seq);
         While &p <= &pEnd And
               %This.SafeMid(&pat, &p, 1) = "|"
            &p = &p + 1;
            Local Hash &nextSeq = %This.ParseSequence(&pat, &p, &pEnd, &groupCounter, False);
            &alts.Push(&nextSeq);
         End-While;
         
         &altNode.SetValue("child", &alts);
         Return &altNode;
      End-If;
   End-If;
   
   
   Return &seq;
end-method;

method SafeMid
   /+ &aStr as String, +/
   /+ &aStart as Number, +/
   /+ &aLength as Number +/
   /+ Returns String +/
   If (&aLength = - 1) Then
      &aLength = Len(&aStr) - &aStart + 1;
   End-If;
   
   If (&aStart >= 1) Then
      Local string &ch = Substring(&aStr, &aStart, &aLength);
      Return &ch;
   Else
      Return "";
   End-If;
end-method;

method DetectUnsupportedCommentSyntax
   /+ &pat as String +/
   Local number &i;
   Local number &L = Len(&pat);
   Local boolean &esc = False;
   Local boolean &inClass = False;
   
   For &i = 1 To &L
      Local string &c = Substring(&pat, &i, 1);
      If (&esc) Then
         &esc = False;
         Continue;
      End-If;
      
      If (&c = "\") Then
         &esc = True;
         Continue;
      End-If;
      
      If (&inClass) Then
         If &c = "]" Then
            &inClass = False;
         End-If;
         Continue;
      Else
         If &c = "[" Then
            &inClass = True;
            Continue;
         End-If;
      End-If;
      
      If (&c = "(") Then
         If (&i + 2 <= &L) Then
            If (Substring(&pat, &i + 1, 2) = "?#") Then
               throw CreateException(0, 0, "(?# comments are not supported");
            End-If;
         End-If;
      End-If;
   End-For;
end-method;

method EnforceFixedWidthLookbehinds
   /+ &ast as Hash +/
   %This.TraverseEnforce(&ast.GetValue("body", True));
end-method;

method TraverseEnforce
   /+ &node as Hash +/
   Local number &i;
   Local array of any &children;
   Local string &type = &node.GetValue("type", True);
   Evaluate &type
   When = "seq"
      &children = &node.GetValue("child", True);
      
      For &i = 1 To &children.Len
         Local any &ch = &children [&i];
         %This.TraverseEnforce(&ch);
      End-For;
      Break;
   When = "group"
   When = "atomic"
   When = "quant"
      %This.TraverseEnforce(&node.GetValue("child", True));
      Break;
   When = "alt"
      &children = &node.GetValue("child", True);
      For &i = 1 To &children.Len
         Local any &altCh = &children [&i];
         %This.TraverseEnforce(&altCh);
      End-For;
      Break;
   When = "lookbehind_pos"
   When = "lookbehind_neg"
      Local Hash &child = &node.GetValue("child", True);
      Local number &w = %This.ComputeFixedWidth(&child);
      &node.SetValue("width", &w);
      If (&w = - 1) Then
         throw CreateException(0, 0, "Variable-length lookbehind not supported");
      End-If;
      Break;
   End-Evaluate;
end-method;

method ComputeMaxLen
   /+ &node as Hash +/
   /+ Returns Number +/
   
   Local string &t = &node.GetValue("type", True);
   Local array of any &children;
   Local any &ch;
   Local integer &i;
   Evaluate &t
   When = "lit"
   When = "dot"
   When = "class"
      Return 1;
   When = "str"
      Return Len(&node.GetValue("val", True));
   When = "seq"
      Local number &SUM = 0;
      &children = &node.GetValue("child", True);
      
      For &i = 1 To &children.Len
         &ch = &children [&i];
         Local number &m = %This.ComputeMaxLen(&ch);
         If (&m = - 1) Then
            Return - 1;
         End-If;
         &SUM = &SUM + &m;
      End-For;
      
      Return &SUM;
   When = "alt"
      Local number &mx = 0;
      &children = &node.GetValue("child", True);
      
      For &i = 1 To &children.Len
         &ch = &children [&i];
         Local number &vm = %This.ComputeMaxLen(&ch);
         If (&vm = - 1) Then
            Return - 1;
         Else
            If (&vm > &mx) Then
               &mx = &vm;
            End-If;
         End-If;
      End-For;
      Return &mx;
      
   When = "quant"
      Local number &mxChild = %This.ComputeMaxLen(&node.GetValue("child", True));
      If (&mxChild = - 1) Then
         If (&node.GetValue("max", True) = - 1) Then
            Return - 1;
         Else
            /* child unbounded but quant bounded by explicit max */
         End-If;
      End-If;
      
      Local number &qmax = &node.GetValue("max", True);
      If (&qmax = - 1) Then
         If &mxChild = - 1 Then
            Return - 1;
         Else
            Return - 1;
         End-If;
      Else
         If &mxChild = - 1 Then
            Return - 1;
         Else
            Return &qmax * &mxChild;
         End-If;
      End-If;
      
      Break;
   When = "group"
   When = "atomic"
   When = "lookahead_pos"
   When = "lookahead_neg"
   When = "lookbehind_pos"
   When = "lookbehind_neg"
      Return %This.ComputeMaxLen(&node.GetValue("child", True));
   When = "backref"
      Return - 1;
   When-Other
      Return - 1;
   End-Evaluate;
   
end-method;

method ComputeMinLen
   /+ &node as Hash +/
   /+ Returns Number +/
   Local integer &i;
   Local array of any &children;
   Local string &type = &node.GetValue("type", True);
   Evaluate &type
   When = "lit"
   When = "dot"
   When = "class"
      Return 1;
   When = "str"
      Return Len(&node.GetValue("val", True));
   When = "seq"
      Local number &SUM = 0;
      &children = &node.GetValue("child", True);
      
      For &i = 1 To &children.Len
         Local any &ch = &children [&i];
         &SUM = &SUM + %This.ComputeMinLen(&ch);
      End-For;
      Return &SUM;
   When = "group"
   When = "atomic"
      Return %This.ComputeMinLen(&node.GetValue("child", True));
   When = "quant"
      Local number &mn = &node.GetValue("min", True);
      If (&mn < 0) Then
         &mn = 0;
      End-If;
      Return &mn * %This.ComputeMinLen(&node.GetValue("child", True));
   When = "alt"
      Local number &minv = - 1;
      
      &children = &node.GetValue("child", True);
      For &i = 1 To &children.Len
         Local Hash &chAlt = &children [&i];
         Local number &vAlt = %This.ComputeMinLen(&chAlt);
         If (&minv = - 1 Or
               &vAlt < &minv) Then
            &minv = &vAlt;
         End-If;
      End-For;
      If (&minv = - 1) Then
         &minv = 0;
      End-If;
      Return &minv;
   When = "anchor_start"
   When = "anchor_end"
   When = "anchor_start_abs"
   When = "anchor_end_abs"
   When = "anchor_end_abs_strict"
   When = "word_boundary"
   When = "word_boundary_neg"
      Return 0;
   When = "backref"
      Return 0;
   When-Other
      Return 0;
   End-Evaluate;
   
end-method;

method ParseEscapeNode
   /+ &ch as String +/
   /+ Returns Hash +/
   Local Hash &node;
   Evaluate &ch
   When = "a"
   When = "e"
      &node = %This.newNode("lit");
      &node.SetValue("ch", Char(7));
      Break;
   When = "f"
      &node = %This.newNode("lit");
      &node.SetValue("ch", Char(12));
      Break;
   When = "v"
      &node = %This.newNode("lit");
      &node.SetValue("ch", Char(11));
      Break;
   When = "\"
      &node = %This.newNode("lit");
      &node.SetValue("ch", "\");
      Break;
   When = "d"
      &node = %This.ParseClassFromSimple("[0-9]");
      Break;
   When = "D"
      &node = %This.ParseClassFromSimple("[0-9]");
      &node.SetValue("neg", True);
      Break;
   When = "w"
      &node = %This.ParseClassFromSimple("[A-Za-z0-9_]");
      Break;
   When = "W"
      &node = %This.ParseClassFromSimple("[A-Za-z0-9_]");
      &node.SetValue("neg", True);
      Break;
   When = "s"
      /* Not including Char(11) - Not supported by RE2 */
      &node = %This.ParseClassFromSimple("[ " | Char(9) | Char(10) | Char(12) | Char(13) | "]");
      Break;
   When = "S"
      /* Not including Char(11) - Not supported by RE2 */
      &node = %This.ParseClassFromSimple("[ " | Char(9) | Char(10) | Char(12) | Char(13) | "]");
      &node.SetValue("neg", True);
      Break;
   When = "n"
      &node = %This.newNode("lit");
      &node.SetValue("ch", Char(10));
      Break;
   When = "r"
      &node = %This.newNode("lit");
      &node.SetValue("ch", Char(13));
      Break;
   When = "t"
      &node = %This.newNode("lit");
      &node.SetValue("ch", Char(9));
      Break;
   When = "C"
      &node = %This.newNode("dot");
      &node.SetValue("flags_on", "s");
      Break;
   When = "A"
      &node = %This.newNode("anchor_start_abs");
      Break;
   When = "Z"
      &node = %This.newNode("anchor_end_abs");
      Break;
   When = "z"
      &node = %This.newNode("anchor_end_abs_strict");
      Break;
   When = "b"
      &node = %This.newNode("word_boundary");
      Break;
   When = "B"
      &node = %This.newNode("word_boundary_neg");
      Break;
   When-Other
      &node = %This.newNode("lit");
      &node.SetValue("ch", &ch);
   End-Evaluate;
   
   Return &node;
end-method;

method FindClassEnd
   /+ &pat as String, +/
   /+ &startPos as Number, +/
   /+ &pEnd as Number +/
   /+ Returns Number +/
   Local number &pos = &startPos;
   Local boolean &escaped = False;
   Local string &ch;
   &pos = &pos + 1;
   Local number &squareDepth;
   /* A ']' immediately after '[' or '[^' is a literal, skip it */
   If &pos <= &pEnd And
         %This.SafeMid(&pat, &pos, 1) = "^" Then
      &pos = &pos + 1;
   End-If;
   If &pos <= &pEnd And
         %This.SafeMid(&pat, &pos, 1) = "]" Then
      &pos = &pos + 1;
   End-If;
   
   While &pos <= &pEnd
      &ch = %This.SafeMid(&pat, &pos, 1);
      If (&escaped) Then
         &escaped = False;
         &pos = &pos + 1;
         Continue;
      End-If;
      If (&ch = "[") Then
         &squareDepth = &squareDepth + 1;
         &pos = &pos + 1;
         Continue;
      End-If;
      If (&ch = "\") Then
         &escaped = True;
         &pos = &pos + 1;
         Continue;
      End-If;
      If (&ch = "]") Then
         If (&squareDepth > 0) Then
            &squareDepth = &squareDepth - 1;
         Else
            Return &pos
         End-If;
      End-If;
      &pos = &pos + 1;
   End-While;
   Return - 1;
end-method;

method FindGroupEnd
   /+ &pat as String, +/
   /+ &startPos as Number, +/
   /+ &pEnd as Number +/
   /+ Returns Number +/
   Local number &pos = &startPos;
   Local number &depth = 0;
   Local boolean &inClass = False;
   Local boolean &escaped = False;
   Local string &ch;
   &pos = &pos + 1;
   While &pos <= &pEnd
      &ch = %This.SafeMid(&pat, &pos, 1);
      If (&escaped) Then
         &escaped = False;
         &pos = &pos + 1;
         Continue;
      End-If;
      
      If (&ch = "\") Then
         &escaped = True;
         &pos = &pos + 1;
         Continue;
      End-If;
      
      If (&inClass) Then
         If &ch = "]" Then
            &inClass = False;
         End-If;
         &pos = &pos + 1;
         Continue;
      End-If;
      
      If &ch = "[" Then
         &inClass = True;
         &pos = &pos + 1;
         Continue;
      End-If;
      
      If (&ch = "(") Then
         &depth = &depth + 1;
         &pos = &pos + 1;
         Continue;
      End-If;
      
      If (&ch = ")") Then
         If (&depth = 0) Then
            Return &pos;
         Else
            &depth = &depth - 1;
            &pos = &pos + 1;
            Continue;
         End-If;
      End-If;
      &pos = &pos + 1;
      
   End-While;
   Return - 1;
end-method;

method ParseClass
   /+ &pat as String, +/
   /+ &pStart as Number, +/
   /+ &pEnd as Number +/
   /+ Returns Hash +/
   
   Local Hash &node = %This.newNode("class");
   Local array of array of string &Chars = CreateArrayRept(CreateArrayRept("", 0), 0);
   Local array of array of boolean &mergeBitmaps = CreateArrayRept(CreateArrayRept( False, 0), 0);
   Local boolean &neg = False;
   Local number &i = &pStart;
   Local boolean &matchNonAscii = False;
   
   If (&i <= &pEnd And
         %This.SafeMid(&pat, &i, 1) = "^") Then
      &neg = True;
      &i = &i + 1;
   End-If;
   
   If (&i <= &pEnd And
         %This.SafeMid(&pat, &i, 1) = "^") Then
      &neg = True;
      &i = &i + 1;
   End-If;
   
   /* A ']' at the very start of the class is a literal */
   If (&i <= &pEnd And
         %This.SafeMid(&pat, &i, 1) = "]") Then
      &Chars.Push(CreateArray("]"));
      &i = &i + 1;
   End-If;
   
   While &i <= &pEnd
      Local string &ch = %This.SafeMid(&pat, &i, 1);
      
      /* ── POSIX character class [:name:] ── */
      If &ch = "[" And
            &i + 1 <= &pEnd And
            %This.SafeMid(&pat, &i + 1, 1) = ":" Then
         /* Read the name */
         Local number &nameStart = &i + 2;
         Local number &nameEnd = 0;
         Local number &scan = &nameStart;
         While &scan + 1 <= &pEnd
            If %This.SafeMid(&pat, &scan, 1) = ":" And
                  %This.SafeMid(&pat, &scan + 1, 1) = "]" Then
               &nameEnd = &scan - 1;
               Break;
            End-If;
            &scan = &scan + 1;
         End-While;
         
         If &nameEnd >= &nameStart Then
            Local string &posixName = %This.SafeMid(&pat, &nameStart, &nameEnd - &nameStart + 1);
            Evaluate Lower(&posixName)
            When = "alnum"
               
               &Chars.Push(CreateArray("range", "A", "Z"));
               &Chars.Push(CreateArray("range", "a", "z"));
               &Chars.Push(CreateArray("range", "0", "9"));
               Break;
            When = "alpha"
               &Chars.Push(CreateArray("range", "A", "Z"));
               &Chars.Push(CreateArray("range", "a", "z"));
               Break;
            When = "blank"
               &Chars.Push(CreateArray(" "));
               &Chars.Push(CreateArray(Char(9)));
               Break;
            When = "cntrl"
               &Chars.Push(CreateArray("range", Char(0), Char(31)));
               &Chars.Push(CreateArray(Char(127)));
               Break;
            When = "digit"
               &Chars.Push(CreateArray("range", "0", "9"));
               Break;
            When = "graph"
               &Chars.Push(CreateArray("range", Char(33), Char(126)));
               Break;
            When = "lower"
               &Chars.Push(CreateArray("range", "a", "z"));
               Break;
            When = "print"
               &Chars.Push(CreateArray("range", Char(32), Char(126)));
               Break;
            When = "punct"
               &Chars.Push(CreateArray("range", Char(33), Char(47)));
               &Chars.Push(CreateArray("range", Char(58), Char(64)));
               &Chars.Push(CreateArray("range", Char(91), Char(96)));
               &Chars.Push(CreateArray("range", Char(123), Char(126)));
               Break;
            When = "space"
               &Chars.Push(CreateArray(" "));
               &Chars.Push(CreateArray(Char(9)));
               &Chars.Push(CreateArray(Char(10)));
               &Chars.Push(CreateArray(Char(11)));
               &Chars.Push(CreateArray(Char(12)));
               &Chars.Push(CreateArray(Char(13)));
               Break;
            When = "upper"
               &Chars.Push(CreateArray("range", "A", "Z"));
               Break;
            When = "xdigit"
               &Chars.Push(CreateArray("range", "0", "9"));
               &Chars.Push(CreateArray("range", "A", "F"));
               &Chars.Push(CreateArray("range", "a", "f"));
               Break;
            When-Other
               throw CreateException(0, 0, "Unknown POSIX class [:" | &posixName | ":]");
            End-Evaluate;
            
            &i = &nameEnd + 3; /* skip past :] */
         Else
            /* Malformed — treat [ as literal */
            &Chars.Push(CreateArray(&ch));
            &i = &i + 1;
         End-If;
      Else
         
         
         If (&ch = "\") Then
            &i = &i + 1;
            If &i <= &pEnd Then
               Local string &esc = %This.SafeMid(&pat, &i, 1);
               Evaluate &esc
               When = "d"
                  &Chars.Push(CreateArray("range", "0", "9"));
                  Break;
               When = "D"
                  &matchNonAscii = True;
                  Local array of boolean &dMap = CreateArrayRept( False, 256);
                  Local number &dc;
                  For &dc = Code("0") To Code("9")
                     &dMap [&dc + 1] = True;
                  End-For;
                  /* Negate */
                  For &dc = 1 To 256
                     &dMap [&dc] = ( Not &dMap [&dc]);
                  End-For;
                  &mergeBitmaps.Push(&dMap);
                  Break;
               When = "w"
                  &Chars.Push(CreateArray("range", "a", "z"));
                  &Chars.Push(CreateArray("range", "A", "Z"));
                  &Chars.Push(CreateArray("range", "0", "9"));
                  &Chars.Push("_");
                  Break;
               When = "W"
                  &matchNonAscii = True;
                  Local array of boolean &wMap = CreateArrayRept( False, 256);
                  Local number &wc;
                  For &wc = Code("a") To Code("z")
                     &wMap [&wc + 1] = True;
                  End-For;
                  For &wc = Code("A") To Code("Z")
                     &wMap [&wc + 1] = True;
                  End-For;
                  For &wc = Code("0") To Code("9")
                     &wMap [&wc + 1] = True;
                  End-For;
                  &wMap [Code("_") + 1] = True;
                  /* Negate */
                  For &wc = 1 To 256
                     &wMap [&wc] = ( Not &wMap [&wc]);
                  End-For;
                  &mergeBitmaps.Push(&wMap);
                  Break;
               When = "s"
                  &Chars.Push(CreateArray(" "));
                  &Chars.Push(CreateArray(Char(9)));
                  &Chars.Push(CreateArray(Char(10)));
                  rem /* Not supported by RE2 */ &Chars.Push(CreateArray(Char(11)));
                  &Chars.Push(CreateArray(Char(12)));
                  &Chars.Push(CreateArray(Char(13)));
                  Break;
               When = "S"
                  &matchNonAscii = True;
                  Local array of boolean &sMap = CreateArrayRept( False, 256);
                  &sMap [Code(" ") + 1] = True;
                  &sMap [Code(Char(9)) + 1] = True;
                  &sMap [Code(Char(10)) + 1] = True;
                  rem /* Not supported by RE2 */ &sMap [Code(Char(11)) + 1] = True;
                  &sMap [Code(Char(12)) + 1] = True;
                  &sMap [Code(Char(13)) + 1] = True;
                  
                  /* Negate */
                  Local number &sc;
                  For &sc = 1 To 256
                     &sMap [&sc] = ( Not &sMap [&sc]);
                  End-For;
                  &mergeBitmaps.Push(&sMap);
                  Break;
               When-Other
                  &Chars.Push(%This.ParseEscapeChar(&esc));
               End-Evaluate;
               
            End-If;
            &i = &i + 1;
         Else
            If (&i + 2 <= &pEnd And
                  %This.SafeMid(&pat, &i + 1, 1) = "-") Then
               Local string &rangeStart = %This.SafeMid(&pat, &i, 1);
               Local string &rangeEnd = %This.SafeMid(&pat, &i + 2, 1);
               
               /* NEW: reject ranges involving non-BMP (PUA stand-in) endpoints */
               If %This.EnableSurrogatePairs Then
                  If (Code(&rangeStart) >= &PUA_START And
                        Code(&rangeStart) <= &PUA_END) Or
                        (Code(&rangeEnd) >= &PUA_START And
                           Code(&rangeEnd) <= &PUA_END) Then
                     throw CreateException(0, 0, "Character class ranges involving non-BMP characters are not supported");
                  End-If;
               End-If;
               
               &Chars.Push(CreateArray("range", &rangeStart, &rangeEnd));
               &i = &i + 3;
            Else
               &Chars.Push(CreateArray(&ch));
               &i = &i + 1;
            End-If;
         End-If;
      End-If;
   End-While;
   
   &node.SetValue("chars", &Chars);
   &node.SetValue("neg", &neg);
   &node.SetValue("matchNonAscii", &matchNonAscii);
   /* Precompute ASCII map */
   Local array of boolean &mapArr = CreateArrayRept( False, 256);
   Local array of string &it;
   
   For &i = 1 To &Chars.Len
      &it = &Chars [&i];
      If (&it [1] = "range") Then
         Local number &aCode = Code(&it [2]);
         Local number &bCode = Code(&it [3]);
         Local number &cc;
         For &cc = &aCode To &bCode;
            If &cc >= 0 And
                  &cc <= 255 Then
               &mapArr [&cc + 1] = True;
            End-If;
         End-For;
      Else
         Local number &code = Code(&it [1]);
         If &code >= 0 And
               &code <= 255 Then
            &mapArr [&code + 1] = True;
         End-If;
      End-If;
   End-For;
   
   /* ── Merge negated shorthand class bitmaps ── */
   Local number &mi;
   For &mi = 1 To &mergeBitmaps.Len
      Local array of boolean &mBmp = &mergeBitmaps [&mi];
      Local number &mj;
      For &mj = 1 To 256
         If &mBmp [&mj] Then
            &mapArr [&mj] = True;
         End-If;
      End-For;
   End-For;
   
   &node.SetValue("map", &mapArr);
   Return &node;
end-method;

method ParseClassFromSimple
   /+ &spec as String +/
   /+ Returns Hash +/
   
   Local Hash &node = %This.newNode("class");
   Local array of array of string &Chars = CreateArrayRept(CreateArrayRept("", 0), 0);
   Local boolean &neg = False;
   Local number &i = 2;
   While &i <= Len(&spec) - 1
      Local string &ch = %This.SafeMid(&spec, &i, 1);
      If (&i + 2 <= Len(&spec) - 1 And
            %This.SafeMid(&spec, &i + 1, 1) = "-") Then
         &Chars.Push(CreateArray("range", &ch, %This.SafeMid(&spec, &i + 2, 1)));
         &i = &i + 3;
      Else
         &Chars.Push(CreateArray(&ch));
         &i = &i + 1;
      End-If;
   End-While;
   
   &node.SetValue("chars", &Chars);
   &node.SetValue("neg", False);
   
   /* Precompute ASCII map */
   Local array of boolean &mapArr = CreateArrayRept( False, 256);
   Local array of string &it;
   
   For &i = 1 To &Chars.Len
      &it = &Chars [&i];
      If (&it [1] = "range") Then
         Local number &aCode = Code(&it [2]);
         Local number &bCode = Code(&it [3]);
         Local number &cc;
         For &cc = &aCode To &bCode;
            If &cc >= 0 And
                  &cc <= 255 Then
               &mapArr [&cc + 1] = True;
            End-If;
         End-For;
      Else
         Local number &code = Code(&it [1]);
         If &code >= 0 And
               &code <= 255 Then
            &mapArr [&code + 1] = True;
         End-If;
      End-If;
   End-For;
   
   &node.SetValue("map", &mapArr);
   Return &node;
   
end-method;

method ParseEscapeChar
   /+ &ch as String +/
   /+ Returns String +/
   Evaluate &ch
   When = "a"
   When = "e"
      Return Char(7);
   When = "b"
      Return Char(8);
   When = "f"
      Return Char(12);
   When = "n"
      Return Char(10);
   When = "r"
      Return Char(13);
   When = "t"
      Return Char(9);
   When = "v"
      Return Char(11);
   When = "\"
      Return "\";
   When-Other
      Return &ch;
   End-Evaluate;
   
end-method;

method PropagateFlags
   /+ &node as Any, +/
   /+ &flags as String +/
   Local any &elm;
   
   If &node = Null Then
      Return;
   End-If;
   try
      If (String(&node) = "Hash") Then
         Local string &t = "";
         If (&node.Exists("type")) Then
            &t = &node.GetValue("type", True);
         End-If;
         Evaluate &t
         When = "lit"
         When = "dot"
         When = "str"
         When = "backref"
            &node.SetValue("flags_on", &flags);
            Break;
         End-Evaluate;
         If (&node.Exists("child")) Then
            %This.PropagateFlags(&node.GetValue("child", True), &flags);
         End-If;
      Else
         If (String(&node) = "Array") Then
            Local integer &i;
            For &i = 1 To &node.Len
               %This.PropagateFlags(&node [&i], &flags);
            End-For;
         End-If;
      End-If;
   catch Exception &ex;
      MessageBox(0, "", 0, 0, "PropagateFlags error: " | &ex.ToString());
   end-try;
   
end-method;

method ComputeFixedWidth
   /+ &node as Hash +/
   /+ Returns Number +/
   
   Local string &t = &node.GetValue("type", True);
   Evaluate &t
   When = "lit"
   When = "dot"
   When = "class"
      Return 1;
   When = "str"
      Return Len(&node.GetValue("val", True));
   When = "seq"
      Local number &SUM = 0;
      Local array of any &children = &node.GetValue("child", True);
      Local integer &i;
      For &i = 1 To &children.Len
         Local any &ch = &children [&i];
         Local number &w = %This.ComputeFixedWidth(&ch);
         If (&w = - 1) Then
            Return - 1;
         End-If;
         &SUM = &SUM + &w;
      End-For;
      Return &SUM;
   When = "group"
   When = "atomic"
      Return %This.ComputeFixedWidth(&node.GetValue("child", True));
   When = "quant"
      Local number &qMin = &node.GetValue("min", True);
      Local number &qMax = &node.GetValue("max", True);
      If &qMin = &qMax And
            &qMin >= 0 Then
         Local number &childW = %This.ComputeFixedWidth(&node.GetValue("child", True));
         If &childW = - 1 Then
            Return - 1;
         End-If;
         Return &qMin * &childW;
      End-If;
      Return - 1;
      Break;
   When = "alt"
      Local array of any &altKids = &node.GetValue("child", True);
      Local number &altW = - 1;
      Local integer &ai;
      For &ai = 1 To &altKids.Len
         Local number &brW = %This.ComputeFixedWidth(&altKids [&ai]);
         If &brW = - 1 Then
            Return - 1;
         End-If;
         If &altW = - 1 Then
            &altW = &brW;
         Else
            If &brW <> &altW Then
               Return - 1;
            End-If;
         End-If;
      End-For;
      Return &altW;
      Break;
   When = "backref"
      Local number &bfIdx = 0;
      
      If &node.Exists("name") Then
         &bfIdx = %This.FindGroupIndexByName(&pAST, &node.GetValue("name", True));
         If &bfIdx = - 1 Then
            Return - 1;
         End-If;
      Else
         &bfIdx = &node.GetValue("idx", True);
      End-If;
      Local Hash &groupNode;
      If &pAST.Exists("groupNodes") Then
         Local array of array of any &gnodes = &pAST.GetValue("groupNodes", True);
         &groupNode = &gnodes [&bfIdx][&gnodes [&bfIdx].Len];
      End-If;
      If &groupNode = Null Then
         Return - 1;
      End-If;
      
      Return %This.ComputeFixedWidth(&groupNode);
   End-Evaluate;
   Return - 1;
end-method;

method BuildGroupNodesFromAST
   /+ &ast as Hash +/
   /+ Returns Array2 of Any +/
   Local array of array of any &groupNodes = CreateArrayRept(CreateArrayAny(), 0);
   try
      If &ast = Null Then
         Return &groupNodes;
      End-If;
      
      %This.CollectGroupNodesRecursive(&ast, &groupNodes);
      If Not &ast.Exists("groupNodes") Then
         &ast.SetValue("groupNodes", &groupNodes);
      End-If;
      Return &groupNodes;
      
   catch Exception &ex
   end-try;
   Return &groupNodes;
end-method;

method CollectGroupNodesRecursive
   /+ &node as Any, +/
   /+ &outColl as Array2 of Any out +/
   If &node = Null Then
      Return;
   End-If;
   
   /* This is what I *think* we do in the case where it is the "Array" type, not sure if this is
      actually something that happens though? */
   If (String(&node) = "Array") Then
      Local integer &i;
      For &i = 1 To &node.Len
         %This.CollectGroupNodesRecursive(&node [&i], &outColl);
      End-For;
      Return;
   End-If;
   /* If we are here it should be a "Hash" type */
   If (String(&node) = "Hash") Then
      Local Hash &nodeAsHash = &node;
      If &nodeAsHash.Exists("type") Then
         Local string &t = &nodeAsHash.GetValue("type", True);
         If (&t = "group") Then
            If (&nodeAsHash.Exists("name")) Then
               Local string &nm = &nodeAsHash.GetValue("name", True);
               Local number &idx = 0;
               If (&nodeAsHash.Exists("idx")) Then
                  &idx = &nodeAsHash.GetValue("idx", True);
               End-If;
               &outColl.Push(CreateArrayAny(&nm, &idx, &node));
            Else
               /* not a named group */
               &idx = 0;
               If (&nodeAsHash.Exists("idx")) Then
                  &idx = &nodeAsHash.GetValue("idx", True);
               End-If;
               &outColl.Push(CreateArrayAny("", &idx, &node));
            End-If;
         End-If;
      End-If;
      
      /* Slightly optimized using a for loop instead of repeated Exists/GetValue blocks */
      Local array of string &propsToCheck = CreateArray("child", "base", "index", "left", "right", "body", "cases");
      For &i = 1 To &propsToCheck.Len
         If (&nodeAsHash.Exists(&propsToCheck [&i])) Then
            %This.CollectGroupNodesRecursive(&nodeAsHash.GetValue(&propsToCheck [&i], True), &outColl);
            
         End-If;
      End-For;
      
   End-If;
   
end-method;

method PrintAST
   /+ &astNode as Any, +/
   /+ &indent as String +/
   If (String(&astNode) = "Array") Then
      Local integer &i;
      For &i = 1 To &astNode.Len
         %Response.Write(&indent | "[" | &i | "]" | "<br />");
         %This.PrintAST(&astNode [&i], &indent | "-");
      End-For;
      Return;
   End-If;
   
   If (String(&astNode) = "Hash") Then
      Local string &k;
      Local any &v;
      &astNode.IterStart();
      While &astNode.IterNext(&k, &v)
         If (&k = "map") Then
            %Response.Write(&indent | "map: [256]" | "<br />");
            Continue;
         End-If;
         If (String(&v) = "Hash" Or
               String(&v) = "Array") Then
            %Response.Write(&indent | &k | ":" | "<br />");
            %This.PrintAST(&v, &indent | "-");
         Else
            %Response.Write(&indent | &k | ": " | String(&v) | "<br />");
         End-If;
      End-While;
      Return;
   End-If;
   If (String(&astNode) = Char(10)) Then
      %Response.Write(&indent | "<br />");
   Else
      If (String(&astNode) = Char(13)) Then
         %Response.Write(&indent | "<br />");
      Else
         If (String(&astNode) = Char(9)) Then
            %Response.Write(&indent | "<pre>&nbsp;&nbsp;&nbsp;</pre>");
         Else
            %Response.Write(&indent | String(&astNode) | "<br />");
         End-If;
      End-If;
   End-If;
   
end-method;

<* method GetGroupCount
   /+ &ast as Hash +/
   /+ Returns Number +/
   Local number &maxIdx = 0;
   %This.TraverseForGroups(&ast.GetValue("body", True), &maxIdx);
   Return &maxIdx;
end-method;
*>
method TraverseForGroups
   /+ &node as Any, +/
   /+ &maxIdx as Number out +/
   
   If &node = Null Then
      Return;
   End-If;
   
   If (String(&node) = "Array") Then
      Local integer &i;
      For &i = 1 To &node.Len
         %This.TraverseForGroups(&node [&i], &maxIdx);
      End-For;
      Return;
   End-If;
   
   If (String(&node) = "Hash") Then
      Local string &t;
      Local number &tmpIdx;
      Local Hash &nodeAsHash = &node;
      If (&nodeAsHash.Exists("type")) Then
         &t = &nodeAsHash.GetValue("type", True);
      End-If;
      
      If (&t = "group") Then
         If (&node.Exists("idx")) Then
            &tmpIdx = &node.GetValue("idx", True);
            If &tmpIdx > &maxIdx Then
               &maxIdx = &tmpIdx;
            End-If;
         End-If;
      End-If;
      If (&node.Exists("child")) Then
         %This.TraverseForGroups(&node.GetValue("child", True), &maxIdx);
      End-If;
   End-If;
   
end-method;

method MatchCharClassNode
   /+ &node as Hash, +/
   /+ &ch as String +/
   /+ Returns Boolean +/
   Local number &code = Code(&ch);
   /* direct ASCII fast-path */
   If (&code >= 0 And
         &code <= 255) Then
      Local array of boolean &mapArr = &node.GetValue("map", True);
      Local boolean &matched = &mapArr [&code + 1];
      
      If ( Not &matched And
            &pIgnoreCase) Then
         If (&code >= 65 And
               &code <= 90) Then
            &matched = &mapArr [&code + 32 + 1];
         Else
            If (&code >= 97 And
                  &code <= 122) Then
               &matched = &mapArr [&code - 32 + 1];
            End-If;
         End-If;
      End-If;
      If &node.Exists("neg") Then
         If (&node.GetValue("neg", True)) Then
            Return ( Not &matched);
         Else
            Return &matched;
         End-If;
      Else
         Return &matched;
      End-If;
   End-If;
   
   
   Local array of array of string &items = &node.GetValue("chars", True);
   Local integer &i;
   Local number &codeLower;
   /* If (&node.GetValue("chars", True) = Null) Then
      MessageBox(0, "", 0, 0, "Chars is null for: " | %This.PrintASTCompact(&node));
   End-If; */
   For &i = 1 To &items.Len
      Local array of string &it = &items [&i];
      If (&it [1] = "range") Then
         If ( Not &pIgnoreCase) Then
            &matched = (&code >= Code(&it [2]) And
               &code <= Code(&it [3]));
         Else
            &codeLower = Code(Lower(&ch));
            &matched = (&codeLower >= Code(Lower(&it [2])) And
               &codeLower <= Code(Lower(&it [3])));
         End-If;
      Else
         If ( Not &pIgnoreCase) Then
            &matched = (&code = Code(&it [1]));
         Else
            &codeLower = Code(Lower(&ch));
            &matched = (&codeLower = Code(Lower(&it [1])));
         End-If;
      End-If;
      If &matched Then
         Break;
      End-If;
      
   End-For;
   If Not &matched And
         &node.Exists("matchNonAscii") And
         &node.GetValue("matchNonAscii", True) Then
      &matched = True;
   End-If;
   If &node.GetValue("neg", True) Then
      Return ( Not &matched);
   Else
      Return &matched;
   End-If;
end-method;

method CopyCaps
   /+ Returns Array2 of Number +/
   Local array of array of number &snap = CreateArrayRept(CreateArrayRept(0, 0), 2);
   &snap [1] = &capsStart.Clone();
   &snap [2] = &capsEnd.Clone();
   %This.SnapshotCount = %This.SnapshotCount + 1;
   Return &snap;
end-method;

method RestoreCaps
   /+ &snapshot as Array2 of Number +/
   %This.SnapshotRestoreCount = %This.SnapshotRestoreCount + 1;
   If &snapshot = Null Then
      Return;
   End-If;
   &capsStart = &snapshot [1].Clone();
   &capsEnd = &snapshot [2].Clone();
end-method;

method MatchNode
   /+ &node as Hash, +/
   /+ &subj as String, +/
   /+ &pos as Number, +/
   /+ &outEnd as Number out +/
   /+ Returns Boolean +/
   If (%PerfTime - &execStartTime > &MAX_EXEC_TIME) Then
      throw CreateException(0, 0, "Match time exceeded: " | (%PerfTime - &execStartTime));
   End-If;
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE MatchNode ENTER type=" | &node.GetValue("type", True) | " pos=" | &pos | " caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
   End-If;
   &MatchSteps = &MatchSteps + 1;
   If &MatchSteps > &pMaxMatchSteps Then
      throw CreateException(0, 0, "Match aborted: too many steps");
   End-If;
   
   /* Memoization: check if we've already proven this node fails at this position */
   Local boolean &memoSafe = False;
   Local string &cacheKey = "";
   If &node.Exists("memoSafe") Then
      &memoSafe = &node.GetValue("memoSafe", True);
      If &memoSafe Then
         &cacheKey = &node.GetValue("nodeId", True) | "_" | &pos;
         If &failCache.Exists(&cacheKey) Then
            Return False;
         End-If;
      End-If;
   End-If;
   
   Local string &t = &node.GetValue("type", True);
   Local boolean &res = False;
   Local number &localEnd = - 1;
   Local string &inlineFlags;
   
   Evaluate &t
   When = "anchor_start"
      If &pos = 1 Then
         &res = True;
         &localEnd = &pos - 1;
      Else
         If &pMultiline Then
            Local string &prevCh = %This.SafeMid(&subj, &pos - 1, 1);
            If &prevCh = Char(10) Or
                  &prevCh = Char(13) Then
               &res = True;
               &localEnd = &pos - 1;
            End-If;
         End-If;
      End-If;
      Break;
   When = "anchor_end"
      If &pos > Len(&subj) Then
         &res = True;
         &localEnd = &pos - 1;
      Else
         If &pMultiline Then
            Local string &aeNxt = %This.SafeMid(&subj, &pos, 1);
            If &aeNxt = Char(10) Or
                  &aeNxt = Char(13) Then
               &res = True;
               &localEnd = &pos - 1;
            End-If;
         End-If;
      End-If;
      Break;
   When = "anchor_start_abs"
      /* \A - matches only at absolute start of string, ignores multiline */
      If &pos = 1 Then
         &res = True;
         &localEnd = &pos - 1;
      End-If;
      Break;
   When = "anchor_end_abs"
      /* \Z - matches at end of string, or before a trailing newline at end */
      If &pos > Len(&subj) Then
         &res = True;
         &localEnd = &pos - 1;
      Else
         If &pos = Len(&subj) Then
            Local string &lastCh = %This.SafeMid(&subj, &pos, 1);
            If &lastCh = Char(10) Or
                  &lastCh = Char(13) Then
               &res = True;
               &localEnd = &pos - 1;
            End-If;
         End-If;
      End-If;
      Break;
   When = "anchor_end_abs_strict"
      /* \z - matches only at absolute end of string */
      If &pos > Len(&subj) Then
         &res = True;
         &localEnd = &pos - 1;
      End-If;
      Break;
   When = "word_boundary"
   When = "word_boundary_neg"
      /* \b and \B - word boundary detection */
      Local boolean &prevIsWord = False;
      Local boolean &currIsWord = False;
      If &pos > 1 Then
         Local number &prevCode = Code(%This.SafeMid(&subj, &pos - 1, 1));
         &prevIsWord = ((&prevCode >= 65 And
            &prevCode <= 90) Or
            (&prevCode >= 97 And
               &prevCode <= 122) Or
            (&prevCode >= 48 And
               &prevCode <= 57) Or
            &prevCode = 95);
      End-If;
      If &pos <= Len(&subj) Then
         Local number &currCode = Code(%This.SafeMid(&subj, &pos, 1));
         &currIsWord = ((&currCode >= 65 And
            &currCode <= 90) Or
            (&currCode >= 97 And
               &currCode <= 122) Or
            (&currCode >= 48 And
               &currCode <= 57) Or
            &currCode = 95);
      End-If;
      Local boolean &atBoundary = (&prevIsWord <> &currIsWord);
      If &t = "word_boundary" Then
         &res = &atBoundary;
      Else
         &res = ( Not &atBoundary);
      End-If;
      If &res Then
         &localEnd = &pos - 1;
      End-If;
      Break;
   When = "seq"
      &res = %This.MatchSequence(&node.GetValue("child", True), &subj, &pos, &localEnd);
      Break;
   When = "str"
      Local string &strVal = &node.GetValue("val", True);
      Local number &strLen = Len(&strVal);
      If &pos + &strLen - 1 > Len(&subj) Then
         &res = False;
      Else
         Local string &subStr = Substring(&subj, &pos, &strLen);
         Local boolean &strICase = &pIgnoreCase;
         Local boolean &strOffCase = False;
         If &node.Exists("flags_on") Then
            &inlineFlags = &node.GetValue("flags_on", True);
            If Find("i", &inlineFlags) > 0 And
                  Find("-i", &inlineFlags) = 0 Then
               &strICase = True;
            End-If;
            If Find("-i", &inlineFlags) > 0 Then
               &strOffCase = True;
            End-If;
         End-If;
         
         If &strICase And
               Not &strOffCase Then
            If Lower(&subStr) = Lower(&strVal) Then
               &localEnd = &pos + &strLen - 1;
               &res = True;
            End-If;
         Else
            If &subStr = &strVal Then
               &localEnd = &pos + &strLen - 1;
               &res = True;
            End-If;
         End-If;
      End-If;
      Break;
   When = "lit"
      If &pos > Len(&subj) Then
         &res = False;
      Else
         Local string &ch = &node.GetValue("ch", True);
         Local string &sc = %This.SafeMid(&subj, &pos, 1);
         Local boolean &iCase;
         Local boolean &tOffCase;
         If &pIgnoreCase Then
            /* Inline flags */
            If &node.Exists("flags_on") Then
               &inlineFlags = &node.GetValue("flags_on", True);
               &tOffCase = (Find("-i", &inlineFlags, 1) > 0);
            End-If;
            
            If Not &tOffCase Then
               If Lower(&sc) = Lower(&ch) Then
                  &localEnd = &pos;
                  &res = True;
               End-If;
            Else
               /* case sensitive */
               If &sc = &ch Then
                  &localEnd = &pos;
                  &res = True;
               End-If;
            End-If;
            
         Else
            
            If &node.Exists("flags_on") Then
               &inlineFlags = &node.GetValue("flags_on", True);
               &iCase = (Find("i", &inlineFlags, 1) > 0 And
                  Find("-i", &inlineFlags, 1) = 0);
               If (&iCase) Then
                  If Lower(&sc) = Lower(&ch) Then
                     &localEnd = &pos;
                     &res = True;
                  End-If;
               Else
                  /* case sensitive */
                  If &sc = &ch Then
                     &localEnd = &pos;
                     &res = True;
                  End-If;
               End-If;
            Else
               If &sc = &ch Then
                  &localEnd = &pos;
                  &res = True;
               End-If;
            End-If;
         End-If;
      End-If;
      Break;
   When = "dot"
      If (&pos > Len(&subj)) Then
         &res = False;
      Else
         Local boolean &dAll;
         If &node.Exists("flags_on") Then
            &inlineFlags = &node.GetValue("flags_on", True);
            &tOffCase = (Find("-s", &inlineFlags, 1) > 0);
            &dAll = (Find("s", &inlineFlags, 1) > 0 And
               Find("-s", &inlineFlags, 1) = 0);
         End-If;
         If &pDotAll And
               &tOffCase Then
            &dAll = False;
         Else
            If Not &dAll Then
               &dAll = &pDotAll;
            End-If;
         End-If;
         
         Local string &dch = %This.SafeMid(&subj, &pos, 1);
         If (&dch = Char(10)) And
               Not &dAll Then
            &res = False;
         Else
            &localEnd = &pos;
            &res = True;
         End-If;
      End-If;
      Break;
   When = "class"
      If &pos > Len(&subj) Then
         &res = False;
      Else
         If %This.MatchCharClassNode(&node, %This.SafeMid(&subj, &pos, 1)) Then
            &localEnd = &pos;
            &res = True;
         End-If;
      End-If;
      Break;
   When = "group"
      Local boolean &hasIdx = &node.Exists("idx");
      Local number &gidx;
      If &hasIdx Then
         &gidx = &node.GetValue("idx", True);
      Else
         &gidx = 0;
      End-If;
      
      Local boolean &flagsApplied = False;
      Local boolean &savedIgnore, &savedMultiline, &savedDotAll;
      If &node.Exists("flags_on") Then
         &flagsApplied = True;
         &savedIgnore = &pIgnoreCase;
         &savedMultiline = &pMultiline;
         &savedDotAll = &pDotAll;
         Local string &fstr = &node.GetValue("flags_on", True);
         &pIgnoreCase = (Find("i", &fstr) > 0);
         &pMultiline = (Find("m", &fstr) > 0);
         &pDotAll = (Find("s", &fstr) > 0);
      End-If;
      
      Local array of array of number &snapGroup = %This.CopyCaps();
      
      /* set group's start (only after we took full snapshot) */
      If &gidx >= 1 Then
         &capsStart [&gidx + 1] = &pos;
      End-If;
      
      Local number &childEnd;
      If %This.MatchNode(&node.GetValue("child", True), &subj, &pos, &childEnd) Then
         If &gidx >= 1 Then
            &capsEnd [&gidx + 1] = &childEnd;
         End-If;
         &localEnd = &childEnd;
         &res = True;
      Else
         %This.RestoreCaps(&snapGroup);
         &res = False;
      End-If;
      
      /* restore flags if applied (always do this after child path) */
      If &flagsApplied Then
         &pIgnoreCase = &savedIgnore;
         &pMultiline = &savedMultiline;
         &pDotAll = &savedDotAll;
      End-If;
      
      Break;
   When = "alt"
      Local Hash &altChild;
      Local integer &i;
      Local array of any &children = &node.GetValue("child", True);
      For &i = 1 To &children.Len
         Local array of array of number &snapAlt = %This.CopyCaps();
         Local number &altEnd;
         If %This.MatchNode(&children [&i], &subj, &pos, &altEnd) Then
            &localEnd = &altEnd;
            &res = True;
            Break;
         Else
            %This.RestoreCaps(&snapAlt);
         End-If;
      End-For;
      
      
      Break;
   When = "quant"
      Local number &mn = &node.GetValue("min", True);
      Local number &mx = &node.GetValue("max", True);
      
      If &mx = - 1 Then
         &mx = Len(&subj) - &pos + 1;
      End-If;
      
      Local array of number &occPos = CreateArrayRept(0, 0);
      Local array of array of array of number &occSnaps = CreateArrayRept(CreateArrayRept(CreateArrayRept(0, 0), 0), 0);
      Local number &occCount = 0;
      Local number &curPos = &pos;
      Local number &nodeEnd;
      
      Local array of array of number &preScanSnap = %This.CopyCaps();
      
      While &occCount < &mx
         Local array of array of number &tempSnap = %This.CopyCaps();
         If %This.MatchNode(&node.GetValue("child", True), &subj, &curPos, &nodeEnd) Then
            &occCount = &occCount + 1;
            &occPos.Push(&nodeEnd);
            &occSnaps.Push(%This.CopyCaps());
            If &nodeEnd + 1 <= &curPos Then
               While &occCount < &mn
                  &occCount = &occCount + 1;
                  &occPos.Push(&nodeEnd);
                  &occSnaps.Push(%This.CopyCaps());
               End-While;
               Break;
            End-If;
            &curPos = &nodeEnd + 1;
         Else
            %This.RestoreCaps(&tempSnap);
            Break;
         End-If;
      End-While;
      
      If &occCount >= &mn Then
         Local boolean &qLazy = False;
         If &node.Exists("lazy") Then
            &qLazy = &node.GetValue("lazy", True);
         End-If;
         
         Local number &pick;
         If &qLazy Then
            &pick = &mn;
         Else
            &pick = &occCount;
         End-If;
         
         If &pick >= 1 Then
            %This.RestoreCaps(&occSnaps [&pick]);
            &localEnd = &occPos [&pick];
         Else
            %This.RestoreCaps(&preScanSnap);
            &localEnd = &pos - 1;
         End-If;
         &res = True;
      Else
         %This.RestoreCaps(&preScanSnap);
         &res = False;
      End-If;
      
      Break;
   When = "lookahead_pos"
   When = "lookahead_neg"
      If Not &node.Exists("child") Then
         Return False;
      End-If;
      Local boolean &laInvert = (&t = "lookahead_neg");
      
      Local Hash &laChild = &node.GetValue("child", True);
      Local array of array of number &snapLA = %This.CopyCaps();
      Local number &laEnd;
      Local boolean &laMatched;
      
      &laMatched = %This.MatchNode(&laChild, &subj, &pos, &laEnd);
      %This.RestoreCaps(&snapLA);
      
      Local boolean &laSuccess = ((&laMatched And
         ( Not &laInvert)) Or
         (( Not &laMatched) And
            &laInvert));
      
      If &laSuccess Then
         &outEnd = &pos - 1;
         Return True;
      Else
         Return False;
      End-If;
      Break;
   When = "lookbehind_pos"
   When = "lookbehind_neg"
      If Not &node.Exists("child") Then
         Return False;
      End-If;
      Local boolean &lbInvert = (&t = "lookbehind_neg");
      
      Local Hash &lbChild = &node.GetValue("child", True);
      Local number &lbWidth = &node.GetValue("width", True);
      Local array of array of number &snapLB;
      Local number &lbStart, &lbEnd;
      Local boolean &lbMatched;
      
      If (&pos - 1 < &lbWidth) Then
         Return False;
      End-If;
      
      &lbStart = &pos - &lbWidth;
      &snapLB = %This.CopyCaps();
      &lbMatched = %This.MatchNode(&lbChild, &subj, &lbStart, &lbEnd);
      %This.RestoreCaps(&snapLB);
      
      If (&lbMatched And
            Not &lbInvert) Or
            ( Not &lbMatched And
               &lbInvert) Then
         &outEnd = &pos - 1;
         Return True;
      Else
         Return False;
      End-If;
      Break;
   When = "atomic"
      /* Attempt to match child; if it succeeds protect changed capture slots from later restore */
      Local array of array of number &beforeSnap = %This.CopyCaps();
      Local number &atomEnd;
      If %This.MatchNode(&node.GetValue("child", True), &subj, &pos, &atomEnd) Then
         &res = True;
         &localEnd = &atomEnd;
         /* mark which capture slots changed and lock them */
         Local number &tot = &pGroupCount;
         Local number &idx;
         For &idx = 1 To &tot
            Local number &beforeS = &beforeSnap [1][&idx];
            Local number &beforeE = &beforeSnap [2][&idx];
            If (&capsStart [&idx] <> &beforeS Or
                  &capsEnd [&idx + &tot + 1] <> &beforeE) Then
               &atomicLocks [&idx] = True;
            End-If;
         End-For;
      Else
         /* restore beforeSnap (child already handled restore in branches), keep atomicLocks unchanged */
         %This.RestoreCaps(&beforeSnap);
         &res = False;
      End-If;
      Break;
   When = "cond"
      /* Conditional node: fields "cond" (string like "1" or "name"), "yes" (node), optional "no" (node) */
      If Not &node.Exists("cond") Then
         Return False;
      End-If;
      
      Local string &condText = &node.GetValue("cond", True);
      Local boolean &condSatisfied = False;
      
      /* numeric? */
      If IsNumber(&condText) Then
         Local number &cIdx = Value(&condText);
         If &cIdx >= 0 And
               &cIdx <= &capsEnd.Len - 1 Then
            If &capsEnd [&cIdx + 1] <> - 1 Then
               &condSatisfied = True;
            End-If;
         End-If;
      Else
         /* named: find index by name */
         Local number &resolvedIdx = %This.FindGroupIndexByName(&pAST, &condText);
         If &resolvedIdx <> - 1 Then
            If &resolvedIdx >= 0 And
                  &resolvedIdx <= &capsEnd.Len - 1 Then
               
               If &capsEnd [&resolvedIdx + 1] <> - 1 Then
                  &condSatisfied = True;
               End-If;
            End-If;
         Else
            &condSatisfied = False;
         End-If;
      End-If;
      
      /* Branch selection */
      If &condSatisfied Then
         If &node.Exists("yes") Then
            Local Hash &yesNode = &node.GetValue("yes", True);
            Local number &yesEnd;
            Local array of array of number &snapY = %This.CopyCaps();
            If %This.MatchNode(&yesNode, &subj, &pos, &yesEnd) Then
               &localEnd = &yesEnd;
               &res = True;
            Else
               %This.RestoreCaps(&snapY);
               &res = False;
            End-If;
         Else
            &res = False;
         End-If;
      Else
         If &node.Exists("no") Then
            Local Hash &noNode = &node.GetValue("no", True);
            Local number &noEnd;
            Local array of array of number &snapN = %This.CopyCaps();
            If %This.MatchNode(&noNode, &subj, &pos, &noEnd) Then
               &localEnd = &noEnd;
               &res = True;
            Else
               %This.RestoreCaps(&snapN);
               &res = False;
            End-If;
         Else
            &res = False;
         End-If;
      End-If;
      
      Break;
   When = "recurse"
      If Not &node.Exists("target") Then
         Return False;
      End-If;
      
      Local number &targ = Value(&node.GetValue("target", True));
      Local boolean &recOK = False;
      Local number &recEnd;
      
      If &targ = 0 Then
         /* (?R) -> recurse into whole root AST */
         Local array of array of number &snapR = %This.CopyCaps();
         If %This.MatchNode(&pAST.GetValue("body", True), &subj, &pos, &recEnd) Then
            &recOK = True;
            &localEnd = &recEnd;
         Else
            %This.RestoreCaps(&snapR);
            &recOK = False;
         End-If;
      Else
         /* recurse into group node child (if available) */
         If &pAST.Exists("groupNodes") Then
            Local array of array of any &gnodes = &pAST.GetValue("groupNodes", True);
            Local number &rIdx = %This.FindGroupIndexByOrdinal(&pAST, &targ);
            Local array of any &targetNode = Null;
            try
               &targetNode = &gnodes [&rIdx];
            catch Exception &ex
               &targetNode = Null;
            end-try;
            
            If (&targetNode <> Null) Then
               Local Hash &childNode = &targetNode [&targetNode.Len];
               Local array of array of number &snapG = %This.CopyCaps();
               If %This.MatchNode(&childNode, &subj, &pos, &recEnd) Then
                  &recOK = True;
                  &localEnd = &recEnd;
               Else
                  %This.RestoreCaps(&snapG);
                  &recOK = False;
               End-If;
            End-If;
         End-If;
      End-If;
      
      &res = &recOK;
      Break;
   When = "backref"
      /* Resolve the group index */
      Local number &bIdx = 0;
      
      If &node.Exists("name") Then
         /* Named backreference: \k<name> */
         Local string &bName = &node.GetValue("name", True);
         &bIdx = %This.FindGroupIndexByName(&pAST, &bName);
         If &bIdx = - 1 Then
            &res = False;
            Break;
         End-If;
      Else
         &bIdx = &node.GetValue("idx", True);
         
         /* Two-digit fallback: if idx exceeds group count, 
            try first digit only */
         If &bIdx > &pGroupCount Then
            Local string &rawDigits = &node.GetValue("raw", True);
            If Len(&rawDigits) > 1 Then
               &bIdx = Value(Substring(&rawDigits, 1, 1));
            End-If;
         End-If;
         
         /* Still out of range → fail */
         If &bIdx < 1 Or
               &bIdx > &pGroupCount Then
            &res = False;
            Break;
         End-If;
      End-If;
      
      /* Check if the referenced group has been captured */
      Local number &bSlot = &bIdx + 1;
      If &bSlot > &capsEnd.Len Or
            &capsEnd [&bSlot] = - 1 Then
         /* Group genuinely unset → fail */
         &res = False;
         Break;
      End-If;
      
      /* Extract the captured text */
      Local string &captured = Substring(&subj, &capsStart [&bSlot], &capsEnd [&bSlot] - &capsStart [&bSlot] + 1);
      Local number &capLen = Len(&captured);
      
      /* Zero-length capture → match succeeds consuming nothing */
      If &capLen = 0 Then
         &localEnd = &pos - 1;
         &res = True;
         Break;
      End-If;
      
      /* Check if enough subject remains */
      If &pos + &capLen - 1 > Len(&subj) Then
         &res = False;
         Break;
      End-If;
      
      Local string &subjSlice = Substring(&subj, &pos, &capLen);
      
      /* Case sensitivity: check inline flags then global */
      Local boolean &brICase = &pIgnoreCase;
      If &node.Exists("flags_on") Then
         Local string &brFlags = &node.GetValue("flags_on", True);
         If Find("i", &brFlags) > 0 And
               Find("-i", &brFlags) = 0 Then
            &brICase = True;
         End-If;
         If Find("-i", &brFlags) > 0 Then
            &brICase = False;
         End-If;
      End-If;
      
      Local boolean &brMatch = False;
      If &brICase Then
         &brMatch = (Lower(&subjSlice) = Lower(&captured));
      Else
         &brMatch = (&subjSlice = &captured);
      End-If;
      
      If &brMatch Then
         &localEnd = &pos + &capLen - 1;
         &res = True;
      Else
         &res = False;
      End-If;
      Break;
   When-Other
      &res = False;
   End-Evaluate;
   
   If &res Then
      If &localEnd >= 0 Then
         &capsEnd [1] = &localEnd;
         &outEnd = &localEnd;
      Else
         &outEnd = &capsEnd [1];
      End-If;
   End-If;
   
   /* Memoize failure */
   If Not &res And
         &memoSafe And
         &cacheKey <> "" Then
      &failCache.SetValue(&cacheKey, True);
   End-If;
   
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE MatchNode EXIT type=" | &t | " pos=" | &pos | " res=" | &res | " localEnd=" | &localEnd | " caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
   End-If;
   Return &res;
   
   Return &res;
   
   
end-method;

method MatchSequence
   /+ &children as Array of Any, +/
   /+ &subj as String, +/
   /+ &pos as Number, +/
   /+ &outEnd as Any out +/
   /+ Returns Boolean +/
   If (%PerfTime - &execStartTime > &MAX_EXEC_TIME) Then
      throw CreateException(0, 0, "Match time exceeded: " | (%PerfTime - &execStartTime));
   End-If;
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE MatchSequence start pos=" | &pos | " children=" | &children.Len);
   End-If;
   
   Local boolean &result = %This.MatchSeqFrom(&children, &subj, &pos, 1, &outEnd);
   
   If &DEBUG_TRACE Then
      If &result Then
         %This.DebugTrace("TRACE MatchSequence success outEnd=" | &outEnd | " caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
      Else
         %This.DebugTrace("TRACE MatchSequence failed");
      End-If;
   End-If;
   
   Return &result;
end-method;

method MatchSeqFrom
   /+ &children as Array of Any, +/
   /+ &subj as String, +/
   /+ &pos as Number, +/
   /+ &childIdx as Number, +/
   /+ &outEnd as Any out +/
   /+ Returns Boolean +/
   
   If (%PerfTime - &execStartTime > &MAX_EXEC_TIME) Then
      throw CreateException(0, 0, "Match time exceeded: " | (%PerfTime - &execStartTime));
   End-If;
   
   /* Base case: all children matched */
   If &childIdx > &children.Len Then
      &outEnd = &pos - 1;
      &capsEnd [1] = &outEnd;
      Return True;
   End-If;
   
   Local Hash &node = &children [&childIdx];
   Local string &nodeType = &node.GetValue("type", True);
   Local array of array of number &snap;
   
   /* At the top of MatchSeqFrom, after getting &node and &nodeType */
   Local string &seqCacheKey = &node.GetValue("nodeId", True) | "_" | &pos | "_" | &childIdx | "_" | &children.Len;
   Local number &ck;
   For &ck = &childIdx + 1 To &children.Len
      Local Hash &ckNode = &children [&ck];
      &seqCacheKey = &seqCacheKey | "_" | &ckNode.GetValue("nodeId", True);
   End-For;
   If &failCache.Exists(&seqCacheKey) Then
      Return False;
   End-If;
   
   Evaluate &nodeType
   When = "quant"
   When = "group"
   When = "cap_end"
      &snap = %This.CopyCaps();
   End-Evaluate;
   
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE  SeqFrom child#" | &childIdx | " type=" | &nodeType | " pos=" | &pos);
   End-If;
   
   /* Zero-width capture-end marker */
   If &nodeType = "cap_end" Then
      Local number &ceIdx = &node.GetValue("gidx", True);
      If &ceIdx >= 1 Then
         &capsEnd [&ceIdx + 1] = &pos - 1;
      End-If;
      Local boolean &ceResult = %This.MatchSeqFrom(&children, &subj, &pos, &childIdx + 1, &outEnd);
      If Not &ceResult Then
         %This.RestoreCaps(&snap);
      End-If;
      Return &ceResult;
   End-If;
   
   Local boolean &canMemo = False;
   
   Evaluate &nodeType
   When = "quant"
      If &node.Exists("memoSafe") Then
         &canMemo = &node.GetValue("memoSafe", True);
      End-If;
      /* ---- Quantifier: try each repetition count, then recurse remainder ---- */
      Local Hash &childNode = &node.GetValue("child", True);
      Local number &mn = &node.GetValue("min", True);
      Local number &mx = &node.GetValue("max", True);
      Local boolean &lazy = &node.GetValue("lazy", True);
      Local boolean &possFlag = False;
      If (&node.Exists("possessive")) Then
         &possFlag = &node.GetValue("possessive", True);
      End-If;
      
      If &mx = - 1 Then
         &mx = Len(&subj) - &pos + 1;
         If &mx < &mn + 1 Then
            &mx = &mn + 1;
         End-If;
      End-If;
      
      /* Collect all possible occurrence endpoints */
      Local array of number &occEnds = CreateArrayRept(0, 0);
      Local array of array of array of number &occSnaps = CreateArrayRept(CreateArrayRept(CreateArrayRept(0, 0), 0), 0);
      Local number &occCount = 0;
      Local number &scanPos = &pos;
      
      Local array of array of number &preSnap = %This.CopyCaps();
      While &occCount < &mx
         Local number &ndEnd;
         If %This.MatchNode(&childNode, &subj, &scanPos, &ndEnd) Then
            &occCount = &occCount + 1;
            &occEnds.Push(&ndEnd);
            Local array of array of number &postSnap = %This.CopyCaps();
            &occSnaps.Push(&postSnap);
            &preSnap = &postSnap;
            If &DEBUG_TRACE Then
               %This.DebugTrace("TRACE  quant matched occ " | &occCount | " nodeEnd=" | &ndEnd);
            End-If;
            /* Zero-width match: child can repeat zero-width indefinitely.
               Fill up to min if needed, then break to prevent infinite loop. */
            If &ndEnd + 1 <= &scanPos Then
               While &occCount < &mn
                  &occCount = &occCount + 1;
                  &occEnds.Push(&ndEnd);
                  &occSnaps.Push(%This.CopyCaps());
               End-While;
               Break;
            End-If;
            &scanPos = &ndEnd + 1;
         Else
            %This.RestoreCaps(&preSnap);
            If &DEBUG_TRACE Then
               %This.DebugTrace("TRACE  quant stop at occCount=" | &occCount);
            End-If;
            Break;
         End-If;
      End-While;
      
      /* If scanning didn't reach min, try unrolled approach for remainder-aware backtracking */
      If &occCount < &mn Then
         Local array of any &unrolled = CreateArrayAny();
         Local number &ui;
         For &ui = 1 To &mn
            &unrolled.Push(&childNode);
         End-For;
         /* Variable part above min */
         Local number &origMax = &node.GetValue("max", True);
         If &origMax = - 1 Or
               &origMax > &mn Then
            Local Hash &varQuant = %This.newNode("quant");
            &varQuant.SetValue("child", &childNode);
            &varQuant.SetValue("min", 0);
            If &origMax = - 1 Then
               &varQuant.SetValue("max", - 1);
            Else
               &varQuant.SetValue("max", &origMax - &mn);
            End-If;
            &varQuant.SetValue("lazy", &lazy);
            &varQuant.SetValue("possessive", &possFlag);
            &unrolled.Push(&varQuant);
         End-If;
         /* Append remaining children from outer sequence */
         For &ui = &childIdx + 1 To &children.Len
            &unrolled.Push(&children [&ui]);
         End-For;
         %This.RestoreCaps(&snap);
         If %This.MatchSeqFrom(&unrolled, &subj, &pos, 1, &outEnd) Then
            Return True;
         End-If;
         %This.RestoreCaps(&snap);
         If &canMemo Then
            &failCache.SetValue(&seqCacheKey, True);
         End-If;
         Return False;
      End-If;
      
      /* Possessive: only try max count */
      If &possFlag Then
         If &occCount < &mn Then
            %This.RestoreCaps(&snap);
            If &canMemo Then
               &failCache.SetValue(&seqCacheKey, True);
            End-If;
            Return False;
         End-If;
         
         If &occCount >= 1 Then
            Local array of array of number &tmpSnapsP = &occSnaps [&occCount];
            %This.RestoreCaps(&tmpSnapsP);
         Else
            %This.RestoreCaps(&snap);
         End-If;
         
         Local number &posTryP = &pos;
         If &occCount >= 1 Then
            &posTryP = &occEnds [&occCount] + 1;
         End-If;
         
         If %This.MatchSeqFrom(&children, &subj, &posTryP, &childIdx + 1, &outEnd) Then
            Return True;
         Else
            %This.RestoreCaps(&snap);
            If &canMemo Then
               &failCache.SetValue(&seqCacheKey, True);
            End-If;
            Return False;
         End-If;
      End-If;
      
      /* Greedy or lazy: iterate over k values */
      Local number &kStart, &kEnd, &kStep;
      If &lazy Then
         &kStart = &mn;
         &kEnd = &occCount;
         &kStep = 1;
      Else
         &kStart = &occCount;
         &kEnd = &mn;
         &kStep = - 1;
      End-If;
      
      Local number &k;
      Local array of array of number &tmpSnaps;
      For &k = &kStart To &kEnd Step &kStep
         If &DEBUG_TRACE Then
            %This.DebugTrace("TRACE  quant trying k=" | &k);
         End-If;
         
         Local number &kPos = &pos;
         If &k >= 1 Then
            &tmpSnaps = &occSnaps [&k];
            %This.RestoreCaps(&tmpSnaps);
            &kPos = &occEnds [&k] + 1;
         Else
            %This.RestoreCaps(&snap);
         End-If;
         
         If %This.MatchSeqFrom(&children, &subj, &kPos, &childIdx + 1, &outEnd) Then
            If &DEBUG_TRACE Then
               %This.DebugTrace("TRACE  quant accepted k=" | &k);
            End-If;
            Return True;
         End-If;
      End-For;
      
      /* Fallback: unroll for cross-occurrence backtracking when scanning
         couldn't find the right distribution of characters across repetitions */
      Local number &fbChildMinLen = %This.ComputeMinLen(&childNode);
      Local number &fbRemaining = Len(&subj) - &pos + 1;
      Local number &fbMaxReps;
      If &fbChildMinLen > 0 Then
         &fbMaxReps = Int(&fbRemaining / &fbChildMinLen);
      Else
         If &fbRemaining > &mn Then
            &fbMaxReps = &fbRemaining;
         Else
            &fbMaxReps = &mn;
         End-If;
      End-If;
      Local number &fbOrigMax = &node.GetValue("max", True);
      If &fbOrigMax <> - 1 And
            &fbOrigMax < &fbMaxReps Then
         &fbMaxReps = &fbOrigMax;
      End-If;
      
      /* Cap to prevent combinatorial explosion */
      Local number &fbCap = &fbRemaining + 1;
      If &fbCap < &mn Then
         &fbCap = &mn;
      End-If;
      If &fbMaxReps > &fbCap Then
         &fbMaxReps = &fbCap;
      End-If;
      
      If &fbMaxReps >= &mn Then
         Local number &fbRStart, &fbREnd, &fbRStep;
         If &lazy Then
            &fbRStart = &mn;
            &fbREnd = &fbMaxReps;
            &fbRStep = 1;
         Else
            &fbRStart = &fbMaxReps;
            &fbREnd = &mn;
            &fbRStep = - 1;
         End-If;
         
         Local number &fbR;
         For &fbR = &fbRStart To &fbREnd Step &fbRStep
            Local array of any &fbUnrolled = CreateArrayAny();
            Local number &fbi;
            For &fbi = 1 To &fbR
               &fbUnrolled.Push(&childNode);
            End-For;
            For &fbi = &childIdx + 1 To &children.Len
               &fbUnrolled.Push(&children [&fbi]);
            End-For;
            %This.RestoreCaps(&snap);
            If %This.MatchSeqFrom(&fbUnrolled, &subj, &pos, 1, &outEnd) Then
               Return True;
            End-If;
         End-For;
      End-If;
      
      If &DEBUG_TRACE Then
         %This.DebugTrace("TRACE  quant exhausted all k -> fail");
      End-If;
      
      %This.RestoreCaps(&snap);
      If &canMemo Then
         &failCache.SetValue(&seqCacheKey, True);
      End-If;
      Return False;
   When = "group"
      If &node.Exists("memoSafe") Then
         &canMemo = &node.GetValue("memoSafe", True);
      End-If;
      /* ---- Group: handle alternation children with remainder-aware backtracking ---- */
      Local number &gidx = 0;
      If &node.Exists("idx") Then
         &gidx = &node.GetValue("idx", True);
      End-If;
      
      Local Hash &grpChild = &node.GetValue("child", True);
      Local string &grpChildType = &grpChild.GetValue("type", True);
      
      /* Handle flags */
      Local boolean &flagsApplied = False;
      Local boolean &savedIgnore, &savedMultiline, &savedDotAll;
      If &node.Exists("flags_on") Then
         &flagsApplied = True;
         &savedIgnore = &pIgnoreCase;
         &savedMultiline = &pMultiline;
         &savedDotAll = &pDotAll;
         Local string &fstr = &node.GetValue("flags_on", True);
         &pIgnoreCase = (Find("i", &fstr) > 0);
         &pMultiline = (Find("m", &fstr) > 0);
         &pDotAll = (Find("s", &fstr) > 0);
      End-If;
      
      If &grpChildType = "alt" Then
         /* Group contains alternation: merge branch children + remainder */
         Local array of any &altBranches = &grpChild.GetValue("child", True);
         Local number &ai;
         
         For &ai = 1 To &altBranches.Len
            %This.RestoreCaps(&snap);
            
            If &gidx >= 1 Then
               &capsStart [&gidx + 1] = &pos;
            End-If;
            
            Local Hash &branch = &altBranches [&ai];
            Local string &branchType = &branch.GetValue("type", True);
            
            /* Build merged sequence */
            Local array of any &merged = CreateArrayAny();
            
            If &branchType = "seq" Then
               Local array of any &branchChildren = &branch.GetValue("child", True);
               Local number &bi;
               For &bi = 1 To &branchChildren.Len
                  &merged.Push(&branchChildren [&bi]);
               End-For;
            Else
               &merged.Push(&branch);
            End-If;
            
            /* Insert capture-end marker if capturing group */
            If &gidx >= 1 Then
               Local Hash &capEndNode = %This.newNode("cap_end");
               &capEndNode.SetValue("gidx", &gidx);
               &merged.Push(&capEndNode);
            End-If;
            
            /* Append remaining outer children */
            Local number &ri;
            For &ri = &childIdx + 1 To &children.Len
               &merged.Push(&children [&ri]);
            End-For;
            
            If %This.MatchSeqFrom(&merged, &subj, &pos, 1, &outEnd) Then
               If &flagsApplied Then
                  &pIgnoreCase = &savedIgnore;
                  &pMultiline = &savedMultiline;
                  &pDotAll = &savedDotAll;
               End-If;
               Return True;
            End-If;
         End-For;
         
         /* No branch worked */
         %This.RestoreCaps(&snap);
         If &flagsApplied Then
            &pIgnoreCase = &savedIgnore;
            &pMultiline = &savedMultiline;
            &pDotAll = &savedDotAll;
         End-If;
         If &canMemo Then
            &failCache.SetValue(&seqCacheKey, True);
         End-If;
         Return False;
         
      Else
         /* Non-alt child: merge into remainder for full backtracking */
         If &gidx >= 1 Then
            &capsStart [&gidx + 1] = &pos;
         End-If;
         
         &merged = CreateArrayAny();
         
         If &grpChildType = "seq" Then
            Local array of any &innerChildren = &grpChild.GetValue("child", True);
            Local number &mi;
            For &mi = 1 To &innerChildren.Len
               &merged.Push(&innerChildren [&mi]);
            End-For;
         Else
            &merged.Push(&grpChild);
         End-If;
         
         /* Insert capture-end marker if capturing group */
         If &gidx >= 1 Then
            Local Hash &capEndNode2 = %This.newNode("cap_end");
            &capEndNode2.SetValue("gidx", &gidx);
            &merged.Push(&capEndNode2);
         End-If;
         
         /* Append remaining outer children */
         Local number &ri2;
         For &ri2 = &childIdx + 1 To &children.Len
            &merged.Push(&children [&ri2]);
         End-For;
         
         If %This.MatchSeqFrom(&merged, &subj, &pos, 1, &outEnd) Then
            If &flagsApplied Then
               &pIgnoreCase = &savedIgnore;
               &pMultiline = &savedMultiline;
               &pDotAll = &savedDotAll;
            End-If;
            Return True;
         End-If;
         
         %This.RestoreCaps(&snap);
         If &flagsApplied Then
            &pIgnoreCase = &savedIgnore;
            &pMultiline = &savedMultiline;
            &pDotAll = &savedDotAll;
         End-If;
         If &canMemo Then
            &failCache.SetValue(&seqCacheKey, True);
         End-If;
         Return False;
      End-If;
   When = "alt"
      &snap = %This.CopyCaps();
      &altBranches = &node.GetValue("child", True);
      
      For &ai = 1 To &altBranches.Len
         %This.RestoreCaps(&snap);
         
         Local Hash &altBranch = &altBranches [&ai];
         Local string &altBrType = &altBranch.GetValue("type", True);
         
         /* Build merged sequence: branch children + remainder */
         &merged = CreateArrayAny();
         
         If &altBrType = "seq" Then
            Local array of any &brKids = &altBranch.GetValue("child", True);
            For &bi = 1 To &brKids.Len
               &merged.Push(&brKids [&bi]);
            End-For;
         Else
            &merged.Push(&altBranch);
         End-If;
         
         /* Append remaining outer children */
         For &ri = &childIdx + 1 To &children.Len
            &merged.Push(&children [&ri]);
         End-For;
         
         If %This.MatchSeqFrom(&merged, &subj, &pos, 1, &outEnd) Then
            Return True;
         End-If;
      End-For;
      
      %This.RestoreCaps(&snap);
      If &canMemo Then
         &failCache.SetValue(&seqCacheKey, True);
      End-If;
      Return False;
   When-Other
      /* ---- All other node types: single match, then recurse remainder ---- */
      
      Local boolean &needsSnap = ( Not (&nodeType = "lit" Or
         &nodeType = "dot" Or
         &nodeType = "class" Or
         &nodeType = "str" Or
         &nodeType = "anchor_start" Or
         &nodeType = "anchor_end"));
      
      If &needsSnap Then
         &snap = %This.CopyCaps();
      End-If;
      
      Local number &nodeEnd;
      If %This.MatchNode(&node, &subj, &pos, &nodeEnd) Then
         If %This.MatchSeqFrom(&children, &subj, &nodeEnd + 1, &childIdx + 1, &outEnd) Then
            Return True;
         End-If;
      End-If;
      
      If &needsSnap Then
         %This.RestoreCaps(&snap);
      End-If;
      
      Return False;
      
   End-Evaluate;
   
end-method;

method FindGroupIndexByName
   /+ &ast as Hash, +/
   /+ &name as String +/
   /+ Returns Number +/
   try
      If Not &ast.Exists("groupNodes") Then
         Return - 1;
      End-If;
      
      Local array of array of any &gnodes = &ast.GetValue("groupNodes", True);
      
      Local array of any &it;
      Local integer &i;
      For &i = 1 To &gnodes.Len
         &it = &gnodes [&i];
         If &it [1] = &name Then
            Return &it [2];
         End-If;
      End-For;
   catch Exception &ex
      Return - 1;
   end-try;
   Return - 1;
end-method;

method FindGroupIndexByOrdinal
   /+ &ast as Hash, +/
   /+ &ord as Number +/
   /+ Returns Number +/
   try
      If Not &ast.Exists("groupNodes") Then
         Return - 1;
      End-If;
      
      Local array of array of any &gnodes = &ast.GetValue("groupNodes", True);
      
      Local array of any &it;
      Local integer &i;
      For &i = 1 To &gnodes.Len
         &it = &gnodes [&i];
         If &it [2] = &ord Then
            Return &i;
         End-If;
      End-For;
   catch Exception &ex
      Return - 1;
   end-try;
   Return - 1;
end-method;

method BuildCaptureCollection
   /+ Returns Array of String +/
   Local array of string &col = CreateArrayRept("", 0);
   
   If &capsStart [1] >= 1 And
         &capsEnd [1] >= &capsStart [1] Then
      &col.Push(%This.SafeMid(&CurSubject, &capsStart [1], &capsEnd [1] - &capsStart [1] + 1));
   Else
      If &col.Len = 0 Then
         &col.Push("");
      End-If;
   End-If;
   
   Local number &i;
   /* Weird here because we want groups 1..N but they are in array slots (1+1)..(N+1) */
   For &i = 2 To &pGroupCount + 1
      If &capsStart [&i] >= 1 And
            &capsEnd [&i] >= &capsStart [&i] Then
         &col.Push(%This.SafeMid(&CurSubject, &capsStart [&i], &capsEnd [&i] - &capsStart [&i] + 1));
      Else
         /* push empty for the group that wasn't used */
         &col.Push("");
      End-If;
   End-For;
   
   Return &col;
end-method;

method Split
   /+ &subj as String +/
   /+ Returns Array of String +/
   If %This.EnableSurrogatePairs Then
      &subj = %This.NormalizeString(&subj);
   End-If;
   Local array of string &res = CreateArrayRept("", 0);
   Local number &pos = 1;
   Local number &L = Len(&subj);
   Local number &foundAt;
   Local array of string &cs;
   Local number &startTry, &mstart, &mend, &matchLen;
   
   /* Empty subject → single empty element */
   If &L = 0 Then
      &res.Push("");
      Return &res;
   End-If;
   
   While True
      &foundAt = 0;
      
      For &startTry = &pos To &L
         &cs = %This.ExecAt(&subj, &startTry);
         If &cs <> Null Then
            &foundAt = &startTry;
            Break;
         End-If;
      End-For;
      
      If &foundAt = 0 Then
         &res.Push(%This.SafeMid(&subj, &pos, - 1));
         Break;
      Else
         &mstart = &capsStart [1];
         &mend = &capsEnd [1];
         
         If &mstart < &pos Then
            &mstart = &pos;
         End-If;
         
         /* Push text before the match (captures are discarded) */
         &res.Push(%This.SafeMid(&subj, &pos, &mstart - &pos));
         
         &matchLen = &mend - &mstart + 1;
         If &matchLen <= 0 Then
            If &foundAt <= &L Then
               If &pos = &foundAt Then
                  &pos = &foundAt + 1;
               Else
                  &pos = &foundAt;
               End-If;
            Else
               &pos = &L + 1;
            End-If;
         Else
            &pos = &mend + 1;
         End-If;
      End-If;
      
      If &pos > &L Then
         &res.Push("");
         Break;
      End-If;
   End-While;
   If %This.EnableSurrogatePairs Then
      Return %This.DenormalizeArray(&res);
   Else
      Return &res;
   End-If;
end-method;

method Escape
   /+ &aInput as String +/
   /+ Returns String +/
   /* Escape a string so it can be used as a literal regex pattern. */
   /* Escapes the common regex metacharacters: \ . ^ $ * + ? ( ) [ ] { } | / */
   Local string &specials = "\.^$*+?()[]{}|/";
   
   Local string &outStr = "";
   Local number &i;
   Local string &ch;
   
   For &i = 1 To Len(&aInput)
      &ch = Substring(&aInput, &i, 1);
      If Find(&ch, &specials, 1) > 0 Then
         &outStr = &outStr | "\" | &ch;
      Else
         &outStr = &outStr | &ch;
      End-If;
   End-For;
   Return &outStr;
end-method;

method Replace
   /+ &subj as String, +/
   /+ &replacement as String +/
   /+ Returns String +/
   Return %This.ReplaceInternal(&subj, &replacement, True);
end-method;

method Exec
   /+ &subj as String +/
   /+ Returns Array of String +/
   
   /* ── NEW: Normalize subject ── */
   If %This.EnableSurrogatePairs Then
      &subj = %This.NormalizeString(&subj);
   End-If;
   
   &execStartTime = %PerfTime;
   %This.SnapshotCount = 0;
   %This.SnapshotRestoreCount = 0;
   
   &CurSubject = &subj;
   &MatchSteps = 0;
   Local number &minLen;
   &minLen = &pAST.GetValue("minLen", True);
   Local array of string &capColl;
   Local number &L = Len(&subj);
   
   Local number &startLimit;
   If &minLen > 0 Then
      &startLimit = &L - &minLen + 1;
   Else
      &startLimit = &L;
   End-If;
   If &startLimit < 1 Then
      &startLimit = 1;
   End-If;
   
   /* ── Anchored-start: only try position 1 ── */
   Local boolean &isAnchored = False;
   If &pAST.Exists("anchored") Then
      &isAnchored = &pAST.GetValue("anchored", True);
   End-If;
   If &isAnchored Then
      If %This.ExecAt(&subj, 1) <> Null Then
         &capColl = %This.BuildCaptureCollection();
         %This.UpdateNamedCapturesFromAST();
         If %This.EnableSurrogatePairs Then
            Return %This.DenormalizeArray(&capColl);
         Else
            Return &capColl;
         End-If;
      End-If;
      Return Null;
   End-If;
   
   /* ── Prefix skip: jump to candidate positions using Find() ── */
   Local string &prefix = "";
   If &pAST.Exists("prefix") Then
      &prefix = &pAST.GetValue("prefix", True);
   End-If;
   
   If Len(&prefix) > 0 Then
      Local number &searchPos = 1;
      Local number &foundPos;
      While &searchPos <= &startLimit
         If &pIgnoreCase Then
            /* Case-insensitive: scan char-by-char using first char only */
            Local string &firstCh = Substring(&prefix, 1, 1);
            &foundPos = 0;
            Local number &si;
            For &si = &searchPos To &startLimit
               If Lower(Substring(&subj, &si, 1)) = Lower(&firstCh) Then
                  &foundPos = &si;
                  Break;
               End-If;
            End-For;
         Else
            &foundPos = Find(&prefix, &subj, &searchPos);
         End-If;
         
         If &foundPos = 0 Or
               &foundPos > &startLimit Then
            Return Null;
         End-If;
         
         If %This.ExecAt(&subj, &foundPos) <> Null Then
            &capColl = %This.BuildCaptureCollection();
            %This.UpdateNamedCapturesFromAST();
            If %This.EnableSurrogatePairs Then
               Return %This.DenormalizeArray(&capColl);
            Else
               Return &capColl;
            End-If;
         End-If;
         
         If &MatchSteps > &pMaxMatchSteps Then
            throw CreateException(0, 0, "Match aborted: too many steps");
         End-If;
         &searchPos = &foundPos + 1;
      End-While;
      Return Null;
   End-If;
   
   /* ── Default linear scan ── */
   Local number &i;
   For &i = 1 To &startLimit
      If %This.ExecAt(&subj, &i) = Null Then
         /* no match at this start */
      Else
         &capColl = %This.BuildCaptureCollection();
         %This.UpdateNamedCapturesFromAST();
         If %This.EnableSurrogatePairs Then
            Return %This.DenormalizeArray(&capColl);
         Else
            Return &capColl;
         End-If;
      End-If;
      If &MatchSteps > &pMaxMatchSteps Then
         throw CreateException(0, 0, "Match aborted: too many steps");
      End-If;
   End-For;
   Return Null;
end-method;

method ExecAt
   /+ &subj as String, +/
   /+ &startPos as Number +/
   /+ Returns Array of String +/
   
   If %This.EnableSurrogatePairs Then
      &subj = %This.NormalizeString(&subj);
   End-If;
   
   &execStartTime = %PerfTime;
   &failCache = CreateHash();
   
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE ExecAt startPos=" | &startPos | " subjLen=" | Len(&subj) | " multiline=" | &pMultiline | " dotAll=" | &pDotAll);
   End-If;
   &CurSubject = &subj;
   &MatchSteps = &MatchSteps + 1;
   
   Local number &totalGroups = &pGroupCount;
   &capsStart = CreateArrayRept(0, &totalGroups + 1);
   &capsEnd = CreateArrayRept(0, &totalGroups + 1);
   
   /* Initialize atomicLocks for this ExecAt attempt (no atomic locks initially) */
   &atomicLocks = CreateArrayRept( False, &totalGroups + 1);
   
   Local number &i;
   For &i = 1 To &totalGroups + 1
      &capsStart [&i + 1] = 0;
      &capsEnd [&i + 1] = - 1;
      &atomicLocks [&i] = False;
   End-For;
   &capsStart [1] = &startPos;
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE ExecAt caps initialized caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
   End-If;
   
   Local number &outEnd = - 1; /* Setting to -1 to be able to detect if it ever gets set */
   Local boolean &ok;
   &ok = %This.MatchNode(&pAST.GetValue("body", True), &subj, &startPos, &outEnd);
   
   If &DEBUG_TRACE Then
      %This.DebugTrace("TRACE ExecAt after MatchNode ok=" | &ok | " outEnd=" | &outEnd | " caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
   End-If;
   
   If &ok Then
      /* ' if outEnd available, ensure capsEnd(0) is synchronized */
      If &outEnd <> - 1 Then
         &capsEnd [1] = &outEnd;
      End-If;
      If &DEBUG_TRACE Then
         %This.DebugTrace("TRACE ExecAt sync caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
      End-If;
      
      /* anchor end is now handled as a node in MatchNode */
      
      If &DEBUG_TRACE Then
         %This.DebugTrace("TRACE ExecAt returning captures caps0=[" | &capsStart [1] | "," | &capsEnd [1] | "]");
      End-If;
      Local array of string &capColl = %This.BuildCaptureCollection();
      %This.UpdateNamedCapturesFromAST(); /* <- keep named captures in sync */
      If %This.EnableSurrogatePairs Then
         Return %This.DenormalizeArray(&capColl);
      Else
         Return &capColl;
      End-If;
      
   Else
      If &DEBUG_TRACE Then
         %This.DebugTrace("TRACE ExecAt MatchNode returned False -> no match");
      End-If;
      Return Null;
   End-If;
   Return Null;
end-method;

/* Ensure AST.top has groupNodes built. Returns the collection (newly built or existing). */
method EnsureGroupNodes
   /+ &ast as Hash +/
   /+ Returns Array2 of Any +/
   If &ast = Null Then
      Return CreateArrayRept(CreateArrayAny(), 0);
   End-If;
   
   If &ast.Exists("groupNodes") Then
      Return &ast.GetValue("groupNodes", True);
   End-If;
   
   Return %This.BuildGroupNodesFromAST(&ast);
end-method;

/* Rebuild the pNamedCaptures collection using the AST's groupNodes index and current caps arrays. */
method UpdateNamedCapturesFromAST
   try
      &pNamedCaptures = CreateHash();
      
      If &pAST = Null Then
         Return;
      End-If;
      If &capsStart = Null Then
         Return;
      End-If;
      
      /* Ensure index exists */
      Local array of array of any &gnodes;
      
      &gnodes = %This.EnsureGroupNodes(&pAST);
      If &gnodes = Null Then
         Return;
      End-If;
      Local number &i;
      Local string &val;
      Local array of any &pair;
      Local string &gname;
      Local number &gidx;
      For &i = 1 To &gnodes.Len
         &pair = &gnodes [&i]; /* Array(name, idx, nodeRef) */
         &gname = &pair [1];
         &gidx = &pair [2];
         Local number &sPos, &ePos;
         &val = "";
         If &gidx > 0 Then
            If &gidx <= &capsStart.Len Then
               &sPos = &capsStart [&gidx + 1];
               &ePos = &capsEnd [&gidx + 1];
               If &sPos >= 1 And
                     &ePos >= &sPos Then
                  &val = Substring(&CurSubject, &sPos, &ePos - &sPos + 1);
               Else
                  &val = "";
               End-If;
            End-If;
         End-If;
         &pNamedCaptures.SetValue(&gname, CreateArrayAny(&gname, &val));
      End-For;
      
   catch Exception &ex;
      %This.DebugTrace(&ex.ToString());
   end-try;
   
end-method;

method DebugTrace
   /+ &msg as String +/
   %Response.Write(&msg | "<br />");
end-method;

method MarkMemoSafe
   /+ &node as Any +/
   /+ Returns Boolean +/
   
   If &node = Null Then
      Return True;
   End-If;
   
   If (String(&node) = "Array") Then
      Local boolean &allSafe = True;
      Local integer &i;
      For &i = 1 To &node.Len
         If Not %This.MarkMemoSafe(&node [&i]) Then
            &allSafe = False;
         End-If;
      End-For;
      Return &allSafe;
   End-If;
   
   If (String(&node) <> "Hash") Then
      Return True;
   End-If;
   
   Local Hash &h = &node;
   If Not &h.Exists("type") Then
      Return True;
   End-If;
   
   Local string &t = &h.GetValue("type", True);
   Local boolean &_;
   /* cond and recurse depend on capture state */
   If (&t = "cond" Or
         &t = "recurse" Or
         &t = "backref") Then
      &h.SetValue("memoSafe", False);
      /* still traverse children so they get marked too */
      If &h.Exists("child") Then
         &_ = %This.MarkMemoSafe(&h.GetValue("child", True));
      End-If;
      If &h.Exists("yes") Then
         &_ = %This.MarkMemoSafe(&h.GetValue("yes", True));
      End-If;
      If &h.Exists("no") Then
         &_ = %This.MarkMemoSafe(&h.GetValue("no", True));
      End-If;
      Return False;
   End-If;
   
   Local boolean &safe = True;
   
   If &h.Exists("child") Then
      If Not %This.MarkMemoSafe(&h.GetValue("child", True)) Then
         &safe = False;
      End-If;
   End-If;
   
   If &h.Exists("yes") Then
      If Not %This.MarkMemoSafe(&h.GetValue("yes", True)) Then
         &safe = False;
      End-If;
   End-If;
   
   If &h.Exists("no") Then
      If Not %This.MarkMemoSafe(&h.GetValue("no", True)) Then
         &safe = False;
      End-If;
   End-If;
   
   &h.SetValue("memoSafe", &safe);
   Return &safe;
end-method;

method OptimizeAST
   /+ &ast as Hash +/
   If &ast = Null Then
      Return;
   End-If;
   
   /* ── Toggle individual optimizations ── */
   &optDeadNodeElim = True;
   &optSingleChildElim = True;
   &optQuantSimplify = True;
   &optClassSimplify = True;
   &optGroupFlatten = True;
   &optLitConcat = True;
   &optAltFactor = True;
   &optAnchoredStart = True;
   &optPrefixExtract = True;
   
   /* ── Run recursive bottom-up pass ── */
   Local Hash &body = &ast.GetValue("body", True);
   &body = %This.OptimizeNode(&body);
   &body = %This.OptimizeNode(&body);
   &ast.SetValue("body", &body);
   
   /* ── Anchored-start detection ── */
   If &optAnchoredStart Then
      Local boolean &anchored = False;
      Local string &bt = &body.GetValue("type", True);
      
      /* Direct anchor at root */
      If &bt = "anchor_start" Or
            &bt = "anchor_start_abs" Then
         &anchored = True;
      End-If;
      
      /* Seq whose first child is an anchor */
      If Not &anchored And
            &bt = "seq" Then
         Local array of any &topKids = &body.GetValue("child", True);
         If &topKids.Len >= 1 Then
            Local string &fType = &topKids [1].GetValue("type", True);
            If &fType = "anchor_start" Or
                  &fType = "anchor_start_abs" Then
               &anchored = True;
            End-If;
         End-If;
      End-If;
      
      /* Alt where every branch is anchored */
      If Not &anchored And
            &bt = "alt" Then
         Local array of any &altKids = &body.GetValue("child", True);
         Local boolean &allAnchored = True;
         Local integer &ai;
         For &ai = 1 To &altKids.Len
            Local Hash &ancBranch = &altKids [&ai];
            Local string &brType = &ancBranch.GetValue("type", True);
            Local boolean &brIsAnchored = False;
            If &brType = "anchor_start" Or
                  &brType = "anchor_start_abs" Then
               &brIsAnchored = True;
            End-If;
            If Not &brIsAnchored And
                  &brType = "seq" Then
               Local array of any &brKids = &ancBranch.GetValue("child", True);
               If &brKids.Len >= 1 Then
                  Local string &brfType = &brKids [1].GetValue("type", True);
                  If &brfType = "anchor_start" Or
                        &brfType = "anchor_start_abs" Then
                     &brIsAnchored = True;
                  End-If;
               End-If;
            End-If;
            If Not &brIsAnchored Then
               &allAnchored = False;
               Break;
            End-If;
         End-For;
         &anchored = &allAnchored;
      End-If;
      
      &ast.SetValue("anchored", &anchored);
   End-If;
   
   /* ── Fixed-prefix extraction ── */
   If &optPrefixExtract Then
      Local string &prefix = "";
      Local string &pt = &body.GetValue("type", True);
      
      If &pt = "lit" Then
         &prefix = &body.GetValue("ch", True);
      Else
         If &pt = "str" Then
            &prefix = &body.GetValue("val", True);
         Else
            If &pt = "seq" Then
               Local array of any &seqKids = &body.GetValue("child", True);
               Local integer &pi;
               For &pi = 1 To &seqKids.Len
                  Local Hash &pNode = &seqKids [&pi];
                  Local string &pnt = &pNode.GetValue("type", True);
                  /* Skip anchors at the front */
                  If &pnt = "anchor_start" Or
                        &pnt = "anchor_start_abs" Then
                     Continue;
                  End-If;
                  If &pnt = "lit" Then
                     &prefix = &prefix | &pNode.GetValue("ch", True);
                  Else
                     If &pnt = "str" Then
                        &prefix = &prefix | &pNode.GetValue("val", True);
                     Else
                        Break;
                     End-If;
                  End-If;
               End-For;
            End-If;
         End-If;
      End-If;
      
      &ast.SetValue("prefix", &prefix);
   End-If;
   
end-method;


method OptimizeNode
   /+ &node as Hash +/
   /+ Returns Hash +/
   If &node = Null Then
      Return &node;
   End-If;
   Local string &t = &node.GetValue("type", True);
   Local integer &i;
   Local array of any &children;
   
   /* ════════════════════════════════════════════
      Step 1: Recurse into children (bottom-up)
      ════════════════════════════════════════════ */
   Evaluate &t
   When = "seq"
   When = "alt"
      &children = &node.GetValue("child", True);
      For &i = 1 To &children.Len
         &children [&i] = %This.OptimizeNode(&children [&i]);
      End-For;
      Break;
   When = "group"
   When = "atomic"
   When = "lookahead_pos"
   When = "lookahead_neg"
   When = "lookbehind_pos"
   When = "lookbehind_neg"
   When = "quant"
      &node.SetValue("child", %This.OptimizeNode(&node.GetValue("child", True)));
      Break;
   When = "cond"
      If &node.Exists("yes") Then
         &node.SetValue("yes", %This.OptimizeNode(&node.GetValue("yes", True)));
      End-If;
      If &node.Exists("no") Then
         &node.SetValue("no", %This.OptimizeNode(&node.GetValue("no", True)));
      End-If;
      Break;
   End-Evaluate;
   
   /* ════════════════════════════════════════════
      Step 2: Dead node elimination
      ════════════════════════════════════════════ */
   If &optDeadNodeElim Then
      /* quant with max=0 → empty seq (matches nothing consumed) */
      If &t = "quant" Then
         Local number &dMax = &node.GetValue("max", True);
         If &dMax = 0 Then
            Local Hash &emptySeq = %This.newNode("seq");
            &emptySeq.SetValue("child", CreateArrayAny());
            Return &emptySeq;
         End-If;
      End-If;
      
      /* seq: remove empty seq children that contribute nothing */
      If &t = "seq" Then
         &children = &node.GetValue("child", True);
         Local array of any &pruned = CreateArrayAny();
         For &i = 1 To &children.Len
            Local Hash &dc = &children [&i];
            Local string &dct = &dc.GetValue("type", True);
            Local boolean &isDead = False;
            If &dct = "seq" Then
               Local array of any &dcKids = &dc.GetValue("child", True);
               If &dcKids.Len = 0 Then
                  &isDead = True;
               End-If;
            End-If;
            If Not &isDead Then
               &pruned.Push(&dc);
            End-If;
         End-For;
         &node.SetValue("child", &pruned);
      End-If;
      
      /* alt: remove dead branches */
      If &t = "alt" Then
         &children = &node.GetValue("child", True);
         &pruned = CreateArrayAny();
         For &i = 1 To &children.Len
            Local Hash &ab = &children [&i];
            Local string &abt = &ab.GetValue("type", True);
            Local boolean &abDead = False;
            If &abt = "quant" Then
               If &ab.GetValue("max", True) = 0 Then
                  &abDead = True;
               End-If;
            End-If;
            If Not &abDead Then
               &pruned.Push(&ab);
            End-If;
         End-For;
         If &pruned.Len > 0 Then
            &node.SetValue("child", &pruned);
         End-If;
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 2b: Alt with empty branch → optional
      ════════════════════════════════════════════ */
   If &optDeadNodeElim And
         &t = "alt" Then
      &children = &node.GetValue("child", True);
      If &children.Len = 2 Then
         Local boolean &firstEmpty = False;
         Local boolean &secondEmpty = False;
         
         If &children [1].GetValue("type", True) = "seq" Then
            Local array of any &ch1Kids = &children [1].GetValue("child", True);
            If &ch1Kids.Len = 0 Then
               &firstEmpty = True;
            End-If;
         End-If;
         If &children [2].GetValue("type", True) = "seq" Then
            Local array of any &ch2Kids = &children [2].GetValue("child", True);
            If &ch2Kids.Len = 0 Then
               &secondEmpty = True;
            End-If;
         End-If;
         
         /* alt[X, empty] → X? (greedy) */
         If &secondEmpty And
               Not &firstEmpty Then
            Local Hash &optQuant = %This.newNode("quant");
            &optQuant.SetValue("child", &children [1]);
            &optQuant.SetValue("min", 0);
            &optQuant.SetValue("max", 1);
            &optQuant.SetValue("lazy", False);
            &optQuant.SetValue("possessive", False);
            Return &optQuant;
         End-If;
         
         /* alt[empty, X] → X? (lazy, since empty branch tried first) */
         If &firstEmpty And
               Not &secondEmpty Then
            Local Hash &optQuantL = %This.newNode("quant");
            &optQuantL.SetValue("child", &children [2]);
            &optQuantL.SetValue("min", 0);
            &optQuantL.SetValue("max", 1);
            &optQuantL.SetValue("lazy", True);
            &optQuantL.SetValue("possessive", False);
            Return &optQuantL;
         End-If;
      End-If;
   End-If;
   /* ════════════════════════════════════════════
      Step 2c: Quant over zero-width child is no-op
      A quantifier whose child can only match empty
      string always succeeds consuming nothing.
      ════════════════════════════════════════════ */
   If &optDeadNodeElim And
         &t = "quant" Then
      Local Hash &qChild = &node.GetValue("child", True);
      Local number &childMaxLen = %This.ComputeMaxLen(&qChild);
      If &childMaxLen = 0 Then
         Local Hash &noopSeq = %This.newNode("seq");
         &noopSeq.SetValue("child", CreateArrayAny());
         Return &noopSeq;
      End-If;
   End-If;
   /* ════════════════════════════════════════════
      Step 3: Quantifier simplification
      ════════════════════════════════════════════ */
   If &optQuantSimplify And
         &t = "quant" Then
      Local number &qmin = &node.GetValue("min", True);
      Local number &qmax = &node.GetValue("max", True);
      /* {1,1} with no lazy/possessive → just the child */
      If &qmin = 1 And
            &qmax = 1 And
            Not &node.GetValue("lazy", True) And
            Not &node.GetValue("possessive", True) Then
         Return &node.GetValue("child", True);
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 4: Character class simplification
      ════════════════════════════════════════════ */
   If &optClassSimplify And
         &t = "class" Then
      Local boolean &negated = False;
      If &node.Exists("neg") Then
         &negated = &node.GetValue("neg", True);
      End-If;
      
      If Not &negated And
            &node.Exists("chars") Then
         Local array of array of string &clsChars = &node.GetValue("chars", True);
         /* Single literal char → lit node */
         If &clsChars.Len = 1 Then
            Local array of string &item = &clsChars [1];
            If &item [1] <> "range" Then
               Local Hash &litRepl = %This.newNode("lit");
               &litRepl.SetValue("ch", &item [1]);
               If &node.Exists("flags_on") Then
                  &litRepl.SetValue("flags_on", &node.GetValue("flags_on", True));
               End-If;
               Return &litRepl;
            End-If;
            /* Single range of width 1 like [a-a] → lit */
            If &item [1] = "range" And
                  &item [2] = &item [3] Then
               &litRepl = %This.newNode("lit");
               &litRepl.SetValue("ch", &item [2]);
               If &node.Exists("flags_on") Then
                  &litRepl.SetValue("flags_on", &node.GetValue("flags_on", True));
               End-If;
               Return &litRepl;
            End-If;
         End-If;
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 5: Single-child elimination
      ════════════════════════════════════════════ */
   If &optSingleChildElim Then
      If &t = "seq" Then
         &children = &node.GetValue("child", True);
         If &children.Len = 1 Then
            Return &children [1];
         End-If;
      End-If;
      If &t = "alt" Then
         &children = &node.GetValue("child", True);
         If &children.Len = 1 Then
            Return &children [1];
         End-If;
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 5b: Unwrap standalone non-capturing groups
      ════════════════════════════════════════════ */
   If &optGroupFlatten And
         &t = "group" And
         Not &node.Exists("idx") And
         Not &node.Exists("flags_on") Then
      Local boolean &isNonCap = False;
      If &node.Exists("noncap_syntax") Then
         &isNonCap = &node.GetValue("noncap_syntax", True);
      End-If;
      If &isNonCap Then
         Return &node.GetValue("child", True);
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 6: Non-capturing group flattening
      (only applies inside seq nodes)
      ════════════════════════════════════════════ */
   If &optGroupFlatten And
         &t = "seq" Then
      &children = &node.GetValue("child", True);
      Local array of any &flatChildren = CreateArrayAny();
      Local boolean &flatChanged = False;
      
      For &i = 1 To &children.Len
         Local Hash &fc = &children [&i];
         Local string &fct = &fc.GetValue("type", True);
         
         /* Candidate: non-capturing group with no flags and no idx */
         Local boolean &canFlatten = False;
         If &fct = "group" And
               Not &fc.Exists("idx") And
               Not &fc.Exists("flags_on") Then
            &canFlatten = True;
         End-If;
         /* Also flatten if it has noncap_syntax but still no idx or flags */
         If &fct = "group" And
               &fc.Exists("noncap_syntax") And
               Not &fc.Exists("idx") And
               Not &fc.Exists("flags_on") Then
            &canFlatten = True;
         End-If;
         
         If &canFlatten Then
            Local Hash &gc = &fc.GetValue("child", True);
            Local string &gct = &gc.GetValue("type", True);
            If &gct = "seq" Then
               /* Splice inner seq's children into outer seq */
               Local array of any &innerKids = &gc.GetValue("child", True);
               Local integer &j;
               For &j = 1 To &innerKids.Len
                  &flatChildren.Push(&innerKids [&j]);
               End-For;
               &flatChanged = True;
            Else
               /* Single non-seq child: just unwrap the group */
               &flatChildren.Push(&gc);
               &flatChanged = True;
            End-If;
         Else
            &flatChildren.Push(&fc);
         End-If;
      End-For;
      
      If &flatChanged Then
         &node.SetValue("child", &flatChildren);
         /* Re-check single child after flattening */
         If &optSingleChildElim And
               &flatChildren.Len = 1 Then
            Return &flatChildren [1];
         End-If;
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 6b: Flatten nested seq nodes
      ════════════════════════════════════════════ */
   If &optGroupFlatten And
         &t = "seq" Then
      &children = &node.GetValue("child", True);
      Local array of any &seqFlat = CreateArrayAny();
      Local boolean &seqChanged = False;
      
      For &i = 1 To &children.Len
         Local Hash &sc = &children [&i];
         If &sc.GetValue("type", True) = "seq" Then
            Local array of any &innerSeqKids = &sc.GetValue("child", True);
            Local integer &sj;
            For &sj = 1 To &innerSeqKids.Len
               &seqFlat.Push(&innerSeqKids [&sj]);
            End-For;
            &seqChanged = True;
         Else
            &seqFlat.Push(&sc);
         End-If;
      End-For;
      
      If &seqChanged Then
         &node.SetValue("child", &seqFlat);
         If &optSingleChildElim And
               &seqFlat.Len = 1 Then
            Return &seqFlat [1];
         End-If;
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 7: Literal concatenation folding
      (only applies inside seq nodes)
      ════════════════════════════════════════════ */
   If &optLitConcat And
         &t = "seq" Then
      &children = &node.GetValue("child", True);
      Local array of any &mergedChildren = CreateArrayAny();
      Local string &litBuf = "";
      Local string &litFlags = "";
      
      For &i = 1 To &children.Len
         Local Hash &mc = &children [&i];
         Local string &mct = &mc.GetValue("type", True);
         
         If &mct = "lit" Then
            Local string &mcFlags = "";
            If &mc.Exists("flags_on") Then
               &mcFlags = &mc.GetValue("flags_on", True);
            End-If;
            
            /* Same flags as buffer (or buffer empty) → accumulate */
            If Len(&litBuf) = 0 Or
                  &litFlags = &mcFlags Then
               &litBuf = &litBuf | &mc.GetValue("ch", True);
               &litFlags = &mcFlags;
            Else
               /* Flags differ: flush current buffer, start new one */
               %This.FlushLitBuffer(&mergedChildren, &litBuf, &litFlags);
               &litBuf = &mc.GetValue("ch", True);
               &litFlags = &mcFlags;
            End-If;
         Else
            If &mct = "str" Then
               /* Already merged str from a previous pass or nested opt */
               Local string &msFlags = "";
               If &mc.Exists("flags_on") Then
                  &msFlags = &mc.GetValue("flags_on", True);
               End-If;
               If Len(&litBuf) = 0 Or
                     &litFlags = &msFlags Then
                  &litBuf = &litBuf | &mc.GetValue("val", True);
                  &litFlags = &msFlags;
               Else
                  %This.FlushLitBuffer(&mergedChildren, &litBuf, &litFlags);
                  &litBuf = &mc.GetValue("val", True);
                  &litFlags = &msFlags;
               End-If;
            Else
               /* Non-literal node: flush buffer then push node */
               If Len(&litBuf) > 0 Then
                  %This.FlushLitBuffer(&mergedChildren, &litBuf, &litFlags);
                  &litBuf = "";
                  &litFlags = "";
               End-If;
               &mergedChildren.Push(&mc);
            End-If;
         End-If;
      End-For;
      
      /* Final flush */
      If Len(&litBuf) > 0 Then
         %This.FlushLitBuffer(&mergedChildren, &litBuf, &litFlags);
      End-If;
      
      &node.SetValue("child", &mergedChildren);
      
      /* Re-check single child */
      If &optSingleChildElim And
            &mergedChildren.Len = 1 Then
         Return &mergedChildren [1];
      End-If;
   End-If;
   
   /* ════════════════════════════════════════════
      Step 8: Alternation prefix factoring
      (builds trie-like structure for shared prefixes)
      ════════════════════════════════════════════ */
   If &optAltFactor And
         &t = "alt" Then
      &children = &node.GetValue("child", True);
      If &children.Len >= 2 Then
         /* Group branches by leading character */
         Local Hash &charGroups = CreateHash(); /* char → array of number (indices) */
         Local array of string &charOrder = CreateArrayRept("", 0); /* preserve order */
         Local array of number &unfactored = CreateArrayRept(0, 0);
         
         For &i = 1 To &children.Len
            Local string &lc = %This.GetLeadingChar(&children [&i]);
            If Len(&lc) > 0 Then
               If &charGroups.Exists(&lc) Then
                  Local array of number &existing = &charGroups.GetValue(&lc, True);
                  &existing.Push(&i);
               Else
                  Local array of number &newArr = CreateArrayRept(0, 0);
                  &newArr.Push(&i);
                  &charGroups.SetValue(&lc, &newArr);
                  &charOrder.Push(&lc);
               End-If;
            Else
               &unfactored.Push(&i);
            End-If;
         End-For;
         
         /* Only proceed if at least one char group has multiple branches */
         Local boolean &worthFactoring = False;
         Local integer &ci;
         For &ci = 1 To &charOrder.Len
            Local array of number &grp = &charGroups.GetValue(&charOrder [&ci], True);
            If &grp.Len > 1 Then
               &worthFactoring = True;
               Break;
            End-If;
         End-For;
         
         If &worthFactoring Then
            Local array of any &newBranches = CreateArrayAny();
            
            For &ci = 1 To &charOrder.Len
               Local string &leadCh = &charOrder [&ci];
               Local array of number &indices = &charGroups.GetValue(&leadCh, True);
               
               If &indices.Len = 1 Then
                  /* Single branch with this lead char → keep as-is */
                  &newBranches.Push(&children [&indices [1]]);
               Else
                  /* Multiple branches share lead char → factor out */
                  Local Hash &charLit = %This.newNode("lit");
                  &charLit.SetValue("ch", &leadCh);
                  
                  Local array of any &tails = CreateArrayAny();
                  Local integer &gi;
                  For &gi = 1 To &indices.Len
                     Local Hash &stripped = %This.StripLeadingChar(&children [&indices [&gi]]);
                     &tails.Push(&stripped);
                  End-For;
                  
                  /* Build sub-alternation from tails */
                  Local Hash &subAlt;
                  If &tails.Len = 1 Then
                     &subAlt = &tails [1];
                  Else
                     &subAlt = %This.newNode("alt");
                     &subAlt.SetValue("child", &tails);
                     /* Recursively factor the sub-alt (builds trie) */
                     &subAlt = %This.OptimizeNode(&subAlt);
                  End-If;
                  
                  /* Wrap in seq: [leadChar, subAlt] */
                  Local Hash &factoredSeq = %This.newNode("seq");
                  Local array of any &factoredKids = CreateArrayAny();
                  &factoredKids.Push(&charLit);
                  /* If subAlt is a seq, splice to avoid nested seqs */
                  If &subAlt.GetValue("type", True) = "seq" Then
                     Local array of any &subKids = &subAlt.GetValue("child", True);
                     Local integer &si;
                     For &si = 1 To &subKids.Len
                        &factoredKids.Push(&subKids [&si]);
                     End-For;
                  Else
                     &factoredKids.Push(&subAlt);
                  End-If;
                  &factoredSeq.SetValue("child", &factoredKids);
                  
                  /* If the seq ended up with one child, unwrap */
                  If &factoredKids.Len = 1 Then
                     &newBranches.Push(&factoredKids [1]);
                  Else
                     &newBranches.Push(&factoredSeq);
                  End-If;
               End-If;
            End-For;
            
            /* Add unfactored branches */
            For &ci = 1 To &unfactored.Len
               &newBranches.Push(&children [&unfactored [&ci]]);
            End-For;
            
            For &ci = 1 To &newBranches.Len
               &newBranches [&ci] = %This.OptimizeNode(&newBranches [&ci]);
            End-For;
            &node.SetValue("child", &newBranches);
            
            &node.SetValue("child", &newBranches);
            
            /* If we ended up with single branch, unwrap */
            If &optSingleChildElim And
                  &newBranches.Len = 1 Then
               Return &newBranches [1];
            End-If;
         End-If;
      End-If;
   End-If;
   /* ════════════════════════════════════════════
      Step 9: Re-wrap quant-of-quant
      A quantifier directly wrapping another quantifier
      is not valid — needs a group wrapper to be meaningful.
      ════════════════════════════════════════════ */
   If &t = "quant" Then
      &qChild = &node.GetValue("child", True);
      If &qChild.GetValue("type", True) = "quant" Then
         Local Hash &wrapGrp = %This.newNode("group");
         &wrapGrp.SetValue("noncap_syntax", True);
         &wrapGrp.SetValue("child", &qChild);
         &node.SetValue("child", &wrapGrp);
      End-If;
   End-If;
   
   
   /* ════════════════════════════════════════════
      Step 10: Collapse nested quantifiers on same atom
      ════════════════════════════════════════════ */
   If &optQuantSimplify And
         &t = "quant" Then
      &qChild = &node.GetValue("child", True);
      If &qChild.GetValue("type", True) = "group" And
            Not &qChild.Exists("idx") And
            Not &qChild.Exists("flags_on") Then
         Local Hash &grandChild = &qChild.GetValue("child", True);
         If &grandChild.GetValue("type", True) = "quant" Then
            Local number &innerMin = &grandChild.GetValue("min", True);
            Local number &innerMax = &grandChild.GetValue("max", True);
            Local number &outerMin = &node.GetValue("min", True);
            Local number &outerMax = &node.GetValue("max", True);
            Local boolean &innerLazy = &grandChild.GetValue("lazy", True);
            Local boolean &outerLazy = &node.GetValue("lazy", True);
            
            If &innerMin <= 1 And
                  &outerMin <= 1 And
                  &innerLazy = &outerLazy Then
               Local number &newMin;
               If &innerMin = 1 And
                     &outerMin = 1 Then
                  &newMin = 1;
               Else
                  &newMin = 0;
               End-If;
               
               Local number &newMax;
               If &innerMax = - 1 Or
                     &outerMax = - 1 Then
                  &newMax = - 1;
               Else
                  &newMax = &innerMax * &outerMax;
               End-If;
               
               Local Hash &collapsed = %This.newNode("quant");
               &collapsed.SetValue("child", &grandChild.GetValue("child", True));
               &collapsed.SetValue("min", &newMin);
               &collapsed.SetValue("max", &newMax);
               &collapsed.SetValue("lazy", &outerLazy);
               &collapsed.SetValue("possessive", &node.GetValue("possessive", True));
               Return &collapsed;
            End-If;
         End-If;
      End-If;
   End-If;
   
   Return &node;
end-method;

method FlushLitBuffer
   /+ &outArr as Array of Any out, +/
   /+ &buf as String, +/
   /+ &flags as String +/
   If Len(&buf) = 1 Then
      Local Hash &litN = %This.newNode("lit");
      &litN.SetValue("ch", &buf);
      If Len(&flags) > 0 Then
         &litN.SetValue("flags_on", &flags);
      End-If;
      &outArr.Push(&litN);
   Else
      Local Hash &strN = %This.newNode("str");
      &strN.SetValue("val", &buf);
      If Len(&flags) > 0 Then
         &strN.SetValue("flags_on", &flags);
      End-If;
      &outArr.Push(&strN);
   End-If;
end-method;


method GetLeadingChar
   /+ &node as Hash +/
   /+ Returns String +/
   If &node = Null Then
      Return "";
   End-If;
   
   Local string &t = &node.GetValue("type", True);
   
   Evaluate &t
   When = "lit"
      Return &node.GetValue("ch", True);
   When = "str"
      Return Substring(&node.GetValue("val", True), 1, 1);
   When = "seq"
      Local array of any &kids = &node.GetValue("child", True);
      If &kids.Len >= 1 Then
         Return %This.GetLeadingChar(&kids [1]);
      End-If;
      Return "";
   When = "group"
      /* Only look through non-capturing groups with no flags */
      If Not &node.Exists("idx") And
            Not &node.Exists("flags_on") Then
         Return %This.GetLeadingChar(&node.GetValue("child", True));
      End-If;
      Return "";
   When-Other
      Return "";
   End-Evaluate;
end-method;


method StripLeadingChar
   /+ &node as Hash +/
   /+ Returns Hash +/
   If &node = Null Then
      Local Hash &e = %This.newNode("seq");
      &e.SetValue("child", CreateArrayAny());
      Return &e;
   End-If;
   
   Local string &t = &node.GetValue("type", True);
   
   Evaluate &t
   When = "lit"
      /* Entire node is one char → empty seq */
      Local Hash &empty = %This.newNode("seq");
      &empty.SetValue("child", CreateArrayAny());
      Return &empty;
   When = "str"
      Local string &val = &node.GetValue("val", True);
      If Len(&val) <= 1 Then
         &empty = %This.newNode("seq");
         &empty.SetValue("child", CreateArrayAny());
         Return &empty;
      Else
         If Len(&val) = 2 Then
            Local Hash &litR = %This.newNode("lit");
            &litR.SetValue("ch", Substring(&val, 2, 1));
            If &node.Exists("flags_on") Then
               &litR.SetValue("flags_on", &node.GetValue("flags_on", True));
            End-If;
            Return &litR;
         Else
            Local Hash &strR = %This.newNode("str");
            &strR.SetValue("val", Substring(&val, 2, Len(&val) - 1));
            If &node.Exists("flags_on") Then
               &strR.SetValue("flags_on", &node.GetValue("flags_on", True));
            End-If;
            Return &strR;
         End-If;
      End-If;
   When = "seq"
      Local array of any &kids = &node.GetValue("child", True);
      If &kids.Len = 0 Then
         Return &node;
      End-If;
      Local Hash &strippedFirst = %This.StripLeadingChar(&kids [1]);
      Local array of any &newKids = CreateArrayAny();
      /* If stripped first child is non-empty, keep it */
      Local boolean &isEmpty = False;
      If &strippedFirst.GetValue("type", True) = "seq" Then
         Local array of any &sfKids = &strippedFirst.GetValue("child", True);
         If &sfKids.Len = 0 Then
            &isEmpty = True;
         End-If;
      End-If;
      If Not &isEmpty Then
         &newKids.Push(&strippedFirst);
      End-If;
      Local integer &i;
      For &i = 2 To &kids.Len
         &newKids.Push(&kids [&i]);
      End-For;
      If &newKids.Len = 0 Then
         &empty = %This.newNode("seq");
         &empty.SetValue("child", CreateArrayAny());
         Return &empty;
      End-If;
      If &newKids.Len = 1 Then
         Return &newKids [1];
      End-If;
      Local Hash &newSeq = %This.newNode("seq");
      &newSeq.SetValue("child", &newKids);
      Return &newSeq;
   When = "group"
      Local Hash &strippedChild = %This.StripLeadingChar(&node.GetValue("child", True));
      Local string &scType = &strippedChild.GetValue("type", True);
      /* If the stripped result is a leaf or simple node, don't re-wrap in a group */
      If &scType = "lit" Or
            &scType = "str" Or
            &scType = "dot" Or
            &scType = "class" Then
         Return &strippedChild;
      End-If;
      /* If it's an empty seq, return it directly */
      If &scType = "seq" Then
         Local array of any &scKids = &strippedChild.GetValue("child", True);
         If &scKids.Len = 0 Then
            Return &strippedChild;
         End-If;
      End-If;
      Local Hash &newGrp = %This.newNode("group");
      &newGrp.SetValue("child", &strippedChild);
      If &node.Exists("noncap_syntax") Then
         &newGrp.SetValue("noncap_syntax", True);
      End-If;
      Return &newGrp;
   When-Other
      Return &node;
   End-Evaluate;
end-method;

method PrintASTCompact
   /+ &astNode as Any +/
   /+ Returns String +/
   
   If &astNode = Null Then
      Return "null";
   End-If;
   
   If (String(&astNode) = "Array") Then
      Local array of string &arrParts = CreateArrayRept("", 0);
      Local integer &ai;
      For &ai = 1 To &astNode.Len
         &arrParts.Push(%This.PrintASTCompact(&astNode [&ai]));
      End-For;
      Return "[" | &arrParts.Join(", ") | "]";
   End-If;
   
   If (String(&astNode) <> "Hash") Then
      Return String(&astNode);
   End-If;
   
   Local Hash &h = &astNode;
   If Not &h.Exists("type") Then
      Return "{hash}";
   End-If;
   
   Local string &t = &h.GetValue("type", True);
   
   Evaluate &t
   When = "lit"
      Local string &ch = &h.GetValue("ch", True);
      /* Show special chars by name */
      Evaluate &ch
      When = Char(10)
         &ch = "\n";
         Break;
      When = Char(13)
         &ch = "\r";
         Break;
      When = Char(9)
         &ch = "\t";
         Break;
      End-Evaluate;
      Local string &litOut = "lit(""" | &ch | """)";
      If &h.Exists("flags_on") Then
         &litOut = &litOut | "[" | &h.GetValue("flags_on", True) | "]";
      End-If;
      Return &litOut;
      
   When = "str"
      Local string &val = &h.GetValue("val", True);
      Local string &strOut = "str(""" | &val | """)";
      If &h.Exists("flags_on") Then
         &strOut = &strOut | "[" | &h.GetValue("flags_on", True) | "]";
      End-If;
      Return &strOut;
      
   When = "dot"
      Local string &dotOut = "dot";
      If &h.Exists("flags_on") Then
         &dotOut = &dotOut | "[" | &h.GetValue("flags_on", True) | "]";
      End-If;
      Return &dotOut;
      
   When = "class"
      Local string &clsOut = "class(";
      Local boolean &neg = False;
      If &h.Exists("neg") Then
         &neg = &h.GetValue("neg", True);
      End-If;
      If &neg Then
         &clsOut = &clsOut | "^";
      End-If;
      If &h.Exists("chars") Then
         Local array of array of string &chars = &h.GetValue("chars", True);
         Local array of string &clsParts = CreateArrayRept("", 0);
         Local integer &ci;
         For &ci = 1 To &chars.Len
            Local array of string &item = &chars [&ci];
            If &item [1] = "range" Then
               &clsParts.Push(&item [2] | "-" | &item [3]);
            Else
               &clsParts.Push(&item [1]);
            End-If;
         End-For;
         &clsOut = &clsOut | &clsParts.Join("");
      End-If;
      Return &clsOut | ")";
      
   When = "seq"
      Local array of any &seqKids = &h.GetValue("child", True);
      If &seqKids.Len = 0 Then
         Return "seq:[]";
      End-If;
      Local array of string &seqParts = CreateArrayRept("", 0);
      Local integer &si;
      For &si = 1 To &seqKids.Len
         &seqParts.Push(%This.PrintASTCompact(&seqKids [&si]));
      End-For;
      Return "seq:[" | &seqParts.Join(", ") | "]";
      
   When = "alt"
      Local array of any &altKids = &h.GetValue("child", True);
      Local array of string &altParts = CreateArrayRept("", 0);
      Local integer &ali;
      For &ali = 1 To &altKids.Len
         &altParts.Push(%This.PrintASTCompact(&altKids [&ali]));
      End-For;
      Return "alt:[" | &altParts.Join(" | ") | "]";
      
   When = "quant"
      Local number &mn = &h.GetValue("min", True);
      Local number &mx = &h.GetValue("max", True);
      Local boolean &lazy = &h.GetValue("lazy", True);
      Local boolean &poss = False;
      If &h.Exists("possessive") Then
         &poss = &h.GetValue("possessive", True);
      End-If;
      Local string &qChild = %This.PrintASTCompact(&h.GetValue("child", True));
      Local string &qMax;
      If &mx = - 1 Then
         &qMax = "inf";
      Else
         &qMax = String(&mx);
      End-If;
      Local string &qMod = "";
      If &lazy Then
         &qMod = ", lazy";
      End-If;
      If &poss Then
         &qMod = ", poss";
      End-If;
      Return "quant(" | &qChild | ", {" | &mn | "," | &qMax | "}" | &qMod | ")";
      
   When = "group"
      Local string &gLabel = "group";
      If &h.Exists("idx") Then
         &gLabel = &gLabel | "#" | &h.GetValue("idx", True);
      End-If;
      If &h.Exists("name") Then
         &gLabel = &gLabel | "<" | &h.GetValue("name", True) | ">";
      End-If;
      If &h.Exists("noncap_syntax") Then
         &gLabel = &gLabel | "(nc)";
      End-If;
      If &h.Exists("flags_on") Then
         &gLabel = &gLabel | "[" | &h.GetValue("flags_on", True) | "]";
      End-If;
      Return &gLabel | "(" | %This.PrintASTCompact(&h.GetValue("child", True)) | ")";
      
   When = "atomic"
      Return "atomic(" | %This.PrintASTCompact(&h.GetValue("child", True)) | ")";
      
   When = "lookahead_pos"
      Return "(?=" | %This.PrintASTCompact(&h.GetValue("child", True)) | ")";
      
   When = "lookahead_neg"
      Return "(?!" | %This.PrintASTCompact(&h.GetValue("child", True)) | ")";
      
   When = "lookbehind_pos"
      Local string &lbpW = "";
      If &h.Exists("width") Then
         &lbpW = ", w=" | &h.GetValue("width", True);
      End-If;
      Return "(?<=" | %This.PrintASTCompact(&h.GetValue("child", True)) | &lbpW | ")";
      
   When = "lookbehind_neg"
      Local string &lbnW = "";
      If &h.Exists("width") Then
         &lbnW = ", w=" | &h.GetValue("width", True);
      End-If;
      Return "(?<!" | %This.PrintASTCompact(&h.GetValue("child", True)) | &lbnW | ")";
      
   When = "cond"
      Local string &condText = &h.GetValue("cond", True);
      Local string &condOut = "cond(" | &condText | ", ";
      If &h.Exists("yes") Then
         &condOut = &condOut | "yes=" | %This.PrintASTCompact(&h.GetValue("yes", True));
      End-If;
      If &h.Exists("no") Then
         &condOut = &condOut | ", no=" | %This.PrintASTCompact(&h.GetValue("no", True));
      End-If;
      Return &condOut | ")";
      
   When = "recurse"
      Return "recurse(" | &h.GetValue("target", True) | ")";
      
   When = "cap_end"
      Return "cap_end(#" | &h.GetValue("gidx", True) | ")";
      
   When = "anchor_start"
      Return "^";
   When = "anchor_end"
      Return "$";
   When = "anchor_start_abs"
      Return "\A";
   When = "anchor_end_abs"
      Return "\Z";
   When = "anchor_end_abs_strict"
      Return "\z";
   When = "word_boundary"
      Return "\b";
   When = "word_boundary_neg"
      Return "\B";
   When = "backref"
      Local string &brOut = "backref(";
      If &h.Exists("name") Then
         &brOut = &brOut | "k<" | &h.GetValue("name", True) | ">";
      Else
         &brOut = &brOut | "\" | &h.GetValue("idx", True);
      End-If;
      Return &brOut | ")";
   When-Other
      Return &t | "(?)";
   End-Evaluate;
   
end-method;

method ExpandReplacement
   /+ &caps as Array of String, +/
   /+ &repl as String, +/
   /+ &namedColl as Hash +/
   /+ Returns String +/
   
   Local string &out = "";
   Local number &i = 1;
   Local number &L = Len(&repl);
   Local string &ch;
   
   While &i <= &L
      &ch = Substring(&repl, &i, 1);
      
      If &ch = "$" Then
         &i = &i + 1;
         If &i > &L Then
            /* Trailing $ with nothing after → literal */
            &out = &out | "$";
            Break;
         End-If;
         
         Local string &next = Substring(&repl, &i, 1);
         Local number &nextCode = Code(&next);
         
         Evaluate &next
         When = "$"
            /* $$ → literal $ */
            &out = &out | "$";
            &i = &i + 1;
            Break;
         When = "&"
            /* $& → full match (same as $0) */
            &out = &out | &caps [1];
            &i = &i + 1;
            Break;
         When = "`"
            /* $` → pre-match text */
            If &capsStart [1] > 1 Then
               &out = &out | Substring(&CurSubject, 1, &capsStart [1] - 1);
            End-If;
            &i = &i + 1;
            Break;
         When = "'"
            /* $' → post-match text */
            If &capsEnd [1] < Len(&CurSubject) Then
               &out = &out | Substring(&CurSubject, &capsEnd [1] + 1, Len(&CurSubject) - &capsEnd [1]);
            End-If;
            &i = &i + 1;
            Break;
         When = "{"
            /* ${name} or ${number} */
            &i = &i + 1;
            Local string &nameBuf = "";
            Local boolean &closedBrace = False;
            While &i <= &L
               Local string &bc = Substring(&repl, &i, 1);
               If &bc = "}" Then
                  &closedBrace = True;
                  &i = &i + 1;
                  Break;
               End-If;
               &nameBuf = &nameBuf | &bc;
               &i = &i + 1;
            End-While;
            
            If &closedBrace And
                  Len(&nameBuf) > 0 Then
               If IsNumber(&nameBuf) Then
                  /* ${0}, ${1}, ${12} etc. */
                  Local number &braceIdx = Value(&nameBuf);
                  If &braceIdx >= 0 And
                        &braceIdx + 1 <= &caps.Len Then
                     &out = &out | &caps [&braceIdx + 1];
                  End-If;
               Else
                  /* ${name} → named group lookup */
                  If &namedColl <> Null And
                        &namedColl.Exists(&nameBuf) Then
                     Local array of any &pair = &namedColl.GetValue(&nameBuf, True);
                     &out = &out | String(&pair [2]);
                  End-If;
               End-If;
            Else
               /* Malformed ${... with no closing brace → output literally */
               &out = &out | "${" | &nameBuf;
            End-If;
            Break;
         When-Other
            /* Check for digit → $0 through $99 */
            If &nextCode >= 48 And
                  &nextCode <= 57 Then
               Local string &digits = &next;
               &i = &i + 1;
               
               /* Speculatively grab second digit */
               If &i <= &L Then
                  Local string &second = Substring(&repl, &i, 1);
                  Local number &secCode = Code(&second);
                  If &secCode >= 48 And
                        &secCode <= 57 Then
                     Local number &twoDigit = Value(&digits | &second);
                     If &twoDigit >= 0 And
                           &twoDigit + 1 <= &caps.Len Then
                        /* Two-digit group exists → consume both digits */
                        &digits = &digits | &second;
                        &i = &i + 1;
                     End-If;
                     /* Otherwise leave &i on the second digit; it becomes literal */
                  End-If;
               End-If;
               
               Local number &groupNum = Value(&digits);
               If &groupNum >= 0 And
                     &groupNum + 1 <= &caps.Len Then
                  &out = &out | &caps [&groupNum + 1];
               End-If;
            Else
               /* Unrecognized $ sequence → output both chars literally */
               &out = &out | "$" | &next;
               &i = &i + 1;
            End-If;
            Break;
         End-Evaluate;
         
      Else
         If &ch = "\" Then
            &i = &i + 1;
            If &i > &L Then
               /* Trailing backslash → literal */
               &out = &out | "\";
               Break;
            End-If;
            
            Local string &ech = Substring(&repl, &i, 1);
            Local number &echCode = Code(&ech);
            Evaluate &ech
            When = "n"
               &out = &out | Char(10);
               &i = &i + 1;
               Break;
            When = "r"
               &out = &out | Char(13);
               &i = &i + 1;
               Break;
            When = "t"
               &out = &out | Char(9);
               &i = &i + 1;
               Break;
            When = "\"
               &out = &out | "\";
               &i = &i + 1;
               Break;
            When-Other
               /* \1-\9 backreference */
               If &echCode >= 49 And
                     &echCode <= 57 Then
                  Local number &bref = Value(&ech);
                  If &bref >= 1 And
                        &bref + 1 <= &caps.Len Then
                     &out = &out | &caps [&bref + 1];
                  End-If;
                  &i = &i + 1;
               Else
                  /* Unknown escape → pass through literally */
                  &out = &out | "\" | &ech;
                  &i = &i + 1;
               End-If;
               Break;
            End-Evaluate;
         Else
            /* Ordinary character */
            &out = &out | &ch;
            &i = &i + 1;
         End-If;
      End-If;
   End-While;
   
   Return &out;
end-method;

method ExecAll
   /+ &subj as String +/
   /+ Returns Array2 of String +/
   If %This.EnableSurrogatePairs Then
      &subj = %This.NormalizeString(&subj);
   End-If;
   Local array of array of string &results = CreateArrayRept(CreateArrayRept("", 0), 0);
   Local number &pos = 1;
   Local number &L = Len(&subj);
   Local number &startTry, &foundAt;
   Local array of string &cs;
   Local number &mstart, &mend, &matchLen;
   
   /* Empty subject: try once for zero-width patterns like ^, $, (?=) */
   If &L = 0 Then
      &cs = %This.Exec(&subj);
      If &cs <> Null Then
         &results.Push(&cs);
      End-If;
      Return &results;
   End-If;
   
   While &pos <= &L
      &foundAt = 0;
      
      For &startTry = &pos To &L
         &cs = %This.ExecAt(&subj, &startTry);
         If &cs <> Null Then
            &foundAt = &startTry;
            Break;
         End-If;
      End-For;
      
      If &foundAt = 0 Then
         Break;
      End-If;
      
      /* Build capture collection from current state */
      Local array of string &capColl = %This.BuildCaptureCollection();
      %This.UpdateNamedCapturesFromAST();
      &results.Push(&capColl);
      
      &mstart = &capsStart [1];
      &mend = &capsEnd [1];
      &matchLen = &mend - &mstart + 1;
      
      If &matchLen <= 0 Then
         /* Zero-width match: advance by one to avoid infinite loop */
         &pos = &foundAt + 1;
      Else
         &pos = &mend + 1;
      End-If;
   End-While;
   
   /* One final check past end for trailing zero-width patterns */
   If &pos = &L + 1 Then
      &cs = %This.ExecAt(&subj, &pos);
      If &cs <> Null Then
         Local array of string &finalCap = %This.BuildCaptureCollection();
         %This.UpdateNamedCapturesFromAST();
         &results.Push(&finalCap);
      End-If;
   End-If;
   
   If %This.EnableSurrogatePairs Then
      Local number &ri;
      For &ri = 1 To &results.Len
         &results [&ri] = %This.DenormalizeArray(&results [&ri]);
      End-For;
   End-If;
   
   Return &results;
end-method;

method ReplaceInternal
   /+ &subj as String, +/
   /+ &replacement as String, +/
   /+ &allMatches as Boolean +/
   /+ Returns String +/
   If %This.EnableSurrogatePairs Then
      &subj = %This.NormalizeString(&subj);
      &replacement = %This.NormalizeString(&replacement);
   End-If;
   Local string &out = "";
   Local number &pos = 1;
   Local number &L = Len(&subj);
   Local number &foundAt;
   Local array of string &cs;
   Local number &startTry, &mstart, &mend, &matchLen;
   Local boolean &replaced = False;
   
   /* Fast path: empty subject */
   If &L = 0 Then
      /* Still try: pattern might match empty string */
      &cs = %This.Exec(&subj);
      If &cs <> Null Then
         Local array of string &emptyCaps = %This.BuildCaptureCollection();
         %This.UpdateNamedCapturesFromAST();
         Return %This.ExpandReplacement(&emptyCaps, &replacement, &pNamedCaptures);
      End-If;
      Return "";
   End-If;
   
   While True
      &foundAt = 0;
      
      /* Scan forward to locate the next match */
      For &startTry = &pos To &L
         &cs = %This.ExecAt(&subj, &startTry);
         If &cs <> Null Then
            &foundAt = &startTry;
            Break;
         End-If;
      End-For;
      
      If &foundAt = 0 Then
         /* No more matches → append remainder and finish */
         &out = &out | %This.SafeMid(&subj, &pos, - 1);
         Break;
      Else
         &mstart = &capsStart [1];
         &mend = &capsEnd [1];
         
         /* Ensure mstart is not before current pos */
         If &mstart < &pos Then
            &mstart = &pos;
         End-If;
         
         /* Append text before the match */
         If &mstart > &pos Then
            &out = &out | %This.SafeMid(&subj, &pos, &mstart - &pos);
         End-If;
         
         /* Build captures and expand replacement */
         Local array of string &capColl = %This.BuildCaptureCollection();
         %This.UpdateNamedCapturesFromAST();
         &out = &out | %This.ExpandReplacement(&capColl, &replacement, &pNamedCaptures);
         
         /* Advance position past the match */
         &matchLen = &mend - &mstart + 1;
         If &matchLen <= 0 Then
            /* Zero-width match: copy one char and advance */
            If &foundAt <= &L Then
               &out = &out | Substring(&subj, &foundAt, 1);
            End-If;
            &pos = &foundAt + 1;
         Else
            &pos = &mend + 1;
         End-If;
         
         &replaced = True;
         
         /* ReplaceFirst: stop after one substitution */
         If Not &allMatches Then
            &out = &out | %This.SafeMid(&subj, &pos, - 1);
            Break;
         End-If;
         
         If &pos > &L Then
            Break;
         End-If;
      End-If;
   End-While;
   
   If %This.EnableSurrogatePairs Then
      Return %This.DenormalizeString(&out);
   Else
      Return &out;
   End-If;
end-method;

method ReplaceFirst
   /+ &subj as String, +/
   /+ &replacement as String +/
   /+ Returns String +/
   Return %This.ReplaceInternal(&subj, &replacement, False);
end-method;

method Test
   /+ &subj as String +/
   /+ Returns Boolean +/
   Local array of string &result = %This.Exec(&subj);
   Return (&result <> Null);
end-method;

method SplitWithCaptures
   /+ &subj as String +/
   /+ Returns Array of String +/
   If %This.EnableSurrogatePairs Then
      &subj = %This.NormalizeString(&subj);
   End-If;
   Local array of string &res = CreateArrayRept("", 0);
   Local number &pos = 1;
   Local number &L = Len(&subj);
   Local number &foundAt;
   Local array of string &cs;
   Local number &startTry, &mstart, &mend, &matchLen;
   
   /* Empty subject → single empty element */
   If &L = 0 Then
      &res.Push("");
      Return &res;
   End-If;
   
   While True
      &foundAt = 0;
      
      /* Scan forward to locate next match */
      For &startTry = &pos To &L
         &cs = %This.ExecAt(&subj, &startTry);
         If &cs <> Null Then
            &foundAt = &startTry;
            Break;
         End-If;
      End-For;
      
      If &foundAt = 0 Then
         /* No more matches → append remainder and finish */
         &res.Push(%This.SafeMid(&subj, &pos, - 1));
         Break;
      Else
         Local array of string &capColl = %This.BuildCaptureCollection();
         %This.UpdateNamedCapturesFromAST();
         
         &mstart = &capsStart [1];
         &mend = &capsEnd [1];
         
         /* Ensure mstart is not before current pos */
         If &mstart < &pos Then
            &mstart = &pos;
         End-If;
         
         /* Push text before the match */
         &res.Push(%This.SafeMid(&subj, &pos, &mstart - &pos));
         
         /* Push captured groups (indices 1..N, which are &capColl slots 2..N+1) */
         Local number &gi;
         For &gi = 2 To &capColl.Len
            &res.Push(&capColl [&gi]);
         End-For;
         
         /* Advance past the match */
         &matchLen = &mend - &mstart + 1;
         If &matchLen <= 0 Then
            /* Zero-width match: include current char in next segment */
            If &foundAt <= &L Then
               /* Don't split on zero-width at same position repeatedly.
                  Push the char and move forward. */
               If &pos = &foundAt Then
                  &pos = &foundAt + 1;
               Else
                  &pos = &foundAt;
               End-If;
            Else
               &pos = &L + 1;
            End-If;
         Else
            &pos = &mend + 1;
         End-If;
      End-If;
      
      If &pos > &L Then
         /* Trailing empty string (match was at the end) */
         &res.Push("");
         Break;
      End-If;
   End-While;
   If %This.EnableSurrogatePairs Then
      Return %This.DenormalizeArray(&res);
   Else
      Return &res;
   End-If;
end-method;

method NormalizeString
   /+ &str as String +/
   /+ Returns String +/
   
   Local number &sLen = Len(&str);
   If &sLen = 0 Then
      Return "";
   End-If;
   
   Local string &result = "";
   Local number &i = 1;
   
   While &i <= &sLen
      Local string &ch = Substring(&str, &i, 1);
      Local number &code = Code(&ch);
      
      /* Check for high surrogate */
      If &code >= &HIGH_SURROGATE_START And
            &code <= &HIGH_SURROGATE_END Then
         
         /* Check if next code unit is a low surrogate */
         If &i + 1 <= &sLen Then
            Local string &next = Substring(&str, &i + 1, 1);
            Local number &nextCode = Code(&next);
            
            If &nextCode >= &LOW_SURROGATE_START And
                  &nextCode <= &LOW_SURROGATE_END Then
               /* Valid surrogate pair — look up or assign PUA char */
               Local string &pair = &ch | &next;
               
               If &surrogateToPua.Exists(&pair) Then
                  &result = &result | &surrogateToPua.GetValue(&pair, True);
               Else
                  /* Check capacity */
                  If &nextPuaCode > &PUA_END Then
                     throw CreateException(0, 0, "PUA capacity exceeded: more than 6400 unique non-BMP characters");
                  End-If;
                  
                  Local string &puaChar = Char(&nextPuaCode);
                  &surrogateToPua.SetValue(&pair, &puaChar);
                  &puaToSurrogate.SetValue(&puaChar, &pair);
                  &nextPuaCode = &nextPuaCode + 1;
                  &result = &result | &puaChar;
               End-If;
               
               &i = &i + 2; /* consumed both code units */
            Else
               /* High surrogate followed by non-low-surrogate: orphan, pass through */
               &result = &result | &ch;
               &i = &i + 1;
            End-If;
         Else
            /* High surrogate at end of string: orphan, pass through */
            &result = &result | &ch;
            &i = &i + 1;
         End-If;
      Else
         /* Normal BMP character — pass through */
         &result = &result | &ch;
         &i = &i + 1;
      End-If;
   End-While;
   
   Return &result;
end-method;

method DenormalizeString
   /+ &str as String +/
   /+ Returns String +/
   
   Local number &sLen = Len(&str);
   If &sLen = 0 Then
      Return "";
   End-If;
   
   Local string &result = "";
   Local number &i;
   
   For &i = 1 To &sLen
      Local string &ch = Substring(&str, &i, 1);
      
      If &puaToSurrogate.Exists(&ch) Then
         &result = &result | &puaToSurrogate.GetValue(&ch, True);
      Else
         &result = &result | &ch;
      End-If;
   End-For;
   
   Return &result;
end-method;

method DenormalizeArray
   /+ &arr as Array of String +/
   /+ Returns Array of String +/
   
   If &arr = Null Then
      Return &arr;
   End-If;
   
   Local array of string &out = CreateArrayRept("", 0);
   Local number &i;
   
   For &i = 1 To &arr.Len
      &out.Push(%This.DenormalizeString(&arr [&i]));
   End-For;
   
   Return &out;
end-method;