@ptolemy2002/rgx 5.4.0 → 5.6.0

package/README.md

@@ -54,7 +54,7 @@ type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // ... see source for full definition
 ;
 
-type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED';
+type RGXErrorCode = 'UNKNOWN' | 'INVALID_RGX_TOKEN' | 'INVALID_REGEX_STRING' | 'INVALID_REGEX_FLAGS' | 'INVALID_VANILLA_REGEX_FLAGS' | 'NOT_IMPLEMENTED' | 'NOT_SUPPORTED' | 'INVALID_IDENTIFIER' | 'OUT_OF_BOUNDS' | 'INVALID_FLAG_TRANSFORMER_KEY' | 'FLAG_TRANSFORMER_CONFLICT' | 'CONSTANT_CONFLICT' | 'INVALID_CONSTANT_KEY' | 'INSERTION_REJECTED' | 'REGEX_NOT_MATCHED_AT_POSITION';
 
 type RangeObject = {
     min?: number | null;
@@ -78,6 +78,23 @@ type RGXGroupTokenArgs = {
     name?: string | null;
     capturing?: boolean;
 };
+
+type RGXPartEventType = "pre-capture" | "post-capture";
+type RGXPartOptions<R, T=string> = {
+    transform: (captured: string) => T;
+    onEvent: ((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null;
+};
+
+type RGXWalkerOptions<R> = {
+    startingSourcePosition?: number;
+    reducedCurrent?: R;
+};
+
+type RGXWalkerFlags = {
+    stopped: boolean;
+    skipped: boolean;
+    nonCapture: boolean;
+};
 ```
 
 ## Classes
@@ -257,6 +274,31 @@ constructor(reason?: string | null, message?: string | null)
 #### Properties
 - `reason` (`string | null`): The reason the insertion was rejected, or `null` if no reason was provided.
 
+### RGXRegexNotMatchedAtPositionError extends RGXError
+A specific error class for regex match failures at a given position. This error is thrown when a regex is expected to match at a specific position in a string but does not (e.g., via `assertRegexMatchesAtPosition`). The error code is set to `REGEX_NOT_MATCHED_AT_POSITION` on instantiation.
+
+#### Constructor
+```typescript
+constructor(message: string, pattern: RegExp, source: string, position: number, contextSize?: number | null)
+```
+- `message` (`string`): The error message.
+- `pattern` (`RegExp`): The regex pattern that failed to match.
+- `source` (`string`): The string that was being matched against.
+- `position` (`number`): The zero-based index in the source string where the match was expected. Must be >= 0 and < `source.length`, or an `RGXOutOfBoundsError` will be thrown.
+- `contextSize` (`number | null`, optional): The number of characters on each side of the position to include in contextual output. Defaults to `null` (full source shown).
+
+#### Properties
+- `pattern` (`RegExp`): The regex pattern that failed to match.
+- `source` (`string`): The string that was being matched against.
+- `position` (`number`): The position where the match was expected. Setting this validates that the value is >= 0 and < `source.length`, throwing `RGXOutOfBoundsError` if not.
+- `contextSize` (`number | null`): The number of characters on each side of the position to include in contextual output, or `null` for the full source.
+
+#### Methods
+- `sourceContext() => string`: Returns the relevant portion of the source string around the position. When `contextSize` is `null` or covers the entire string, returns the full source. Otherwise, returns a substring from `max(0, position - contextSize)` to `min(source.length, position + contextSize)`.
+- `hasLeftContext() => boolean`: Returns `true` if the context window starts after the beginning of the source string (i.e., there is truncated content on the left). Returns `false` when `contextSize` is `null`.
+- `hasRightContext() => boolean`: Returns `true` if the context window ends before the end of the source string (i.e., there is truncated content on the right). Returns `false` when `contextSize` is `null`.
+- `hasFullContext() => boolean`: Returns `true` when the full source is shown (neither side is truncated). This is the case when `contextSize` is `null` or when the context window covers the entire source string.
+
 ### RGXOutOfBoundsError extends RGXError
 A specific error class for out-of-bounds values. This error is thrown when a numeric value falls outside an expected range. The error code is set to `OUT_OF_BOUNDS` on instantiation.
 
@@ -536,6 +578,87 @@ constructor(pattern: string | RegExp, flags?: string)
 #### Static Properties
 - `[Symbol.species]` (`RegExpConstructor`): Returns `ExtRegExp`, ensuring that derived `RegExp` methods (like those returning new regex instances) produce `ExtRegExp` instances rather than plain `RegExp`.
 
+### RGXPart\<R, T=string\>
+A class that wraps an `RGXToken` and captures the matched string when used within an `RGXWalker`. It implements `RGXConvertibleToken`, delegating `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token. After a walker captures a match for this part, the `capturedString` and `capturedValue` properties are populated, with the latter produced by the `transform` function.
+
+A function `rgxPart` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXPart`: A type guard that checks if the given value is an instance of `RGXPart`.
+- `assert(value: unknown): asserts value is RGXPart`: An assertion that checks if the given value is an instance of `RGXPart`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>)
+```
+- `token` (`RGXToken`): The token to wrap.
+- `options` (`Partial<RGXPartOptions<R, T>>`, optional): Configuration options. Defaults to `{}`.
+  - `transform` (`(captured: string) => T`, optional): A function that transforms the captured string into the desired type `T`. Defaults to an identity function that casts the string to `T`.
+  - `onEvent` (`((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null`, optional): A callback invoked when an event is triggered on this part during walking. Defaults to `null`.
+
+#### Properties
+- `token` (`RGXToken`): The wrapped token.
+- `capturedString` (`string | null`): The raw string captured by the walker for this part, or `null` if not yet captured.
+- `capturedValue` (`T | null`): The transformed value produced by applying `transform` to `capturedString`, or `null` if not yet captured.
+- `transform` (`(captured: string) => T`): The transform function used to convert captured strings to values of type `T`.
+- `onEvent` (`((part: RGXPart<R, T>, eventType: RGXPartEventType, walker: RGXWalker<R>) => void) | null`): The event callback, or `null`.
+- `rgxIsGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`.
+- `rgxIsRepeatable` (`boolean`): If the wrapped token is an `RGXConvertibleToken`, delegates to its `rgxIsRepeatable` property (defaulting to `true` if not present). Otherwise, returns `true`.
+
+#### Methods
+- `triggerEvent(eventType: RGXPartEventType, walker: RGXWalker<R>) => void`: Triggers an event on this part. For `"post-capture"` events, sets `capturedString` to the walker's last captured string and `capturedValue` to the result of `transform`. Then calls the `onEvent` callback if present.
+- `toRgx() => RGXToken`: Returns the wrapped token.
+- `clone(depth: CloneDepth = "max") => RGXPart`: Creates a clone of this part. When `depth` is `0`, returns `this`; otherwise, returns a new `RGXPart` with a cloned token and the same `transform` and `onEvent` references.
+
+### RGXWalker\<R\>
+A class that walks through a sequence of RGX tokens, matching each token against a source string at the current position. It implements `RGXConvertibleToken`, delegating to its internal `RGXTokenCollection`. The walker maintains a source position and a token position, advancing through both as tokens are matched. When an `RGXPart` is encountered, its event callbacks are triggered around the capture. The generic type `R` represents a user-defined "reduced" value that can accumulate state during walking (e.g., via `RGXPart` event callbacks).
+
+A function `rgxWalker` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
+
+#### Static Properties
+- `check(value: unknown): value is RGXWalker`: A type guard that checks if the given value is an instance of `RGXWalker`.
+- `assert(value: unknown): asserts value is RGXWalker`: An assertion that checks if the given value is an instance of `RGXWalker`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(source: string, tokens: RGXTokenCollectionInput, options?: RGXWalkerOptions<R>)
+```
+- `source` (`string`): The string to walk through, matching tokens against.
+- `tokens` (`RGXTokenCollectionInput`): The tokens to match sequentially. Internally stored as an `RGXTokenCollection` in 'concat' mode.
+- `options` (`RGXWalkerOptions<R>`, optional): Configuration options. Defaults to `{}`.
+  - `startingSourcePosition` (`number`, optional): The starting index in the source string. Defaults to `0`.
+  - `reducedCurrent` (`R`, optional): The initial value for the `reducedCurrent` accumulator. Defaults to `null`.
+
+#### Properties
+- `source` (`string`): The source string being walked (readonly).
+- `sourcePosition` (`number`): The current index in the source string. Setting this validates that the value is >= 0 and < `source.length`, throwing `RGXOutOfBoundsError` if not.
+- `tokens` (`RGXTokenCollection`): The internal collection of tokens in 'concat' mode (readonly).
+- `tokenPosition` (`number`): The current index in the token collection. Setting this validates that the value is >= 0 and <= `tokens.length`, throwing `RGXOutOfBoundsError` if not.
+- `reducedCurrent` (`R`): A user-defined accumulator value, typically updated by `RGXPart` event callbacks during walking.
+- `capturedStrings` (`string[]`): An array of all strings captured during walking (excluding those captured with the `nonCapture` flag set).
+- `flags` (`RGXWalkerFlags`): The current walker flags: `stopped` halts `stepToToken`/`stepToPart`/`walk`, `skipped` causes `step` to skip the current token without capturing, and `nonCapture` prevents the captured string from being added to `capturedStrings`.
+
+#### Methods
+- `resetFlags() => void`: Resets all flags (`stopped`, `skipped`, `nonCapture`) to `false`.
+- `stop() => void`: Sets the `stopped` flag to `true`, causing any active `stepToToken`, `stepToPart`, or `walk` loop to halt after the current iteration.
+- `skip() => void`: Sets the `skipped` flag to `true`, causing the current `step` call to skip capturing the current token.
+- `preventCapture() => void`: Sets the `nonCapture` flag to `true`, causing the current `step` call to capture the token but not add the matched string to `capturedStrings`.
+- `atTokenEnd() => boolean`: Returns `true` if the token position is at or past the end of the token collection.
+- `hasNextToken(predicate?: (token: RGXToken) => boolean) => boolean`: Returns `true` if there is a next token and it satisfies the optional predicate (defaults to `() => true`).
+- `atSourceEnd() => boolean`: Returns `true` if the source position is at the last character of the source string.
+- `hasNextSource(predicate?: (rest: string) => boolean) => boolean`: Returns `true` if the source position is not at the end and the remaining source satisfies the optional predicate (defaults to `() => true`).
+- `hasCapturedStrings(minCount?: number) => boolean`: Returns `true` if `capturedStrings` has at least `minCount` entries (defaults to `1`).
+- `getLastCapturedString() => string | null`: Returns the last entry in `capturedStrings`, or `null` if empty.
+- `nextToken() => RGXToken | null`: Returns the token at the current token position, or `null` if at the end.
+- `remainingSource() => string | null`: Returns the remaining source string from the current position onward, or `null` if at the end.
+- `capture(token: RGXToken) => string`: Resolves the token to a regex, asserts that it matches at the current source position (throwing `RGXRegexNotMatchedAtPositionError` if not), captures the matched string (unless `nonCapture` is set), and advances the source position by the match length. Returns the matched string.
+- `step(flagReset?: boolean) => string | null`: Steps through the next token in the collection. If `flagReset` is `true` (the default), resets flags first. If the token is an `RGXPart`, triggers `"pre-capture"` before capturing and `"post-capture"` after (when not skipped or non-capturing). Advances the token position and returns the captured string, or `null` if there are no more tokens or the step was skipped.
+- `stepToToken(predicate: (token: RGXToken) => boolean) => void`: Steps through tokens until the predicate returns `true` for the next token or the walker is stopped. The matching token is not consumed.
+- `stepToPart(predicate?: (part: RGXPart<R>) => boolean) => void`: Steps through tokens until the next `RGXPart` satisfying the predicate is reached. If already at a part, steps once first to move past it. The matching part is not consumed.
+- `walk() => void`: Steps through all remaining tokens until the end of the token collection.
+- `toRgx() => RGXToken`: Returns the internal `RGXTokenCollection`, allowing the walker to be used as a convertible token.
+- `clone(depth: CloneDepth = "max") => RGXWalker`: Creates a clone of the walker. When `depth` is `0`, returns `this`; otherwise, creates a new `RGXWalker` with cloned tokens, source position, reduced value, captured strings, and flags.
+
 ## Functions
 The following functions are exported by the library:
 
@@ -950,11 +1073,13 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 
 ### rgx
 ```typescript
-function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => ExtRegExp
+function rgx(flags?: string, multiline?: boolean): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => ExtRegExp
 ```
 
 Creates and returns a template tag function that constructs an `ExtRegExp` object from the provided template literal with the provided flags. The template literal can contain RGX tokens, which will be resolved and concatenated with the literal parts to form the final regex pattern. Before constructing the pattern, any convertible token that defines `rgxAcceptInsertion` is checked; if it returns `false` or a string, an `RGXInsertionRejectedError` is thrown with details about the reason and exactly where the rejection occurred.
 
+When `multiline` is `true` (the default), the literal string parts of the template are processed to strip newlines, trim leading whitespace from each line, and remove empty lines, then joined together. This allows you to write regex patterns across multiple lines in the source code for readability without the newlines and indentation becoming part of the pattern. Only the literal string parts between tokens are affected — interpolated values (tokens) are preserved as-is, including string tokens passed via `${"..."}`. When `multiline` is `false`, all literal string parts are preserved exactly as written, including newlines and whitespace.
+
 The provided `flags` are passed as `currentFlags` to the resolver, enabling inline modifier groups for any `RegExp` literal tokens whose localizable flags (`i`, `m`, `s`) differ from the parent flags. For example, embedding `/foo/i` in a no-flag context produces `(?i:foo)`, while embedding `/bar/` in an `i`-flag context produces `(?-i:bar)`.
 
 Example usages:
@@ -971,11 +1096,26 @@ const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^
 
 const caseInsensitiveWord = /hello/i;
 const pattern4 = rgx()`${beginning}${caseInsensitiveWord} world${end}`; // /^(?i:hello) world$/ - "hello" matches case-insensitively via an inline modifier group, while " world" remains case-sensitive
+
+// Multiline template for readability (multiline is true by default):
+const pattern5 = rgx()`
+    ${beginning}
+    testing ${word}
+    ${end}
+`; // /^testing \w+$/ - same as pattern, but written across multiple lines
+
+// Preserving literal newlines with multiline mode:
+const pattern6 = rgx()`
+    foo
+    bar${rgxConstant("newline")}
+    baz
+`; // /foobar\nbaz/ - the constant newline is preserved, but template newlines are stripped
 ```
 
 #### Parameters
 **Direct**
   - `flags` (`string`, optional): The regex flags to apply to the resulting `ExtRegExp` object (e.g., 'g', 'i', 'm', or custom registered flags). If not provided, no flags will be applied. If provided and not valid regex flags (vanilla or registered custom), an `RGXInvalidRegexFlagsError` will be thrown.
+  - `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.
 
 **Template Tag**
   - `strings` (`TemplateStringsArray`): The literal parts of the template string.
@@ -1270,10 +1410,25 @@ Creates a new `ExtRegExp` from an existing one with additional or replaced flags
 
 ### regexMatchAtPosition
 ```typescript
-function regexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+function regexMatchAtPosition(regex: RegExp, str: string, position: number): string | null
 ```
 
-Tests whether the given regular expression matches at a specific position in the string. This is done by creating a sticky (`y` flag) copy of the regex and setting its `lastIndex` to the desired position. The position must be within the bounds of the string (>= 0 and < string length), or an `RGXOutOfBoundsError` will be thrown.
+Attempts to match the given regular expression at a specific position in the string and returns the matched string, or `null` if there is no match. This is done by creating a sticky (`y` flag) copy of the regex and setting its `lastIndex` to the desired position. The position must be within the bounds of the string (>= 0 and < string length), or an `RGXOutOfBoundsError` will be thrown.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to match.
+  - `str` (`string`): The string to match against.
+  - `position` (`number`): The zero-based index in the string at which to attempt the match. Must be >= 0 and < `str.length`.
+
+#### Returns
+- `string | null`: The matched string if the regex matches at the specified position, otherwise `null`.
+
+### doesRegexMatchAtPosition
+```typescript
+function doesRegexMatchAtPosition(regex: RegExp, str: string, position: number): boolean
+```
+
+Tests whether the given regular expression matches at a specific position in the string. This is a boolean wrapper around `regexMatchAtPosition`, returning `true` if the match is non-null.
 
 #### Parameters
   - `regex` (`RegExp`): The regular expression to test.
@@ -1283,6 +1438,22 @@ Tests whether the given regular expression matches at a specific position in the
 #### Returns
 - `boolean`: `true` if the regex matches at the specified position, otherwise `false`.
 
+### assertRegexMatchesAtPosition
+```typescript
+function assertRegexMatchesAtPosition(regex: RegExp, str: string, position: number, contextSize?: number | null): string
+```
+
+Asserts that the given regular expression matches at a specific position in the string, throwing an `RGXRegexNotMatchedAtPositionError` if it does not. On success, returns the matched string.
+
+#### Parameters
+  - `regex` (`RegExp`): The regular expression to match.
+  - `str` (`string`): The string to match against.
+  - `position` (`number`): The zero-based index in the string at which to assert the match. Must be >= 0 and < `str.length`.
+  - `contextSize` (`number | null`, optional): The number of characters on each side of the position to include in the error's context output. Defaults to `10`.
+
+#### Returns
+- `string`: The matched string if the regex matches at the specified position. Throws `RGXRegexNotMatchedAtPositionError` if there is no match.
+
 ### cloneRGXToken
 ```typescript
 function cloneRGXTokeN<T extends RGXToken>(token: T, depth: CloneDepth="max"): T
@@ -1350,14 +1521,14 @@ Asserts that an RGX constant with the given name does not exist. If the assertio
 function defineRGXConstant(name: string, value: RGXToken): RGXToken
 ```
 
-Defines a new RGX constant with the given name and value. Throws an `RGXConstantConflictError` if a constant with the same name already exists.
+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.
-  - `value` (`RGXToken`): The token value to associate with the name.
+  - `value` (`RGXToken`): The token value to associate with the name. Native tokens are automatically wrapped in `RGXClassWrapperToken`.
 
 #### Returns
-- `RGXToken`: The value that was defined.
+- `RGXToken`: The stored value (after wrapping, if applicable).
 
 ### rgxConstant
 ```typescript
@@ -1389,6 +1560,8 @@ Deletes an existing RGX constant by name. Throws an `RGXInvalidConstantKeyError`
 The library defines the following built-in constants, which are available immediately after import. Each can be retrieved via `rgxConstant(name)`.
 
 ### Control Characters
+Since these are defined as native tokens (strings), they are automatically wrapped in `RGXClassWrapperToken` by `defineRGXConstant`, ensuring they are preserved in multiline mode.
+
 | Name | Resolves To | Description |
 | --- | --- | --- |
 | `"newline"` | `\n` | Newline character |

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/constants.d.ts

@@ -3,6 +3,6 @@ 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): RGXToken;
+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;

package/dist/constants.js

@@ -7,7 +7,9 @@ exports.assertNotHasRGXConstant = assertNotHasRGXConstant;
 exports.defineRGXConstant = defineRGXConstant;
 exports.rgxConstant = rgxConstant;
 exports.deleteRGXConstant = deleteRGXConstant;
+const class_1 = require("./class");
 const errors_1 = require("./errors");
+const typeGuards_1 = require("./typeGuards");
 const rgxConstants = {};
 function listRGXConstants() {
     return Object.keys(rgxConstants);
@@ -27,8 +29,9 @@ function assertNotHasRGXConstant(name) {
 }
 function defineRGXConstant(name, value) {
     assertNotHasRGXConstant(name);
-    rgxConstants[name] = value;
-    return value;
+    // Not strings themselves so that they aren't removed in multiline mode.
+    rgxConstants[name] = (0, typeGuards_1.isRGXNativeToken)(value) ? (0, class_1.rgxClassWrapper)(value) : value;
+    return rgxConstants[name];
 }
 function rgxConstant(name) {
     assertHasRGXConstant(name);

package/dist/errors/base.d.ts

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

package/dist/errors/index.d.ts

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

package/dist/errors/index.js

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

package/dist/errors/regexNotMatchedAtPosition.d.ts

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

package/dist/errors/regexNotMatchedAtPosition.js

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

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export * from "./ExtRegExp";
 export * from "./flag-transformer";
 export * from "./clone";
 export * from "./constants";
+export * from "./walker";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
-export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => 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
@@ -43,9 +44,9 @@ function rgxa(tokens, flags = '') {
     const pattern = (0, concat_1.rgxConcat)(tokens, true, flags);
     return (0, ExtRegExp_1.extRegExp)(pattern, flags);
 }
-function rgx(flags = '') {
+function rgx(flags = '', multiline = true) {
     (0, ExtRegExp_1.assertValidRegexFlags)(flags);
     return (strings, ...tokens) => {
-        return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens), flags);
+        return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens, multiline), flags);
     };
 }

package/dist/internal/taggedTemplateToArray.d.ts

@@ -1 +1 @@
-export declare function taggedTemplateToArray<T>(strings: TemplateStringsArray, tokens: T[]): (string | T)[];
+export declare function taggedTemplateToArray<T>(strings: TemplateStringsArray, tokens: T[], multiline: boolean): (string | T)[];

package/dist/internal/taggedTemplateToArray.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.taggedTemplateToArray = taggedTemplateToArray;
-function taggedTemplateToArray(strings, tokens) {
+function taggedTemplateToArray(strings, tokens, multiline) {
     function isNullOrUndefined(value) {
         return value === null || value === undefined;
     }
@@ -10,8 +10,16 @@ function taggedTemplateToArray(strings, tokens) {
         const string = strings[i];
         const token = tokens[i];
         // Strings always come before tokens
-        if (!isNullOrUndefined(string))
-            array.push(string);
+        if (!isNullOrUndefined(string)) {
+            if (!multiline) {
+                array.push(string);
+            }
+            else {
+                // Remove all empty lines and trim whitespace from the start of each line.
+                let lines = string.split("\n").map(line => line.trimStart()).filter(line => line.length > 0).join("");
+                array.push(lines);
+            }
+        }
         if (!isNullOrUndefined(token))
             array.push(token);
     }

package/dist/utils/regexMatchAtPosition.d.ts

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

package/dist/utils/regexMatchAtPosition.js

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

package/dist/walker/base.d.ts

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

package/dist/walker/base.js

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

package/dist/walker/index.d.ts

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

package/dist/walker/index.js

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

package/dist/walker/part.d.ts

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

package/dist/walker/part.js

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

package/package.json

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