@ptolemy2002/rgx 5.4.0 → 5.5.0

package/README.md

@@ -950,11 +950,13 @@ A helper function that resolves an array of RGX tokens and concatenates their re
 
 ### rgx
 ```typescript
-function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => ExtRegExp
+function rgx(flags?: string, multiline?: boolean): (strings: TemplateStringsArray, ...tokens: RGXToken[]) => ExtRegExp
 ```
 
 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. Before constructing the pattern, any convertible token that defines `rgxAcceptInsertion` is checked; if it returns `false` or a string, an `RGXInsertionRejectedError` is thrown with details about the reason and exactly where the rejection occurred.
 
+When `multiline` is `true` (the default), the literal string parts of the template are processed to strip newlines, trim leading whitespace from each line, and remove empty lines, then joined together. This allows you to write regex patterns across multiple lines in the source code for readability without the newlines and indentation becoming part of the pattern. Only the literal string parts between tokens are affected — interpolated values (tokens) are preserved as-is, including string tokens passed via `${"..."}`. When `multiline` is `false`, all literal string parts are preserved exactly as written, including newlines and whitespace.
+
 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:
@@ -971,11 +973,26 @@ const pattern3 = rgx()`${beginning}value: ${[word, optionalDigit]}${end}`; // /^
 
 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
+
+// Multiline template for readability (multiline is true by default):
+const pattern5 = rgx()`
+    ${beginning}
+    testing ${word}
+    ${end}
+`; // /^testing \w+$/ - same as pattern, but written across multiple lines
+
+// Preserving literal newlines with multiline mode:
+const pattern6 = rgx()`
+    foo
+    bar${rgxConstant("newline")}
+    baz
+`; // /foobar\nbaz/ - the constant newline is preserved, but template newlines are stripped
 ```
 
 #### Parameters
 **Direct**
   - `flags` (`string`, optional): The regex flags to apply to the resulting `ExtRegExp` object (e.g., 'g', 'i', 'm', or custom registered flags). If not provided, no flags will be applied. If provided and not valid regex flags (vanilla or registered custom), an `RGXInvalidRegexFlagsError` will be thrown.
+  - `multiline` (`boolean`, optional): Whether to strip newlines and trim leading whitespace from the literal string parts of the template. Defaults to `true`. When `true`, each literal string part is split by newlines, each line has its leading whitespace trimmed, empty lines are removed, and the remaining lines are joined together. Interpolated tokens (including string tokens via `${"..."}`) are not affected. When `false`, literal string parts are preserved exactly as written.
 
 **Template Tag**
   - `strings` (`TemplateStringsArray`): The literal parts of the template string.
@@ -1350,14 +1367,14 @@ Asserts that an RGX constant with the given name does not exist. If the assertio
 function defineRGXConstant(name: string, value: RGXToken): RGXToken
 ```
 
-Defines a new RGX constant with the given name and value. Throws an `RGXConstantConflictError` if a constant with the same name already exists.
+Defines a new RGX constant with the given name and value. If the value is a native token (string, number, boolean, or no-op), it is automatically wrapped in an `RGXClassWrapperToken` before being stored. This ensures that native-valued constants are not stripped by multiline template processing in `rgx`, since only the literal string parts of the template are affected by multiline mode. Throws an `RGXConstantConflictError` if a constant with the same name already exists.
 
 #### Parameters
   - `name` (`string`): The name for the constant.
-  - `value` (`RGXToken`): The token value to associate with the name.
+  - `value` (`RGXToken`): The token value to associate with the name. Native tokens are automatically wrapped in `RGXClassWrapperToken`.
 
 #### Returns
