@ptolemy2002/rgx 4.4.0 → 4.6.0

package/README.md

@@ -277,7 +277,9 @@ An abstract base class for creating custom RGX token classes. Subclasses must im
 #### Methods
 - `or(...others: RGXTokenCollectionInput[]) => RGXClassUnionToken`: Creates an `RGXClassUnionToken` that represents a union (alternation) of this token with the provided others. If any of the `others` are `RGXClassUnionToken` instances, their tokens are flattened into the union rather than nested. If `this` is already an `RGXClassUnionToken`, its existing tokens are preserved and the others are appended.
 - `group(args?: RGXGroupTokenArgs) => RGXGroupToken`: Wraps this token in an `RGXGroupToken` with the provided arguments. The `args` parameter defaults to `{}`, which creates a capturing group with no name. This is a convenience method that creates a new `RGXGroupToken` with `this` as the sole token.
-- `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` and `RGXGroupToken`.
+- `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.
+- `optional() => RGXRepeatToken`: Shorthand for `repeat(0, 1)`. Wraps this token in an `RGXRepeatToken` that matches the token zero or one times.
+- `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`, and `RGXRepeatToken`.
 
 ### RGXClassUnionToken extends RGXClassToken
 A class representing a union (alternation) of RGX tokens. This is typically created via the `or()` method on `RGXClassToken`, but can also be instantiated directly.
@@ -296,8 +298,6 @@ constructor(tokens: RGXTokenCollectionInput = [])
 
 #### Properties
 - `tokens` (`RGXTokenCollection`): The internal collection of tokens managed in 'union' mode.
-- `isGroup` (`boolean`): Returns `true`, indicating this token represents a group.
-
 #### Methods
 - `add(token: RGXToken, pos?: RGXUnionInsertionPosition) => this`: Adds a token to the union. The `pos` parameter controls where the token is inserted: `'prefix'` inserts at the beginning, `'suffix'` (default) appends to the end. Returns `this` for chaining.
 - `concat(pos?: RGXUnionInsertionPosition, ...others: RGXTokenCollectionInput[]) => this`: Concatenates additional tokens into the union. The `pos` parameter controls insertion position: `'suffix'` (default) appends to the end, `'prefix'` prepends to the beginning. Returns `this` for chaining.
@@ -332,6 +332,33 @@ constructor(args?: RGXGroupTokenArgs, tokens?: RGXTokenCollectionInput)
 #### Methods
 - `toRgx() => RegExp`: Resolves the group by concatenating the internal tokens and wrapping the result in the appropriate group syntax: `(?<name>...)` for named groups, `(?:...)` for non-capturing groups, or `(...)` for capturing groups.
 
+### RGXRepeatToken extends RGXClassToken
+A class representing a repetition quantifier wrapping an RGX token. This allows specifying how many times a token should be matched (e.g., exactly N times, between N and M times, or unlimited). This is typically created via the `repeat()` or `optional()` methods on `RGXClassToken`, but can also be instantiated directly.
+
+A function `rgxRepeat` 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 RGXRepeatToken`: A type guard that checks if the given value is an instance of `RGXRepeatToken`.
+- `assert(value: unknown): asserts value is RGXRepeatToken`: An assertion that checks if the given value is an instance of `RGXRepeatToken`. If the assertion fails, an `RGXInvalidTokenError` will be thrown.
+
+#### Constructor
+```typescript
+constructor(token: RGXToken, min?: number, max?: number | null)
+```
+- `token` (`RGXToken`): The token to repeat. If the token is not already a group (i.e., not an array, `RegExp`, or an `RGXClassToken` with `isGroup` set to `true`), it will be automatically wrapped in an `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`.
+
+#### Properties
+- `token` (`RGXToken`): The token being repeated. Setting this will automatically wrap non-group tokens in an `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).
+- `rgxGroupWrap` (`boolean`): Returns `false`, since the quantifier suffix binds tightly to the preceding group and does not need additional wrapping.
+
+#### Methods
+- `toRgx() => RGXToken`: Resolves the repeat token to a `RegExp` by resolving the inner token and appending the `repeaterSuffix`. Returns `null` (a no-op) when both `min` and `max` are `0`.
+
 ### 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.
 
@@ -805,7 +832,7 @@ Removes duplicate tokens from the provided list using `Set` equality and returns
 function rgxClassInit(): void
 ```
 
-Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or` and `group`) 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.
+Initializes internal method patches required for `RGXClassToken` subclass methods (such as `or`, `group`, and `repeat`) 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.
 
 ### isInRange
 ```typescript
@@ -905,6 +932,48 @@ Unregisters a previously registered custom flag transformer by its key. If the k
 #### Returns
 - `void`: This function does not return a value.
 
+### accentInsensitiveFlagTransformer
+```typescript
+const accentInsensitiveFlagTransformer: RegExpFlagTransformer
+```
+
+A pre-built `RegExpFlagTransformer` that makes a regex pattern accent-insensitive. It replaces any accentable characters (a, e, i, o, u and their uppercase equivalents) in the regex source with alternation groups that match both the base character and its accented variants. For example, `é` becomes `(e|é|è|ë|ê)`. The following accent mappings are supported:
+
+- `a` / `A`: á, à, ä, â, ã / Á, À, Ä, Â, Ã
+- `e` / `E`: é, è, ë, ê / É, È, Ë, Ê
+- `i` / `I`: í, ì, ï, î / Í, Ì, Ï, Î
+- `o` / `O`: ó, ò, ö, ô, õ / Ó, Ò, Ö, Ô, Õ
+- `u` / `U`: ú, ù, ü, û / Ú, Ù, Ü, Û
+
+#### Parameters
+  - `exp` (`RegExp`): The regular expression to transform.
+
+#### Returns
+- `RegExp`: A new `RegExp` with the same flags but with accentable characters in the source replaced by accent-insensitive alternation groups.
+
+### registerCustomFlagTransformers
+```typescript
+function registerCustomFlagTransformers(): void
+```
+
+Registers the library's built-in custom flag transformers. Currently registers the following:
+- `"a"` flag: `accentInsensitiveFlagTransformer` — makes patterns accent-insensitive.
+
+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.
+
+#### Returns
+- `void`: This function does not return a value.
+
+### unregisterCustomFlagTransformers
+```typescript
+function unregisterCustomFlagTransformers(): void
+```
+
+Unregisters all built-in custom flag transformers that were registered by `registerCustomFlagTransformers`. Currently unregisters the `"a"` flag.
+
+#### Returns
+- `void`: This function does not return a value.
+
 ### applyFlagTransformers
 ```typescript
 function applyFlagTransformers(regex: RegExp, flags: string, alreadyAppliedFlags?: string): RegExp

package/dist/class/base.d.ts

@@ -2,6 +2,7 @@ import { RGXToken, ValidRegexString } from "../types";
 import { RGXTokenCollectionInput } from "../collection";
 import type { RGXClassUnionToken } from "./union";
 import type { RGXGroupToken, RGXGroupTokenArgs } from "./group";
+import type { RGXRepeatToken } from "./repeat";
 export declare abstract class RGXClassToken {
     abstract toRgx(): RGXToken;
     static check: (value: unknown) => value is RGXClassToken;
@@ -10,5 +11,7 @@ export declare abstract class RGXClassToken {
     get rgxGroupWrap(): boolean;
     or(...others: RGXTokenCollectionInput[]): RGXClassUnionToken;
     group(args?: RGXGroupTokenArgs): RGXGroupToken;
+    repeat(min?: number, max?: number | null): RGXRepeatToken;
+    optional(): RGXRepeatToken;
     resolve(): ValidRegexString;
 }

package/dist/class/base.js

@@ -16,6 +16,12 @@ 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.');
+    }
+    optional() {
+        return this.repeat(0, 1);
+    }
     resolve() {
         return (0, resolve_1.resolveRGXToken)(this);
     }

package/dist/class/index.d.ts

@@ -2,3 +2,4 @@ export * from "./init";
 export * from "./base";
 export * from "./union";
 export * from "./group";
+export * from "./repeat";

package/dist/class/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./init"), exports);
 __exportStar(require("./base"), exports);
 __exportStar(require("./union"), exports);
 __exportStar(require("./group"), exports);
+__exportStar(require("./repeat"), exports);

package/dist/class/init.js

@@ -4,6 +4,7 @@ exports.rgxClassInit = rgxClassInit;
 const base_1 = require("./base");
 const union_1 = require("./union");
 const group_1 = require("./group");
+const repeat_1 = require("./repeat");
 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.
@@ -23,4 +24,7 @@ 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) {
+        return new repeat_1.RGXRepeatToken(this, min, max);
+    };
 }

package/dist/class/repeat.d.ts

@@ -0,0 +1,20 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+export declare class RGXRepeatToken extends RGXClassToken {
+    _token: RGXToken;
+    _min: number;
+    _max: number | null;
+    static check: (value: unknown) => value is RGXRepeatToken;
+    static assert: (value: unknown) => asserts value is RGXRepeatToken;
+    get min(): number;
+    set min(value: number);
+    get max(): number | null;
+    set max(value: number | null);
+    get token(): RGXToken;
+    set token(value: RGXToken);
+    get rgxGroupWrap(): boolean;
+    constructor(token: RGXToken, min?: number, max?: number | null);
+    get repeaterSuffix(): string;
+    toRgx(): RGXToken;
+}
+export declare const rgxRepeat: (token: RGXToken, min?: number | undefined, max?: number | null | undefined) => RGXRepeatToken;

package/dist/class/repeat.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgxRepeat = exports.RGXRepeatToken = void 0;
+const base_1 = require("./base");
+const group_1 = require("./group");
+const typeGuards_1 = require("../typeGuards");
+const errors_1 = require("../errors");
+const resolve_1 = require("../resolve");
+const internal_1 = require("../internal");
+class RGXRepeatToken extends base_1.RGXClassToken {
+    get min() {
+        return this._min;
+    }
+    set min(value) {
+        (0, errors_1.assertInRange)(value, { min: 0, max: this.max }, "min cannot be negative and cannot be greater than max");
+        this._min = Math.floor(value);
+    }
+    get max() {
+        return this._max;
+    }
+    set max(value) {
+        if (value === null) {
+            this._max = null;
+            return;
+        }
+        (0, errors_1.assertInRange)(value, { min: Math.max(0, this.min) }, "max cannot be negative and cannot be less than min");
+        this._max = Math.floor(value);
+    }
+    get token() {
+        return this._token;
+    }
+    set token(value) {
+        // Arrays and Literals are implicitly grouped.
+        const isGroup = (0, typeGuards_1.isRGXToken)(value, "array") ||
+            (0, typeGuards_1.isRGXToken)(value, "literal") ||
+            ((0, typeGuards_1.isRGXToken)(value, "class") && value.isGroup);
+        // Make sure we are always working with a group token.
+        if (isGroup)
+            this._token = value;
+        else
+            this._token = new group_1.RGXGroupToken({}, value);
+    }
+    // We don't need to group wrap this token because the repeater has no
+    // semantics that would be lost if there are other tokens to the right.
+    get rgxGroupWrap() {
+        return false;
+    }
+    // By default, repeat a fixed number of times.
+    constructor(token, min = 1, max = min) {
+        super();
+        this._max = null;
+        this.token = token;
+        this.min = min;
+        this.max = max;
+    }
+    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}}`;
+    }
+    toRgx() {
+        // No-op if we're repeating zero times.
+        if (this.min === 0 && this.max === 0)
+            return null;
+        const resolvedSource = (0, resolve_1.resolveRGXToken)(this.token);
+        return new RegExp(`${resolvedSource}${this.repeaterSuffix}`);
+    }
+}
+exports.RGXRepeatToken = RGXRepeatToken;
+RGXRepeatToken.check = (0, internal_1.createClassGuardFunction)(RGXRepeatToken);
+RGXRepeatToken.assert = (0, internal_1.createAssertClassGuardFunction)(RGXRepeatToken);
+exports.rgxRepeat = (0, internal_1.createConstructFunction)(RGXRepeatToken);

