@ptolemy2002/rgx 7.4.0 → 7.6.0

package/README.md

@@ -88,10 +88,12 @@ type RGXCapture<T = unknown> = {
     start: number;
     end: number;
     ownerId: string | null;
+    branch: number;
 };
 
 type RGXPartOptions<R, T=string> = {
     id: string;
+    rawTransform: (captured: string) => 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;
@@ -108,6 +110,10 @@ type RGXWalkerOptions<R> = {
 type RGXWOptions<R = unknown> = Omit<RGXWalkerOptions<R>, "startingSourcePosition"> & {
     multiline?: boolean;
 };
+
+// See src/constants.ts for the actual mapping of predefined constant names to their token values
+type RGXPredefinedConstant = keyof typeof RGX_PREDEFINED_CONSTANTS;
+type RGXConstantName = RGXPredefinedConstant | (string & {});
 ```
 
 ## Classes
@@ -622,6 +628,7 @@ constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>)
 - `token` (`RGXToken`): The token to wrap.
 - `options` (`Partial<RGXPartOptions<R, T>>`, optional): Configuration options. Defaults to `{}`.
   - `id` (`string`, optional): An optional identifier for this part. Defaults to `null`, but must be a string if provided.
+  - `rawTransform` (`(captured: string) => string`, optional): A function that transforms the raw captured string before it is stored as `raw` on the capture result and before `transform` is applied. Defaults to an identity function.
   - `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`.
@@ -630,6 +637,7 @@ constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>)
 #### Properties
 - `id` (`string | null`): An optional identifier for this part.
 - `token` (`RGXToken`): The wrapped token.
+- `rawTransform` (`(captured: string) => string`, readonly): The raw transform function applied to the matched string before it is stored as `raw` and before `transform` is called.
 - `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`.
@@ -638,7 +646,7 @@ constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>)
 
 #### 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.
+- `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 `rawTransform`, `transform`, `beforeCapture`, and `afterCapture` references.
 - `hasId() => this is RGXPart<R, T> & { id: string }`: A type guard that checks if this part has a non-null `id`. If `true`, narrows the type to indicate that `id` is a string.
 - `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`.
 
@@ -669,14 +677,14 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `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, a `value` (the transform result for Parts, or the raw string for plain tokens), `start` and `end` indices in the source string, and an `ownerId` that is the `id` of the Part that produced it (or `null` for captures from plain tokens or parts without ids).
+- `captures` (`RGXCapture[]`): An array of structured capture results recorded during walking. Each entry has a `raw` string (the `rawTransform` result for Parts, or the matched string for plain tokens), a `value` (the `transform` result for Parts, or the matched string for plain tokens), `start` and `end` indices in the source string, an `ownerId` that is the `id` of the Part that produced it (or `null` for captures from plain tokens or parts without ids), and a `branch` index indicating which alternative of a multi-branch Part token was matched (or `0` if there is only one branch or the token is not a Part).
 - `namedCaptures` (`Record<string, RGXCapture[]>`): An object mapping capture IDs to their corresponding `RGXCapture` results. Only Parts with non-null IDs are included. The captures occur in the same order as they appear in the `captures` array.
 - `infinite` (`boolean`): Whether the walker is in infinite mode — stays at the last token when the token collection is exhausted until the source is consumed.
 - `looping` (`boolean`): Whether the walker is in looping mode — loops back to token position `0` when the token collection is exhausted until the source is consumed.
 - `stopped` (`boolean`, readonly): Whether the walker has been stopped, either by a Part's `beforeCapture` returning `"stop"` or by calling `stop()` in an `afterCapture` callback.
 
 #### Methods
-- `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.
+- `stop() => this`: 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`).
@@ -684,11 +692,12 @@ constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalker
 - `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.
+- `capture(token: RGXToken, includeMatch?: false) => 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.
+- `capture(token: RGXToken, includeMatch: true) => RegExpExecArray`: Same as above, but returns the full `RegExpExecArray` from the match instead of just the matched string.
 - `step() => RGXCapture | null`: Steps through the next token in the collection. If the token is an `RGXPart`, calls `beforeCapture` first — if it returns `"stop"`, sets `stopped` and returns `null` without advancing; if `"skip"`, advances the token position and returns `null` without capturing; if `"silent"`, captures but does not add to `captures` or `namedCaptures`. After capturing, validates. After validating, calls `afterCapture` if present. Returns the `RGXCapture` result, or `null` if there are no more tokens (or no more source in `infinite`/`looping` mode), the step was skipped, or the walker was stopped.
-- `stepToToken(predicate: (token: RGXToken) => boolean) => void`: Steps through tokens until the predicate returns `true` for the current token or the walker is stopped. The matching token is not consumed.
-- `stepToPart(predicate?: (part: RGXPart<R>) => boolean) => void`: Steps through tokens until the next `RGXPart` satisfying the predicate is reached. If already at a Part, steps once first to move past it. The matching Part is not consumed.
-- `walk() => void`: Steps through all remaining tokens until the end of the token collection (or until the source is consumed in `infinite`/`looping` mode) or the walker is stopped.
+- `stepToToken(predicate: (token: RGXToken) => boolean) => this`: 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) => this`: 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() => this`: Steps through all remaining tokens until the end of the token collection (or until the source is consumed in `infinite`/`looping` mode) or the walker is stopped.
 - `toRgx() => RGXToken`: Returns the internal `RGXTokenCollection`, allowing the walker to be used as a convertible token.
 - `clone(depth: CloneDepth = "max") => RGXWalker`: Creates a clone of the walker. When `depth` is `0`, returns `this`; otherwise, creates a new `RGXWalker` with cloned tokens, source position, reduced value, captures, stopped state, and the `infinite`/`looping` flags.
 
@@ -1480,49 +1489,58 @@ Creates a new `ExtRegExp` from an existing one with additional or replaced flags
 
 ### regexMatchAtPosition
 ```typescript
-function regexMatchAtPosition(regex: RegExp, str: string, position: number): string | null
+function regexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch: true): RegExpExecArray | null
+function regexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch?: false): 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.
+Attempts to match the given regular expression 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.
 
 #### 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`.
