@ptolemy2002/rgx 4.8.0 → 4.11.0

package/README.md

@@ -1,9 +1,13 @@
 # RGX
 A library for easy construction and validation of regular expressions in TypeScript. You can use `rgx` to concatenate various types of tokens into a valid regular expression string, with type safety and validation.
 
+**Note**: This library is tested with nearly 100% coverage, but any override of `RGXClassToken.clone()` does not have the depth parameter fully tested, as that is ultimately part of `@ptolemy2002/immutability-utils`, which is tested, and setting up tests for that functionality is exceedingly complex.
+
 ## Type Reference
 ```typescript
 import { Branded } from "@ptolemy2002/ts-brand-utils";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+// type CloneDepth = number | "max";
 
 type RGXNoOpToken = null | undefined;
 type RGXLiteralToken = RegExp;
@@ -253,7 +257,7 @@ constructor(tokens: RGXTokenCollectionInput = [], mode: RGXTokenCollectionMode =
 - `toRgx() => RegExp`: A method that resolves the collection to a `RegExp` object based on the collection mode. In 'union' mode, the tokens are resolved as alternatives (using the `|` operator), while in 'concat' mode, the tokens are resolved as concatenated together. No flags are applied to the resulting `RegExp`. Since this method returns a `RegExp` (which is `RGXLiteralToken`), `RGXTokenCollection` instances satisfy the `RGXConvertibleToken` interface and can be used directly as tokens in `rgx`, `rgxa`, and other token-accepting functions.
 - `getTokens() => RGXToken[]`: A method that returns a copy of the array of RGX tokens managed by the collection. This is used to prevent external mutation of the internal `tokens` array.
 - `toArray() => RGXToken[]`: An alias for `getTokens()`, provided for convenience.
-- `clone() => RGXTokenCollection`: A method that creates and returns a deep clone of the RGXTokenCollection instance. This is useful for creating a new collection with the same tokens and mode without affecting the original collection.
+- `clone(depth: CloneDepth = "max") => RGXTokenCollection`: A method that creates and returns a deep clone of the RGXTokenCollection instance. This is useful for creating a new collection with the same tokens and mode without affecting the original collection. The `depth` parameter controls how deeply nested collections are cloned: `0` for no clone, `1` for a shallow clone of the top-level collection, any other number for that many levels down, and `"max"` (the default) for a full deep clone.
 - `asConcat() => RGXTokenCollection`: If this collection is in 'union' mode, this method returns a new RGXTokenCollection instance with the same tokens but in 'concat' mode. If the collection is already in 'concat' mode, it simply returns itself.
 - `asUnion() => RGXTokenCollection`: If this collection is in 'concat' mode, this method returns a new RGXTokenCollection instance with the same tokens but in 'union' mode. If the collection is already in 'union' mode, it simply returns itself.
 
@@ -272,6 +276,7 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 
 #### Abstract Methods
 - `toRgx() => RGXToken`: Must be implemented by subclasses to return the token's regex representation as any valid RGX token (native, literal, convertible, or array of tokens).
+- `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.
@@ -419,6 +424,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 `(?<!...)`.
 
+### 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 function `rgxClassWrapper` 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 RGXClassWrapperToken`: A type guard that checks if the given value is an instance of `RGXClassWrapperToken`.
+- `assert(value: unknown): asserts value is RGXClassWrapperToken`: An assertion that checks if the given value is an instance of `RGXClassWrapperToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(token: RGXToken)
+```
+- `token` (`RGXToken`): The token to wrap.
+
+#### 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`.
+
+#### Methods
+- `unwrap() => RGXToken`: Returns the original wrapped token.
+- `toRgx() => RGXToken`: Returns the original wrapped token (alias for `unwrap()`).
+
 ### ExtRegExp extends RegExp
 A subclass of `RegExp` that supports custom flag transformers in addition to the standard vanilla regex flags (g, i, m, s, u, y). When constructed, custom flags are extracted, their corresponding transformers are applied to the pattern and vanilla flags, and the resulting transformed `RegExp` is created. The `flags` getter returns both the vanilla flags and any custom flags.
 
