@ptolemy2002/rgx 12.5.0 → 12.6.0

package/dist/walker/base.d.ts

@@ -9,6 +9,7 @@ export type RGXWalkerOptions<R, S = unknown> = {
     looping?: boolean;
 };
 export type RGXTokenOrPart<R, S = unknown, T = unknown> = RGXToken | RGXPart<R, S, T>;
+export type RGXWalkerStepDirective = "stop" | "skip" | "silent";
 export declare class RGXWalker<R, S = unknown> {
     readonly source: string;
     _sourcePosition: number;
@@ -39,6 +40,14 @@ export declare class RGXWalker<R, S = unknown> {
     remainingSource(): string | null;
     capture(token: RGXTokenOrPart<R, S>, includeMatch: true): RegExpExecArray;
     capture(token: RGXTokenOrPart<R, S>, includeMatch?: false): string;
+    private advanceToken;
+    private determineBranch;
+    private registerCapture;
+    private unregisterLastCapture;
+    private handleBeforeCapture;
+    private attemptCapture;
+    private validateCapture;
+    private handleAfterCapture;
     step(): RGXCapture | null;
     stepToToken(predicate: (token: RGXTokenOrPart<R>) => boolean): this;
     stepToPart(predicate?: (part: RGXPart<R, S, unknown>) => boolean): this;

package/dist/walker/base.js

@@ -96,6 +96,106 @@ class RGXWalker {
         this.sourcePosition += match[0].length;
         return includeMatch ? match : match[0];
     }
+    advanceToken() {
+        if (!this.infinite || this.tokenPosition < this.tokens.length - 1) {
+            this.tokenPosition++;
+            if (this.looping && this.atTokenEnd()) {
+                this.tokenPosition = 0;
+            }
+        }
+    }
+    determineBranch(capture) {
+        for (let i = 0; i < capture.length - 1; i++) {
+            if (capture.groups?.[`rgx_branch_${i}`] !== undefined)
+                return i;
+        }
+        return 0;
+    }
+    registerCapture(captureResult, token) {
+        this.captures.push(captureResult);
+        if (token instanceof part_1.RGXPart && token.hasId()) {
+            if (!(token.id in this.namedCaptures))
+                this.namedCaptures[token.id] = [];
+            this.namedCaptures[token.id].push(captureResult);
+        }
+    }
+    unregisterLastCapture(token) {
+        this.captures.pop();
+        if (token instanceof part_1.RGXPart && token.hasId()) {
+            this.namedCaptures[token.id].pop();
+        }
+    }
+    handleBeforeCapture(token) {
+        const control = token.beforeCapture?.({ part: token, walker: this });
+        // If this happens, beforeCapture itself stopped the walker, so we just need to respect that.
+        if (this.stopped)
+            return "stop";
+        if (control === "stop" || control === "stop-silent")
+            return "stop";
+        if (control === "skip")
+            return "skip";
+        if (control === "silent")
+            return "silent";
+        return null;
+    }
+    // Returns the capture on success, or a directive on handled failure. Unhandled errors are rethrown.
+    attemptCapture(branchedToken, part) {
+        try {
+            return this.capture(branchedToken, true);
+        }
+        catch (e) {
+            if (part !== null && e instanceof errors_1.RGXRegexNotMatchedAtPositionError) {
+                const control = part.afterFailure?.(e, { part, walker: this });
+                // If this happens, afterFailure itself stopped the walker, so we just need to respect that.
+                if (this.stopped)
+                    return "stop";
+                if (control === "stop" || control === "stop-silent")
+                    return "stop";
+                if (control === "skip")
+                    return "skip";
+                // Handling silent is pointless here since it won't add a capture in either case, so we don't check for it.
+            }
+            throw e;
+        }
+    }
+    // Returns a directive on handled validation failure, null on success. Unhandled errors are rethrown.
+    validateCapture(token, captureResult, start) {
+        try {
+            token.validate(captureResult, { part: token, walker: this });
+            return null;
+        }
+        catch (e) {
+            this.sourcePosition = start; // Reset source position on validation failure
+            if (e instanceof errors_1.RGXPartValidationFailedError) {
+                const control = token.afterValidationFailure?.(e, { part: token, walker: this });
+                // If this happens, afterValidationFailure itself stopped the walker, so we just need to respect that.
+                if (this.stopped)
+                    return "stop";
+                if (control === "stop" || control === "stop-silent")
+                    return "stop";
+                if (control === "skip")
+                    return "skip";
+                // Handling silent is pointless here since it won't add a capture in either case, so we don't check for it.
+            }
+            throw e;
+        }
+    }
+    handleAfterCapture(token, captureResult, silent, start) {
+        const control = token.afterCapture?.(captureResult, { part: token, walker: this });
+        // If this happens, afterCapture itself stopped the walker, so we just need to respect that.
+        if (this.stopped)
+            return "stop";
+        if (!silent && (control === "skip" || control === "silent" || control === "stop-silent")) {
+            this.unregisterLastCapture(token);
+        }
+        if (control === "skip") {
+            this.sourcePosition = start;
+            return "skip";
+        }
+        if (control === "stop" || control === "stop-silent")
+            return "stop";
+        return null;
+    }
     step() {
         if (!this.infinite && !this.looping && this.atTokenEnd()) {
             this._stopped = true;
@@ -109,106 +209,64 @@ class RGXWalker {
         const token = this.currentToken();
         const isPart = token instanceof part_1.RGXPart;
         let silent = false;
-        // Ask Part what to do — control flow via return values, not flags.
         if (isPart) {
-            const control = token.beforeCapture?.({ part: token, walker: this });
-            if (control === "stop") {
+            const dir = this.handleBeforeCapture(token);
+            if (dir === "stop") {
                 this._stopped = true;
                 return null;
             }
-            if (control === "skip") {
-                this.tokenPosition++;
+            if (dir === "skip") {
+                this.advanceToken();
                 return null;
             }
-            if (control === "silent") {
-                silent = true;
-            }
+            silent = dir === "silent";
         }
-        // Capture the match
         const start = this.sourcePosition;
-        let branchedToken;
-        if (isPart)
-            branchedToken = createBranchGroups(token.token);
-        else
-            branchedToken = createBranchGroups(token);
-        let capture;
-        try {
-            capture = this.capture(branchedToken, true);
+        const branchedToken = isPart ? createBranchGroups(token.token) : createBranchGroups(token);
+        const captureAttempt = this.attemptCapture(branchedToken, isPart ? token : null);
+        if (captureAttempt === "stop") {
+            this._stopped = true;
+            return null;
         }
-        catch (e) {
-            if (isPart && e instanceof errors_1.RGXRegexNotMatchedAtPositionError) {
-                const control = token.afterFailure?.(e, { part: token, walker: this });
-                if (control === "stop") {
-                    this._stopped = true;
-                    return null;
-                }
-                if (control === "skip") {
-                    this.tokenPosition++;
-                    return null;
-                }
-                // Handling silent is pointless here since it won't add a capture in either case, so we don't check for it.
-            }
-            throw e;
+        if (captureAttempt === "skip") {
+            this.advanceToken();
+            return null;
         }
-        const raw = isPart ? token.rawTransform(capture[0]) : capture[0];
+        const raw = isPart ? token.rawTransform(captureAttempt[0]) : captureAttempt[0];
         const end = this.sourcePosition;
         const value = isPart ? token.transform(raw) : raw;
-        let branch = 0;
-        // Determine branch index for captureResult by finding the first index
-        // with non-undefined match group.
-        for (let i = 0; i < capture.length - 1; i++) {
-            const branchKey = `rgx_branch_${i}`;
-            if (capture.groups && capture.groups[branchKey] !== undefined) {
-                branch = i;
-                break;
-            }
-        }
         const captureResult = {
-            raw, value, start, end, branch,
+            raw, value, start, end,
+            branch: this.determineBranch(captureAttempt),
             ownerId: isPart && token.hasId() ? token.id : null,
-            groups: capture.groups ?? null
+            groups: captureAttempt.groups ?? null
         };
-        // Validate the part. If validation fails, it will throw an error, so nothing below will run.
         if (isPart) {
-            try {
-                token.validate(captureResult, { part: token, walker: this });
-            }
-            catch (e) {
-                this.sourcePosition = start; // Reset source position on validation failure
-                if (e instanceof errors_1.RGXPartValidationFailedError) {
-                    const control = token.afterValidationFailure?.(e, { part: token, walker: this });
-                    if (control === "stop") {
-                        this._stopped = true;
-                        return null;
-                    }
-                    if (control === "skip") {
-                        this.tokenPosition++;
-                        return null;
-                    }
-                    // Handling silent is pointless here since it won't add a capture in either case, so we don't check for it.
-                }
-                throw e;
+            const dir = this.validateCapture(token, captureResult, start);
+            if (dir === "stop") {
+                this._stopped = true;
+                return null;
             }
-        }
-        // Skip adding the capture if in silent mode.
-        if (!silent) {
-            this.captures.push(captureResult);
-            if (isPart && token.hasId()) {
-                if (!(token.id in this.namedCaptures))
-                    this.namedCaptures[token.id] = [];
-                this.namedCaptures[token.id].push(captureResult);
+            if (dir === "skip") {
+                this.advanceToken();
+                return null;
             }
         }
-        // Notify Part after capture
+        if (!silent)
+            this.registerCapture(captureResult, token);
         if (isPart) {
-            token.afterCapture?.(captureResult, { part: token, walker: this });
-        }
-        if (!this.infinite || this.tokenPosition < this.tokens.length - 1) {
-            this.tokenPosition++;
-            if (this.looping && this.atTokenEnd()) {
-                this.tokenPosition = 0;
+            const dir = this.handleAfterCapture(token, captureResult, silent, start);
+            if (dir === "stop") {
+                this.advanceToken();
+                this._stopped = true;
+                return null;
+            }
+            if (dir === "skip") {
+                this.advanceToken();
+                return null;
             }
         }
+        this.advanceToken();
         return captureResult;
     }
     stepToToken(predicate) {

package/dist/walker/part.d.ts

@@ -2,7 +2,7 @@ import { RGXToken } from "../types";
 import type { RGXWalker } from "./base";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { RGXPartValidationFailedError, RGXRegexNotMatchedAtPositionError } from "../errors";
-export type RGXPartControl = "skip" | "stop" | "silent" | void;
+export type RGXPartControl = "skip" | "stop" | "silent" | "stop-silent" | void;
 export type RGXCapture<T = unknown> = {
     raw: string;
     value: T;
@@ -22,7 +22,7 @@ export type RGXPartOptions<R, S = unknown, T = string> = {
     transform: (captured: string) => T;
     validate: (captured: RGXCapture<T>, context: RGXPartContext<R, S, T>) => boolean | string;
     beforeCapture: ((context: RGXPartContext<R, S, T>) => RGXPartControl) | null;
-    afterCapture: ((capture: RGXCapture<T>, context: RGXPartContext<R, S, T>) => void) | null;
+    afterCapture: ((capture: RGXCapture<T>, context: RGXPartContext<R, S, T>) => RGXPartControl) | null;
     afterFailure: ((e: RGXRegexNotMatchedAtPositionError, context: RGXPartContext<R, S, T>) => RGXPartControl) | null;
     afterValidationFailure: ((e: RGXPartValidationFailedError, context: RGXPartContext<R, S, T>) => RGXPartControl) | null;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ptolemy2002/rgx",
-    "version": "12.5.0",
+    "version": "12.6.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",