@ptolemy2002/rgx 4.11.0 → 5.1.0

package/README.md

@@ -12,12 +12,12 @@ import { CloneDepth } from "@ptolemy2002/immutability-utils";
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
 type RGXNativeToken = string | number | boolean | RGXNoOpToken;
-type RGXConvertibleToken = { toRgx: () => RGXToken, readonly rgxGroupWrap?: boolean };
+type RGXConvertibleToken = { toRgx: () => RGXToken, readonly rgxGroupWrap?: boolean, readonly rgxIsGroup?: boolean, readonly rgxIsRepeatable?: boolean };
 type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 
 type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
-type RGXGroupedToken = RGXToken[] | RGXLiteralToken | (RGXClassToken & { isGroup: true }) | RGXGroupedConvertibleToken;
-type RGXGroupedConvertibleToken = { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true };
+type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
+type RGXGroupedConvertibleToken = (RGXConvertibleToken & { readonly rgxIsGroup: true }) | (Omit<RGXConvertibleToken, "toRGX"> & { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true  });
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
 type ValidRegexBrandSymbol = typeof validRegexSymbol;
@@ -39,7 +39,7 @@ type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;
 
 type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
+type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
 type RGXTokenFromType<T extends RGXTokenTypeGuardInput> =
     // Maps token type strings to their corresponding types, e.g.:
     // 'no-op' -> RGXNoOpToken, 'literal' -> RGXLiteralToken, etc.
@@ -279,15 +279,15 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 - `clone(depth: CloneDepth = "max") => RGXClassToken`: Must be implemented by subclasses to return a deep clone of the token instance. The `depth` parameter controls how deeply nested tokens are cloned: `0` for no clone, `1` for a shallow clone of the top-level token, any other number for that many levels down, and `"max"` (the default) for a full deep clone.
 
 #### Properties
-- `isGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
-- `isRepeatable` (`boolean`): Returns `true` by default. Subclasses can override this to indicate that the token cannot be wrapped in an `RGXRepeatToken`. When `false`, attempting to set this token as the `token` property of an `RGXRepeatToken` (including via `repeat()` or `optional()`) will throw an `RGXNotSupportedError`.
+- `rgxIsGroup` (`boolean`): Returns `false` by default. Subclasses can override this to indicate whether the token represents a group.
+- `rgxIsRepeatable` (`boolean`): Returns `true` by default. Subclasses can override this to indicate that the token cannot be wrapped in an `RGXRepeatToken`. When `false`, attempting to set this token as the `token` property of an `RGXRepeatToken` (including via `repeat()` or `optional()`) will throw an `RGXNotSupportedError`.
 - `rgxGroupWrap` (`boolean`): Returns `true` by default. Controls whether the resolver wraps this token's resolved output in a non-capturing group. Subclasses can override this to prevent double-wrapping (e.g., when the token already wraps itself in a group).
 
 #### Methods
 - `or(...others: RGXTokenCollectionInput[]) => RGXClassUnionToken`: Creates an `RGXClassUnionToken` that represents a union (alternation) of this token with the provided others. If any of the `others` are `RGXClassUnionToken` instances, their tokens are flattened into the union rather than nested. If `this` is already an `RGXClassUnionToken`, its existing tokens are preserved and the others are appended.
 - `group(args?: RGXGroupTokenArgs) => RGXGroupToken`: Wraps this token in an `RGXGroupToken` with the provided arguments. The `args` parameter defaults to `{}`, which creates a capturing group with no name. This is a convenience method that creates a new `RGXGroupToken` with `this` as the sole token.
-- `repeat(min?: number, max?: number | null) => RGXRepeatToken`: Wraps this token in an `RGXRepeatToken` with the given repetition bounds. `min` defaults to `1`, `max` defaults to `min`. Pass `null` for `max` to allow unlimited repetitions. This is a convenience method that creates a new `RGXRepeatToken` with `this` as the token. Throws `RGXNotSupportedError` if called on an `RGXLookaroundToken`, as lookaround assertions cannot be repeated.
-- `optional() => RGXRepeatToken`: Shorthand for `repeat(0, 1)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times. Throws `RGXNotSupportedError` if called on an `RGXLookaroundToken`, as lookaround assertions cannot be made optional.
+- `repeat(min?: number, max?: number | null, lazy?: boolean) => RGXRepeatToken`: Wraps this token in an `RGXRepeatToken` with the given repetition bounds. `min` defaults to `1`, `max` defaults to `min`, `lazy` defaults to `false`. Pass `null` for `max` to allow unlimited repetitions. When `lazy` is `true`, the resulting quantifier will be non-greedy. This is a convenience method that creates a new `RGXRepeatToken` with `this` as the token. Throws `RGXNotSupportedError` if called on a token with `rgxIsRepeatable` set to `false` (e.g., `RGXLookaroundToken`).
+- `optional(lazy?: boolean) => RGXRepeatToken`: Shorthand for `repeat(0, 1, lazy)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times. `lazy` defaults to `false`. Throws `RGXNotSupportedError` if called on a token with `rgxIsRepeatable` set to `false` (e.g., `RGXLookaroundToken`).
 - `asLookahead(positive?: boolean) => RGXLookaheadToken`: Wraps this token in an `RGXLookaheadToken`. `positive` defaults to `true`. If this token is already an `RGXLookaheadToken`, it is returned as-is without re-wrapping.
 - `asLookbehind(positive?: boolean) => RGXLookbehindToken`: Wraps this token in an `RGXLookbehindToken`. `positive` defaults to `true`. If this token is already an `RGXLookbehindToken`, it is returned as-is without re-wrapping.
 - `resolve() => ValidRegexString`: A convenience method that resolves this token by calling `resolveRGXToken(this)`, returning the resolved regex string representation. Since this method is defined on `RGXClassToken`, it is available on all subclasses including `RGXClassUnionToken`, `RGXGroupToken`, `RGXRepeatToken`, and `RGXLookaroundToken`.
@@ -337,7 +337,7 @@ constructor(args?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput)
 - `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'concat' mode.
 - `name` (`string | null`): The name of the group. Setting this to a non-null value validates it as a valid identifier via `assertValidIdentifier`.
 - `capturing` (`boolean`): Whether the group is capturing. Any named group is automatically capturing (returns `true` when `name` is not `null`). Setting this to `false` also clears `name` to `null`.