+  - `includeMatch` (`boolean`, optional): When `true`, returns the full `RegExpExecArray` instead of just the matched string. Defaults to `false`.
 
 #### Returns
-- `string | null`: The matched string if the regex matches at the specified position, otherwise `null`.
+- `string | null`: When `includeMatch` is `false` (default): the matched string if the regex matches at the specified position, otherwise `null`.
+- `RegExpExecArray | null`: When `includeMatch` is `true`: the full match array if the regex matches, otherwise `null`.
 
 ### doesRegexMatchAtPosition
 ```typescript
-function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch: true): RegExpExecArray | false
+function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch?: false): 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.
+Tests whether the given regular expression matches at a specific position in the string.
 
 #### Parameters
   - `regex` (`RegExp`): The regular expression to test.
   - `str` (`string`): The string to test against.
   - `position` (`number`): The zero-based index in the string at which to test the match. Must be >= 0 and < `str.length`.
+  - `includeMatch` (`boolean`, optional): When `true`, returns the full `RegExpExecArray` on a match instead of `true`. Defaults to `false`.
 
 #### Returns
-- `boolean`: `true` if the regex matches at the specified position, otherwise `false`.
+- `boolean`: When `includeMatch` is `false` (default): `true` if the regex matches at the specified position, otherwise `false`.
+- `RegExpExecArray | false`: When `includeMatch` is `true`: the full match array if the regex matches, otherwise `false`.
 
 ### assertRegexMatchesAtPosition
 ```typescript
-function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize?: number | null): string
+function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize?: number | null, includeMatch?: false): string
+function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize: number | null | undefined, includeMatch: true): RegExpExecArray
 ```
 
-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.
+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 or full match array depending on `includeMatch`.
 
 #### 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`.
