@ptolemy2002/rgx 4.10.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.
@@ -1208,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/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/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

@@ -1,5 +1,6 @@
 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;
@@ -9,5 +10,6 @@ export declare class RGXClassWrapperToken extends RGXClassToken {
     get isRepeatable(): boolean;
     unwrap(): RGXToken;
     toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXClassWrapperToken;
 }
 export declare const rgxClassWrapper: (token: RGXToken) => RGXClassWrapperToken;

package/dist/class/wrapper.js

@@ -4,6 +4,8 @@ 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();
@@ -24,6 +26,11 @@ class RGXClassWrapperToken extends base_1.RGXClassToken {
     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);

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/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,6 +31,7 @@ __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

package/package.json

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