-- `isGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `rgxIsGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
 - `rgxGroupWrap` (`false`): Returns `false` as a constant, since the group already wraps itself, preventing the resolver from double-wrapping.
 
 #### Methods
@@ -354,17 +354,19 @@ A function `rgxRepeat` is provided with the same parameters as this class' const
 
 #### Constructor
 ```typescript
-constructor(token: RGXToken, min?: number, max?: number | null)
+constructor(token: RGXToken, min?: number, max?: number | null, lazy?: boolean)
 ```
 - `token` (`RGXToken`): The token to repeat. If the token is not already a grouped token, it will be automatically wrapped in a non-capturing `RGXGroupToken`.
 - `min` (`number`, optional): The minimum number of repetitions. Must be >= 0 and <= `max` (when `max` is not `null`). Non-integer values are floored. Defaults to `1`.
 - `max` (`number | null`, optional): The maximum number of repetitions. Must be >= `min` when not `null`. Non-integer values are floored. Pass `null` for unlimited repetitions. Defaults to `min`.
+- `lazy` (`boolean`, optional): Whether the quantifier should be non-greedy (lazy). Defaults to `false`.
 
 #### Properties
-- `token` (`RGXGroupedToken`): The token being repeated. Setting this will throw `RGXNotSupportedError` if the value is a class token with `isRepeatable` set to `false`, and will automatically wrap non-grouped tokens in a non-capturing `RGXGroupToken`.
+- `token` (`RGXGroupedToken`): The token being repeated. Setting this will throw `RGXNotSupportedError` if the value is a convertible token with `rgxIsRepeatable` set to `false`, and will automatically wrap non-grouped tokens in a non-capturing `RGXGroupToken`.
 - `min` (`number`): The minimum number of repetitions. Setting this validates that the value is >= 0 and <= `max` (when `max` is not `null`), and floors non-integer values. Throws `RGXOutOfBoundsError` if validation fails.
 - `max` (`number | null`): The maximum number of repetitions. Setting this validates that the value is >= `min` when not `null`, and floors non-integer values. Pass `null` for unlimited. Throws `RGXOutOfBoundsError` if validation fails.
