@ptolemy2002/rgx 5.5.0 → 6.0.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,25 @@ type RGXGroupTokenArgs = {
     name?: string | null;
     capturing?: boolean;
 };
+
+type RGXPartControl = "skip" | "stop" | "silent" | void;
+
+type RGXCapture<T = unknown> = {
+    raw: string;
+    value: T;
+};
+
+type RGXPartOptions<R, T=string> = {
+    transform: (captured: string) => T;
+    validate: (captured: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => boolean | string;
+    beforeCapture: ((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null;
+    afterCapture: ((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null;
+};
+
+type RGXWalkerOptions<R> = {
+    startingSourcePosition?: number;
+    reduced?: R;
+};
 ```
 
 ## Classes
@@ -257,6 +276,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.
 
@@ -283,6 +327,21 @@ constructor(message: string, got: number, { min, max, inclusiveLeft, inclusiveRi
 - `failedAtMax() => boolean`: Returns `true` if the `got` value is above the maximum bound (respecting `inclusiveRight`), otherwise `false`. Returns `false` if `max` is `null`.
 - `failedAtAny() => boolean`: Returns `true` if the value failed at either the minimum or maximum bound.
 
+### RGXPartValidationFailedError extends RGXError
+A specific error class for RGX part validation failures. This error is thrown when a captured value fails validation in a custom part's `validate` function. The error code is set to `PART_VALIDATION_FAILED` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, gotRaw: string, gotTransformed: unknown)
+```
+- `message` (`string`): The error message.
+- `gotRaw` (`string`): The raw captured string value that failed validation.
+- `gotTransformed` (`unknown`): The transformed value that was produced by the part's `transform` function, which also failed validation.
+
+#### Properties
+- `gotRaw` (`string`): The raw captured string value that failed validation.
+- `gotTransformed` (`unknown`): The transformed value that was produced by the part's `transform` function, which also failed validation.
+
 ### RGXTokenCollection
 A class representing a collection of RGX tokens. This class manages collections of RGX tokens like an array, but with additional metadata about the collection mode (union or concat). Since `toRgx()` returns a `RegExp`, instances of this class satisfy the `RGXConvertibleToken` interface and can be used directly as tokens in `rgx`, `rgxa`, and other token-accepting functions.
 
@@ -536,6 +595,84 @@ 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` with optional callbacks for use within an `RGXWalker`. It implements `RGXConvertibleToken`, delegating `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token. Unlike plain tokens, Parts can control walker behavior via `beforeCapture` (returning an `RGXPartControl` value) and react to captures via `afterCapture`. Parts are purely definitions and do not store capture state — all captures are stored on the walker as `RGXCapture` objects.
+
+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`.
+  - `beforeCapture` (`((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null`, optional): A callback invoked before capturing this part during walking. Returns an `RGXPartControl` value to control walker behavior: `"skip"` to skip this token without capturing, `"silent"` to capture but not record in `captures`, `"stop"` to halt immediately without capturing or advancing, or `void`/`undefined` to proceed normally. Defaults to `null`.
+  - `afterCapture` (`((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null`, optional): A callback invoked after capturing this part during walking. Receives the typed `RGXCapture<T>` result. Can call `walker.stop()` to halt walking after this capture. Defaults to `null`.
+  - `validate` (`((capture: RGXCapture<T>, walker: RGXWalker<R>) => boolean | string) | null`, optional): A callback invoked during validation after capturing and transforming, but before `afterCapture`. Returns `true` if validation passes, `false` to fail with a generic error, or a string to fail with that string as the error message. Defaults to `null`.
+
+#### Properties
+- `token` (`RGXToken`): The wrapped token.
+- `transform` (`(captured: string) => T`, readonly): The transform function used to convert captured strings to values of type `T`.
+- `beforeCapture` (`((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null`, readonly): The before-capture callback, or `null`.
+- `afterCapture` (`((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null`, readonly): The after-capture 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
+- `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`, `beforeCapture`, and `afterCapture` references.
+- `validate(capture: RGXCapture<T>, walker: RGXWalker<R>) => void`: A method that calls the inner passed validation logic for this part, if any. If it returns `false`, a generic `RGXPartValidationFailedError` is thrown. If it returns a string, an `RGXPartValidationFailedError` is thrown with that string as the message. If it returns `true`, validation passed. This is called internally by the walker after capturing and transforming a part, before invoking `afterCapture`.
+
+### 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 `beforeCapture` callback can control behavior via return values (`RGXPartControl`), and its `afterCapture` callback is invoked with the typed capture result. All captures are stored as structured `RGXCapture` objects on the walker. The generic type `R` represents a user-defined "reduced" value that can accumulate state during walking (e.g., via `RGXPart` 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`.
+  - `reduced` (`R`, optional): The initial value for the `reduced` accumulator. Defaults to `null`.
+
+#### Properties
+- `source` (`string`): The source string being walked (readonly).
+- `sourcePosition` (`number`): The current index in the source string. Range is `[0, source.length]` inclusive, where `source.length` represents "fully consumed". 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.
+- `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 and a `value` (the transform result for Parts, or the raw string for plain tokens).
+- `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
+- `stop() => void`: Sets `stopped` to `true`, causing any active `stepToToken`, `stepToPart`, or `walk` loop to halt after the current iteration. Typically called from an `afterCapture` callback to stop walking after the current capture.
+- `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 current token and it satisfies the optional predicate (defaults to `() => true`).
+- `atSourceEnd() => boolean`: Returns `true` if the source has been fully consumed (`sourcePosition >= source.length`).
+- `hasNextSource(predicate?: (rest: string) => boolean) => boolean`: Returns `true` if the source is not fully consumed and the remaining source satisfies the optional predicate (defaults to `() => true`).
+- `lastCapture() => RGXCapture | null`: Returns the last entry in `captures`, or `null` if empty.
+- `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`. 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.
+- `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.
+- `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.
+
 ## Functions
 The following functions are exported by the library:
 
@@ -1287,10 +1424,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
+```
+
+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 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.
+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 +1452,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' | 'PART_VALIDATION_FAILED';
 export declare class RGXError extends Error {
     _message: string;
     code: RGXErrorCode;

package/dist/errors/index.d.ts

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

package/dist/errors/index.js

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

package/dist/errors/partValidationFailed.d.ts

@@ -0,0 +1,7 @@
+import { RGXError } from "./base";
+export declare class RGXPartValidationFailedError extends RGXError {
+    gotRaw: string;
+    gotTransformed: unknown;
+    constructor(message: string, gotRaw: string, gotTransformed: unknown);
+    calcMessage(message: string): string;
+}

package/dist/errors/partValidationFailed.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXPartValidationFailedError = void 0;
+const base_1 = require("./base");
+class RGXPartValidationFailedError extends base_1.RGXError {
+    constructor(message, gotRaw, gotTransformed) {
+        super(message, 'PART_VALIDATION_FAILED');
+        this.name = 'RGXPartValidationFailedError';
+        this.gotRaw = gotRaw;
+        this.gotTransformed = gotTransformed;
+    }
+    calcMessage(message) {
+        return `${message}; Got: ${this.gotRaw} (transformed: ${JSON.stringify(this.gotTransformed)})`;
+    }
+}
+exports.RGXPartValidationFailedError = RGXPartValidationFailedError;

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,16 @@ 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) {
+    const result = regexMatchAtPosition(regex, str, position);
+    if (result === null) {
+        throw new errors_1.RGXRegexNotMatchedAtPositionError("Regex not matched at index", regex, str, position, contextSize);
+    }
+    return result;
 }

package/dist/walker/base.d.ts

@@ -0,0 +1,41 @@
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
+import { RGXConvertibleToken, RGXToken } from "../types";
+import { RGXPart, RGXCapture } from "./part";
+export type RGXWalkerOptions<R> = {
+    startingSourcePosition?: number;
+    reduced?: R;
+};
+export declare class RGXWalker<R> implements RGXConvertibleToken {
+    readonly source: string;
+    _sourcePosition: number;
+    readonly tokens: RGXTokenCollection;
+    _tokenPosition: number;
+    reduced: R;
+    captures: RGXCapture[];
+    private _stopped;
+    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);
+    get stopped(): boolean;
+    constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalkerOptions<R>);
+    stop(): void;
+    atTokenEnd(): boolean;
+    hasNextToken(predicate?: (token: RGXToken) => boolean): boolean;
+    atSourceEnd(): boolean;
+    hasNextSource(predicate?: (rest: string) => boolean): boolean;
+    lastCapture(): RGXCapture | null;
+    currentToken(): RGXToken;
+    remainingSource(): string | null;
+    capture(token: RGXToken): string;
+    step(): RGXCapture | 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,161 @@
+"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 }, "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;
+    }
+    get stopped() {
+        return this._stopped;
+    }
+    constructor(source, tokens, options = {}) {
+        this.captures = [];
+        this._stopped = false;
+        this.source = source;
+        this.sourcePosition = options.startingSourcePosition ?? 0;
+        this.tokens = new collection_1.RGXTokenCollection(tokens, "concat");
+        this.tokenPosition = 0;
+        this.reduced = options.reduced ?? null;
+    }
+    stop() {
+        this._stopped = true;
+    }
+    atTokenEnd() {
+        return this.tokenPosition >= this.tokens.length;
+    }
+    hasNextToken(predicate = () => true) {
+        return !this.atTokenEnd() && predicate(this.currentToken());
+    }
+    atSourceEnd() {
+        return this.sourcePosition >= this.source.length;
+    }
+    hasNextSource(predicate = () => true) {
+        return !this.atSourceEnd() && predicate(this.remainingSource());
+    }
+    lastCapture() {
+        if (this.captures.length === 0)
+            return null;
+        return this.captures[this.captures.length - 1];
+    }
+    currentToken() {
+        if (this.atTokenEnd())
+            return null;
+        return this.tokens.at(this.tokenPosition);
+    }
+    remainingSource() {
+        if (this.atSourceEnd())
+            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);
+        this.sourcePosition += match.length;
+        return match;
+    }
+    step() {
+        if (this.atTokenEnd())
+            return null;
+        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?.(token, this);
+            if (control === "stop") {
+                this._stopped = true;
+                return null;
+            }
+            if (control === "skip") {
+                this.tokenPosition++;
+                return null;
+            }
+            if (control === "silent") {
+                silent = true;
+            }
+        }
+        // Capture the match
+        const raw = this.capture(token);
+        const value = isPart ? token.transform(raw) : raw;
+        const captureResult = { raw, value };
+        // Validate the part. If validation fails, it will throw an error, so nothing below will run.
+        if (isPart) {
+            token.validate(captureResult, this);
+        }
+        // Skip adding the capture if in silent mode.
+        if (!silent) {
+            this.captures.push(captureResult);
+        }
+        // Notify Part after capture
+        if (isPart) {
+            token.afterCapture?.(captureResult, token, this);
+        }
+        this.tokenPosition++;
+        return captureResult;
+    }
+    stepToToken(predicate) {
+        while (this.hasNextToken()) {
+            this._stopped = false;
+            if (predicate(this.currentToken()))
+                break;
+            this.step();
+            if (this._stopped)
+                break;
+        }
+    }
+    stepToPart(predicate = () => true) {
+        // If currently at a Part, step past it first so repeated
+        // calls advance to the next Part rather than getting stuck.
+        if (this.currentToken() instanceof part_1.RGXPart) {
+            this._stopped = false;
+            this.step();
+            if (this._stopped)
+                return;
+        }
+        this.stepToToken(token => token instanceof part_1.RGXPart && predicate(token));
+    }
+    walk() {
+        return this.stepToToken(() => false);
+    }
+    // When used as a convertible token, treat the walker as its 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,
+            reduced: (0, immutability_utils_1.extClone)(this.reduced, (0, immutability_utils_1.depthDecrement)(1))
+        });
+        clone._tokenPosition = this.tokenPosition;
+        clone.captures = (0, immutability_utils_1.extClone)(this.captures, (0, immutability_utils_1.depthDecrement)(1));
+        clone._stopped = this._stopped;
+        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,30 @@
+import { RGXConvertibleToken, RGXToken } from "../types";
+import type { RGXWalker } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+export type RGXPartControl = "skip" | "stop" | "silent" | void;
+export type RGXCapture<T = unknown> = {
+    raw: string;
+    value: T;
+};
+export type RGXPartOptions<R, T = string> = {
+    transform: (captured: string) => T;
+    validate: (captured: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => boolean | string;
+    beforeCapture: ((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null;
+    afterCapture: ((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null;
+};
+export declare class RGXPart<R, T = string> implements RGXConvertibleToken {
+    token: RGXToken;
+    readonly transform: RGXPartOptions<R, T>["transform"];
+    private readonly _validate;
+    readonly beforeCapture: RGXPartOptions<R, T>["beforeCapture"];
+    readonly afterCapture: RGXPartOptions<R, T>["afterCapture"];
+    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>>);
+    validate(capture: RGXCapture<T>, 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,56 @@
+"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");
+const errors_1 = require("../errors");
+// A Part is purely a definition: a token + optional callbacks.
+// It does NOT store capture state — that lives on the walker.
+class RGXPart {
+    constructor(token, options = {}) {
+        this.token = token;
+        this.transform = options.transform ?? ((captured) => captured);
+        this._validate = options.validate ?? (() => true);
+        this.beforeCapture = options.beforeCapture ?? null;
+        this.afterCapture = options.afterCapture ?? null;
+    }
+    validate(capture, walker) {
+        const result = this._validate(capture, this, walker);
+        if (result === true)
+            return;
+        const message = typeof result === "string" ? result : "Part Validation Failed";
+        throw new errors_1.RGXPartValidationFailedError(message, capture.raw, capture.value);
+    }
+    // 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,
+            beforeCapture: this.beforeCapture,
+            afterCapture: this.afterCapture,
+        });
+    }
+}
+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": "6.0.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",