@ptolemy2002/rgx 6.0.0 → 6.1.0

package/README.md

@@ -97,6 +97,10 @@ type RGXWalkerOptions<R> = {
     startingSourcePosition?: number;
     reduced?: R;
 };
+
+type RGXWOptions<R = unknown> = Omit<RGXWalkerOptions<R>, "startingSourcePosition"> & {
+    multiline?: boolean;
+};
 ```
 
 ## Classes
@@ -1151,6 +1155,37 @@ As an alternative to using the `rgx` template tag, you can directly call `rgxa`
 #### Returns
 - `ExtRegExp`: An `ExtRegExp` object constructed from the resolved tokens and the provided flags.
 
+### rgxw
+```typescript
+function rgxw<R = unknown>(source: string, {multiline=true, ...options}: RGXWOptions<R> = {}): (strings: TemplateStringsArray, ...tokens: RGXToken[]
+) => RGXWalker<R>
+```
+A helper function that creates an `RGXWalker` instance from an interpolation of strings and tokens. The token array is processed exactly like in `rgx`, but instead of returning an `ExtRegExp`, it returns an `RGXWalker` that can be used to walk through matches of the regex pattern in the source string.
+
+#### Parameters
+  - `source` (`string`): An arbitrary string value that will be included in the `source` property of the walker object.
+  - `options` (`RGXWOptions<R>`, optional): Additional options for configuring the behavior of the resulting `RGXWalker`. This includes:
+    - `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.
+    - `reduced` (`R`, optional): An optional initial value for the walker's `reduced` property, which can be used to accumulate results across matches.
+
+#### Returns
+- `(strings: TemplateStringsArray, ...tokens: RGXToken[]) => RGXWalker<R>`: A template tag function that takes a template literal and returns an `RGXWalker` instance configured with the provided source, the provided tokens, and the specified options.
+
+### rgxwa
+```typescript
+function rgxwa<R = unknown>(source: string, tokens: RGXToken[], options: Omit<RGXWOptions<R>, "multiline"> = {}): RGXWalker<R>
+```
+As an alternative to using the `rgxw` template tag, you can directly call `rgxwa` with a source string, an array of RGX tokens, and options to get an `RGXWalker` instance. This is useful in cases where you don't want to use a template literal. The token array is processed exactly like in `rgxa`, and the provided options are passed through to configure the resulting walker.
+
+#### Parameters
+  - `source` (`string`): An arbitrary string value that will be included in the `source` property of the walker object.
+  - `tokens` (`RGXToken[]`): The RGX tokens to be resolved and concatenated to form the regex pattern for the walker.
+  - `options` (`Omit<RGXWOptions<R>, "multiline">`, optional): Additional options for configuring the behavior of the resulting `RGXWalker`, excluding the `multiline` option which is not applicable when not using a template literal. This includes:
+    - `reduced` (`R`, optional): An optional initial value for the walker's `reduced` property, which can be used to accumulate results across matches.
+
+#### Returns
+- `RGXWalker<R>`: An `RGXWalker` instance configured with the provided source, the resolved tokens, and the specified options.
+
 ### expandRgxUnionTokens
 ```typescript
 function expandRgxUnionTokens(...tokens: RGXTokenCollectionInput[]): RGXTokenCollection

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import * as t from "./types";
 import { ExtRegExp } from "./ExtRegExp";
+import { RGXWalker } from "./walker";
 export * from "./errors";
 export * from "./types";
 export * from "./typeGuards";
@@ -15,3 +16,5 @@ export * from "./constants";
 export * from "./walker";
 export declare function rgxa(tokens: t.RGXToken[], flags?: string): ExtRegExp;
 export default function rgx(flags?: string, multiline?: boolean): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => ExtRegExp;
+export declare function rgxwa<R = unknown>(source: string, tokens: t.RGXToken[], options?: Omit<t.RGXWOptions<R>, "multiline">): RGXWalker<R>;
+export declare function rgxw<R = unknown>(source: string, { multiline, ...options }?: t.RGXWOptions<R>): (strings: TemplateStringsArray, ...tokens: t.RGXToken[]) => RGXWalker<R>;

package/dist/index.js

@@ -16,11 +16,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.rgxa = rgxa;
 exports.default = rgx;
+exports.rgxwa = rgxwa;
+exports.rgxw = rgxw;
 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");
+const walker_1 = require("./walker");
 __exportStar(require("./errors"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./typeGuards"), exports);
@@ -50,3 +53,11 @@ function rgx(flags = '', multiline = true) {
         return rgxa((0, internal_1.taggedTemplateToArray)(strings, tokens, multiline), flags);
     };
 }
+function rgxwa(source, tokens, options = {}) {
+    return new walker_1.RGXWalker(source, tokens, options);
+}
+function rgxw(source, { multiline = true, ...options } = {}) {
+    return (strings, ...tokens) => {
+        return rgxwa(source, (0, internal_1.taggedTemplateToArray)(strings, tokens, multiline), options);
+    };
+}

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { Branded } from "@ptolemy2002/ts-brand-utils";
 import type { RGXClassToken } from "./class";
 import type { ExtRegExp } from "./ExtRegExp";
 import type { RGXTokenCollection } from "./collection";
+import type { RGXWalkerOptions } from "./walker";
 export type RGXNoOpToken = null | undefined;
 export type RGXLiteralToken = RegExp;
 export type RGXNativeToken = string | number | boolean | RGXNoOpToken;
@@ -45,3 +46,6 @@ export type ValidRegexFlags = Branded<string, [ValidRegexFlagsBrandSymbol]> | Va
 export declare const validIdentifierSymbol: unique symbol;
 export type ValidIdentifierBrandSymbol = typeof validIdentifierSymbol;
 export type ValidIdentifier = Branded<string, [ValidIdentifierBrandSymbol]>;
+export type RGXWOptions<R = unknown> = Omit<RGXWalkerOptions<R>, "startingSourcePosition"> & {
+    multiline?: boolean;
+};

package/package.json

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