@ptolemy2002/rgx 5.0.0 → 5.2.0

package/README.md

@@ -12,12 +12,18 @@ 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, readonly rgxIsGroup?: boolean, readonly rgxIsRepeatable?: boolean };
+type RGXConvertibleToken = {
+    toRgx: () => RGXToken,
+    rgxAcceptInsertion?: (tokens: RGXToken[], flags: ValidRegexFlags) => string | boolean,
+    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 | RGXGroupedConvertibleToken;
-type RGXGroupedConvertibleToken = (RGXConvertibleToken & { readonly rgxIsGroup: true }) | (Omit<RGXConvertibleToken, "toRGX"> & { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true  });
+type RGXGroupedConvertibleToken = (RGXConvertibleToken & { readonly rgxIsGroup: true }) | (Omit<RGXConvertibleToken, "toRgx"> & { toRgx: () => RGXGroupedToken, readonly rgxGroupWrap: true  });
 
 const validRegexSymbol = Symbol('rgx.ValidRegex');
 type ValidRegexBrandSymbol = typeof validRegexSymbol;
@@ -48,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';
+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' | 'INSERTION_REJECTED';
 
 type RangeObject = {
     min?: number | null;
@@ -212,6 +218,19 @@ constructor(message: string, got: string)
 #### Properties
 - `got` (`string`): The conflicting key string.
 
+### RGXInsertionRejectedError extends RGXError
+A specific error class for token insertion rejection. This error is thrown when a convertible token's `rgxAcceptInsertion` method returns `false` or a string (rejection reason) during pattern construction via `rgx`, `rgxa`, or `rgxConcat`. The error code is set to `INSERTION_REJECTED` on instantiation.
+
+#### Constructor
+```typescript
+constructor(reason?: string | null, message?: string | null)
+```
+- `reason` (`string | null`, optional): The reason the insertion was rejected. Defaults to `null`.
+- `message` (`string | null`, optional): An optional additional message providing more context. Defaults to `null`.
+
+#### Properties
+- `reason` (`string | null`): The reason the insertion was rejected, or `null` if no reason was provided.
+
 ### 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.
 
@@ -284,10 +303,11 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 - `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
+- `rgxAcceptInsertion(tokens: RGXToken[], flags: ValidRegexFlags) => string | boolean`: Called during pattern construction (via `rgx`, `rgxa`, or `rgxConcat`) to allow the token to reject its own insertion based on the surrounding tokens and the pattern's flags. Returns `true` to accept insertion (the default), `false` to reject with no reason, or a string to reject with a reason message. When a token rejects insertion, an `RGXInsertionRejectedError` is thrown. Subclasses can override this to enforce constraints such as requiring certain flags to be present.
 - `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 a token with `rgxIsRepeatable` set to `false` (e.g., `RGXLookaroundToken`).
-- `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 a token with `rgxIsRepeatable` set to `false` (e.g., `RGXLookaroundToken`).
+- `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`.
@@ -354,17 +374,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 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
@@ -424,6 +446,28 @@ 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 `rgxIsGroup` and `rgxIsRepeatable` to the wrapped token where possible.
 
@@ -442,7 +486,7 @@ constructor(token: RGXToken)
 #### Properties
 - `token` (`RGXToken`): The wrapped token.
 - `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 `RGXClassToken`, delegates to its `rgxIsRepeatable` property. Otherwise, returns `true`.
+- `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,11 +596,11 @@ 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`, `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).
+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. If the `rgxAcceptInsertion` property is present, it must be a callable that returns a `string` or `boolean`; otherwise, the check fails. 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). When `returnCheck` is `false`, only checks for the presence and callability of function properties instead of also checking their return values.
 
 #### Parameters
   - `value` (`unknown`): The value to check.
-  - `returnCheck` (`boolean`, optional): Whether to validate the return value of the `toRgx` method. Defaults to `true`. When `false`, only checks that `toRgx` exists and is callable. **Note**: Setting this to `false` makes the type guard assertion strictly unsafe, as it doesn't verify that the `toRgx` method actually returns a valid `RGXToken`. However, depending on the type of the value you're checking, you might not need that safety (e.g., when checking values that you know are valid based on other context).
+  - `returnCheck` (`boolean`, optional): Whether to validate the return value of the `toRgx` method. Defaults to `true`. When `false`, only checks that `toRgx` exists and is callable. **Note**: Setting this to `false` makes the type guard assertion strictly unsafe, as it doesn't verify that the methods actually return valid values. However, depending on the type of the value you're checking, you might not need that safety (e.g., when checking values that you know are valid based on other context).
 
 #### Returns
 - `boolean`: `true` if the value is a convertible token, otherwise `false`.
@@ -565,7 +609,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`, `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.
+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. If the `rgxAcceptInsertion` property is present, it must be a callable that returns a `string` or `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.
 
 #### Parameters
   - `value` (`unknown`): The value to assert.
@@ -868,7 +912,7 @@ For convertible tokens, if the token has an `rgxGroupWrap` property, that value
 function rgxConcat(tokens: RGXToken[], groupWrap?: boolean, currentFlags?: string): ValidRegexString
 ```
 
-A helper function that resolves an array of RGX tokens and concatenates their resolved string representations together. This is useful for cases where you want to concatenate multiple tokens without creating a union between them.
+A helper function that resolves an array of RGX tokens and concatenates their resolved string representations together. This is useful for cases where you want to concatenate multiple tokens without creating a union between them. Before returning, any convertible token in the array that defines `rgxAcceptInsertion` is checked; if it returns `false` or a string, an `RGXInsertionRejectedError` is thrown.
 
 #### Parameters
   - `tokens` (`RGXToken[]`): The array of RGX tokens to resolve and concatenate.
@@ -883,7 +927,7 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 function rgx(flags?: string): (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.
+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.
 
 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)`.
 
@@ -918,7 +962,7 @@ const pattern4 = rgx()`${beginning}${caseInsensitiveWord} world${end}`; // /^(?i
 ```typescript
 function rgxa(tokens: RGXToken[], flags?: string): ExtRegExp
 ```
-As an alternative to using the `rgx` template tag, you can directly call `rgxa` with an array of RGX tokens and optional flags to get an `ExtRegExp` object. This is useful in cases where you don't want to use a template literal. Like `rgx`, the provided `flags` are passed as `currentFlags` to the resolver, enabling inline modifier groups for `RegExp` literal tokens whose localizable flags differ.
+As an alternative to using the `rgx` template tag, you can directly call `rgxa` with an array of RGX tokens and optional flags to get an `ExtRegExp` object. This is useful in cases where you don't want to use a template literal. Like `rgx`, the provided `flags` are passed as `currentFlags` to the resolver, enabling inline modifier groups for `RegExp` literal tokens whose localizable flags differ. Before constructing the pattern, any convertible token in the array that defines `rgxAcceptInsertion` is checked; if it returns `false` or a string, an `RGXInsertionRejectedError` is thrown.
 
 #### Parameters
   - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern.

package/dist/class/base.d.ts

@@ -1,4 +1,4 @@
-import { RGXConvertibleToken, RGXToken, ValidRegexString } from "../types";
+import { RGXConvertibleToken, RGXToken, ValidRegexFlags, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import type { RGXClassUnionToken } from "./union";
@@ -9,6 +9,7 @@ import type { RGXLookbehindToken } from "./lookbehind";
 export declare abstract class RGXClassToken implements RGXConvertibleToken {
     abstract toRgx(): RGXToken;
     abstract clone(depth?: CloneDepth): ThisType<this>;
+    rgxAcceptInsertion(tokens: RGXToken[], flags: ValidRegexFlags): string | boolean;
     static check: (value: unknown) => value is RGXClassToken;
     static assert: (value: unknown) => asserts value is RGXClassToken;
     get rgxIsGroup(): boolean;
@@ -16,8 +17,8 @@ export declare abstract class RGXClassToken implements RGXConvertibleToken {
     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,6 +4,9 @@ exports.RGXClassToken = void 0;
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 class RGXClassToken {
+    rgxAcceptInsertion(tokens, flags) {
+        return true;
+    }
     get rgxIsGroup() {
         return false;
     }
@@ -19,11 +22,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/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/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

@@ -52,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.js

@@ -15,8 +15,8 @@ class RGXClassWrapperToken extends base_1.RGXClassToken {
         return (0, typeGuards_1.isRGXGroupedToken)(this.token);
     }
     get rgxIsRepeatable() {
-        if ((0, typeGuards_1.isRGXToken)(this.token, 'class'))
-            return this.token.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/concat.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxConcat = rgxConcat;
+const internal_1 = require("./internal");
 const resolve_1 = require("./resolve");
 // Wrapper for letting an array of tokens be resolved as a concatenation instead of a union.
 function rgxConcat(tokens, groupWrap = true, currentFlags = '') {
-    return tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap, true, currentFlags)).join('');
+    const result = tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap, true, currentFlags)).join('');
+    (0, internal_1.assureAcceptance)(tokens, currentFlags);
+    return result;
 }

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';
+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' | 'INSERTION_REJECTED';
 export declare class RGXError extends Error {
     _message: string;
     code: RGXErrorCode;

package/dist/errors/index.d.ts

@@ -9,3 +9,4 @@ export * from './outOfBounds';
 export * from './invalidFlagTransformerKey';
 export * from './flagTransformerConflict';
 export * from './notSupported';
+export * from './insertionRejected';

package/dist/errors/index.js

@@ -25,3 +25,4 @@ __exportStar(require("./outOfBounds"), exports);
 __exportStar(require("./invalidFlagTransformerKey"), exports);
 __exportStar(require("./flagTransformerConflict"), exports);
 __exportStar(require("./notSupported"), exports);
+__exportStar(require("./insertionRejected"), exports);

package/dist/errors/insertionRejected.d.ts

@@ -0,0 +1,6 @@
+import { RGXError } from "./base";
+export declare class RGXInsertionRejectedError extends RGXError {
+    reason: string | null;
+    constructor(reason?: string | null, message?: string | null);
+    calcMessage(message: string): string;
+}

package/dist/errors/insertionRejected.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RGXInsertionRejectedError = void 0;
+const base_1 = require("./base");
+class RGXInsertionRejectedError extends base_1.RGXError {
+    constructor(reason = null, message = null) {
+        super(message || "", "INSERTION_REJECTED");
+        this.reason = null;
+        this.reason = reason;
+        this.name = "RGXInsertionRejectedError";
+    }
+    calcMessage(message) {
+        let result = `Insertion rejected`;
+        if (this.reason)
+            result += `; Reason: ${this.reason}`;
+        if (message)
+            result += `; Additional info: ${message}`;
+        return result;
+    }
+}
+exports.RGXInsertionRejectedError = RGXInsertionRejectedError;

package/dist/index.js

@@ -38,6 +38,7 @@ __exportStar(require("./clone"), exports);
 (0, flag_transformer_1.registerCustomFlagTransformers)();
 function rgxa(tokens, flags = '') {
     (0, ExtRegExp_1.assertValidRegexFlags)(flags);
+    (0, internal_1.assureAcceptance)(tokens, flags);
     const pattern = (0, concat_1.rgxConcat)(tokens, true, flags);
     return (0, ExtRegExp_1.extRegExp)(pattern, flags);
 }

package/dist/internal/assureAcceptance.d.ts

@@ -0,0 +1,2 @@
+import { RGXToken, ValidRegexFlags } from "../types";
+export declare function assureAcceptance(tokens: RGXToken[], flags: ValidRegexFlags): void;

package/dist/internal/assureAcceptance.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assureAcceptance = assureAcceptance;
+const errors_1 = require("../errors");
+const typeGuards_1 = require("../typeGuards");
+function assureAcceptance(tokens, flags) {
+    for (const token of tokens) {
+        if ((0, typeGuards_1.isRGXConvertibleToken)(token) && token.rgxAcceptInsertion) {
+            const messageOrAccepted = token.rgxAcceptInsertion(tokens, flags);
+            if (messageOrAccepted === true)
+                continue;
+            if (messageOrAccepted === false)
+                throw new errors_1.RGXInsertionRejectedError();
+            throw new errors_1.RGXInsertionRejectedError(messageOrAccepted);
+        }
+    }
+}

package/dist/internal/index.d.ts

@@ -3,3 +3,4 @@ export * from "./createClassGuardFunction";
 export * from "./taggedTemplateToArray";
 export * from "./isConstructor";
 export * from "./getProxy";
+export * from "./assureAcceptance";

package/dist/internal/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./createClassGuardFunction"), exports);
 __exportStar(require("./taggedTemplateToArray"), exports);
 __exportStar(require("./isConstructor"), exports);
 __exportStar(require("./getProxy"), exports);
+__exportStar(require("./assureAcceptance"), exports);

package/dist/typeGuards.js

@@ -98,6 +98,16 @@ function isRGXConvertibleToken(value, returnCheck = true) {
             return false;
         if ('rgxIsGroup' in value && typeof value.rgxIsGroup !== 'boolean')
             return false;
+        // If the rgxAcceptInsertion property exists, it must be a function that returns a string or boolean.
+        if ('rgxAcceptInsertion' in value) {
+            if (!(0, is_callable_1.default)(value.rgxAcceptInsertion))
+                return false;
+            if (returnCheck) {
+                const acceptResult = value.rgxAcceptInsertion([], '');
+                if (typeof acceptResult !== 'string' && typeof acceptResult !== 'boolean')
+                    return false;
+            }
+        }
         if ((0, is_callable_1.default)(value.toRgx)) {
             if (!returnCheck)
                 return true;

package/dist/types.d.ts

@@ -7,6 +7,7 @@ export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
 export type RGXConvertibleToken = {
     toRgx: () => RGXToken;
+    rgxAcceptInsertion?: (tokens: RGXToken[], flags: ValidRegexFlags) => string | boolean;
     readonly rgxGroupWrap?: boolean;
     readonly rgxIsGroup?: boolean;
     readonly rgxIsRepeatable?: boolean;
@@ -16,7 +17,7 @@ export type RGXClassTokenConstructor = new (...args: unknown[]) => RGXClassToken
 export type RGXGroupedToken = RGXToken[] | RGXLiteralToken | RGXGroupedConvertibleToken;
 export type RGXGroupedConvertibleToken = (RGXConvertibleToken & {
     readonly rgxIsGroup: true;
-}) | (Omit<RGXConvertibleToken, "toRGX"> & {
+}) | (Omit<RGXConvertibleToken, "toRgx"> & {
     toRgx: () => RGXGroupedToken;
     readonly rgxGroupWrap: true;
 });

package/package.json

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