@ptolemy2002/rgx 13.0.2 → 13.2.0

package/README.md

@@ -33,6 +33,7 @@ Because there is so much to document, it has been broken up into multiple files.
     - [union](./docs/class/token/union.md) - The `RGXClassUnionToken` class, which represents a union of tokens that can match any one of the tokens in the union.
     - [subpattern](./docs/class/token/subpattern.md) - The `RGXSubpatternToken` class, which re-matching the content of a previous capturing group.
     - [wrapper](./docs/class/token/wrapper.md) - The `RGXClassWrapperToken` class, which represents a class token that can wrap any arbitrary token (even non-class), giving you the benefit of the class API for any token.
+    - [exclusion](./docs/class/token/exclusion.md) - The `RGXExclusionToken` class, which matches a token while excluding specific alternatives using lookahead-based subtraction.
     - [to](./docs/class/token/to.md) - A utility for converting any token into a class token. Most tokens just get wrapped in a `RGXClassWrapperToken`, but some do not.
     - `lookaround` - A directory containing documentation for lookahead and lookbehind tokens.
       - [base](./docs/class/token/lookaround/base.md) - The `RGXLookaroundToken` class, which is the base class for lookahead and lookbehind tokens.

package/dist/class/base.d.ts

@@ -1,11 +1,13 @@
 import { RGXConvertibleToken, RGXToken, ValidRegexFlags, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
+import { ResolveRGXTokenOptions } from "../resolve";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import type { RGXClassUnionToken } from "./union";
 import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
 import type { RGXRepeatToken } from "./repeat";
 import type { RGXLookaheadToken } from "./lookahead";
 import type { RGXLookbehindToken } from "./lookbehind";
+import type { RGXExclusionToken } from "./exclusion";
 export declare abstract class RGXClassToken implements RGXConvertibleToken {
     abstract toRgx(): RGXToken;
     abstract clone(depth?: CloneDepth): ThisType<this>;
@@ -22,5 +24,6 @@ export declare abstract class RGXClassToken implements RGXConvertibleToken {
     optional(lazy?: boolean): RGXRepeatToken;
     asLookahead(positive?: boolean): RGXLookaheadToken;
     asLookbehind(positive?: boolean): RGXLookbehindToken;
-    resolve(): ValidRegexString;
+    subtract(exclusionId: string, exclusions?: RGXTokenCollectionInput, terminal?: RGXToken): RGXExclusionToken;
+    resolve(options?: ResolveRGXTokenOptions): ValidRegexString;
 }

package/dist/class/base.js

@@ -37,8 +37,11 @@ class RGXClassToken {
     asLookbehind(positive = true) {
         throw new errors_1.RGXNotImplementedError('RGXClassToken.asLookbehind(positive)', 'call rgxClassInit() first.');
     }
-    resolve() {
-        return (0, resolve_1.resolveRGXToken)(this);
+    subtract(exclusionId, exclusions = [], terminal = null) {
+        throw new errors_1.RGXNotImplementedError('RGXClassToken.subtract(exclusionId, exclusions, terminal)', 'call rgxClassInit() first.');
+    }
+    resolve(options = {}) {
+        return (0, resolve_1.resolveRGXToken)(this, options);
     }
 }
 exports.RGXClassToken = RGXClassToken;

package/dist/class/exclusion.d.ts

@@ -0,0 +1,19 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+import { RGXClassUnionToken } from "./union";
+import { RGXTokenCollectionInput } from "../collection";
+import { CloneDepth } from "@ptolemy2002/immutability-utils";
+export declare class RGXExclusionToken extends RGXClassToken {
+    _exclusionId: string;
+    token: RGXToken;
+    exclusions: RGXClassUnionToken;
+    terminal: RGXToken;
+    static check: (value: unknown) => value is RGXExclusionToken;
+    static assert: (value: unknown) => asserts value is RGXExclusionToken;
+    get exclusionId(): string;
+    set exclusionId(value: string);
+    constructor(exclusionId: string, token: RGXToken, exclusions?: RGXTokenCollectionInput, terminal?: RGXToken);
+    toRgx(): RGXToken;
+    clone(depth?: CloneDepth): RGXExclusionToken;
+}
+export declare const rgxExclusion: (exclusionId: string, token: RGXToken, exclusions?: RGXTokenCollectionInput, terminal?: RGXToken) => RGXExclusionToken;

package/dist/class/exclusion.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxExclusion = exports.RGXExclusionToken = void 0;
+const base_1 = require("./base");
+const union_1 = require("./union");
+const resolve_1 = require("../resolve");
+const typeGuards_1 = require("../typeGuards");
+const immutability_utils_1 = require("@ptolemy2002/immutability-utils");
+const clone_1 = require("../clone");
+const utils_1 = require("../utils");
+const internal_1 = require("../internal");
+class RGXExclusionToken extends base_1.RGXClassToken {
+    // exclusionId should be both a valid identifier and a unique group identifier across this branch of the entire pattern.
+    // The issue is that we can't verify that second condition. We should just tell that to the user in documentation.
+    get exclusionId() {
+        return this._exclusionId;
+    }
+    set exclusionId(value) {
+        (0, typeGuards_1.assertValidIdentifier)(value);
+        this._exclusionId = value;
+    }
+    constructor(exclusionId, token, exclusions = [], terminal = null) {
+        super();
+        this.terminal = null;
+        this.exclusionId = exclusionId;
+        this.token = token;
+        this.exclusions = new union_1.RGXClassUnionToken(exclusions);
+        this.terminal = terminal;
+    }
+    toRgx() {
+        const resolvedToken = (0, resolve_1.resolveRGXToken)(this.token);
+        const resolvedExclusions = this.exclusions.resolve();
+        // null and undefined are no-ops and will resolve to empty strings.
+        const resolvedTerminal = (0, resolve_1.resolveRGXToken)(this.terminal);
+        // Get a match to the pattern in a lookahead, use a negative lookahead to
+        // exclude the exclusion group from the match, then actually consume what we
+        // got from the lookahead.
+        // Note: the exclusions will prevent the pattern from matching if the matched text only
+        // begins with an exclusion pattern, not just if it is the entire exclusion pattern. The solution to this is to provide
+        // a terminal anchor, but that might not always be desirable or possible, so it's something to be aware of.
+        const source = `(?=(?<${this.exclusionId}>${resolvedToken}${resolvedTerminal}))(?!${resolvedExclusions}${resolvedTerminal})\\k<${this.exclusionId}>`;
+        // Because the terminal should be consuming no actual characters, it shuld be able to be repeated without issue, but we cannot actually validate
+        // that the terminal is not consuming characters, so we will just document that the user not consume characters in the terminal.
+        return new RegExp(source);
+    }
+    clone(depth = "max") {
+        if (depth === 0)
+            return this;
+        return new RGXExclusionToken(this.exclusionId, (0, clone_1.cloneRGXToken)(this.token, (0, immutability_utils_1.depthDecrement)(depth, 1)), this.exclusions.clone((0, immutability_utils_1.depthDecrement)(depth, 1)), (0, clone_1.cloneRGXToken)(this.terminal, (0, immutability_utils_1.depthDecrement)(depth, 1)));
+    }
+}
+exports.RGXExclusionToken = RGXExclusionToken;
+RGXExclusionToken.check = (0, utils_1.createRGXClassGuardFunction)(RGXExclusionToken);
+RGXExclusionToken.assert = (0, utils_1.createAssertRGXClassGuardFunction)(RGXExclusionToken);
+exports.rgxExclusion = (0, internal_1.createConstructFunction)(RGXExclusionToken);

package/dist/class/index.d.ts

@@ -9,3 +9,4 @@ export * from "./lookbehind";
 export * from "./wrapper";
 export * from "./subpattern";
 export * from "./toRGXClassToken";
+export * from "./exclusion";

package/dist/class/index.js

@@ -25,3 +25,4 @@ __exportStar(require("./lookbehind"), exports);
 __exportStar(require("./wrapper"), exports);
 __exportStar(require("./subpattern"), exports);
 __exportStar(require("./toRGXClassToken"), exports);
+__exportStar(require("./exclusion"), exports);

package/dist/class/init.js

@@ -9,6 +9,7 @@ const lookaround_1 = require("./lookaround");
 const errors_1 = require("../errors");
 const lookahead_1 = require("./lookahead");
 const lookbehind_1 = require("./lookbehind");
+const exclusion_1 = require("./exclusion");
 function rgxClassInit() {
     // Patch RGXClassToken here, Since classes like RGXClassUnionToken are instances of RGXClassToken
     // themselves. If we tried to import RGXClassUnionToken in base.ts, it would cause a circular dependency.
@@ -61,4 +62,7 @@ function rgxClassInit() {
             return this.negate();
         return new lookbehind_1.RGXLookbehindToken([this], positive);
     };
+    base_1.RGXClassToken.prototype.subtract = function (exclusionId, exclusions = [], terminal = null) {
+        return new exclusion_1.RGXExclusionToken(exclusionId, this, exclusions, terminal);
+    };
 }

package/dist/collection.d.ts

@@ -1,4 +1,5 @@
 import { RGXConvertibleToken, RGXToken, ValidRegexString } from "./types";
+import { ResolveRGXTokenOptions } from "./resolve";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { Collection } from "@ptolemy2002/ts-utils";
 export type RGXTokenCollectionMode = 'union' | 'concat';
@@ -9,7 +10,7 @@ export declare class RGXTokenCollection implements Collection<RGXToken>, RGXConv
     static check: (value: unknown) => value is RGXTokenCollection;
     static assert: (value: unknown) => asserts value is RGXTokenCollection;
     constructor(tokens?: RGXTokenCollectionInput, mode?: RGXTokenCollectionMode);
-    resolve(): ValidRegexString;
+    resolve(options?: ResolveRGXTokenOptions): ValidRegexString;
     toRgx(): RegExp;
     getTokens(): RGXToken[];
     clone(depth?: CloneDepth): RGXTokenCollection;

package/dist/collection.js

@@ -20,8 +20,8 @@ class RGXTokenCollection {
         }
         this.mode = mode;
     }
-    resolve() {
-        return (0, resolve_1.resolveRGXToken)(this);
+    resolve(options = {}) {
+        return (0, resolve_1.resolveRGXToken)(this, options);
     }
     toRgx() {
         let pattern;

package/dist/utils/createRGXBounds.d.ts

@@ -1,2 +1,7 @@
 import { RGXConvertibleToken, RGXToken } from "../types";
-export declare function createRGXBounds(positive: RGXToken, negative: RGXToken, flags?: string): [RGXConvertibleToken, RGXConvertibleToken];
+export type CreateRGXBoundsOptions = {
+    flags?: string;
+    anchorStart?: boolean;
+    anchorEnd?: boolean;
+};
+export declare function createRGXBounds(positive: RGXToken, negative: RGXToken, options?: CreateRGXBoundsOptions | string | boolean): [RGXConvertibleToken, RGXConvertibleToken];

package/dist/utils/createRGXBounds.js

@@ -22,10 +22,15 @@ function convertToBound(token) {
         toRgx: () => token
     };
 }
-function createRGXBounds(positive, negative, flags = "") {
+function createRGXBounds(positive, negative, options = {}) {
+    if (typeof options === "string")
+        options = { flags: options };
+    else if (typeof options === "boolean")
+        options = { anchorStart: options, anchorEnd: options };
+    const { flags = "", anchorStart = true, anchorEnd = true } = options;
     const resolvedPositive = (0, resolve_1.resolveRGXToken)(convertNoGroupWrap(positive), { groupWrap: false, currentFlags: flags });
     const resolvedNegative = (0, resolve_1.resolveRGXToken)(convertNoGroupWrap(negative), { groupWrap: false, currentFlags: flags });
-    const startBound = convertToBound((0, createRegex_1.createRegex)(`(?<=${resolvedNegative})(?=${resolvedPositive})`, flags, true));
-    const endBound = convertToBound((0, createRegex_1.createRegex)(`(?<=${resolvedPositive})(?=${resolvedNegative})`, flags, true));
+    const startBound = convertToBound((0, createRegex_1.createRegex)(`(?<=${resolvedNegative}${anchorStart ? "|^" : ""})(?=${resolvedPositive})`, flags, true));
+    const endBound = convertToBound((0, createRegex_1.createRegex)(`(?<=${resolvedPositive})(?=${resolvedNegative}${anchorEnd ? "|$" : ""})`, flags, true));
     return [startBound, endBound];
 }

package/package.json

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