+  - `includeMatch` (`boolean`, optional): When `true`, returns the full `RegExpExecArray` instead of just the matched string. Defaults to `false`.
 
 #### Returns
-- `string`: The matched string if the regex matches at the specified position. Throws `RGXRegexNotMatchedAtPositionError` if there is no match.
+- `string`: When `includeMatch` is `false` (default): the matched string. Throws `RGXRegexNotMatchedAtPositionError` if there is no match.
+- `RegExpExecArray`: When `includeMatch` is `true`: the full match array. Throws `RGXRegexNotMatchedAtPositionError` if there is no match.
 
 ### cloneRGXToken
 ```typescript
@@ -1537,6 +1555,13 @@ Creates a clone of the given RGX token to the given depth, provided that the tok
 #### Returns
 - `T`: The cloned token.
 
+### RGX_PREDEFINED_CONSTANTS
+```typescript
+const RGX_PREDEFINED_CONSTANTS: Record<RGXPredefinedConstant, RGXToken>
+```
+
+A read-only object containing all of the library's built-in constant definitions, keyed by their `RGXPredefinedConstant` name. This is the source from which the predefined constants are registered at module load time. It can be used to inspect available constant names at compile time (via `keyof typeof RGX_PREDEFINED_CONSTANTS`) or to iterate over the predefined set without calling `listRGXConstants`.
+
 ### listRGXConstants
 ```typescript
 function listRGXConstants(): string[]
@@ -1549,52 +1574,52 @@ Returns the names of all currently defined RGX constants.
 
 ### hasRGXConstant
 ```typescript
-function hasRGXConstant(name: string): boolean
+function hasRGXConstant(name: RGXConstantName): boolean
 ```
 
 Checks if an RGX constant with the given name exists.
 
 #### Parameters
-  - `name` (`string`): The constant name to check.
+  - `name` (`RGXConstantName`): The constant name to check.
 
 #### Returns
 - `boolean`: `true` if the constant exists, otherwise `false`.
 
 ### assertHasRGXConstant
 ```typescript
-function assertHasRGXConstant(name: string): void
+function assertHasRGXConstant(name: RGXConstantName): void
 ```
 
 Asserts that an RGX constant with the given name exists. If the assertion fails, an `RGXInvalidConstantKeyError` will be thrown.
 
 #### Parameters
-  - `name` (`string`): The constant name to assert.
+  - `name` (`RGXConstantName`): The constant name to assert.
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
 
 ### assertNotHasRGXConstant
 ```typescript
-function assertNotHasRGXConstant(name: string): void
+function assertNotHasRGXConstant(name: RGXConstantName): void
 ```
 
 Asserts that an RGX constant with the given name does not exist. If the assertion fails, an `RGXConstantConflictError` will be thrown.
 
 #### Parameters
-  - `name` (`string`): The constant name to assert.
+  - `name` (`RGXConstantName`): The constant name to assert.
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.
 
 ### defineRGXConstant
 ```typescript
-function defineRGXConstant(name: string, value: RGXToken): RGXToken
+function defineRGXConstant(name: RGXConstantName, value: RGXToken): RGXToken
 ```
 
 Defines a new RGX constant with the given name and value. If the value is a native token (string, number, boolean, or no-op), it is automatically wrapped in an `RGXClassWrapperToken` before being stored. This ensures that native-valued constants are not stripped by multiline template processing in `rgx`, since only the literal string parts of the template are affected by multiline mode. Throws an `RGXConstantConflictError` if a constant with the same name already exists.
 
 #### Parameters
-  - `name` (`string`): The name for the constant.
+  - `name` (`RGXConstantName`): The name for the constant.
   - `value` (`RGXToken`): The token value to associate with the name. Native tokens are automatically wrapped in `RGXClassWrapperToken`.
 
 #### Returns