-- `repeaterSuffix` (`string`): Returns the regex quantifier suffix based on the current `min` and `max` values: `*` for `{0,}`, `+` for `{1,}`, `?` for `{0,1}`, `{n}` for exact repetitions, `{n,}` for minimum-only, `{n,m}` for a range, or an empty string for `{1,1}` (exactly once, no quantifier needed).
+- `lazy` (`boolean`): Whether the quantifier is non-greedy (lazy). When `true`, a `?` is appended to the `repeaterSuffix` (except when the suffix is `?` or empty, since those cases don't benefit from a lazy modifier). Defaults to `false`.
+- `repeaterSuffix` (`string`): Returns the regex quantifier suffix based on the current `min`, `max`, and `lazy` values: `*` for `{0,}`, `+` for `{1,}`, `?` for `{0,1}`, `{n}` for exact repetitions, `{n,}` for minimum-only, `{n,m}` for a range, or an empty string for `{1,1}` (exactly once, no quantifier needed). When `lazy` is `true`, a `?` is appended to the suffix (e.g., `*?`, `+?`, `{2,5}?`), except when the suffix is already `?` or empty.
 - `rgxGroupWrap` (`false`): Returns `false` as a constant, since the quantifier suffix binds tightly to the preceding group and does not need additional wrapping.
 
 #### Methods
@@ -388,8 +390,8 @@ constructor(tokens?: RGXTokenCollectionInput, positive?: boolean)
 - `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'concat' mode.
 - `positive` (`boolean`): Whether the lookaround is positive. Setting this updates `negative` accordingly.
 - `negative` (`boolean`): Whether the lookaround is negative. Setting this updates `positive` accordingly.
-- `isGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
-- `isRepeatable` (`false`): Returns `false` as a constant, since lookaround assertions cannot be repeated.
+- `rgxIsGroup` (`true`): Returns `true` as a constant, indicating this token represents a group.
+- `rgxIsRepeatable` (`false`): Returns `false` as a constant, since lookaround assertions cannot be repeated.
 - `rgxGroupWrap` (`false`): Returns `false` as a constant, since the lookaround already wraps itself in a group.
 
 #### Abstract Methods
@@ -424,8 +426,30 @@ A function `rgxLookbehind` is provided with the same parameters as this class' c
 - `reverse() => RGXLookaheadToken`: Returns a new `RGXLookaheadToken` with the same tokens and positivity.
 - `toRgx() => RegExp`: Resolves the lookbehind to a `RegExp`. Positive lookbehinds produce `(?<=...)` and negative lookbehinds produce `(?<!...)`.
 
+### RGXSubpatternToken extends RGXClassToken
+A class representing a backreference to a previously captured group, either by name or by group number. Named backreferences produce `\k<name>` and numbered backreferences produce `\N` (where N is the group number). This is useful for matching the same text that was captured by a previous group.
+
+A function `rgxSubpattern` 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 RGXSubpatternToken`: A type guard that checks if the given value is an instance of `RGXSubpatternToken`.
+- `assert(value: unknown): asserts value is RGXSubpatternToken`: An assertion that checks if the given value is an instance of `RGXSubpatternToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(pattern: string | number)
+```
+- `pattern` (`string | number`): The backreference pattern. If a string, it must be a valid identifier (validated via `assertValidIdentifier`) and produces a named backreference (`\k<name>`). If a number, it must be a positive integer (>= 1, as groups are 1-indexed) and produces a numbered backreference (`\N`). Non-integer numbers are floored.
+
+#### Properties
+- `pattern` (`string | number`): The backreference pattern. Setting this validates the value: strings must be valid identifiers, numbers must be positive integers (>= 1). Non-integer numbers are floored.
+
+#### Methods
+- `toRgx() => RegExp`: Resolves the backreference to a `RegExp`. Named patterns produce `/\k<name>/` and numbered patterns produce `/\N/`.
+- `clone(depth: CloneDepth = "max") => RGXSubpatternToken`: Creates a clone of this token. When `depth` is `0`, returns `this`; otherwise, returns a new `RGXSubpatternToken` with the same pattern.
+
 ### RGXClassWrapperToken extends RGXClassToken
-A class that wraps any `RGXToken` as an `RGXClassToken`, giving you access to the extended API class tokens provide. It delegates `isGroup` and `isRepeatable` to the wrapped token where possible.
+A class that wraps any `RGXToken` as an `RGXClassToken`, giving you access to the extended API class tokens provide. It delegates `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token where possible.
 
 A function `rgxClassWrapper` is provided with the same parameters as this class' constructor, for easier instantiation without needing to use the `new` keyword.
 
@@ -441,8 +465,8 @@ constructor(token: RGXToken)
 
 #### Properties
 - `token` (`RGXToken`): The wrapped token.
-- `isGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`. Returns `true` if the wrapped token is a grouped token, otherwise `false`.
-- `isRepeatable` (`boolean`): If the wrapped token is an `RGXClassToken`, delegates to its `isRepeatable` property. Otherwise, returns `true`.
+- `rgxIsGroup` (`boolean`): Delegates to the wrapped token's group status via `isRGXGroupedToken`. Returns `true` if the wrapped token is a grouped token, otherwise `false`.
+- `rgxIsRepeatable` (`boolean`): If the wrapped token is an `RGXConvertibleToken`, delegates to its `rgxIsRepeatable` property (defaulting to `true` if not present). Otherwise, returns `true`.
 
 #### Methods
 - `unwrap() => RGXToken`: Returns the original wrapped token.
@@ -552,7 +576,7 @@ Asserts that the given value is a native token (string, number, boolean, or no-o
 function isRGXConvertibleToken(value: unknown, returnCheck?: boolean): value is RGXConvertibleToken
 ```
 
-Checks if the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap` property is present, it must be a boolean; otherwise, the check fails. When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures).
+Checks if the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap`, `rgxIsRepeatable`, or `rgxIsGroup` properties are present, they must be booleans; otherwise, the check fails. When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures).
 
 #### Parameters
   - `value` (`unknown`): The value to check.
@@ -565,7 +589,7 @@ Checks if the given value is a convertible token (an object with a `toRgx` metho
 ```typescript
 function assertRGXConvertibleToken(value: unknown, returnCheck?: boolean): asserts value is RGXConvertibleToken
 ```
-Asserts that the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap` property is present, it must be a boolean; otherwise, the assertion fails. When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures). If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+Asserts that the given value is a convertible token (an object with a `toRgx` method). If the `rgxGroupWrap`, `rgxIsRepeatable`, or `rgxIsGroup` properties are present, they must be booleans; otherwise, the assertion fails. When `returnCheck` is `true` (the default), also validates that `toRgx` is callable and returns a valid `RGXToken` (which can be any RGX token type, including other convertible tokens, allowing for recursive structures). If the assertion fails, an `RGXInvalidTokenError` will be thrown.
 
 #### Parameters
   - `value` (`unknown`): The value to assert.