@@ -816,24 +845,27 @@ Escapes special regex characters in the given string and brands the result as a
 
 ### resolveRGXToken
 ```typescript
-function resolveRGXToken(token: RGXToken, groupWrap?: boolean, topLevel?: boolean): ValidRegexString
+function resolveRGXToken(token: RGXToken, groupWrap?: boolean, topLevel?: boolean, currentFlags?: string): ValidRegexString
 ```
 
 Resolves an RGX token to a string. No-op tokens resolve to an empty string, literal tokens are included as-is (wrapped in a non-capturing group when `groupWrap` is `true`), native tokens are converted to strings and escaped, convertible tokens are converted using their `toRgx` method and then resolved recursively, and arrays of tokens are resolved as unions of their resolved elements (repeats removed, placed in a non-capturing group when `groupWrap` is `true`).
 
+For literal tokens (`RegExp` instances), if the token's flags differ from `currentFlags` in any of the localizable flags (`i`, `m`, `s`), the token is wrapped in an inline modifier group (e.g., `(?i:...)`, `(?-i:...)`, `(?ms-i:...)`) instead of a plain non-capturing group. Non-localizable flags (such as `g`, `u`, `y`, `d`, `v`) are ignored when computing the diff. When an inline modifier group is used, it always wraps the token regardless of the `groupWrap` setting, since the modifier group itself serves as a group.
+
 For convertible tokens, if the token has an `rgxGroupWrap` property, that value always takes precedence. If `rgxGroupWrap` is not present, the behavior depends on whether the call is top-level: at the top level, the `groupWrap` parameter is passed through; in recursive calls, it falls back to `true` regardless of the `groupWrap` parameter. This ensures that the caller's `groupWrap` preference only affects the outermost convertible token and does not leak into deeply nested resolution.
 
 #### Parameters
   - `token` (`RGXToken`): The RGX token to resolve.
-  - `groupWrap` (`boolean`, optional): Whether to wrap literal tokens and array unions in non-capturing groups (`(?:...)`). Defaults to `true`. When `false`, literals use their raw source and array unions omit the wrapping group. For convertible tokens, the token's `rgxGroupWrap` property always takes precedence; otherwise, this value is only passed through at the top level (in recursive calls it falls back to `true`). Array union elements always use `groupWrap=true` internally.
+  - `groupWrap` (`boolean`, optional): Whether to wrap literal tokens and array unions in non-capturing groups (`(?:...)`). Defaults to `true`. When `false`, literals use their raw source and array unions omit the wrapping group. For convertible tokens, the token's `rgxGroupWrap` property always takes precedence; otherwise, this value is only passed through at the top level (in recursive calls it falls back to `true`). Array union elements always use `groupWrap=true` internally. Note that when a literal token requires an inline modifier group due to a localizable flag diff, it is always wrapped regardless of this setting.
   - `topLevel` (`boolean`, optional): Tracks whether the current call is the initial (top-level) invocation. Defaults to `true`. **Warning**: This parameter is intended for internal use by the resolver's own recursion. External callers should not set this parameter, as doing so may produce unexpected wrapping behavior.