@@ -1602,26 +1627,26 @@ Defines a new RGX constant with the given name and value. If the value is a nati
 
 ### rgxConstant
 ```typescript
-function rgxConstant(name: string): RGXToken
+function rgxConstant(name: RGXConstantName): RGXToken
 ```
 
 Retrieves the value of an RGX constant by name. Throws an `RGXInvalidConstantKeyError` if no constant with the given name exists.
 
 #### Parameters
-  - `name` (`string`): The constant name to retrieve.
+  - `name` (`RGXConstantName`): The constant name to retrieve.
 
 #### Returns
 - `RGXToken`: The token value associated with the constant name.
 
 ### deleteRGXConstant
 ```typescript
-function deleteRGXConstant(name: string): void
+function deleteRGXConstant(name: RGXConstantName): void
 ```
 
 Deletes an existing RGX constant by name. Throws an `RGXInvalidConstantKeyError` if no constant with the given name exists.
 
 #### Parameters
-  - `name` (`string`): The constant name to delete.
+  - `name` (`RGXConstantName`): The constant name to delete.
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the constant does not exist.
@@ -1643,7 +1668,8 @@ Since these are defined as native tokens (strings), they are automatically wrapp
 ### Special Characters
 | Name | Resolves To | Description |
 | --- | --- | --- |
-| `"any"` | `.` | Matches any single character (except newline by default) |
+| `"any"` | `(?s:.)` | Matches any single character, including newlines |
+| `"non-newline"` | `.` | Matches any single character except newlines |
 | `"start"` | `^` | Start of string anchor |
 | `"line-start"` | `^` (with `m` flag) | Start of line anchor |
 | `"end"` | `$` | End of string anchor |

package/dist/constants.d.ts

@@ -1,8 +1,133 @@
 import { RGXToken } from "./types";