-- `RGXToken`: The value that was defined.
+- `RGXToken`: The stored value (after wrapping, if applicable).
 
 ### rgxConstant
 ```typescript
@@ -1389,6 +1406,8 @@ Deletes an existing RGX constant by name. Throws an `RGXInvalidConstantKeyError`
 The library defines the following built-in constants, which are available immediately after import. Each can be retrieved via `rgxConstant(name)`.
 
 ### Control Characters
+Since these are defined as native tokens (strings), they are automatically wrapped in `RGXClassWrapperToken` by `defineRGXConstant`, ensuring they are preserved in multiline mode.
+
 | Name | Resolves To | Description |
 | --- | --- | --- |
 | `"newline"` | `\n` | Newline character |

package/dist/constants.d.ts

@@ -3,6 +3,6 @@ export declare function listRGXConstants(): string[];
 export declare function hasRGXConstant(name: string): boolean;
 export declare function assertHasRGXConstant(name: string): void;
 export declare function assertNotHasRGXConstant(name: string): void;
-export declare function defineRGXConstant(name: string, value: RGXToken): RGXToken;
+export declare function defineRGXConstant(name: string, value: RGXToken): RegExp | import("./types").RGXConvertibleToken | RGXToken[];
 export declare function rgxConstant(name: string): RGXToken;
 export declare function deleteRGXConstant(name: string): void;

package/dist/constants.js

@@ -7,7 +7,9 @@ exports.assertNotHasRGXConstant = assertNotHasRGXConstant;
 exports.defineRGXConstant = defineRGXConstant;
 exports.rgxConstant = rgxConstant;
 exports.deleteRGXConstant = deleteRGXConstant;
+const class_1 = require("./class");
 const errors_1 = require("./errors");
+const typeGuards_1 = require("./typeGuards");
 const rgxConstants = {};
 function listRGXConstants() {
     return Object.keys(rgxConstants);
@@ -27,8 +29,9 @@ function assertNotHasRGXConstant(name) {
 }
 function defineRGXConstant(name, value) {
     assertNotHasRGXConstant(name);
-    rgxConstants[name] = value;
-    return value;
+    // Not strings themselves so that they aren't removed in multiline mode.
+    rgxConstants[name] = (0, typeGuards_1.isRGXNativeToken)(value) ? (0, class_1.rgxClassWrapper)(value) : value;
+    return rgxConstants[name];
 }
 function rgxConstant(name) {
     assertHasRGXConstant(name);

package/dist/index.d.ts

@@ -13,4 +13,4 @@ export * from "./flag-transformer";
 export * from "./clone";
 export * from "./constants";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
-export default function rgx(flags?: string): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;
+export default function rgx(flags?: string, multiline?: boolean): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;

package/dist/index.js

@@ -43,9 +43,9 @@ function rgxa(tokens, flags = '') {
     const pattern = (0, concat_1.rgxConcat)(tokens, true, flags);
     return (0, ExtRegExp_1.extRegExp)(pattern, flags);
 }
-function rgx(flags = '') {
+function rgx(flags = '', multiline = true) {
     (0, ExtRegExp_1.assertValidRegexFlags)(flags);
     return (strings, ...tokens) => {
-        return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens), flags);
+        return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens, multiline), flags);
     };
 }

package/dist/internal/taggedTemplateToArray.d.ts

@@ -1 +1 @@
-export declare function taggedTemplateToArray<T>(strings: TemplateStringsArray, tokens: T[]): (string | T)[];
+export declare function taggedTemplateToArray<T>(strings: TemplateStringsArray, tokens: T[], multiline: boolean): (string | T)[];

package/dist/internal/taggedTemplateToArray.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.taggedTemplateToArray = taggedTemplateToArray;
-function taggedTemplateToArray(strings, tokens) {
+function taggedTemplateToArray(strings, tokens, multiline) {
     function isNullOrUndefined(value) {
         return value === null || value === undefined;
     }
@@ -10,8 +10,16 @@ function taggedTemplateToArray(strings, tokens) {
         const string = strings[i];
         const token = tokens[i];
         // Strings always come before tokens
-        if (!isNullOrUndefined(string))
-            array.push(string);
+        if (!isNullOrUndefined(string)) {
+            if (!multiline) {
+                array.push(string);
+            }
+            else {
+                // Remove all empty lines and trim whitespace from the start of each line.
+                let lines = string.split("\n").map(line => line.trimStart()).filter(line => line.length > 0).join("");
+                array.push(lines);
+            }
+        }
         if (!isNullOrUndefined(token))
             array.push(token);
     }

package/package.json

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