package/dist/class/union.d.ts

@@ -6,7 +6,6 @@ export declare class RGXClassUnionToken extends RGXClassToken {
     tokens: RGXTokenCollection;
     static check: (value: unknown) => value is RGXClassUnionToken;
     static assert: (value: unknown) => asserts value is RGXClassUnionToken;
-    get isGroup(): boolean;
     constructor(tokens?: RGXTokenCollectionInput);
     cleanTokens(): this;
     add(token: RGXToken, pos?: RGXUnionInsertionPosition): this;

package/dist/class/union.js

@@ -7,9 +7,6 @@ const internal_1 = require("../internal");
 const collection_1 = require("../collection");
 const base_1 = require("./base");
 class RGXClassUnionToken extends base_1.RGXClassToken {
-    get isGroup() {
-        return true;
-    }
     constructor(tokens = []) {
         super();
         if (tokens instanceof collection_1.RGXTokenCollection && tokens.mode === 'concat')

package/dist/flag-transformer/accentInsensitive.d.ts

@@ -0,0 +1,2 @@
+import { RegExpFlagTransformer } from "../ExtRegExp";
+export declare const accentInsensitiveFlagTransformer: RegExpFlagTransformer;

package/dist/flag-transformer/accentInsensitive.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accentInsensitiveFlagTransformer = void 0;
+const accentPatterns = [
+    "(a|á|à|ä|â|ã)", "(A|Á|À|Ä|Â|Ã)",
+    "(e|é|è|ë|ê)", "(E|É|È|Ë|Ê)",
+    "(i|í|ì|ï|î)", "(I|Í|Ì|Ï|Î)",
+    "(o|ó|ò|ö|ô|õ)", "(O|Ó|Ò|Ö|Ô|Õ)",
+    "(u|ú|ù|ü|û)", "(U|Ú|Ù|Ü|Û)"
+];
+const accentInsensitiveFlagTransformer = function (exp) {
+    let source = exp.source;
+    const flags = exp.flags;
+    accentPatterns.forEach((pattern) => {
+        // Replace any of the characters in the pattern with the pattern itself
+        source = source.replaceAll(new RegExp(pattern, "g"), pattern);
+    });
+    return new RegExp(source, flags);
+};
+exports.accentInsensitiveFlagTransformer = accentInsensitiveFlagTransformer;

package/dist/flag-transformer/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./accentInsensitive";
+export * from "./register";

package/dist/flag-transformer/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./accentInsensitive"), exports);
+__exportStar(require("./register"), exports);

package/dist/flag-transformer/register.d.ts

@@ -0,0 +1,2 @@
+export declare function registerCustomFlagTransformers(): void;
+export declare function unregisterCustomFlagTransformers(): void;

package/dist/flag-transformer/register.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCustomFlagTransformers = registerCustomFlagTransformers;
+exports.unregisterCustomFlagTransformers = unregisterCustomFlagTransformers;
+const ExtRegExp_1 = require("../ExtRegExp");
+const accentInsensitive_1 = require("./accentInsensitive");
+function registerCustomFlagTransformers() {
+    (0, ExtRegExp_1.registerFlagTransformer)("a", accentInsensitive_1.accentInsensitiveFlagTransformer);
+}
+function unregisterCustomFlagTransformers() {
+    (0, ExtRegExp_1.unregisterFlagTransformer)("a");
+}

package/dist/index.d.ts

@@ -9,5 +9,6 @@ export * from "./resolve";
 export * from "./concat";
 export * from "./utils";
 export * from "./ExtRegExp";
+export * from "./flag-transformer";
 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

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxa = rgxa;
 exports.default = rgx;
 const class_1 = require("./class");
+const flag_transformer_1 = require("./flag-transformer");
 const concat_1 = require("./concat");
 const internal_1 = require("./internal");
 const ExtRegExp_1 = require("./ExtRegExp");
@@ -29,8 +30,11 @@ __exportStar(require("./resolve"), exports);
 __exportStar(require("./concat"), exports);
 __exportStar(require("./utils"), exports);
 __exportStar(require("./ExtRegExp"), exports);
+__exportStar(require("./flag-transformer"), 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);

package/package.json

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