@@ -701,7 +725,7 @@ function isRGXToken<T extends RGXTokenTypeGuardInput = null>(value: unknown, typ
 
 Checks if the given value is a valid RGX token, optionally narrowed to a specific token type. When `type` is `null` (the default), it checks against all token types. When `type` is a specific token type string, it checks only against that type. The `'class'` type matches `RGXClassToken` instances specifically, while `'convertible'` also matches class tokens since they implement the convertible interface.
 
-When `type` is an `RGXClassTokenConstructor` (a constructor for an `RGXClassToken` subclass), it performs an `instanceof` check against that specific constructor, allowing you to narrow to a specific class token subclass rather than all class tokens. In this case, `RGXTokenFromType` resolves to `InstanceType<T>`, giving you the specific subclass type.
+When `type` is a constructor, it performs an `instanceof` check against that specific constructor, allowing you to narrow to a specific class token subclass rather than all class tokens. In this case, `RGXTokenFromType` resolves to `InstanceType<T>`, giving you the specific subclass type.
 
 When `type` is an array, it checks that every element of the value array is a valid RGX token matching the corresponding type in the `type` array. If `matchLength` is `true` (the default), it also requires that the value array has the same length as the type array; if `false`, it allows the value array to be longer than the type array, as long as all elements up to the length of the type array match and all elements after that are still valid RGX tokens of any type.
 
@@ -733,11 +757,11 @@ Asserts that the given value is a valid RGX token, optionally narrowed to a spec
 function isRGXGroupedToken(value: unknown, contentCheck?: boolean): value is RGXGroupedToken
 ```
 
-Checks if the given value is a grouped token — a token that is implicitly or explicitly a group. Arrays and literal tokens (`RegExp`) are implicitly groups. Class tokens are only groups if they have the `isGroup` property set to `true`. Convertible tokens are groups if they have `rgxGroupWrap` set to `true` and their `toRgx()` method returns a grouped token.
+Checks if the given value is a grouped token — a token that is implicitly or explicitly a group. Arrays and literal tokens (`RegExp`) are implicitly groups. Convertible tokens (including class tokens) are groups if they have `rgxIsGroup` set to `true`, or if they have `rgxGroupWrap` set to `true` and their `toRgx()` method returns a grouped token.
 
 #### Parameters
   - `value` (`unknown`): The value to check.
-  - `contentCheck` (`boolean`, optional): Whether to validate the contents of array tokens and the return values of convertible tokens. Defaults to `true`. When `false`, arrays are accepted without checking their elements, and convertible tokens with `rgxGroupWrap` set to `true` are accepted without checking their `toRgx()` return value.
+  - `contentCheck` (`boolean`, optional): Whether to validate the contents of array tokens and the return values of convertible tokens. Defaults to `true`. When `false`, arrays are accepted without checking their elements, and convertible tokens with `rgxGroupWrap` set to `true` are accepted without checking their `toRgx()` return value. This has no effect on the `rgxIsGroup` check, which always accepts the token as grouped regardless of `contentCheck`.
 
 #### Returns
 - `boolean`: `true` if the value is a grouped token, otherwise `false`.
@@ -751,7 +775,7 @@ Asserts that the given value is a grouped token. Uses the same logic as `isRGXGr
 
 #### Parameters
   - `value` (`unknown`): The value to assert.
-  - `contentCheck` (`boolean`, optional): Whether to validate the contents of array tokens and the return values of convertible tokens. Defaults to `true`. When `false`, arrays are accepted without checking their elements, and convertible tokens with `rgxGroupWrap` set to `true` are accepted without checking their `toRgx()` return value.
+  - `contentCheck` (`boolean`, optional): Whether to validate the contents of array tokens and the return values of convertible tokens. Defaults to `true`. When `false`, arrays are accepted without checking their elements, and convertible tokens with `rgxGroupWrap` set to `true` are accepted without checking their `toRgx()` return value. This has no effect on the `rgxIsGroup` check, which always accepts the token as grouped regardless of `contentCheck`.
 
 #### Returns
 - `void`: This function does not return a value, but will throw an error if the assertion fails.

package/dist/class/base.d.ts

@@ -1,4 +1,4 @@
-import { RGXToken, ValidRegexString } from "../types";
+import { RGXConvertibleToken, RGXToken, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import type { RGXClassUnionToken } from "./union";
@@ -6,18 +6,18 @@ import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
 import type { RGXRepeatToken } from "./repeat";
 import type { RGXLookaheadToken } from "./lookahead";
 import type { RGXLookbehindToken } from "./lookbehind";
-export declare abstract class RGXClassToken {
+export declare abstract class RGXClassToken implements RGXConvertibleToken {
     abstract toRgx(): RGXToken;
     abstract clone(depth?: CloneDepth): ThisType<this>;
     static check: (value: unknown) => value is RGXClassToken;
     static assert: (value: unknown) => asserts value is RGXClassToken;
-    get isGroup(): boolean;
-    get isRepeatable(): boolean;
+    get rgxIsGroup(): boolean;
+    get rgxIsRepeatable(): boolean;
     get rgxGroupWrap(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
     group(args?: RGXGroupTokenArgs): RGXGroupToken;
-    repeat(min?: number, max?: number | null): RGXRepeatToken;
-    optional(): RGXRepeatToken;
+    repeat(min?: number, max?: number | null, lazy?: boolean): RGXRepeatToken;
+    optional(lazy?: boolean): RGXRepeatToken;
     asLookahead(positive?: boolean): RGXLookaheadToken;
     asLookbehind(positive?: boolean): RGXLookbehindToken;
     resolve(): ValidRegexString;

package/dist/class/base.js

@@ -4,10 +4,10 @@ exports.RGXClassToken = void 0;
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 class RGXClassToken {
-    get isGroup() {
+    get rgxIsGroup() {
         return false;
     }
-    get isRepeatable() {
+    get rgxIsRepeatable() {
         return true;
     }
     get rgxGroupWrap() {
@@ -19,11 +19,11 @@ class RGXClassToken {
     group(args = {}) {
         throw new errors_1.RGXNotImplementedError('RGXClassToken.group(args)', 'call rgxClassInit() first.');
     }
-    repeat(min = 1, max = min) {
-        throw new errors_1.RGXNotImplementedError('RGXClassToken.repeat(min, max)', 'call rgxClassInit() first.');
+    repeat(min = 1, max = min, lazy = false) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.repeat(min, max, lazy)', 'call rgxClassInit() first.');
     }
-    optional() {
-        return this.repeat(0, 1);
+    optional(lazy = false) {
+        return this.repeat(0, 1, lazy);
     }
     asLookahead(positive = true) {
         throw new errors_1.RGXNotImplementedError('RGXClassToken.asLookahead(positive)', 'call rgxClassInit() first.');

package/dist/class/group.d.ts

@@ -15,7 +15,7 @@ export declare class RGXGroupToken extends RGXClassToken {
     set name(value: string | null);
     get capturing(): boolean;
     set capturing(value: boolean);
-    get isGroup(): true;
+    get rgxIsGroup(): true;
     get rgxGroupWrap(): false;
     constructor({ name, capturing }?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput);
     toRgx(): RegExp;

package/dist/class/group.js

@@ -24,7 +24,7 @@ class RGXGroupToken extends base_1.RGXClassToken {
             this.name = null; // Non-capturing groups cannot have names
         this._capturing = value;
     }
-    get isGroup() {
+    get rgxIsGroup() {
         return true;
     }
     get rgxGroupWrap() {

package/dist/class/index.d.ts

@@ -7,4 +7,5 @@ export * from "./lookaround";
 export * from "./lookahead";
 export * from "./lookbehind";
 export * from "./wrapper";
+export * from "./subpattern";
 export * from "./toRGXClassToken";

package/dist/class/index.js

@@ -23,4 +23,5 @@ __exportStar(require("./lookaround"), exports);
 __exportStar(require("./lookahead"), exports);
 __exportStar(require("./lookbehind"), exports);
 __exportStar(require("./wrapper"), exports);
+__exportStar(require("./subpattern"), exports);
 __exportStar(require("./toRGXClassToken"), exports);

package/dist/class/init.js

@@ -28,10 +28,10 @@ function rgxClassInit() {
     base_1.RGXClassToken.prototype.group = function (args = {}) {
         return new group_1.RGXGroupToken(args, [this]);
     };
-    base_1.RGXClassToken.prototype.repeat = function (min = 1, max = min) {
+    base_1.RGXClassToken.prototype.repeat = function (min = 1, max = min, lazy = false) {
         if (lookaround_1.RGXLookaroundToken.check(this))
             throw new errors_1.RGXNotSupportedError("RGXLookaroundToken.repeat()", "Lookaround tokens cannot be repeated or made optional.");
-        return new repeat_1.RGXRepeatToken(this, min, max);
+        return new repeat_1.RGXRepeatToken(this, min, max, lazy);
     };
     base_1.RGXClassToken.prototype.asLookahead = function (positive = true) {
         if (lookahead_1.RGXLookaheadToken.check(this))

package/dist/class/lookaround.d.ts

@@ -5,8 +5,8 @@ export declare abstract class RGXLookaroundToken extends RGXClassToken {
     _negative: boolean;
     static check: (value: unknown) => value is RGXLookaroundToken;
     static assert: (value: unknown) => asserts value is RGXLookaroundToken;
-    get isGroup(): true;
-    get isRepeatable(): false;
+    get rgxIsGroup(): true;
+    get rgxIsRepeatable(): false;
     get rgxGroupWrap(): false;
     set negative(value: boolean);
     get negative(): boolean;

package/dist/class/lookaround.js

@@ -5,10 +5,10 @@ const collection_1 = require("../collection");
 const base_1 = require("./base");
 const errors_1 = require("../errors");
 class RGXLookaroundToken extends base_1.RGXClassToken {
-    get isGroup() {
+    get rgxIsGroup() {
         return true;
     }
-    get isRepeatable() {
+    get rgxIsRepeatable() {
         return false;
     }
     get rgxGroupWrap() {

package/dist/class/repeat.d.ts

@@ -5,6 +5,7 @@ export declare class RGXRepeatToken extends RGXClassToken {
     _token: RGXGroupedToken;
     _min: number;
     _max: number | null;
+    lazy: boolean;
     static check: (value: unknown) => value is RGXRepeatToken;
     static assert: (value: unknown) => asserts value is RGXRepeatToken;
     get min(): number;
@@ -14,9 +15,9 @@ export declare class RGXRepeatToken extends RGXClassToken {
     get token(): RGXGroupedToken;
     set token(value: RGXToken);
     get rgxGroupWrap(): false;
-    constructor(token: RGXToken, min?: number, max?: number | null);
+    constructor(token: RGXToken, min?: number, max?: number | null, lazy?: boolean);
     get repeaterSuffix(): string;
     toRgx(): RGXToken;
     clone(depth?: CloneDepth): RGXRepeatToken;
 }
-export declare const rgxRepeat: (token: RGXToken, min?: number | undefined, max?: number | null | undefined) => RGXRepeatToken;
+export declare const rgxRepeat: (token: RGXToken, min?: number | undefined, max?: number | null | undefined, lazy?: boolean | undefined) => RGXRepeatToken;

package/dist/class/repeat.js

@@ -32,8 +32,13 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         return this._token;
     }
     set token(value) {
-        if ((0, typeGuards_1.isRGXToken)(value, "class") && !value.isRepeatable) {
-            throw new errors_1.RGXNotSupportedError(`Repeating ${value.constructor.name} tokens`, "The token was manually marked as non-repeatable.");
+        if ((0, typeGuards_1.isRGXToken)(value, "convertible") && !value.rgxIsRepeatable) {
+            if ((0, typeGuards_1.isRGXToken)(value, "class")) {
+                throw new errors_1.RGXNotSupportedError(`Repeating ${value.constructor.name} tokens`, "The token was manually marked as non-repeatable.");
+            }
+            else {
+                throw new errors_1.RGXNotSupportedError("Repeating tokens with {rgxIsRepeatable: false}", "The token was manually marked as non-repeatable.");
+            }
         }
         // Make sure we are always working with a grouped token.
         if ((0, typeGuards_1.isRGXGroupedToken)(value))
@@ -47,29 +52,37 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         return false;
     }
     // By default, repeat a fixed number of times.
-    constructor(token, min = 1, max = min) {
+    constructor(token, min = 1, max = min, lazy = false) {
         super();
         this._max = null;
+        this.lazy = false;
         this.token = token;
         this.min = min;
         this.max = max;
+        this.lazy = lazy;
     }
     get repeaterSuffix() {
-        if (this.min === 0 && this.max === null)
-            return '*';
-        if (this.min === 1 && this.max === null)
-            return '+';
-        if (this.min === 0 && this.max === 1)
-            return '?';
-        if (this.max === null)
-            return `{${this.min},}`;
-        if (this.min === this.max) {
-            // No need for a repeater suffix if we're repeating exactly once.
-            if (this.min === 1)
-                return '';
-            return `{${this.min}}`;
-        }
-        return `{${this.min},${this.max}}`;
+        const result = (() => {
+            if (this.min === 0 && this.max === null)
+                return '*';
+            if (this.min === 1 && this.max === null)
+                return '+';
+            if (this.min === 0 && this.max === 1)
+                return '?';
+            if (this.max === null)
+                return `{${this.min},}`;
+            if (this.min === this.max) {
+                // No need for a repeater suffix if we're repeating exactly once.
+                if (this.min === 1)
+                    return '';
+                return `{${this.min}}`;
+            }
+            return `{${this.min},${this.max}}`;
+        })();
+        if (this.lazy && result.length > 0 && result !== "?")
+            return result + '?';
+        else
+            return result;
     }
     toRgx() {
         // No-op if we're repeating zero times.

package/dist/class/subpattern.d.ts

@@ -0,0 +1,13 @@
+import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+export declare class RGXSubpatternToken extends RGXClassToken {
+    _pattern: string | number;
+    get pattern(): string | number;
+    set pattern(value: string | number);
+    static check: (value: unknown) => value is RGXSubpatternToken;
+    static assert: (value: unknown) => asserts value is RGXSubpatternToken;
+    constructor(pattern: string | number);
+    toRgx(): RegExp;
+    clone(depth?: CloneDepth): RGXSubpatternToken;
+}
+export declare const rgxSubpattern: (pattern: string | number) => RGXSubpatternToken;

package/dist/class/subpattern.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxSubpattern = exports.RGXSubpatternToken = void 0;
+const base_1 = require("./base");
+const typeGuards_1 = require("../typeGuards");
+const errors_1 = require("../errors");
+const internal_1 = require("../internal");
+class RGXSubpatternToken extends base_1.RGXClassToken {
+    get pattern() {
+        return this._pattern;
+    }
+    set pattern(value) {
+        if (typeof value === "string") {
+            (0, typeGuards_1.assertValidIdentifier)(value);
+            this._pattern = value;
+        }
+        else {
+            (0, errors_1.assertInRange)(value, { min: 1 }, "Subpattern group numbers must be positive integers (groups are 1-indexed).");
+            this._pattern = Math.floor(value);
+        }
+    }
+    constructor(pattern) {
+        super();
+        this.pattern = pattern;
+    }
+    toRgx() {
+        if (typeof this.pattern === "string") {
+            return new RegExp(`\\k<${this.pattern}>`);
+        }
+        else {
+            return new RegExp(`\\${this.pattern}`);
+        }
+    }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXSubpatternToken(this.pattern);
+    }
+}
+exports.RGXSubpatternToken = RGXSubpatternToken;
+RGXSubpatternToken.check = (0, internal_1.createClassGuardFunction)(RGXSubpatternToken);
+RGXSubpatternToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXSubpatternToken);
+exports.rgxSubpattern = (0, internal_1.createConstructFunction)(RGXSubpatternToken);

package/dist/class/wrapper.d.ts

@@ -6,8 +6,8 @@ export declare class RGXClassWrapperToken extends RGXClassToken {
     static check: (value: unknown) => value is RGXClassWrapperToken;
     static assert: (value: unknown) => asserts value is RGXClassWrapperToken;
     constructor(token: RGXToken);
-    get isGroup(): boolean;
-    get isRepeatable(): boolean;
+    get rgxIsGroup(): boolean;
+    get rgxIsRepeatable(): boolean;
     unwrap(): RGXToken;
     toRgx(): RGXToken;
     clone(depth?: CloneDepth): RGXClassWrapperToken;

package/dist/class/wrapper.js

@@ -11,12 +11,12 @@ class RGXClassWrapperToken extends base_1.RGXClassToken {
         super();
         this.token = token;
     }
-    get isGroup() {
+    get rgxIsGroup() {
         return (0, typeGuards_1.isRGXGroupedToken)(this.token);
     }
-    get isRepeatable() {
-        if ((0, typeGuards_1.isRGXToken)(this.token, 'class'))
-            return this.token.isRepeatable;
+    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;
     }

package/dist/typeGuards.js

@@ -91,9 +91,13 @@ function assertRGXNativeToken(value) {
 }
 function isRGXConvertibleToken(value, returnCheck = true) {
     if (typeof value === 'object' && value !== null && 'toRgx' in value) {
-        // The rgxGroupWrap property is optional, but if it exists it must be a boolean.
+        // The rgxGroupWrap, rgxIsRepeatable, and rgxIsGroup properties are optional, but if they exist they must be booleans.
         if ('rgxGroupWrap' in value && typeof value.rgxGroupWrap !== 'boolean')
             return false;
+        if ('rgxIsRepeatable' in value && typeof value.rgxIsRepeatable !== 'boolean')
+            return false;
+        if ('rgxIsGroup' in value && typeof value.rgxIsGroup !== 'boolean')
+            return false;
         if ((0, is_callable_1.default)(value.toRgx)) {
             if (!returnCheck)
                 return true;
@@ -200,8 +204,8 @@ function isRGXGroupedToken(value, contentCheck = true) {
     // Classes are only groups if they have the isGroup property set to true.
     return (isRGXArrayToken(value, contentCheck) ||
         isRGXToken(value, "literal") ||
-        (isRGXToken(value, "class") && value.isGroup) ||
-        (isRGXConvertibleToken(value, false) && value.rgxGroupWrap === true && (!contentCheck || isRGXGroupedToken(value.toRgx()))));
+        (isRGXConvertibleToken(value, false) && (value.rgxIsGroup ||
+            (value.rgxGroupWrap === true && (!contentCheck || isRGXGroupedToken(value.toRgx()))))));
 }
 function assertRGXGroupedToken(value, contentCheck = true) {
     if (!isRGXGroupedToken(value, contentCheck)) {

package/dist/types.d.ts

@@ -8,19 +8,21 @@ export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 export type RGXConvertibleToken = {
     toRgx: () => RGXToken;
     readonly rgxGroupWrap?: boolean;
+    readonly rgxIsGroup?: boolean;
+    readonly rgxIsRepeatable?: boolean;
 };
 export type RGXToken = RGXNativeToken | RGXLiteralToken | RGXConvertibleToken | RGXToken[];
 export type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken;
-export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | (RGXClassToken & {
-    isGroup: true;
-}) | RGXGroupedConvertibleToken;
-export type RGXGroupedConvertibleToken = {
+export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
+export type RGXGroupedConvertibleToken = (RGXConvertibleToken & {
+    readonly rgxIsGroup: true;
+}) | (Omit<RGXConvertibleToken, "toRGX"> & {
     toRgx: () => RGXGroupedToken;
     readonly rgxGroupWrap: true;
-};
+});
 export type RGXTokenType = 'no-op' | 'literal' | 'native' | 'convertible' | 'class' | RGXTokenType[];
 export type RGXTokenTypeFlat = Exclude<RGXTokenType, RGXTokenType[]> | "array";
-export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
+export type RGXTokenTypeGuardInput = RGXTokenTypeFlat | null | RGXClassTokenConstructor | typeof RegExp | typeof ExtRegExp | typeof RGXTokenCollection | RGXTokenTypeGuardInput[];
 export type RGXTokenFromType<T extends RGXTokenTypeGuardInput> = T extends null ? RGXToken : T extends 'no-op' ? RGXNoOpToken : T extends 'literal' ? RGXLiteralToken : T extends 'native' ? RGXNativeToken : T extends 'convertible' ? RGXConvertibleToken : T extends 'class' ? RGXClassToken : T extends 'array' ? RGXToken[] : T extends new (...args: unknown[]) => infer R ? R : T extends RGXTokenTypeGuardInput[] ? {
     [K in keyof T]: T[K] extends RGXTokenTypeGuardInput ? RGXTokenFromType<T[K]> : never;
 } : never;

package/package.json

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