@ptolemy2002/rgx 5.6.0 → 6.1.0

package/README.md

@@ -79,21 +79,27 @@ type RGXGroupTokenArgs = {
     capturing?: boolean;
 };
 
-type RGXPartEventType = "pre-capture" | "post-capture";
+type RGXPartControl = "skip" | "stop" | "silent" | void;
+
+type RGXCapture<T = unknown> = {
+    raw: string;
+    value: T;
+};
+
 type RGXPartOptions<R, T=string> = {
     transform: (captured: string) => T;
-    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+    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;
-    reducedCurrent?: R;
+    reduced?: R;
 };
 
-type RGXWalkerFlags = {
-    stopped: boolean;
-    skipped: boolean;
-    nonCapture: boolean;
+type RGXWOptions<R = unknown> = Omit<RGXWalkerOptions<R>, "startingSourcePosition"> & {
+    multiline?: boolean;
 };
 ```
 
@@ -325,6 +331,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.
 
@@ -579,7 +600,7 @@ constructor(pattern: string | RegExp, flags?: string)
 - `[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 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.
 
@@ -594,24 +615,25 @@ 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`.
+  - `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.
-- `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`.
+- `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
-- `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.
+- `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 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 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.
 
@@ -627,37 +649,33 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `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`.
+  - `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. Setting this validates that the value is >= 0 and < `source.length`, throwing `RGXOutOfBoundsError` if not.
+- `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.
-- `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`.
+- `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
-- `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`.
+- `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 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.
+- `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, captured strings, and flags.
+- `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:
@@ -1137,6 +1155,37 @@ As an alternative to using the `rgx` template tag, you can directly call `rgxa`
 #### Returns
 - `ExtRegExp`: An `ExtRegExp` object constructed from the resolved tokens and the provided flags.
 
+### rgxw
+```typescript
+function rgxw<R = unknown>(source: string, {multiline=true, ...options}: RGXWOptions<R> = {}): (strings: TemplateStringsArray, ...tokens: RGXToken[]
+) => RGXWalker<R>
+```
+A helper function that creates an `RGXWalker` instance from an interpolation of strings and tokens. The token array is processed exactly like in `rgx`, but instead of returning an `ExtRegExp`, it returns an `RGXWalker` that can be used to walk through matches of the regex pattern in the source string.
+
+#### Parameters
+  - `source` (`string`): An arbitrary string value that will be included in the `source` property of the walker object.
+  - `options` (`RGXWOptions<R>`, optional): Additional options for configuring the behavior of the resulting `RGXWalker`. This includes:
+    - `multiline` (`boolean`, optional): Whether to strip newlines and trim leading whitespace from the literal string parts of the template. Defaults to `true`. When `true`, each literal string part is split by newlines, each line has its leading whitespace trimmed, empty lines are removed, and the remaining lines are joined together. Interpolated tokens (including string tokens via `${"..."}`) are not affected. When `false`, literal string parts are preserved exactly as written.
+    - `reduced` (`R`, optional): An optional initial value for the walker's `reduced` property, which can be used to accumulate results across matches.
+
+#### Returns
+- `(strings: TemplateStringsArray, ...tokens: RGXToken[]) => RGXWalker<R>`: A template tag function that takes a template literal and returns an `RGXWalker` instance configured with the provided source, the provided tokens, and the specified options.
+
+### rgxwa
+```typescript
+function rgxwa<R = unknown>(source: string, tokens: RGXToken[], options: Omit<RGXWOptions<R>, "multiline"> = {}): RGXWalker<R>
+```
+As an alternative to using the `rgxw` template tag, you can directly call `rgxwa` with a source string, an array of RGX tokens, and options to get an `RGXWalker` instance. This is useful in cases where you don't want to use a template literal. The token array is processed exactly like in `rgxa`, and the provided options are passed through to configure the resulting walker.
+
+#### Parameters
+  - `source` (`string`): An arbitrary string value that will be included in the `source` property of the walker object.
+  - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern for the walker.
+  - `options` (`Omit<RGXWOptions<R>, "multiline">`, optional): Additional options for configuring the behavior of the resulting `RGXWalker`, excluding the `multiline` option which is not applicable when not using a template literal. This includes:
+    - `reduced` (`R`, optional): An optional initial value for the walker's `reduced` property, which can be used to accumulate results across matches.
+
+#### Returns
+- `RGXWalker<R>`: An `RGXWalker` instance configured with the provided source, the resolved tokens, and the specified options.
+
 ### expandRgxUnionTokens
 ```typescript
 function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): 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' | 'REGEX_NOT_MATCHED_AT_POSITION';
+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

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

package/dist/errors/index.js

@@ -29,3 +29,4 @@ __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/index.d.ts

@@ -1,5 +1,6 @@
 import * as t from "./types";
 import { ExtRegExp } from "./ExtRegExp";
+import { RGXWalker } from "./walker";
 export * from "./errors";
 export * from "./types";
 export * from "./typeGuards";
@@ -15,3 +16,5 @@ 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;
+export declare function rgxwa<R = unknown>(source: string, tokens: t.RGXToken[], options?: Omit<t.RGXWOptions<R>, "multiline">): RGXWalker<R>;
+export declare function rgxw<R = unknown>(source: string, { multiline, ...options }?: t.RGXWOptions<R>): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => RGXWalker<R>;

package/dist/index.js

@@ -16,11 +16,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxa = rgxa;
 exports.default = rgx;
+exports.rgxwa = rgxwa;
+exports.rgxw = rgxw;
 const class_1 = require("./class");
 const flag_transformer_1 = require("./flag-transformer");
 const concat_1 = require("./concat");
 const internal_1 = require("./internal");
 const ExtRegExp_1 = require("./ExtRegExp");
+const walker_1 = require("./walker");
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
@@ -50,3 +53,11 @@ function rgx(flags = '', multiline = true) {
         return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens, multiline), flags);
     };
 }
