@ptolemy2002/rgx 7.1.0 → 7.3.0

package/README.md

@@ -24,6 +24,7 @@ type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToke
 type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
 type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
 type RGXGroupedConvertibleToken = (RGXConvertibleToken & { readonly rgxIsGroup: true }) | (Omit<RGXConvertibleToken, "toRgx"> & { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true  });
+type RGXRepeatableConvertibleToken = RGXConvertibleToken & { readonly rgxIsRepeatable: true | undefined };
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
 type ValidRegexBrandSymbol = typeof validRegexSymbol;
@@ -45,7 +46,7 @@ type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
+type RGXTokenTypeGuardInput = "repeatable" | RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
 type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // Maps token type strings to their corresponding types, e.g.:
     // 'no-op' -> RGXNoOpToken, 'literal' -> RGXLiteralToken, etc.
@@ -100,6 +101,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 +660,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 +671,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 +685,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:
@@ -905,7 +912,7 @@ Converts an `RGXTokenType` to its flat equivalent `RGXTokenTypeFlat`. If the typ
 function rgxTokenTypeGuardInputToFlat(type: RGXTokenTypeGuardInput): RGXTokenTypeFlat | null
 ```
 
-Converts an `RGXTokenTypeGuardInput` to its flat equivalent. If the type is `null`, it returns `null`; if it is an array, it returns `'array'`; if it is an `RGXClassTokenConstructor` (a constructor for an `RGXClassToken` subclass), it returns `'class'` (making it slightly lossy in that case); otherwise, it returns the type as-is.
+Converts an `RGXTokenTypeGuardInput` to its flat equivalent. If the type is `null`, it returns `null`; if it is an array, it returns `'array'`; if it is a RegEx constructor, it returns `'literal`; if it is the `RGXTokenCollection` constructor, it returns `'convertible'`; if it is an `RGXClassTokenConstructor` (a constructor for an `RGXClassToken` subclass), it returns `'class'` (making it slightly lossy in that case); otherwise, it returns the type as-is.
 
 #### Parameters
   - `type` (`RGXTokenTypeGuardInput`): The type guard input to convert.
@@ -924,6 +931,8 @@ When `type` is a constructor, it performs an `instanceof` check against that spe
 
 When `type` is an array, it checks that every element of the value array is a valid RGX token matching the corresponding type in the `type` array. If `matchLength` is `true` (the default), it also requires that the value array has the same length as the type array; if `false`, it allows the value array to be longer than the type array, as long as all elements up to the length of the type array match and all elements after that are still valid RGX tokens of any type.
 
+When `type` is `"repeatable"`, it passes for any token that is not convertible, then checks if `rgxIsRepeatable` is `true | undefined` for convertible tokens.
+
 #### Parameters
   - `value` (`unknown`): The value to check.
   - `type` (`T`, optional): The token type to check against. Can be a token type string, `null` (checks against all token types), an `RGXClassTokenConstructor` (checks via `instanceof`), or an array of these. Defaults to `null`.

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") && !(0, typeGuards_1.isRGXToken)(value, "repeatable")) {
             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

@@ -61,6 +61,13 @@ defineRGXConstant("start", {
         return /^/;
     }
 });
+defineRGXConstant("line-start", {
+    rgxGroupWrap: false,
+    rgxIsRepeatable: false,
+    toRgx() {
+        return /^/m;
+    }
+});
 defineRGXConstant("end", {
     rgxGroupWrap: false,
     rgxIsRepeatable: false,
@@ -68,6 +75,13 @@ defineRGXConstant("end", {
         return /$/;
     }
 });
+defineRGXConstant("line-end", {
+    rgxGroupWrap: false,
+    rgxIsRepeatable: false,
+    toRgx() {
+        return /$/m;
+    }
+});
 defineRGXConstant("word-bound", {
     rgxGroupWrap: false,
     rgxIsRepeatable: false,

package/dist/typeGuards.js

@@ -65,6 +65,8 @@ const e = __importStar(require("./errors"));
 const is_callable_1 = __importDefault(require("is-callable"));
 const internal_1 = require("./internal");
 const class_1 = require("./class");
+const ExtRegExp_1 = require("./ExtRegExp");
+const collection_1 = require("./collection");
 function isRGXNoOpToken(value) {
     return value === null || value === undefined;
 }
@@ -171,8 +173,14 @@ function rgxTokenTypeGuardInputToFlat(type) {
         return null;
     if (Array.isArray(type))
         return 'array';
+    if (type === RegExp || type === ExtRegExp_1.ExtRegExp)
+        return 'literal';
+    if (type === collection_1.RGXTokenCollection)
+        return 'convertible';
     if ((0, internal_1.isConstructor)(type))
         return 'class';
+    if (type === "repeatable")
+        return null;
     return type;
 }
 function isRGXToken(value, type = null, matchLength = true) {
@@ -192,6 +200,11 @@ function isRGXToken(value, type = null, matchLength = true) {
         return true;
     if (typeMatches('convertible') && isRGXConvertibleToken(value))
         return true;
+    // Non-covertible tokens are repeatable by default. Convertible tokens are only non-repeatable if they have the rgxIsRepeatable property set to false.
+    if (type === 'repeatable' && !isRGXConvertibleToken(value, false))
+        return true;
+    if (type === 'repeatable' && isRGXConvertibleToken(value))
+        return value.rgxIsRepeatable ?? true;
     if (typeMatches('array') && isRGXArrayToken(value))
         return true;
     if (Array.isArray(type) && Array.isArray(value) && (!matchLength || type.length === value.length)) {

package/dist/types.d.ts

@@ -22,10 +22,13 @@ export type RGXGroupedConvertibleToken = (RGXConvertibleToken & {
     toRgx: () => RGXGroupedToken;
     readonly rgxGroupWrap: true;
 });
+export type RGXRepeatableConvertibleToken = RGXConvertibleToken & {
+    readonly rgxIsRepeatable: true | undefined;
+};
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
-export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends new (...args: unknown[]) => infer R ? R : T extends RGXTokenTypeGuardInput[] ? {
+export type RGXTokenTypeGuardInput = "repeatable" | RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
+export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends 'repeatable' ? Exclude<RGXToken, RGXConvertibleToken> | RGXRepeatableConvertibleToken : T extends new (...args: unknown[]) => infer R ? R : T extends RGXTokenTypeGuardInput[] ? {
     [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
 } : never;
 export type RangeObject = {

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.1.0",
+    "version": "7.3.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",