+  - `currentFlags` (`string`, optional): The flags of the current regex context, used to compute inline modifier groups for literal tokens. Defaults to `''`. When a literal token's localizable flags (`i`, `m`, `s`) differ from this value, the resolver wraps the token in an inline modifier group that adds or removes the differing flags locally.
 
 #### Returns
 - `ValidRegexString`: The resolved string representation of the RGX token. This is guaranteed to be a valid regex string, as convertible tokens are validated to only produce valid regex strings or arrays of valid regex strings.
 
 ### rgxConcat
 ```typescript
-function rgxConcat(tokens: RGXToken[], groupWrap?: boolean): ValidRegexString
+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.
@@ -841,6 +873,7 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 #### Parameters
   - `tokens` (`RGXToken[]`): The array of RGX tokens to resolve and concatenate.
   - `groupWrap` (`boolean`, optional): Whether to wrap individual resolved tokens in non-capturing groups. Passed through to `resolveRGXToken`. Defaults to `true`.
+  - `currentFlags` (`string`, optional): The flags of the current regex context, passed through to `resolveRGXToken` as its `currentFlags` parameter. Used to compute inline modifier groups for literal tokens whose localizable flags differ. Defaults to `''`.
 
 #### Returns
 - `ValidRegexString`: The concatenated string representation of the resolved RGX tokens. This is guaranteed to be a valid regex string, as it is composed of the resolved forms of RGX tokens, which are all valid regex strings.
@@ -852,6 +885,8 @@ function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToke
 
 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.
 
+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:
 ```typescript
 const beginning = /^/;
@@ -863,6 +898,9 @@ const optionalDigit = /\d?/;
 const pattern2 = rgx()`${beginning}optional digit: ${optionalDigit}${end}`; // /^optional digit: \d?$/ - matches the string "optional digit: " followed by an optional digit, anchored to the start and end of the string
 
 const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^value: (?:\w+|\d?)$/ - matches the string "value: " followed by either a word or an optional digit, anchored to the start and end of the string
+
+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
 ```
 
 #### Parameters
@@ -880,7 +918,7 @@ const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^
 ```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.
+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.
 
 #### Parameters
   - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern.
@@ -922,6 +960,22 @@ function rgxClassInit(): void
 
 Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or`, `group`, `repeat`, `asLookahead`, and `asLookbehind`) to work correctly. This function is called automatically when importing from the main module entry point, so you typically do not need to call it yourself. It only needs to be called manually if you import directly from sub-modules.
 
+### toRGXClassToken
+```typescript
+function toRGXClassToken(token: RGXToken): RGXClassToken
+```
+
+Converts any `RGXToken` into an appropriate `RGXClassToken` subclass, giving you access to the extended API that class tokens provide. Tokens that are already class tokens are returned as-is. Array tokens and `RGXTokenCollection` instances in union mode are converted to `RGXClassUnionToken`. `RGXTokenCollection` instances in concat mode are converted to a non-capturing `RGXGroupToken`. All other tokens are wrapped in an `RGXClassWrapperToken`.
+
+#### Parameters
+  - `token` (`RGXToken`): The token to convert.
+
+#### Returns
+- `RGXClassToken`: The corresponding class token:
+  - `RGXClassUnionToken` for array tokens and union-mode `RGXTokenCollection` instances.
+  - `RGXGroupToken` (non-capturing) for concat-mode `RGXTokenCollection` instances.
+  - `RGXClassWrapperToken` for all other tokens.
+
 ### isInRange
 ```typescript
 function isInRange(value: number, { min, max, inclusiveLeft, inclusiveRight }?: RangeObject): boolean
