@ptolemy2002/rgx 4.8.0 → 4.10.0

package/README.md

@@ -419,6 +419,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 +840,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 +868,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 +880,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 +893,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 +913,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 +955,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

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/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/wrapper.d.ts

@@ -0,0 +1,13 @@
+import { RGXToken } from "../types";
+import { RGXClassToken } from "./base";
+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;
+}
+export declare const rgxClassWrapper: (token: RGXToken) => RGXClassWrapperToken;

package/dist/class/wrapper.js

@@ -0,0 +1,31 @@
+"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");
+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();
+    }
+}
+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/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.js

@@ -37,7 +37,7 @@ __exportStar(require("./flag-transformer"), exports);
 (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.10.0",
     "private": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",