+function rgxwa(source, tokens, options = {}) {
+    return new walker_1.RGXWalker(source, tokens, options);
+}
+function rgxw(source, { multiline = true, ...options } = {}) {
+    return (strings, ...tokens) => {
+        return rgxwa(source, (0, internal_1.taggedTemplateToArray)(strings, tokens, multiline), options);
+    };
+}

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { Branded } from "@ptolemy2002/ts-brand-utils";
 import type { RGXClassToken } from "./class";
 import type { ExtRegExp } from "./ExtRegExp";
 import type { RGXTokenCollection } from "./collection";
+import type { RGXWalkerOptions } from "./walker";
 export type RGXNoOpToken = null | undefined;
 export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
@@ -45,3 +46,6 @@ export type ValidRegexFlags = Branded<string, [ValidRegexFlagsBrandSymbol]> | Va
 export declare const validIdentifierSymbol: unique symbol;
 export type ValidIdentifierBrandSymbol = typeof validIdentifierSymbol;
 export type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;
+export type RGXWOptions<R = unknown> = Omit<RGXWalkerOptions<R>, "startingSourcePosition"> & {
+    multiline?: boolean;
+};

package/dist/utils/regexMatchAtPosition.js

@@ -22,8 +22,9 @@ function doesRegexMatchAtPosition(regex, str, position) {
     return regexMatchAtPosition(regex, str, position) !== null;
 }
 function assertRegexMatchesAtPosition(regex, str, position, contextSize = 10) {
-    if (!doesRegexMatchAtPosition(regex, str, position)) {
+    const result = regexMatchAtPosition(regex, str, position);
+    if (result === null) {
         throw new errors_1.RGXRegexNotMatchedAtPositionError("Regex not matched at index", regex, str, position, contextSize);
     }
-    return regexMatchAtPosition(regex, str, position);
+    return result;
 }

package/dist/walker/base.d.ts

@@ -1,45 +1,37 @@
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
 import { RGXConvertibleToken, RGXToken } from "../types";
-import { RGXPart } from "./part";
+import { RGXPart, RGXCapture } from "./part";
 export type RGXWalkerOptions<R> = {
     startingSourcePosition?: number;
-    reducedCurrent?: R;
-};
-export type RGXWalkerFlags = {
-    stopped: boolean;
-    skipped: boolean;
-    nonCapture: boolean;
+    reduced?: R;
 };
 export declare class RGXWalker<R> implements RGXConvertibleToken {
     readonly source: string;
     _sourcePosition: number;
     readonly tokens: RGXTokenCollection;
     _tokenPosition: number;
-    reducedCurrent: R;
-    capturedStrings: string[];
-    flags: RGXWalkerFlags;
+    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>);
-    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;
+    lastCapture(): RGXCapture | null;
+    currentToken(): RGXToken;
     remainingSource(): string | null;
     capture(token: RGXToken): string;
-    step(flagReset?: boolean): string | null;
+    step(): RGXCapture | null;
     stepToToken(predicate: (token: RGXToken) => boolean): void;
     stepToPart(predicate?: (part: RGXPart<R>) => boolean): void;
     walk(): void;

package/dist/walker/base.js

@@ -13,7 +13,7 @@ class RGXWalker {
         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");
+        (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() {
@@ -23,114 +23,119 @@ class RGXWalker {
         (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.capturedStrings = [];
-        this.flags = {
-            stopped: false,
-            skipped: false,
-            nonCapture: false
-        };
+        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.reducedCurrent = options.reducedCurrent ?? null;
-    }
-    resetFlags() {
-        this.flags.stopped = false;
-        this.flags.skipped = false;
-        this.flags.nonCapture = false;
+        this.reduced = options.reduced ?? null;
     }
     stop() {
-        this.flags.stopped = true;
-    }
-    skip() {
-        this.flags.skipped = true;
-    }
-    preventCapture() {
-        this.flags.nonCapture = true;
+        this._stopped = true;
     }
     atTokenEnd() {
         return this.tokenPosition >= this.tokens.length;
     }
     hasNextToken(predicate = () => true) {
-        return !this.atTokenEnd() && predicate(this.nextToken());
+        return !this.atTokenEnd() && predicate(this.currentToken());
     }
     atSourceEnd() {
-        return this.sourcePosition >= this.source.length - 1;
+        return this.sourcePosition >= this.source.length;
     }
     hasNextSource(predicate = () => true) {
         return !this.atSourceEnd() && predicate(this.remainingSource());
     }
-    hasCapturedStrings(minCount = 1) {
-        return this.capturedStrings.length >= minCount;
-    }
-    getLastCapturedString() {
-        if (!this.hasCapturedStrings())
+    lastCapture() {
+        if (this.captures.length === 0)
             return null;
-        return this.capturedStrings[this.capturedStrings.length - 1];
+        return this.captures[this.captures.length - 1];
     }
-    nextToken() {
-        if (this.tokenPosition >= this.tokens.length)
+    currentToken() {
+        if (this.atTokenEnd())
             return null;
         return this.tokens.at(this.tokenPosition);
     }
     remainingSource() {
-        if (this.sourcePosition >= this.source.length - 1)
+        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);
-        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
+        this.sourcePosition += match.length;
         return match;
     }
-    step(flagReset = true) {
-        if (flagReset)
-            this.resetFlags();
-        if (!this.hasNextToken())
+    step() {
+        if (this.atTokenEnd())
             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);
+        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 captured;
+        return captureResult;
     }
     stepToToken(predicate) {
         while (this.hasNextToken()) {
-            this.resetFlags();
-            if (predicate(this.nextToken()))
+            this._stopped = false;
+            if (predicate(this.currentToken()))
                 break;
-            this.step(false);
-            if (this.flags.stopped)
+            this.step();
+            if (this._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)
+        // 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.flags.stopped)
-            return;
+            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, just treat the walker as
-    // a collection.
+    // When used as a convertible token, treat the walker as its collection.
     toRgx() {
         return this.tokens;
     }
@@ -140,11 +145,11 @@ class RGXWalker {
             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))
+            reduced: (0, immutability_utils_1.extClone)(this.reduced, (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));
+        clone.captures = (0, immutability_utils_1.extClone)(this.captures, (0, immutability_utils_1.depthDecrement)(1));
+        clone._stopped = this._stopped;
         return clone;
     }
 }

package/dist/walker/part.d.ts

@@ -1,21 +1,27 @@
 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 RGXPartControl = "skip" | "stop" | "silent" | void;
+export type RGXCapture<T = unknown> = {
+    raw: string;
+    value: T;
+};
 export type RGXPartOptions<R, T = string> = {
     transform: (captured: string) => T;
-    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+    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;
-    capturedString: string | null;
-    capturedValue: T | null;
     readonly transform: RGXPartOptions<R, T>["transform"];
-    readonly onEvent: RGXPartOptions<R, T>["onEvent"];
+    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>>);
-    triggerEvent(eventType: RGXPartEventType, walker: RGXWalker<R>): void;
+    validate(capture: RGXCapture<T>, walker: RGXWalker<R>): void;
     get rgxIsGroup(): boolean;
     get rgxIsRepeatable(): boolean;
     toRgx(): RGXToken;

package/dist/walker/part.js

@@ -6,23 +6,23 @@ 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.capturedString = null;
-        this.capturedValue = null;
         this.token = token;
         this.transform = options.transform ?? ((captured) => captured);
-        this.onEvent = options.onEvent ?? null;
+        this._validate = options.validate ?? (() => true);
+        this.beforeCapture = options.beforeCapture ?? null;
+        this.afterCapture = options.afterCapture ?? 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);
+    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() {
@@ -41,7 +41,11 @@ class RGXPart {
     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 });
+        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;

package/package.json

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