+export declare const RGX_PREDEFINED_CONSTANTS: {
+    readonly newline: "\n";
+    readonly "carriage-return": "\r";
+    readonly tab: "\t";
+    readonly null: "\0";
+    readonly "form-feed": "\f";
+    readonly any: {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-newline": {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly start: {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "line-start": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly end: {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "line-end": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "word-bound": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-word-bound": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "word-bound-start": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "word-bound-end": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly letter: {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "lowercase-letter": {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "uppercase-letter": {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-letter": {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly alphanumeric: {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-alphanumeric": {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly digit: {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-digit": {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly whitespace: {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-whitespace": {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "vertical-whitespace": {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "word-char": {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-word-char": {
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly backspace: {
+        readonly rgxIsGroup: true;
+        readonly rgxGroupWrap: false;
+        readonly toRgx: () => RegExp;
+    };
+    readonly "non-escape-bound": {
+        readonly rgxGroupWrap: false;
+        readonly rgxIsRepeatable: false;
+        readonly toRgx: () => RegExp;
+    };
+};
+export type RGXPredefinedConstant = keyof typeof RGX_PREDEFINED_CONSTANTS;
+export type RGXConstantName = RGXPredefinedConstant | (string & {});
 export declare function listRGXConstants(): string[];
-export declare function hasRGXConstant(name: string): boolean;
-export declare function assertHasRGXConstant(name: string): void;
-export declare function assertNotHasRGXConstant(name: string): void;
-export declare function defineRGXConstant(name: string, value: RGXToken): RegExp | import("./types").RGXConvertibleToken | RGXToken[];
-export declare function rgxConstant(name: string): RGXToken;
-export declare function deleteRGXConstant(name: string): void;
+export declare function hasRGXConstant(name: RGXConstantName): boolean;
+export declare function assertHasRGXConstant(name: RGXConstantName): void;
+export declare function assertNotHasRGXConstant(name: RGXConstantName): void;
+export declare function defineRGXConstant(name: RGXConstantName, value: RGXToken): RegExp | import("./types").RGXConvertibleToken | RGXToken[];
+export declare function rgxConstant(name: RGXConstantName): RGXToken;
+export declare function deleteRGXConstant(name: RGXConstantName): void;

package/dist/constants.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGX_PREDEFINED_CONSTANTS = void 0;
 exports.listRGXConstants = listRGXConstants;
 exports.hasRGXConstant = hasRGXConstant;
 exports.assertHasRGXConstant = assertHasRGXConstant;
@@ -11,6 +12,143 @@ const class_1 = require("./class");
 const errors_1 = require("./errors");
 const typeGuards_1 = require("./typeGuards");
 const rgxConstants = {};
+exports.RGX_PREDEFINED_CONSTANTS = {
+    // Control Characters
+    "newline": "\n",
+    "carriage-return": "\r",
+    "tab": "\t",
+    "null": "\0",
+    "form-feed": "\f",
+    // Special Characters
+    "any": {
+        rgxGroupWrap: false,
+        toRgx() { return /./s; }
+    },
+    "non-newline": {
+        rgxGroupWrap: false,
+        toRgx() { return /./; }
+    },
+    "start": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() { return /^/; }
+    },
+    "line-start": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() { return /^/m; }
+    },
+    "end": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() { return /$/; }
+    },
+    "line-end": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() { return /$/m; }
+    },
+    "word-bound": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() { return /\b/; }
+    },
+    "non-word-bound": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() { return /\B/; }
+    },
+    "word-bound-start": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() {
+            // Make sure there is a non-word character before and a word character after
+            return /(?<=\W)(?=\w)/;
+        }
+    },
+    "word-bound-end": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() {
+            // Make sure there is a word character before and a non-word character after
+            return /(?<=\w)(?=\W)/;
+        }
+    },
+    // Character Sets
+    "letter": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[a-zA-Z]/; }
+    },
+    "lowercase-letter": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[a-z]/; }
+    },
+    "uppercase-letter": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[A-Z]/; }
+    },
+    "non-letter": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[^a-zA-Z]/; }
+    },
+    "alphanumeric": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[a-zA-Z0-9]/; }
+    },
+    "non-alphanumeric": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[^a-zA-Z0-9]/; }
+    },
+    // Predefined Character Sets
+    "digit": {
+        rgxGroupWrap: false,
+        toRgx() { return /\d/; }
+    },
+    "non-digit": {
+        rgxGroupWrap: false,
+        toRgx() { return /\D/; }
+    },
+    "whitespace": {
+        rgxGroupWrap: false,
+        toRgx() { return /\s/; }
+    },
+    "non-whitespace": {
+        rgxGroupWrap: false,
+        toRgx() { return /\S/; }
+    },
+    "vertical-whitespace": {
+        rgxGroupWrap: false,
+        toRgx() { return /\v/; }
+    },
+    "word-char": {
+        rgxGroupWrap: false,
+        toRgx() { return /\w/; }
+    },
+    "non-word-char": {
+        rgxGroupWrap: false,
+        toRgx() { return /\W/; }
+    },
+    "backspace": {
+        rgxIsGroup: true,
+        rgxGroupWrap: false,
+        toRgx() { return /[\b]/; }
+    },
+    // Complex Constructs
+    "non-escape-bound": {
+        rgxGroupWrap: false,
+        rgxIsRepeatable: false,
+        toRgx() {
+            // Put this before any pattern to ensure that the pattern is not escaped, i.e., not preceded by an odd number of backslashes.
+            return /(?<=(?<!\\)(?:\\\\)*)(?=[^\\]|$)/;
+        }
+    },
+};
 function listRGXConstants() {
     return Object.keys(rgxConstants);
 }
@@ -41,176 +179,6 @@ function deleteRGXConstant(name) {
     assertHasRGXConstant(name);
     delete rgxConstants[name];
 }
