@ptolemy2002/rgx 7.0.0 → 7.2.0

package/README.md

@@ -100,6 +100,8 @@ type RGXPartOptions<R, T=string> = {
 type RGXWalkerOptions<R> = {
     startingSourcePosition?: number;
     reduced?: R;
+    infinite?: boolean;
+    looping?: boolean;
 };
 
 type RGXWOptions<R = unknown> = Omit<RGXWalkerOptions<R>, "startingSourcePosition"> & {
@@ -657,6 +659,8 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `options` (`RGXWalkerOptions<R>`, optional): Configuration options. Defaults to `{}`.
   - `startingSourcePosition` (`number`, optional): The starting index in the source string. Defaults to `0`.
   - `reduced` (`R`, optional): The initial value for the `reduced` accumulator. Defaults to `null`.
+  - `infinite` (`boolean`, optional): When `true`, the walker stays at the last token indefinitely rather than stopping when the token collection is exhausted, continuing to match the last token until the source is consumed. Defaults to `false`.
+  - `looping` (`boolean`, optional): When `true`, the walker loops back to token position `0` when the token collection is exhausted, continuing to match from the start until the source is consumed. Defaults to `false`.
 
 #### Properties
 - `source` (`string`): The source string being walked (readonly).
@@ -666,6 +670,8 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `reduced` (`R`): A user-defined accumulator value, typically updated by `RGXPart` callbacks during walking.
 - `captures` (`RGXCapture[]`): An array of structured capture results recorded during walking. Each entry has a `raw` string, a `value` (the transform result for Parts, or the raw string for plain tokens), `start` and `end` indices in the source string, and an `ownerId` that is the `id` of the Part that produced it (or `null` for captures from plain tokens or parts without ids).
 - `namedCaptures` (`Record<string, RGXCapture[]>`): An object mapping capture IDs to their corresponding `RGXCapture` results. Only Parts with non-null IDs are included. The captures occur in the same order as they appear in the `captures` array.
+- `infinite` (`boolean`): Whether the walker is in infinite mode — stays at the last token when the token collection is exhausted until the source is consumed.
+- `looping` (`boolean`): Whether the walker is in looping mode — loops back to token position `0` when the token collection is exhausted until the source is consumed.
 - `stopped` (`boolean`, readonly): Whether the walker has been stopped, either by a Part's `beforeCapture` returning `"stop"` or by calling `stop()` in an `afterCapture` callback.
 
 #### Methods
@@ -678,12 +684,12 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `currentToken() => RGXToken | null`: Returns the token at the current token position, or `null` if at the end.
 - `remainingSource() => string | null`: Returns the remaining source string from the current position onward, or `null` if the source is fully consumed.
 - `capture(token: RGXToken) => string`: Resolves the token to a regex, asserts that it matches at the current source position (throwing `RGXRegexNotMatchedAtPositionError` if not), and advances the source position by the match length. Returns the matched string.
-- `step() => RGXCapture | null`: Steps through the next token in the collection. If the token is an `RGXPart`, calls `beforeCapture` first — if it returns `"stop"`, sets `stopped` and returns `null` without advancing; if `"skip"`, advances the token position and returns `null` without capturing; if `"silent"`, captures but does not add to `captures` or `namedCaptures`. After capturing, validates. After validating, calls `afterCapture` if present. Returns the `RGXCapture` result, or `null` if there are no more tokens, the step was skipped, or the walker was stopped.
+- `step() => RGXCapture | null`: Steps through the next token in the collection. If the token is an `RGXPart`, calls `beforeCapture` first — if it returns `"stop"`, sets `stopped` and returns `null` without advancing; if `"skip"`, advances the token position and returns `null` without capturing; if `"silent"`, captures but does not add to `captures` or `namedCaptures`. After capturing, validates. After validating, calls `afterCapture` if present. Returns the `RGXCapture` result, or `null` if there are no more tokens (or no more source in `infinite`/`looping` mode), the step was skipped, or the walker was stopped.
 - `stepToToken(predicate: (token: RGXToken) => boolean) => void`: Steps through tokens until the predicate returns `true` for the current token or the walker is stopped. The matching token is not consumed.
 - `stepToPart(predicate?: (part: RGXPart<R>) => boolean) => void`: Steps through tokens until the next `RGXPart` satisfying the predicate is reached. If already at a Part, steps once first to move past it. The matching Part is not consumed.
-- `walk() => void`: Steps through all remaining tokens until the end of the token collection or the walker is stopped.
+- `walk() => void`: Steps through all remaining tokens until the end of the token collection (or until the source is consumed in `infinite`/`looping` mode) or the walker is stopped.
 - `toRgx() => RGXToken`: Returns the internal `RGXTokenCollection`, allowing the walker to be used as a convertible token.
-- `clone(depth: CloneDepth = "max") => RGXWalker`: Creates a clone of the walker. When `depth` is `0`, returns `this`; otherwise, creates a new `RGXWalker` with cloned tokens, source position, reduced value, captures, and stopped state.
+- `clone(depth: CloneDepth = "max") => RGXWalker`: Creates a clone of the walker. When `depth` is `0`, returns `this`; otherwise, creates a new `RGXWalker` with cloned tokens, source position, reduced value, captures, stopped state, and the `infinite`/`looping` flags.
 
 ## Functions
 The following functions are exported by the library:
@@ -1354,6 +1360,8 @@ A pre-built `RegExpFlagTransformer` that makes a regex pattern accent-insensitiv
 - `o` / `O`: ó, ò, ö, ô, õ / Ó, Ò, Ö, Ô, Õ
 - `u` / `U`: ú, ù, ü, û / Ú, Ù, Ü, Û
 
+Note that this transformer intentionally excludes replacing characters preceded by an odd number of backslashes, to allow for escaping. For example, in the pattern `\\a`, the `a` is preceded by two backslashes (an even number), so it will be replaced with `(a|á|à|ä|â|ã)`. In the pattern `\a`, the `a` is preceded by one backslash (an odd number), so it will not be replaced.
+
 #### Parameters
   - `exp` (`RegExp`): The regular expression to transform.
 
@@ -1660,6 +1668,11 @@ Since these are defined as native tokens (strings), they are automatically wrapp
 | `"non-word-char"` | `\W` | Any non-word character |
 | `"backspace"` | `[\b]` | Backspace character |
 
+### Complex Constructs
+| Name | Resolves To | Description |
+| --- | --- | --- |
+| `"non-escape-bound"` | `(?<=(?<!\\)(?:\\\\)*)(?=[^\\]\|$)` | Matches a position that is not preceded by an odd number of backslashes, i.e., the next character is not escaped. Note that this doesn't match when the next character is a backslash, since allowing it to do that would cause non-escaped backslashes within a series of backslashes to be treated as escaped. For example, in the string `\\\a`, the first and third backslashes would be treated as escaped. |
+
 ## Peer Dependencies
 - `@ptolemy2002/immutability-utils` ^2.0.0
 - `@ptolemy2002/js-utils` ^3.2.2

package/dist/class/repeat.js

@@ -32,7 +32,7 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         return this._token;
     }
     set token(value) {
-        if ((0, typeGuards_1.isRGXToken)(value, "convertible") && !value.rgxIsRepeatable) {
+        if ((0, typeGuards_1.isRGXToken)(value, "convertible") && typeof value.rgxIsRepeatable === "boolean" && !value.rgxIsRepeatable) {
             if ((0, typeGuards_1.isRGXToken)(value, "class")) {
                 throw new errors_1.RGXNotSupportedError(`Repeating ${value.constructor.name} tokens`, "The token was manually marked as non-repeatable.");
             }

package/dist/constants.js

@@ -191,3 +191,12 @@ defineRGXConstant("backspace", {
         return /[\b]/;
     }
 });
+// Complex Constructs
+// Put this before any pattern to ensure that the pattern is not escaped, i.e., not preceded by an odd number of backslashes.
+defineRGXConstant("non-escape-bound", {
+    rgxGroupWrap: false,
+    rgxIsRepeatable: false,
+    toRgx() {
+        return /(?<=(?<!\\)(?:\\\\)*)(?=[^\\]|$)/;
+    }
+});

package/dist/flag-transformer/accentInsensitive.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.accentInsensitiveFlagTransformer = void 0;
+const constants_1 = require("../constants");
+const resolve_1 = require("../resolve");
 const accentPatterns = [
     "(a|á|à|ä|â|ã)", "(A|Á|À|Ä|Â|Ã)",
     "(e|é|è|ë|ê)", "(E|É|È|Ë|Ê)",
@@ -11,9 +13,10 @@ const accentPatterns = [
 const accentInsensitiveFlagTransformer = function (exp) {
     let source = exp.source;
     const flags = exp.flags;
+    const nonEscapeBound = (0, resolve_1.resolveRGXToken)((0, constants_1.rgxConstant)("non-escape-bound"));
     accentPatterns.forEach((pattern) => {
         // Replace any of the characters in the pattern with the pattern itself
-        source = source.replaceAll(new RegExp(pattern, "g"), pattern);
+        source = source.replaceAll(new RegExp(nonEscapeBound + pattern, "g"), pattern);
     });
     return new RegExp(source, flags);
 };

package/dist/walker/base.d.ts

@@ -5,6 +5,8 @@ import { RGXPart, RGXCapture } from "./part";
 export type RGXWalkerOptions<R> = {
     startingSourcePosition?: number;
     reduced?: R;
+    infinite?: boolean;
+    looping?: boolean;
 };
 export declare class RGXWalker<R> implements RGXConvertibleToken {
     readonly source: string;
@@ -14,6 +16,8 @@ export declare class RGXWalker<R> implements RGXConvertibleToken {
     reduced: R;
     captures: RGXCapture[];
     namedCaptures: Record<string, RGXCapture[]>;
+    infinite: boolean;
+    looping: boolean;
     private _stopped;
     static check: (value: unknown) => value is RGXWalker<unknown>;
     static assert: (value: unknown) => asserts value is RGXWalker<unknown>;

package/dist/walker/base.js

@@ -35,6 +35,8 @@ class RGXWalker {
         this.tokens = new collection_1.RGXTokenCollection(tokens, "concat");
         this.tokenPosition = 0;
         this.reduced = options.reduced ?? null;
+        this.infinite = options.infinite ?? false;
+        this.looping = options.looping ?? false;
     }
     stop() {
         this._stopped = true;
@@ -73,8 +75,15 @@ class RGXWalker {
         return match;
     }
     step() {
-        if (this.atTokenEnd())
+        if (!this.infinite && !this.looping && this.atTokenEnd()) {
+            this._stopped = true;
+            return null;
+        }
+        // If we're infinite, we need to manually stop when all is exhausted.
+        if ((this.infinite || this.looping) && this.atSourceEnd()) {
+            this._stopped = true;
             return null;
+        }
         const token = this.currentToken();
         const isPart = token instanceof part_1.RGXPart;
         let silent = false;
@@ -116,7 +125,12 @@ class RGXWalker {
         if (isPart) {
             token.afterCapture?.(captureResult, token, this);
         }
-        this.tokenPosition++;
+        if (!this.infinite || this.tokenPosition < this.tokens.length - 1) {
+            this.tokenPosition++;
+            if (this.looping && this.atTokenEnd()) {
+                this.tokenPosition = 0;
+            }
+        }
         return captureResult;
     }
     stepToToken(predicate) {
@@ -153,7 +167,9 @@ class RGXWalker {
             return this;
         const clone = new RGXWalker(this.source, this.tokens.clone((0, immutability_utils_1.depthDecrement)(1)), {
             startingSourcePosition: this.sourcePosition,
-            reduced: (0, immutability_utils_1.extClone)(this.reduced, (0, immutability_utils_1.depthDecrement)(1))
+            reduced: (0, immutability_utils_1.extClone)(this.reduced, (0, immutability_utils_1.depthDecrement)(1)),
+            infinite: this.infinite,
+            looping: this.looping
         });
         clone._tokenPosition = this.tokenPosition;
         clone.captures = (0, immutability_utils_1.extClone)(this.captures, (0, immutability_utils_1.depthDecrement)(1));

package/package.json

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