@@ -1159,6 +1213,19 @@ 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`.
 
+### cloneRGXToken
+```typescript
+function cloneRGXTokeN<T extends RGXToken>(token: T, depth: CloneDepth="max"): T
+```
+Creates a clone of the given RGX token to the given depth, provided that the token is not a no-op or native token.
+
+#### Parameters
+  - `token` (`T`): The RGX token to clone. Must not be a no-op or native token, or an error will be thrown.
+  - `depth` (`CloneDepth`, optional): The depth to which to clone the token. Can be a number (with 0 resulting in no clone at all and 1 resulting in a shallow clone) or the string `"max"` for a full deep clone. Defaults to `"max"`.
+
+#### Returns
+- `T`: The cloned token.
+
 ## Peer Dependencies
 - `@ptolemy2002/immutability-utils` ^2.0.0
 - `@ptolemy2002/js-utils` ^3.2.2

package/dist/class/base.d.ts

@@ -1,5 +1,6 @@
 import { RGXToken, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import type { RGXClassUnionToken } from "./union";
 import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
 import type { RGXRepeatToken } from "./repeat";
@@ -7,6 +8,7 @@ import type { RGXLookaheadToken } from "./lookahead";
 import type { RGXLookbehindToken } from "./lookbehind";
 export declare abstract class RGXClassToken {
     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;

package/dist/class/group.d.ts

@@ -1,5 +1,6 @@
 import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export type RGXGroupTokenArgs = {
     name?: string | null;
     capturing?: boolean;
@@ -18,5 +19,6 @@ export declare class RGXGroupToken extends RGXClassToken {
     get rgxGroupWrap(): false;
     constructor({ name, capturing }?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput);
     toRgx(): RegExp;
+    clone(depth?: CloneDepth): RGXGroupToken;
 }
 export declare const rgxGroup: (args_0?: RGXGroupTokenArgs | undefined, tokens?: RGXTokenCollectionInput) => RGXGroupToken;

package/dist/class/group.js

@@ -5,6 +5,7 @@ const collection_1 = require("../collection");
 const base_1 = require("./base");
 const internal_1 = require("../internal");
 const typeGuards_1 = require("../typeGuards");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXGroupToken extends base_1.RGXClassToken {
     get name() {
         return this._name;
@@ -52,6 +53,11 @@ class RGXGroupToken extends base_1.RGXClassToken {
             result = `(${result})`;
         return new RegExp(result);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXGroupToken({ name: this.name, capturing: this._capturing }, this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
 }
 exports.RGXGroupToken = RGXGroupToken;
 RGXGroupToken.check = (0, internal_1.createClassGuardFunction)(RGXGroupToken);

package/dist/class/index.d.ts

@@ -6,3 +6,5 @@ export * from "./repeat";
 export * from "./lookaround";
 export * from "./lookahead";
 export * from "./lookbehind";
+export * from "./wrapper";
+export * from "./toRGXClassToken";

package/dist/class/index.js

@@ -22,3 +22,5 @@ __exportStar(require("./repeat"), exports);
 __exportStar(require("./lookaround"), exports);
 __exportStar(require("./lookahead"), exports);
 __exportStar(require("./lookbehind"), exports);
+__exportStar(require("./wrapper"), exports);
+__exportStar(require("./toRGXClassToken"), exports);

package/dist/class/init.js

@@ -36,11 +36,15 @@ function rgxClassInit() {
     base_1.RGXClassToken.prototype.asLookahead = function (positive = true) {
         if (lookahead_1.RGXLookaheadToken.check(this))
             return this;
+        if (lookbehind_1.RGXLookbehindToken.check(this))
+            return this.negate();
         return new lookahead_1.RGXLookaheadToken([this], positive);
     };
     base_1.RGXClassToken.prototype.asLookbehind = function (positive = true) {
         if (lookbehind_1.RGXLookbehindToken.check(this))
             return this;
+        if (lookahead_1.RGXLookaheadToken.check(this))
+            return this.negate();
         return new lookbehind_1.RGXLookbehindToken([this], positive);
     };
 }

package/dist/class/lookahead.d.ts

@@ -1,11 +1,13 @@
 import { RGXToken } from "../types";
 import { RGXLookaroundToken } from "./lookaround";
 import { RGXLookbehindToken } from "./lookbehind";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export declare class RGXLookaheadToken extends RGXLookaroundToken {
     static check: (value: unknown) => value is RGXLookaheadToken;
     static assert: (value: unknown) => asserts value is RGXLookaheadToken;
     negate(): RGXLookaheadToken;
     reverse(): RGXLookbehindToken;
     toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXLookaheadToken;
 }
 export declare const rgxLookahead: (tokens?: import("..").RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookaheadToken;

package/dist/class/lookahead.js

@@ -4,6 +4,7 @@ exports.rgxLookahead = exports.RGXLookaheadToken = void 0;
 const internal_1 = require("../internal");
 const lookaround_1 = require("./lookaround");
 const lookbehind_1 = require("./lookbehind");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXLookaheadToken extends lookaround_1.RGXLookaroundToken {
     negate() {
         return new RGXLookaheadToken(this.tokens, !this.positive);
@@ -19,6 +20,11 @@ class RGXLookaheadToken extends lookaround_1.RGXLookaroundToken {
             result = `(?!${result})`;
         return new RegExp(result);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXLookaheadToken(this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)), this.positive);
+    }
 }
 exports.RGXLookaheadToken = RGXLookaheadToken;
 RGXLookaheadToken.check = (0, internal_1.createClassGuardFunction)(RGXLookaheadToken);

package/dist/class/lookbehind.d.ts

@@ -1,12 +1,13 @@
-import { RGXTokenCollectionInput } from "../collection";
 import { RGXToken } from "../types";
 import { RGXLookaheadToken } from "./lookahead";
 import { RGXLookaroundToken } from "./lookaround";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export declare class RGXLookbehindToken extends RGXLookaroundToken {
     static check: (value: unknown) => value is RGXLookbehindToken;
     static assert: (value: unknown) => asserts value is RGXLookbehindToken;
     negate(): RGXLookbehindToken;
     reverse(): RGXLookaheadToken;
     toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXLookbehindToken;
 }
-export declare const rgxLookbehind: (tokens?: RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookbehindToken;
+export declare const rgxLookbehind: (tokens?: import("..").RGXTokenCollectionInput, positive?: boolean | undefined) => RGXLookbehindToken;

package/dist/class/lookbehind.js

@@ -4,6 +4,7 @@ exports.rgxLookbehind = exports.RGXLookbehindToken = void 0;
 const internal_1 = require("../internal");
 const lookahead_1 = require("./lookahead");
 const lookaround_1 = require("./lookaround");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXLookbehindToken extends lookaround_1.RGXLookaroundToken {
     negate() {
         return new RGXLookbehindToken(this.tokens, !this.positive);
@@ -19,6 +20,11 @@ class RGXLookbehindToken extends lookaround_1.RGXLookaroundToken {
             result = `(?<!${result})`;
         return new RegExp(result);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXLookbehindToken(this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)), this.positive);
+    }
 }
 exports.RGXLookbehindToken = RGXLookbehindToken;
 RGXLookbehindToken.check = (0, internal_1.createClassGuardFunction)(RGXLookbehindToken);

package/dist/class/repeat.d.ts

@@ -1,5 +1,6 @@
 import { RGXGroupedToken, RGXToken } from "../types";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export declare class RGXRepeatToken extends RGXClassToken {
     _token: RGXGroupedToken;
     _min: number;
@@ -10,11 +11,12 @@ export declare class RGXRepeatToken extends RGXClassToken {
     set min(value: number);
     get max(): number | null;
     set max(value: number | null);
-    get token(): RGXToken;
+    get token(): RGXGroupedToken;
     set token(value: RGXToken);
     get rgxGroupWrap(): false;
     constructor(token: RGXToken, min?: number, max?: number | null);
     get repeaterSuffix(): string;
     toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXRepeatToken;
 }
 export declare const rgxRepeat: (token: RGXToken, min?: number | undefined, max?: number | null | undefined) => RGXRepeatToken;

package/dist/class/repeat.js

@@ -7,6 +7,8 @@ const typeGuards_1 = require("../typeGuards");
 const errors_1 = require("../errors");
 const resolve_1 = require("../resolve");
 const internal_1 = require("../internal");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const clone_1 = require("../clone");
 class RGXRepeatToken extends base_1.RGXClassToken {
     get min() {
         return this._min;
@@ -76,6 +78,11 @@ class RGXRepeatToken extends base_1.RGXClassToken {
         const resolvedSource = (0, resolve_1.resolveRGXToken)(this.token);
         return new RegExp(`${resolvedSource}${this.repeaterSuffix}`);
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXRepeatToken((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), this.min, this.max);
+    }
 }
 exports.RGXRepeatToken = RGXRepeatToken;
 RGXRepeatToken.check = (0, internal_1.createClassGuardFunction)(RGXRepeatToken);

package/dist/class/toRGXClassToken.d.ts

@@ -0,0 +1,3 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+export declare function toRGXClassToken(token: RGXToken): RGXClassToken;

package/dist/class/toRGXClassToken.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRGXClassToken = toRGXClassToken;
+const base_1 = require("./base");
+const typeGuards_1 = require("../typeGuards");
+const union_1 = require("./union");
+const collection_1 = require("../collection");
+const group_1 = require("./group");
+const wrapper_1 = require("./wrapper");
+function toRGXClassToken(token) {
+    if (base_1.RGXClassToken.check(token))
+        return token;
+    if ((0, typeGuards_1.isRGXArrayToken)(token))
+        return new union_1.RGXClassUnionToken(token);
+    if (collection_1.RGXTokenCollection.check(token) && token.mode === 'union')
+        return new union_1.RGXClassUnionToken(token.tokens);
+    if (collection_1.RGXTokenCollection.check(token) && token.mode === 'concat')
+        return new group_1.RGXGroupToken({ capturing: false }, token);
+    return new wrapper_1.RGXClassWrapperToken(token);
+}

package/dist/class/union.d.ts

@@ -1,6 +1,7 @@
 import { RGXToken } from "../types";
 import { RGXTokenCollection, RGXTokenCollectionInput } from "../collection";
 import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
 export type RGXUnionInsertionPosition = 'prefix' | 'suffix';
 export declare class RGXClassUnionToken extends RGXClassToken {
     tokens: RGXTokenCollection;
@@ -11,6 +12,7 @@ export declare class RGXClassUnionToken extends RGXClassToken {
     add(token: RGXToken, pos?: RGXUnionInsertionPosition): this;
     concat(pos?: RGXUnionInsertionPosition, ...others: RGXTokenCollectionInput[]): this;
     toRgx(): RegExp;
+    clone(depth?: CloneDepth): RGXClassUnionToken;
 }
 export declare function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;
 export declare function removeRgxUnionDuplicates(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection;

package/dist/class/union.js

@@ -6,6 +6,7 @@ exports.removeRgxUnionDuplicates = removeRgxUnionDuplicates;
 const internal_1 = require("../internal");
 const collection_1 = require("../collection");
 const base_1 = require("./base");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
 class RGXClassUnionToken extends base_1.RGXClassToken {
     constructor(tokens = []) {
         super();
@@ -44,6 +45,11 @@ class RGXClassUnionToken extends base_1.RGXClassToken {
     toRgx() {
         return this.tokens.toRgx();
     }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXClassUnionToken(this.tokens.clone((0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
 }
 exports.RGXClassUnionToken = RGXClassUnionToken;
 RGXClassUnionToken.check = (0, internal_1.createClassGuardFunction)(RGXClassUnionToken);

package/dist/class/wrapper.d.ts

@@ -0,0 +1,15 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+export declare class RGXClassWrapperToken extends RGXClassToken {
+    token: RGXToken;
+    static check: (value: unknown) => value is RGXClassWrapperToken;
+    static assert: (value: unknown) => asserts value is RGXClassWrapperToken;
+    constructor(token: RGXToken);
+    get isGroup(): boolean;
+    get isRepeatable(): boolean;
+    unwrap(): RGXToken;
+    toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXClassWrapperToken;
+}
+export declare const rgxClassWrapper: (token: RGXToken) => RGXClassWrapperToken;

package/dist/class/wrapper.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxClassWrapper = exports.RGXClassWrapperToken = void 0;
+const base_1 = require("./base");
+const typeGuards_1 = require("../typeGuards");
+const internal_1 = require("../internal");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const clone_1 = require("../clone");
+class RGXClassWrapperToken extends base_1.RGXClassToken {
+    constructor(token) {
+        super();
+        this.token = token;
+    }
+    get isGroup() {
+        return (0, typeGuards_1.isRGXGroupedToken)(this.token);
+    }
+    get isRepeatable() {
+        if ((0, typeGuards_1.isRGXToken)(this.token, 'class'))
+            return this.token.isRepeatable;
+        // Assume any other token is repeatable, since we don't know its implementation.
+        return true;
+    }
+    unwrap() {
+        return this.token;
+    }
+    toRgx() {
+        return this.unwrap();
+    }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXClassWrapperToken((0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
+}
+exports.RGXClassWrapperToken = RGXClassWrapperToken;
+RGXClassWrapperToken.check = (0, internal_1.createClassGuardFunction)(RGXClassWrapperToken);
+RGXClassWrapperToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXClassWrapperToken);
+exports.rgxClassWrapper = (0, internal_1.createConstructFunction)(RGXClassWrapperToken);

package/dist/clone.d.ts

@@ -0,0 +1,3 @@
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+import { RGXToken } from "./types";
+export declare function cloneRGXToken<T extends RGXToken>(token: T, depth?: CloneDepth): T;

package/dist/clone.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloneRGXToken = cloneRGXToken;
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const typeGuards_1 = require("./typeGuards");
+function cloneRGXToken(token, depth = "max") {
+    if (depth === 0)
+        return token;
+    if ((0, typeGuards_1.isRGXToken)(token, "no-op") || (0, typeGuards_1.isRGXToken)(token, "native"))
+        return token;
+    return (0, immutability_utils_1.extClone)(token, (0, immutability_utils_1.depthDecrement)(depth, 1));
+}

package/dist/concat.d.ts

@@ -1,2 +1,2 @@
 import * as t from "./types";
-export declare function rgxConcat(tokens: t.RGXToken[], groupWrap?: boolean): t.ValidRegexString;
+export declare function rgxConcat(tokens: t.RGXToken[], groupWrap?: boolean, currentFlags?: string): t.ValidRegexString;

package/dist/concat.js

@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxConcat = rgxConcat;
 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) {
-    return tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap)).join('');
+function rgxConcat(tokens, groupWrap = true, currentFlags = '') {
+    return tokens.map(t => (0, resolve_1.resolveRGXToken)(t, groupWrap, true, currentFlags)).join('');
 }

package/dist/index.d.ts

@@ -10,5 +10,6 @@ export * from "./concat";
 export * from "./utils";
 export * from "./ExtRegExp";
 export * from "./flag-transformer";
+export * from "./clone";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
 export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;

package/dist/index.js

@@ -31,13 +31,14 @@ __exportStar(require("./concat"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./ExtRegExp"), exports);
 __exportStar(require("./flag-transformer"), exports);
+__exportStar(require("./clone"), exports);
 // Call this for certain class methods to work correctly
 (0, class_1.rgxClassInit)();
 // Call this for our custom flags to work correctly
 (0, flag_transformer_1.registerCustomFlagTransformers)();
 function rgxa(tokens, flags = '') {
     (0, ExtRegExp_1.assertValidRegexFlags)(flags);
-    const pattern = (0, concat_1.rgxConcat)(tokens);
+    const pattern = (0, concat_1.rgxConcat)(tokens, true, flags);
     return (0, ExtRegExp_1.extRegExp)(pattern, flags);
 }
 function rgx(flags = '') {

package/dist/resolve.d.ts

@@ -1,3 +1,3 @@
 import * as t from "./types";
 export declare function escapeRegex(value: string): t.ValidRegexString;
-export declare function resolveRGXToken(token: t.RGXToken, groupWrap?: boolean, topLevel?: boolean): t.ValidRegexString;
+export declare function resolveRGXToken(token: t.RGXToken, groupWrap?: boolean, topLevel?: boolean, currentFlags?: string): t.ValidRegexString;

package/dist/resolve.js

@@ -41,21 +41,42 @@ const tg = __importStar(require("./typeGuards"));
 function escapeRegex(value) {
     return value.replaceAll(/[\-\^\$.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function resolveRGXToken(token, groupWrap = true, topLevel = true) {
+function localizableVanillaRegexFlagDiff(prev, next) {
+    // Remove anything other than the "ims" flags from both strings, as
+    // other flags are not localizable (including our custom flags).
+    prev = prev.replaceAll(/[^ims]/g, '');
+    next = next.replaceAll(/[^ims]/g, '');
+    // Format <added flags>-<removed flags>
+    const added = [...new Set(next.split(''))].filter(flag => !prev.includes(flag)).join('');
+    const removed = [...new Set(prev.split(''))].filter(flag => !next.includes(flag)).join('');
+    if (added === '' && removed === '')
+        return '';
+    if (removed === '')
+        return `${added}`;
+    return `${added}-${removed}`;
+}
+function resolveRGXToken(token, groupWrap = true, topLevel = true, currentFlags = '') {
     if (tg.isRGXNoOpToken(token))
         return '';
     if (tg.isRGXLiteralToken(token)) {
-        if (groupWrap)
-            return '(?:' + token.source + ')';
-        else
-            return token.source;
+        const localizableFlagDiff = localizableVanillaRegexFlagDiff(currentFlags, token.flags);
+        currentFlags = token.flags;
+        if (!localizableFlagDiff) {
+            if (groupWrap)
+                return '(?:' + token.source + ')';
+            else
+                return token.source;
+        }
+        else {
+            return `(?${localizableFlagDiff}:${token.source})`;
+        }
     }
     if (tg.isRGXNativeToken(token))
         return escapeRegex(String(token));
     if (tg.isRGXConvertibleToken(token)) {
         // The top-level group-wrapping preference propogates to a direct convertible token, but after that
         // the preference falls back to true whenever a token doesn't explicitly specify a preference.
-        return resolveRGXToken(token.toRgx(), token.rgxGroupWrap ?? (topLevel ? groupWrap : true), false);
+        return resolveRGXToken(token.toRgx(), token.rgxGroupWrap ?? (topLevel ? groupWrap : true), false, currentFlags);
     }
     // Interpret arrays as unions
     if (tg.isRGXArrayToken(token, false)) {
@@ -66,11 +87,11 @@ function resolveRGXToken(token, groupWrap = true, topLevel = true) {
             token = [...(0, class_1.removeRgxUnionDuplicates)(...token)];
             // Don't preserve group wrapping preference for the recursive calls
             if (groupWrap)
-                return '(?:' + token.map(t => resolveRGXToken(t, true, false)).join('|') + ')';
+                return '(?:' + token.map(t => resolveRGXToken(t, true, false, currentFlags)).join('|') + ')';
             else
-                return token.map(t => resolveRGXToken(t, true, false)).join('|');
+                return token.map(t => resolveRGXToken(t, true, false, currentFlags)).join('|');
         }
-        return resolveRGXToken(token[0]);
+        return resolveRGXToken(token[0], true, false, currentFlags);
     }
     // Ignoring this line since it should be impossible to reach if the types are correct, but we need it to satisfy the return type
     /* istanbul ignore next */

package/dist/typeGuards.js

@@ -223,7 +223,7 @@ function assertValidRegexString(value) {
     }
 }
 function isValidVanillaRegexFlags(value) {
-    const patternMatch = /^[gimsuy]*$/.test(value);
+    const patternMatch = /^[gimsuydv]*$/.test(value);
     if (!patternMatch)
         return false;
     // No repeated flags allowed

package/package.json

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