-// Control Characters
-defineRGXConstant("newline", "\n");
-defineRGXConstant("carriage-return", "\r");
-defineRGXConstant("tab", "\t");
-defineRGXConstant("null", "\0");
-defineRGXConstant("form-feed", "\f");
-// Special Characters
-defineRGXConstant("any", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /./;
-    }
-});
-defineRGXConstant("start", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /^/;
-    }
-});
-defineRGXConstant("line-start", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /^/m;
-    }
-});
-defineRGXConstant("end", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /$/;
-    }
-});
-defineRGXConstant("line-end", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /$/m;
-    }
-});
-defineRGXConstant("word-bound", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /\b/;
-    }
-});
-defineRGXConstant("non-word-bound", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /\B/;
-    }
-});
-defineRGXConstant("word-bound-start", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        // Make sure there is a non-word character before and a word character after
-        return /(?<=\W)(?=\w)/;
-    }
-});
-defineRGXConstant("word-bound-end", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        // Make sure there is a word character before and a non-word character after
-        return /(?<=\w)(?=\W)/;
-    }
-});
-// Character Sets
-defineRGXConstant("letter", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[a-zA-Z]/;
-    }
-});
-defineRGXConstant("lowercase-letter", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[a-z]/;
-    }
-});
-defineRGXConstant("uppercase-letter", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[A-Z]/;
-    }
-});
-defineRGXConstant("non-letter", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[^a-zA-Z]/;
-    }
-});
-defineRGXConstant("alphanumeric", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[a-zA-Z0-9]/;
-    }
-});
-defineRGXConstant("non-alphanumeric", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[^a-zA-Z0-9]/;
-    }
-});
-// Predefined Character Sets
-defineRGXConstant("digit", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\d/;
-    }
-});
-defineRGXConstant("non-digit", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\D/;
-    }
-});
-defineRGXConstant("whitespace", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\s/;
-    }
-});
-defineRGXConstant("non-whitespace", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\S/;
-    }
-});
-defineRGXConstant("vertical-whitespace", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\v/;
-    }
-});
-defineRGXConstant("word-char", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\w/;
-    }
-});
-defineRGXConstant("non-word-char", {
-    rgxGroupWrap: false,
-    toRgx() {
-        return /\W/;
-    }
-});
-defineRGXConstant("backspace", {
-    rgxIsGroup: true,
-    rgxGroupWrap: false,
-    toRgx() {
-        return /[\b]/;
-    }
-});
-// Complex Constructs
-// Put this before any pattern to ensure that the pattern is not escaped, i.e., not preceded by an odd number of backslashes.
-defineRGXConstant("non-escape-bound", {
-    rgxGroupWrap: false,
-    rgxIsRepeatable: false,
-    toRgx() {
-        return /(?<=(?<!\\)(?:\\\\)*)(?=[^\\]|$)/;
-    }
-});
+for (const [name, value] of Object.entries(exports.RGX_PREDEFINED_CONSTANTS)) {
+    defineRGXConstant(name, value);
+}

package/dist/utils/regexMatchAtPosition.d.ts

@@ -1,3 +1,6 @@
-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;
+export declare function regexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch: true): RegExpExecArray | null;
+export declare function regexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch?: false): string | null;
+export declare function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch: true): RegExpExecArray | false;
+export declare function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number, includeMatch?: false): boolean;
+export declare function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize?: number | null, includeMatch?: false): string;
+export declare function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize: number | null | undefined, includeMatch: true): RegExpExecArray;

package/dist/utils/regexMatchAtPosition.js

@@ -6,7 +6,7 @@ exports.assertRegexMatchesAtPosition = assertRegexMatchesAtPosition;
 const outOfBounds_1 = require("../errors/outOfBounds");
 const regexWithFlags_1 = require("./regexWithFlags");
 const errors_1 = require("../errors");
