@ptolemy2002/rgx 5.5.0 → 5.6.0

package/README.md

@@ -54,7 +54,7 @@ type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED' | 'REGEX_NOT_MATCHED_AT_POSITION';
 
 type RangeObject = {
     min?: number | null;
@@ -78,6 +78,23 @@ type RGXGroupTokenArgs = {
     name?: string | null;
     capturing?: boolean;
 };
+
+type RGXPartEventType = "pre-capture" | "post-capture";
+type RGXPartOptions<R, T=string> = {
+    transform: (captured: string) => T;
+    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+};
+
+type RGXWalkerOptions<R> = {
+    startingSourcePosition?: number;
+    reducedCurrent?: R;
+};
+
+type RGXWalkerFlags = {
+    stopped: boolean;
+    skipped: boolean;
+    nonCapture: boolean;
+};
 ```
 
 ## Classes
@@ -257,6 +274,31 @@ constructor(reason?: string | null, message?: string | null)
 #### Properties
 - `reason` (`string | null`): The reason the insertion was rejected, or `null` if no reason was provided.
 
+### RGXRegexNotMatchedAtPositionError extends RGXError
+A specific error class for regex match failures at a given position. This error is thrown when a regex is expected to match at a specific position in a string but does not (e.g., via `assertRegexMatchesAtPosition`). The error code is set to `REGEX_NOT_MATCHED_AT_POSITION` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, pattern: RegExp, source: string, position: number, contextSize?: number | null)
+```
+- `message` (`string`): The error message.
+- `pattern` (`RegExp`): The regex pattern that failed to match.
+- `source` (`string`): The string that was being matched against.
+- `position` (`number`): The zero-based index in the source string where the match was expected. Must be >= 0 and < `source.length`, or an `RGXOutOfBoundsError` will be thrown.
+- `contextSize` (`number | null`, optional): The number of characters on each side of the position to include in contextual output. Defaults to `null` (full source shown).
+
+#### Properties
+- `pattern` (`RegExp`): The regex pattern that failed to match.
+- `source` (`string`): The string that was being matched against.
+- `position` (`number`): The position where the match was expected. Setting this validates that the value is >= 0 and < `source.length`, throwing `RGXOutOfBoundsError` if not.
+- `contextSize` (`number | null`): The number of characters on each side of the position to include in contextual output, or `null` for the full source.
+
+#### Methods
+- `sourceContext() => string`: Returns the relevant portion of the source string around the position. When `contextSize` is `null` or covers the entire string, returns the full source. Otherwise, returns a substring from `max(0, position - contextSize)` to `min(source.length, position + contextSize)`.
+- `hasLeftContext() => boolean`: Returns `true` if the context window starts after the beginning of the source string (i.e., there is truncated content on the left). Returns `false` when `contextSize` is `null`.
+- `hasRightContext() => boolean`: Returns `true` if the context window ends before the end of the source string (i.e., there is truncated content on the right). Returns `false` when `contextSize` is `null`.
+- `hasFullContext() => boolean`: Returns `true` when the full source is shown (neither side is truncated). This is the case when `contextSize` is `null` or when the context window covers the entire source string.
+
 ### RGXOutOfBoundsError extends RGXError
 A specific error class for out-of-bounds values. This error is thrown when a numeric value falls outside an expected range. The error code is set to `OUT_OF_BOUNDS` on instantiation.
 
@@ -536,6 +578,87 @@ constructor(pattern: string | RegExp, flags?: string)
 #### Static Properties
 - `[Symbol.species]` (`RegExpConstructor`): Returns `ExtRegExp`, ensuring that derived `RegExp` methods (like those returning new regex instances) produce `ExtRegExp` instances rather than plain `RegExp`.
 
+### RGXPart\<R, T=string\>
+A class that wraps an `RGXToken` and captures the matched string when used within an `RGXWalker`. It implements `RGXConvertibleToken`, delegating `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token. After a walker captures a match for this part, the `capturedString` and `capturedValue` properties are populated, with the latter produced by the `transform` function.
+
+A function `rgxPart` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXPart`: A type guard that checks if the given value is an instance of `RGXPart`.
+- `assert(value: unknown): asserts value is RGXPart`: An assertion that checks if the given value is an instance of `RGXPart`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>)
+```
+- `token` (`RGXToken`): The token to wrap.
+- `options` (`Partial<RGXPartOptions<R, T>>`, optional): Configuration options. Defaults to `{}`.
+  - `transform` (`(captured: string) => T`, optional): A function that transforms the captured string into the desired type `T`. Defaults to an identity function that casts the string to `T`.
+  - `onEvent` (`((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null`, optional): A callback invoked when an event is triggered on this part during walking. Defaults to `null`.
+
+#### Properties
+- `token` (`RGXToken`): The wrapped token.
+- `capturedString` (`string | null`): The raw string captured by the walker for this part, or `null` if not yet captured.
+- `capturedValue` (`T | null`): The transformed value produced by applying `transform` to `capturedString`, or `null` if not yet captured.
+- `transform` (`(captured: string) => T`): The transform function used to convert captured strings to values of type `T`.
+- `onEvent` (`((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null`): The event callback, or `null`.
+- `rgxIsGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`.
+- `rgxIsRepeatable` (`boolean`): If the wrapped token is an `RGXConvertibleToken`, delegates to its `rgxIsRepeatable` property (defaulting to `true` if not present). Otherwise, returns `true`.
+
+#### Methods
+- `triggerEvent(eventType: RGXPartEventType, walker: RGXWalker<R>) => void`: Triggers an event on this part. For `"post-capture"` events, sets `capturedString` to the walker's last captured string and `capturedValue` to the result of `transform`. Then calls the `onEvent` callback if present.
+- `toRgx() => RGXToken`: Returns the wrapped token.
+- `clone(depth: CloneDepth = "max") => RGXPart`: Creates a clone of this part. When `depth` is `0`, returns `this`; otherwise, returns a new `RGXPart` with a cloned token and the same `transform` and `onEvent` references.
+
+### RGXWalker\<R\>
+A class that walks through a sequence of RGX tokens, matching each token against a source string at the current position. It implements `RGXConvertibleToken`, delegating to its internal `RGXTokenCollection`. The walker maintains a source position and a token position, advancing through both as tokens are matched. When an `RGXPart` is encountered, its event callbacks are triggered around the capture. The generic type `R` represents a user-defined "reduced" value that can accumulate state during walking (e.g., via `RGXPart` event callbacks).
+
+A function `rgxWalker` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXWalker`: A type guard that checks if the given value is an instance of `RGXWalker`.
+- `assert(value: unknown): asserts value is RGXWalker`: An assertion that checks if the given value is an instance of `RGXWalker`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalkerOptions<R>)
+```
+- `source` (`string`): The string to walk through, matching tokens against.
+- `tokens` (`RGXTokenCollectionInput`): The tokens to match sequentially. Internally stored as an `RGXTokenCollection` in 'concat' mode.
+- `options` (`RGXWalkerOptions<R>`, optional): Configuration options. Defaults to `{}`.
+  - `startingSourcePosition` (`number`, optional): The starting index in the source string. Defaults to `0`.
+  - `reducedCurrent` (`R`, optional): The initial value for the `reducedCurrent` accumulator. Defaults to `null`.
+
+#### Properties
+- `source` (`string`): The source string being walked (readonly).
+- `sourcePosition` (`number`): The current index in the source string. Setting this validates that the value is >= 0 and < `source.length`, throwing `RGXOutOfBoundsError` if not.
+- `tokens` (`RGXTokenCollection`): The internal collection of tokens in 'concat' mode (readonly).
+- `tokenPosition` (`number`): The current index in the token collection. Setting this validates that the value is >= 0 and <= `tokens.length`, throwing `RGXOutOfBoundsError` if not.
+- `reducedCurrent` (`R`): A user-defined accumulator value, typically updated by `RGXPart` event callbacks during walking.
+- `capturedStrings` (`string[]`): An array of all strings captured during walking (excluding those captured with the `nonCapture` flag set).
+- `flags` (`RGXWalkerFlags`): The current walker flags: `stopped` halts `stepToToken`/`stepToPart`/`walk`, `skipped` causes `step` to skip the current token without capturing, and `nonCapture` prevents the captured string from being added to `capturedStrings`.
+
+#### Methods
+- `resetFlags() => void`: Resets all flags (`stopped`, `skipped`, `nonCapture`) to `false`.
+- `stop() => void`: Sets the `stopped` flag to `true`, causing any active `stepToToken`, `stepToPart`, or `walk` loop to halt after the current iteration.
+- `skip() => void`: Sets the `skipped` flag to `true`, causing the current `step` call to skip capturing the current token.
+- `preventCapture() => void`: Sets the `nonCapture` flag to `true`, causing the current `step` call to capture the token but not add the matched string to `capturedStrings`.
+- `atTokenEnd() => boolean`: Returns `true` if the token position is at or past the end of the token collection.
+- `hasNextToken(predicate?: (token: RGXToken) => boolean) => boolean`: Returns `true` if there is a next token and it satisfies the optional predicate (defaults to `() => true`).
+- `atSourceEnd() => boolean`: Returns `true` if the source position is at the last character of the source string.
+- `hasNextSource(predicate?: (rest: string) => boolean) => boolean`: Returns `true` if the source position is not at the end and the remaining source satisfies the optional predicate (defaults to `() => true`).
+- `hasCapturedStrings(minCount?: number) => boolean`: Returns `true` if `capturedStrings` has at least `minCount` entries (defaults to `1`).
+- `getLastCapturedString() => string | null`: Returns the last entry in `capturedStrings`, or `null` if empty.
+- `nextToken() => 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 at the end.
+- `capture(token: RGXToken) => string`: Resolves the token to a regex, asserts that it matches at the current source position (throwing `RGXRegexNotMatchedAtPositionError` if not), captures the matched string (unless `nonCapture` is set), and advances the source position by the match length. Returns the matched string.
+- `step(flagReset?: boolean) => string | null`: Steps through the next token in the collection. If `flagReset` is `true` (the default), resets flags first. If the token is an `RGXPart`, triggers `"pre-capture"` before capturing and `"post-capture"` after (when not skipped or non-capturing). Advances the token position and returns the captured string, or `null` if there are no more tokens or the step was skipped.
+- `stepToToken(predicate: (token: RGXToken) => boolean) => void`: Steps through tokens until the predicate returns `true` for the next 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.
+- `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, captured strings, and flags.
+
 ## Functions
 The following functions are exported by the library:
 
@@ -1287,10 +1410,25 @@ Creates a new `ExtRegExp` from an existing one with additional or replaced flags
 
 ### regexMatchAtPosition
 ```typescript
-function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+function regexMatchAtPosition(regex: RegExp, str: string, position: number): string | null
 ```
 
-Tests whether the given regular expression matches at a specific position in the string. This is done by creating a sticky (`y` flag) copy of the regex and setting its `lastIndex` to the desired position. The position must be within the bounds of the string (>= 0 and < string length), or an `RGXOutOfBoundsError` will be thrown.
+Attempts to match the given regular expression at a specific position in the string and returns the matched string, or `null` if there is no match. This is done by creating a sticky (`y` flag) copy of the regex and setting its `lastIndex` to the desired position. The position must be within the bounds of the string (>= 0 and < string length), or an `RGXOutOfBoundsError` will be thrown.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to match.
+  - `str` (`string`): The string to match against.
+  - `position` (`number`): The zero-based index in the string at which to attempt the match. Must be >= 0 and < `str.length`.
+
+#### Returns
+- `string | null`: The matched string if the regex matches at the specified position, otherwise `null`.
+
+### doesRegexMatchAtPosition
+```typescript
+function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+```
+
+Tests whether the given regular expression matches at a specific position in the string. This is a boolean wrapper around `regexMatchAtPosition`, returning `true` if the match is non-null.
 
 #### Parameters
   - `regex` (`RegExp`): The regular expression to test.
@@ -1300,6 +1438,22 @@ Tests whether the given regular expression matches at a specific position in the
 #### Returns
 - `boolean`: `true` if the regex matches at the specified position, otherwise `false`.
 
+### assertRegexMatchesAtPosition
+```typescript
+function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize?: number | null): string
+```
+
+Asserts that the given regular expression matches at a specific position in the string, throwing an `RGXRegexNotMatchedAtPositionError` if it does not. On success, returns the matched string.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to match.
+  - `str` (`string`): The string to match against.
+  - `position` (`number`): The zero-based index in the string at which to assert the match. Must be >= 0 and < `str.length`.
+  - `contextSize` (`number | null`, optional): The number of characters on each side of the position to include in the error's context output. Defaults to `10`.
+
+#### Returns
+- `string`: The matched string if the regex matches at the specified position. Throws `RGXRegexNotMatchedAtPositionError` if there is no match.
+
 ### cloneRGXToken
 ```typescript
 function cloneRGXTokeN<T extends RGXToken>(token: T, depth: CloneDepth="max"): T

package/dist/collection.d.ts

@@ -1,9 +1,9 @@
-import { RGXToken, ValidRegexString } from "./types";
+import { RGXConvertibleToken, RGXToken, ValidRegexString } from "./types";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { Collection } from "@ptolemy2002/ts-utils";
 export type RGXTokenCollectionMode = 'union' | 'concat';
 export type RGXTokenCollectionInput = RGXToken | RGXTokenCollection;
-export declare class RGXTokenCollection implements Collection<RGXToken> {
+export declare class RGXTokenCollection implements Collection<RGXToken>, RGXConvertibleToken {
     mode: RGXTokenCollectionMode;
     tokens: RGXToken[];
     static check: (value: unknown) => value is RGXTokenCollection;

package/dist/errors/base.d.ts

@@ -1,4 +1,4 @@
-export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED';
+export type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED' | 'REGEX_NOT_MATCHED_AT_POSITION';
 export declare class RGXError extends Error {
     _message: string;
     code: RGXErrorCode;

package/dist/errors/index.d.ts

@@ -12,3 +12,4 @@ export * from './notSupported';
 export * from './insertionRejected';
 export * from './constantConflict';
 export * from './invalidConstantKey';
+export * from './regexNotMatchedAtPosition';

package/dist/errors/index.js

@@ -28,3 +28,4 @@ __exportStar(require("./notSupported"), exports);
 __exportStar(require("./insertionRejected"), exports);
 __exportStar(require("./constantConflict"), exports);
 __exportStar(require("./invalidConstantKey"), exports);
+__exportStar(require("./regexNotMatchedAtPosition"), exports);

package/dist/errors/regexNotMatchedAtPosition.d.ts

@@ -0,0 +1,15 @@
+import { RGXError } from "./base";
+export declare class RGXRegexNotMatchedAtPositionError extends RGXError {
+    pattern: RegExp;
+    source: string;
+    _position: number;
+    contextSize: number | null;
+    set position(value: number);
+    get position(): number;
+    constructor(message: string, pattern: RegExp, source: string, position: number, contextSize?: number | null);
+    sourceContext(): string;
+    hasLeftContext(): boolean;
+    hasRightContext(): boolean;
+    hasFullContext(): boolean;
+    calcMessage(message: string): string;
+}

package/dist/errors/regexNotMatchedAtPosition.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXRegexNotMatchedAtPositionError = void 0;
+const base_1 = require("./base");
+const outOfBounds_1 = require("./outOfBounds");
+class RGXRegexNotMatchedAtPositionError extends base_1.RGXError {
+    set position(value) {
+        (0, outOfBounds_1.assertInRange)(value, { min: 0, max: this.source.length, inclusiveRight: false }, "position is outside the bounds of the source string");
+        this._position = value;
+    }
+    get position() {
+        return this._position;
+    }
+    constructor(message, pattern, source, position, contextSize = null) {
+        super(message, 'REGEX_NOT_MATCHED_AT_POSITION');
+        this.name = 'RGXRegexNotMatchedAtPositionError';
+        this.pattern = pattern;
+        this.source = source;
+        this.position = position;
+        this.contextSize = contextSize;
+    }
+    sourceContext() {
+        if (this.hasFullContext())
+            return this.source;
+        const start = Math.max(0, this.position - this.contextSize);
+        const end = Math.min(this.source.length, this.position + this.contextSize);
+        return this.source.slice(start, end);
+    }
+    hasLeftContext() {
+        if (this.contextSize === null)
+            return false;
+        return this.position - this.contextSize >= 0;
+    }
+    hasRightContext() {
+        if (this.contextSize === null)
+            return false;
+        return this.position + this.contextSize <= this.source.length;
+    }
+    hasFullContext() {
+        return !this.hasLeftContext() && !this.hasRightContext();
+    }
+    calcMessage(message) {
+        let context = this.sourceContext();
+        if (this.contextSize !== null) {
+            if (this.hasLeftContext())
+                context = `...${context}`;
+            if (this.hasRightContext())
+                context = `${context}...`;
+        }
+        return `${message}; Pattern: ${this.pattern.toString()}, Position: ${this.position}, Context: ${context}`;
+    }
+}
+exports.RGXRegexNotMatchedAtPositionError = RGXRegexNotMatchedAtPositionError;

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export * from "./ExtRegExp";
 export * from "./flag-transformer";
 export * from "./clone";
 export * from "./constants";
+export * from "./walker";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
 export default function rgx(flags?: string, multiline?: boolean): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;

package/dist/index.js

@@ -33,6 +33,7 @@ __exportStar(require("./ExtRegExp"), exports);
 __exportStar(require("./flag-transformer"), exports);
 __exportStar(require("./clone"), exports);
 __exportStar(require("./constants"), exports);
+__exportStar(require("./walker"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
 // Call this for our custom flags to work correctly

package/dist/utils/regexMatchAtPosition.d.ts

@@ -1 +1,3 @@
-export declare function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean;
+export declare function regexMatchAtPosition(regex: RegExp, str: string, position: number): string | null;
+export declare function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number): boolean;
+export declare function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize?: number | null): string;

package/dist/utils/regexMatchAtPosition.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.regexMatchAtPosition = regexMatchAtPosition;
+exports.doesRegexMatchAtPosition = doesRegexMatchAtPosition;
+exports.assertRegexMatchesAtPosition = assertRegexMatchesAtPosition;
 const outOfBounds_1 = require("../errors/outOfBounds");
 const regexWithFlags_1 = require("./regexWithFlags");
+const errors_1 = require("../errors");
 function regexMatchAtPosition(regex, str, position) {
     /*
         The y flag means sticky mode, which means the next match must start at
@@ -12,5 +15,15 @@ function regexMatchAtPosition(regex, str, position) {
     (0, outOfBounds_1.assertInRange)(position, { min: 0, max: str.length, inclusiveRight: false }, 'String index out of bounds');
     const stickyRegex = (0, regexWithFlags_1.regexWithFlags)(regex, "y");
     stickyRegex.lastIndex = position;
-    return stickyRegex.test(str);
+    const match = stickyRegex.exec(str);
+    return match ? match[0] : null;
+}
+function doesRegexMatchAtPosition(regex, str, position) {
+    return regexMatchAtPosition(regex, str, position) !== null;
+}
+function assertRegexMatchesAtPosition(regex, str, position, contextSize = 10) {
+    if (!doesRegexMatchAtPosition(regex, str, position)) {
+        throw new errors_1.RGXRegexNotMatchedAtPositionError("Regex not matched at index", regex, str, position, contextSize);
+    }
+    return regexMatchAtPosition(regex, str, position);
 }

package/dist/walker/base.d.ts

@@ -0,0 +1,49 @@
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
+import { RGXConvertibleToken, RGXToken } from "../types";
+import { RGXPart } from "./part";
+export type RGXWalkerOptions<R> = {
+    startingSourcePosition?: number;
+    reducedCurrent?: R;
+};
+export type RGXWalkerFlags = {
+    stopped: boolean;
+    skipped: boolean;
+    nonCapture: boolean;
+};
+export declare class RGXWalker<R> implements RGXConvertibleToken {
+    readonly source: string;
+    _sourcePosition: number;
+    readonly tokens: RGXTokenCollection;
+    _tokenPosition: number;
+    reducedCurrent: R;
+    capturedStrings: string[];
+    flags: RGXWalkerFlags;
+    static check: (value: unknown) => value is RGXWalker<unknown>;
+    static assert: (value: unknown) => asserts value is RGXWalker<unknown>;
+    get sourcePosition(): number;
+    set sourcePosition(value: number);
+    get tokenPosition(): number;
+    set tokenPosition(value: number);
+    constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalkerOptions<R>);
+    resetFlags(): void;
+    stop(): void;
+    skip(): void;
+    preventCapture(): void;
+    atTokenEnd(): boolean;
+    hasNextToken(predicate?: (token: RGXToken) => boolean): boolean;
+    atSourceEnd(): boolean;
+    hasNextSource(predicate?: (rest: string) => boolean): boolean;
+    hasCapturedStrings(minCount?: number): boolean;
+    getLastCapturedString(): string | null | undefined;
+    nextToken(): RGXToken;
+    remainingSource(): string | null;
+    capture(token: RGXToken): string;
+    step(flagReset?: boolean): string | null;
+    stepToToken(predicate: (token: RGXToken) => boolean): void;
+    stepToPart(predicate?: (part: RGXPart<R>) => boolean): void;
+    walk(): void;
+    toRgx(): RGXTokenCollection;
+    clone(depth?: CloneDepth): RGXWalker<R>;
+}
+export declare function rgxWalker<R>(...args: ConstructorParameters<typeof RGXWalker<R>>): RGXWalker<R>;

package/dist/walker/base.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXWalker = void 0;
+exports.rgxWalker = rgxWalker;
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const collection_1 = require("../collection");
+const errors_1 = require("../errors");
+const part_1 = require("./part");
+const index_1 = require("../index");
+const internal_1 = require("../internal");
+class RGXWalker {
+    get sourcePosition() {
+        return this._sourcePosition;
+    }
+    set sourcePosition(value) {
+        (0, errors_1.assertInRange)(value, { min: 0, max: this.source.length, inclusiveRight: false }, "sourcePosition is outside the bounds of the source string");
+        this._sourcePosition = value;
+    }
+    get tokenPosition() {
+        return this._tokenPosition;
+    }
+    set tokenPosition(value) {
+        (0, errors_1.assertInRange)(value, { min: 0, max: this.tokens.length }, "tokenPosition is outside the bounds of the token collection");
+        this._tokenPosition = value;
+    }
+    constructor(source, tokens, options = {}) {
+        this.capturedStrings = [];
+        this.flags = {
+            stopped: false,
+            skipped: false,
+            nonCapture: false
+        };
+        this.source = source;
+        this.sourcePosition = options.startingSourcePosition ?? 0;
+        this.tokens = new collection_1.RGXTokenCollection(tokens, "concat");
+        this.tokenPosition = 0;
+        this.reducedCurrent = options.reducedCurrent ?? null;
+    }
+    resetFlags() {
+        this.flags.stopped = false;
+        this.flags.skipped = false;
+        this.flags.nonCapture = false;
+    }
+    stop() {
+        this.flags.stopped = true;
+    }
+    skip() {
+        this.flags.skipped = true;
+    }
+    preventCapture() {
+        this.flags.nonCapture = true;
+    }
+    atTokenEnd() {
+        return this.tokenPosition >= this.tokens.length;
+    }
+    hasNextToken(predicate = () => true) {
+        return !this.atTokenEnd() && predicate(this.nextToken());
+    }
+    atSourceEnd() {
+        return this.sourcePosition >= this.source.length - 1;
+    }
+    hasNextSource(predicate = () => true) {
+        return !this.atSourceEnd() && predicate(this.remainingSource());
+    }
+    hasCapturedStrings(minCount = 1) {
+        return this.capturedStrings.length >= minCount;
+    }
+    getLastCapturedString() {
+        if (!this.hasCapturedStrings())
+            return null;
+        return this.capturedStrings[this.capturedStrings.length - 1];
+    }
+    nextToken() {
+        if (this.tokenPosition >= this.tokens.length)
+            return null;
+        return this.tokens.at(this.tokenPosition);
+    }
+    remainingSource() {
+        if (this.sourcePosition >= this.source.length - 1)
+            return null;
+        return this.source.slice(this.sourcePosition);
+    }
+    capture(token) {
+        const regex = (0, index_1.rgxa)([token]);
+        const match = (0, index_1.assertRegexMatchesAtPosition)(regex, this.source, this.sourcePosition);
+        if (!this.flags.nonCapture)
+            this.capturedStrings.push(match);
+        if (this.sourcePosition < this.source.length - match.length)
+            this.sourcePosition += match.length;
+        else
+            this.sourcePosition = this.source.length - 1; // Move to the end of the source if the match goes beyond it
+        return match;
+    }
+    step(flagReset = true) {
+        if (flagReset)
+            this.resetFlags();
+        if (!this.hasNextToken())
+            return null;
+        const token = this.nextToken();
+        if (token instanceof part_1.RGXPart)
+            token.triggerEvent("pre-capture", this);
+        let captured = null;
+        if (!this.flags.skipped) {
+            captured = this.capture(token);
+            if (token instanceof part_1.RGXPart && !this.flags.nonCapture)
+                token.triggerEvent("post-capture", this);
+        }
+        this.tokenPosition++;
+        return captured;
+    }
+    stepToToken(predicate) {
+        while (this.hasNextToken()) {
+            this.resetFlags();
+            if (predicate(this.nextToken()))
+                break;
+            this.step(false);
+            if (this.flags.stopped)
+                break;
+        }
+    }
+    stepToPart(predicate = () => true) {
+        // If we're currently at a part, step once so that we can get to the next one.
+        if (this.nextToken() instanceof part_1.RGXPart)
+            this.step();
+        if (this.flags.stopped)
+            return;
+        this.stepToToken(token => token instanceof part_1.RGXPart && predicate(token));
+    }
+    walk() {
+        return this.stepToToken(() => false);
+    }
+    // When used as a convertible token, just treat the walker as
+    // a collection.
+    toRgx() {
+        return this.tokens;
+    }
+    // Clone method
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        const clone = new RGXWalker(this.source, this.tokens.clone((0, immutability_utils_1.depthDecrement)(1)), {
+            startingSourcePosition: this.sourcePosition,
+            reducedCurrent: (0, immutability_utils_1.extClone)(this.reducedCurrent, (0, immutability_utils_1.depthDecrement)(1))
+        });
+        clone._tokenPosition = this.tokenPosition;
+        clone.capturedStrings = (0, immutability_utils_1.extClone)(this.capturedStrings, (0, immutability_utils_1.depthDecrement)(1));
+        clone.flags = (0, immutability_utils_1.extClone)(this.flags, (0, immutability_utils_1.depthDecrement)(1));
+        return clone;
+    }
+}
+exports.RGXWalker = RGXWalker;
+RGXWalker.check = (0, internal_1.createClassGuardFunction)(RGXWalker);
+RGXWalker.assert = (0, internal_1.createAssertClassGuardFunction)(RGXWalker);
+function rgxWalker(...args) {
+    return new RGXWalker(...args);
+}

package/dist/walker/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./base";
+export * from "./part";

package/dist/walker/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./base"), exports);
+__exportStar(require("./part"), exports);

package/dist/walker/part.d.ts

@@ -0,0 +1,24 @@
+import { RGXConvertibleToken, RGXToken } from "../types";
+import type { RGXWalker } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+export type RGXPartEventType = "pre-capture" | "post-capture";
+export type RGXPartOptions<R, T = string> = {
+    transform: (captured: string) => T;
+    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+};
+export declare class RGXPart<R, T = string> implements RGXConvertibleToken {
+    token: RGXToken;
+    capturedString: string | null;
+    capturedValue: T | null;
+    readonly transform: RGXPartOptions<R, T>["transform"];
+    readonly onEvent: RGXPartOptions<R, T>["onEvent"];
+    static check: (value: unknown) => value is RGXPart<unknown, unknown>;
+    static assert: (value: unknown) => asserts value is RGXPart<unknown, unknown>;
+    constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>);
+    triggerEvent(eventType: RGXPartEventType, walker: RGXWalker<R>): void;
+    get rgxIsGroup(): boolean;
+    get rgxIsRepeatable(): boolean;
+    toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXPart<R, T>;
+}
+export declare function rgxPart<R, T = string>(...args: ConstructorParameters<typeof RGXPart<R, T>>): RGXPart<R, T>;

package/dist/walker/part.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXPart = void 0;
+exports.rgxPart = rgxPart;
+const typeGuards_1 = require("../typeGuards");
+const internal_1 = require("../internal");
+const clone_1 = require("../clone");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+class RGXPart {
+    constructor(token, options = {}) {
+        this.capturedString = null;
+        this.capturedValue = null;
+        this.token = token;
+        this.transform = options.transform ?? ((captured) => captured);
+        this.onEvent = options.onEvent ?? null;
+    }
+    triggerEvent(eventType, walker) {
+        switch (eventType) {
+            case "post-capture": {
+                this.capturedString = walker.getLastCapturedString();
+                this.capturedValue = this.transform(this.capturedString);
+                break;
+            }
+        }
+        this.onEvent?.(this, eventType, walker);
+    }
+    // Properties used for conversion to an RGXToken
+    get rgxIsGroup() {
+        return (0, typeGuards_1.isRGXGroupedToken)(this.token);
+    }
+    get rgxIsRepeatable() {
+        if ((0, typeGuards_1.isRGXToken)(this.token, 'convertible'))
+            return this.token.rgxIsRepeatable ?? true;
+        // Assume any other token is repeatable, since we don't know its implementation.
+        return true;
+    }
+    toRgx() {
+        return this.token;
+    }
+    // Clone method
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXPart((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), { transform: this.transform, onEvent: this.onEvent });
+    }
+}
+exports.RGXPart = RGXPart;
+RGXPart.check = (0, internal_1.createClassGuardFunction)(RGXPart);
+RGXPart.assert = (0, internal_1.createAssertClassGuardFunction)(RGXPart);
+function rgxPart(...args) {
+    return new RGXPart(...args);
+}

package/package.json

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