-function regexMatchAtPosition(regex, str, position) {
+function regexMatchAtPosition(regex, str, position, includeMatch = false) {
     /*
         The y flag means sticky mode, which means the next match must start at
         lastIndex. By setting lastIndex to the position we want to check, we can test
@@ -16,15 +16,18 @@ function regexMatchAtPosition(regex, str, position) {
     const stickyRegex = (0, regexWithFlags_1.regexWithFlags)(regex, "y");
     stickyRegex.lastIndex = position;
     const match = stickyRegex.exec(str);
-    return match ? match[0] : null;
+    return includeMatch ? match : (match ? match[0] : null);
 }
-function doesRegexMatchAtPosition(regex, str, position) {
-    return regexMatchAtPosition(regex, str, position) !== null;
+function doesRegexMatchAtPosition(regex, str, position, includeMatch = false) {
+    const match = regexMatchAtPosition(regex, str, position, true);
+    if (includeMatch)
+        return match ?? false;
+    return match !== null;
 }
-function assertRegexMatchesAtPosition(regex, str, position, contextSize = 10) {
-    const result = regexMatchAtPosition(regex, str, position);
+function assertRegexMatchesAtPosition(regex, str, position, contextSize = 10, includeMatch = false) {
+    const result = regexMatchAtPosition(regex, str, position, true);
     if (result === null) {
         throw new errors_1.RGXRegexNotMatchedAtPositionError("Regex not matched at index", regex, str, position, contextSize);
     }
-    return result;
+    return includeMatch ? result : result[0];
 }

package/dist/walker/base.d.ts

@@ -27,7 +27,7 @@ export declare class RGXWalker<R> implements RGXConvertibleToken {
     set tokenPosition(value: number);
     get stopped(): boolean;
     constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalkerOptions<R>);
-    stop(): void;
+    stop(): this;
     atTokenEnd(): boolean;
     hasNextToken(predicate?: (token: RGXToken) => boolean): boolean;
     atSourceEnd(): boolean;
@@ -35,11 +35,12 @@ export declare class RGXWalker<R> implements RGXConvertibleToken {
     lastCapture(): RGXCapture | null;
     currentToken(): RGXToken;
     remainingSource(): string | null;
-    capture(token: RGXToken): string;
+    capture(token: RGXToken, includeMatch: true): RegExpExecArray;
+    capture(token: RGXToken, includeMatch?: false): string;
     step(): RGXCapture | null;
-    stepToToken(predicate: (token: RGXToken) => boolean): void;
-    stepToPart(predicate?: (part: RGXPart<R>) => boolean): void;
-    walk(): void;
+    stepToToken(predicate: (token: RGXToken) => boolean): this;
+    stepToPart(predicate?: (part: RGXPart<R>) => boolean): this;
+    walk(): this;
     toRgx(): RGXTokenCollection;
     clone(depth?: CloneDepth): RGXWalker<R>;
 }

package/dist/walker/base.js

@@ -8,6 +8,20 @@ const errors_1 = require("../errors");
 const part_1 = require("./part");
 const index_1 = require("../index");
 const internal_1 = require("../internal");
+function createBranchGroups(tokens) {
+    if ((tokens instanceof collection_1.RGXTokenCollection && tokens.mode === "union") ||
+        index_1.RGXClassUnionToken.check(tokens))
+        return createBranchGroups(tokens.tokens);
+    if ((0, index_1.isRGXArrayToken)(tokens)) {
+        const newTokens = tokens.map((token, i) => {
+            return new index_1.RGXGroupToken({ name: `rgx_branch_${i}` }, [token]);
+        });
+        return new index_1.RGXClassUnionToken(newTokens);
+    }
+    else {
+        return tokens;
+    }
+}
 class RGXWalker {
     get sourcePosition() {
         return this._sourcePosition;
@@ -40,6 +54,7 @@ class RGXWalker {
     }
     stop() {
         this._stopped = true;
+        return this;
     }
     atTokenEnd() {
         return this.tokenPosition >= this.tokens.length;
@@ -68,11 +83,11 @@ class RGXWalker {
             return null;
         return this.source.slice(this.sourcePosition);
     }
-    capture(token) {
+    capture(token, includeMatch = false) {
         const regex = (0, index_1.rgxa)([token]);
-        const match = (0, index_1.assertRegexMatchesAtPosition)(regex, this.source, this.sourcePosition);
-        this.sourcePosition += match.length;
-        return match;
+        const match = (0, index_1.assertRegexMatchesAtPosition)(regex, this.source, this.sourcePosition, 10, true);
+        this.sourcePosition += match[0].length;
+        return includeMatch ? match : match[0];
     }
     step() {
         if (!this.infinite && !this.looping && this.atTokenEnd()) {
@@ -104,10 +119,26 @@ class RGXWalker {
         }
         // Capture the match
         const start = this.sourcePosition;
-        const raw = this.capture(token);
+        let innerToken = token;
+        if (isPart)
+            innerToken = createBranchGroups(token.token);
+        const capture = this.capture(innerToken, true);
+        const raw = isPart ? token.rawTransform(capture[0]) : capture[0];
         const end = this.sourcePosition;
         const value = isPart ? token.transform(raw) : raw;
-        const captureResult = { raw, value, start, end, ownerId: isPart && token.hasId() ? token.id : null };
+        let branch = 0;
+        if (isPart) {
+            // Determine branch index for captureResult by finding the first index
+            // with non-undefined match group.
+            for (let i = 0; i < capture.length; i++) {
+                const branchKey = `rgx_branch_${i}`;
+                if (capture.groups && capture.groups[branchKey] !== undefined) {
+                    branch = i;
+                    break;
+                }
+            }
+        }
+        const captureResult = { raw, value, start, end, branch, ownerId: isPart && token.hasId() ? token.id : null };
         // Validate the part. If validation fails, it will throw an error, so nothing below will run.
         if (isPart) {
             token.validate(captureResult, this);
@@ -142,6 +173,7 @@ class RGXWalker {
             if (this._stopped)
                 break;
         }
+        return this;
     }
     stepToPart(predicate = () => true) {
         // If currently at a Part, step past it first so repeated
@@ -150,9 +182,10 @@ class RGXWalker {
             this._stopped = false;
             this.step();
             if (this._stopped)
-                return;
+                return this;
         }
         this.stepToToken(token => token instanceof part_1.RGXPart && predicate(token));
+        return this;
     }
     walk() {
         return this.stepToToken(() => false);

package/dist/walker/part.d.ts

@@ -8,9 +8,11 @@ export type RGXCapture<T = unknown> = {
     start: number;
     end: number;
     ownerId: string | null;
+    branch: number;
 };
 export type RGXPartOptions<R, T = string> = {
     id: string;
+    rawTransform: (captured: string) => 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;
@@ -19,6 +21,7 @@ export type RGXPartOptions<R, T = string> = {
 export declare class RGXPart<R, T = string> implements RGXConvertibleToken {
     id: string | null;
     token: RGXToken;
+    readonly rawTransform: RGXPartOptions<R, T>["rawTransform"];
     readonly transform: RGXPartOptions<R, T>["transform"];
     private readonly _validate;
     readonly beforeCapture: RGXPartOptions<R, T>["beforeCapture"];

package/dist/walker/part.js

@@ -11,6 +11,7 @@ class RGXPart {
     constructor(token, options = {}) {
         this.id = options.id ?? null;
         this.token = token;
+        this.rawTransform = options.rawTransform ?? (captured => captured);
         this.transform = options.transform ?? ((captured) => captured);
         this._validate = options.validate ?? (() => true);
         this.beforeCapture = options.beforeCapture ?? null;
@@ -45,6 +46,7 @@ class RGXPart {
             return this;
         return new RGXPart((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), {
             id: this.id ?? undefined,
+            rawTransform: this.rawTransform,
             transform: this.transform,
             beforeCapture: this.beforeCapture,
             afterCapture: this.afterCapture,

package/package.json

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