@ptolemy2002/rgx 8.2.0 → 9.0.0

package/dist/index.d.ts

@@ -17,5 +17,5 @@ export * from "./walker";
 export * from "./lexer";
 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, T = unknown>(source: string, tokens: RGXTokenOrPart<R, T>[], options?: Omit<t.RGXWOptions<R>, "multiline">): RGXWalker<R>;
-export declare function rgxw<R = unknown, T = unknown>(source: string, { multiline, ...options }?: t.RGXWOptions<R>): (strings: TemplateStringsArray, ...tokens: RGXTokenOrPart<R, T>[]) => RGXWalker<R>;
+export declare function rgxwa<R = unknown, S = unknown, T = unknown>(source: string, tokens: RGXTokenOrPart<R, S, T>[], options?: Omit<t.RGXWOptions<R, S>, "multiline">): RGXWalker<R, S>;
+export declare function rgxw<R = unknown, S = unknown, T = unknown>(source: string, { multiline, ...options }?: t.RGXWOptions<R, S>): (strings: TemplateStringsArray, ...tokens: RGXTokenOrPart<R, S, T>[]) => RGXWalker<R, S>;

package/dist/lexer/base.d.ts

@@ -1,13 +1,14 @@
 import { RGXToken } from "../types";
 import { RGXTokenOrPart, RGXWalkerOptions } from "../walker";
-export type RGXLexemeDefinition<Data> = Readonly<({
+export type RGXLexemeDefinition<Data, Share = unknown> = Readonly<({
     type: "resolve";
     token: RGXToken;
 } | {
     type: "walk";
-    tokens: RGXTokenOrPart<Data>[];
-    options?: Omit<RGXWalkerOptions<Data>, "startingSourcePosition" | "reduced"> & {
+    tokens: RGXTokenOrPart<Data, Share>[];
+    options?: Omit<RGXWalkerOptions<Data, Share>, "startingSourcePosition" | "reduced" | "share"> & {
         reduced?: (() => Data) | null;
+        share?: (() => Share) | null;
     };
 }) & {
     id: string;
@@ -20,23 +21,23 @@ export type RGXLexeme<Data> = {
     end: RGXLexemeLocation;
     data?: Data;
 };
-export type RGXLexemeDefinitions<Data> = Readonly<Record<string, ReadonlyArray<RGXLexemeDefinition<Data>>>>;
+export type RGXLexemeDefinitions<Data, Share = unknown> = Readonly<Record<string, ReadonlyArray<RGXLexemeDefinition<Data, Share>>>>;
 export type RGXLexemeLocation = {
     index: number;
     line: number;
     column: number;
 };
 export declare function rgxLexemeLocationFromIndex(source: string, index: number): RGXLexemeLocation;
-export declare class RGXLexer<Data> {
+export declare class RGXLexer<Data, Share = unknown> {
     readonly source: string;
     _position: number;
-    readonly lexemeDefinitions: RGXLexemeDefinitions<Data>;
+    readonly lexemeDefinitions: RGXLexemeDefinitions<Data, Share>;
     readonly matched: RGXLexeme<Data>[];
-    static check: (value: unknown) => value is RGXLexer<unknown>;
-    static assert: (value: unknown) => asserts value is RGXLexer<unknown>;
+    static check: (value: unknown) => value is RGXLexer<unknown, unknown>;
+    static assert: (value: unknown) => asserts value is RGXLexer<unknown, unknown>;
     get position(): number;
     set position(value: number);
-    constructor(source: string, lexemeDefinitions?: RGXLexemeDefinitions<Data>, startingPosition?: number);
+    constructor(source: string, lexemeDefinitions?: RGXLexemeDefinitions<Data, Share>, startingPosition?: number);
     private matchDefinition;
     private next;
     private expect;
@@ -56,4 +57,4 @@ export declare class RGXLexer<Data> {
     consumeWhile(predicate: (lexeme: RGXLexeme<Data>) => boolean, mode?: string, skipWhitespace?: boolean): RGXLexeme<Data>[];
     consumeUntil(predicate: (lexeme: RGXLexeme<Data>) => boolean, mode?: string, skipWhitespace?: boolean): RGXLexeme<Data>[];
 }
-export declare const rgxLexer: <Data>(...args: ConstructorParameters<typeof RGXLexer<Data>>) => RGXLexer<Data>;
+export declare const rgxLexer: <Data, Share = unknown>(...args: ConstructorParameters<typeof RGXLexer<Data, Share>>) => RGXLexer<Data, Share>;

package/dist/lexer/base.js

@@ -52,10 +52,11 @@ class RGXLexer {
             // No data part for token lexemes.
         }
         else {
-            const { tokens, options: { reduced, ...options } = {} } = lexemeDefinition;
+            const { tokens, options: { reduced, share, ...options } = {} } = lexemeDefinition;
             const walker = new walker_1.RGXWalker(this.source, tokens, {
                 ...options,
                 reduced: reduced?.() ?? undefined,
+                share: share?.() ?? undefined,
                 startingSourcePosition: startPosition
             });
             // Since the walker will throw an error if it fails to match to the end of its tokens (assuming it isn't stopped before then), this is safe.

package/dist/types.d.ts

@@ -49,6 +49,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> = RGXWalkerOptions<R> & {
+export type RGXWOptions<R = unknown, S = unknown> = RGXWalkerOptions<R, S> & {
     multiline?: boolean;
 };

package/dist/walker/base.d.ts

@@ -1,46 +1,48 @@
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
 import { RGXToken } from "../types";
 import { RGXPart, RGXCapture } from "./part";
-export type RGXWalkerOptions<R> = {
+export type RGXWalkerOptions<R, S = unknown> = {
     startingSourcePosition?: number;
     reduced?: R;
+    share?: S;
     infinite?: boolean;
     looping?: boolean;
 };
-export type RGXTokenOrPart<R, T = unknown> = RGXToken | RGXPart<R, T>;
-export declare class RGXWalker<R> {
+export type RGXTokenOrPart<R, S = unknown, T = unknown> = RGXToken | RGXPart<R, S, T>;
+export declare class RGXWalker<R, S = unknown> {
     readonly source: string;
     _sourcePosition: number;
-    readonly tokens: RGXTokenOrPart<R>[];
+    readonly tokens: RGXTokenOrPart<R, S>[];
     _tokenPosition: number;
     reduced: R;
+    share: S;
     captures: RGXCapture[];
     namedCaptures: Record<string, RGXCapture[]>;
     infinite: boolean;
     looping: boolean;
     private _stopped;
-    static check: (value: unknown) => value is RGXWalker<unknown>;
-    static assert: (value: unknown) => asserts value is RGXWalker<unknown>;
+    static check: (value: unknown) => value is RGXWalker<unknown, unknown>;
+    static assert: (value: unknown) => asserts value is RGXWalker<unknown, unknown>;
     get sourcePosition(): number;
     set sourcePosition(value: number);
     get tokenPosition(): number;
     set tokenPosition(value: number);
     get stopped(): boolean;
-    constructor(source: string, tokens: RGXTokenOrPart<R>[], options?: RGXWalkerOptions<R>);
+    constructor(source: string, tokens: RGXTokenOrPart<R, S>[], options?: RGXWalkerOptions<R, S>);
     stop(): this;
     atTokenEnd(): boolean;
-    hasNextToken(predicate?: (token: RGXToken | RGXPart<R>) => boolean): boolean;
+    hasNextToken(predicate?: (token: RGXToken | RGXPart<R, S>) => boolean): boolean;
     atSourceEnd(): boolean;
     hasNextSource(predicate?: (rest: string) => boolean): boolean;
     lastCapture(): RGXCapture | null;
-    currentToken(): RGXTokenOrPart<R, unknown>;
+    currentToken(): RGXTokenOrPart<R, S, unknown>;
     remainingSource(): string | null;
-    capture(token: RGXTokenOrPart<R>, includeMatch: true): RegExpExecArray;
-    capture(token: RGXTokenOrPart<R>, includeMatch?: false): string;
+    capture(token: RGXTokenOrPart<R, S>, includeMatch: true): RegExpExecArray;
+    capture(token: RGXTokenOrPart<R, S>, includeMatch?: false): string;
     step(): RGXCapture | null;
     stepToToken(predicate: (token: RGXTokenOrPart<R>) => boolean): this;
-    stepToPart(predicate?: (part: RGXPart<R, unknown>) => boolean): this;
+    stepToPart(predicate?: (part: RGXPart<R, S, unknown>) => boolean): this;
     walk(): this;
-    clone(depth?: CloneDepth): RGXWalker<R>;
+    clone(depth?: CloneDepth): RGXWalker<R, S>;
 }
-export declare function rgxWalker<R>(...args: ConstructorParameters<typeof RGXWalker<R>>): RGXWalker<R>;
+export declare function rgxWalker<R, S = unknown>(...args: ConstructorParameters<typeof RGXWalker<R, S>>): RGXWalker<R, S>;

package/dist/walker/base.js

@@ -52,6 +52,7 @@ class RGXWalker {
         this.tokens = tokens;
         this.tokenPosition = 0;
         this.reduced = options.reduced ?? null;
+        this.share = options.share ?? null;
         this.infinite = options.infinite ?? false;
         this.looping = options.looping ?? false;
     }
@@ -107,7 +108,7 @@ class RGXWalker {
         let silent = false;
         // Ask Part what to do — control flow via return values, not flags.
         if (isPart) {
-            const control = token.beforeCapture?.(token, this);
+            const control = token.beforeCapture?.(this.share, token, this);
             if (control === "stop") {
                 this._stopped = true;
                 return null;
@@ -127,7 +128,16 @@ class RGXWalker {
             branchedToken = createBranchGroups(token.token);
         else
             branchedToken = createBranchGroups(token);
-        const capture = this.capture(branchedToken, true);
+        let capture;
+        try {
+            capture = this.capture(branchedToken, true);
+        }
+        catch (e) {
+            if (isPart && e instanceof errors_1.RGXRegexNotMatchedAtPositionError) {
+                token.afterFailure?.(e, this.share, token, this);
+            }
+            throw e;
+        }
         const raw = isPart ? token.rawTransform(capture[0]) : capture[0];
         const end = this.sourcePosition;
         const value = isPart ? token.transform(raw) : raw;
@@ -148,7 +158,15 @@ class RGXWalker {
         };
         // Validate the part. If validation fails, it will throw an error, so nothing below will run.
         if (isPart) {
-            token.validate(captureResult, this);
+            try {
+                token.validate(captureResult, this.share, this);
+            }
+            catch (e) {
+                if (e instanceof errors_1.RGXPartValidationFailedError) {
+                    token.afterValidationFailure?.(e, this.share, token, this);
+                }
+                throw e;
+            }
         }
         // Skip adding the capture if in silent mode.
         if (!silent) {
@@ -161,7 +179,7 @@ class RGXWalker {
         }
         // Notify Part after capture
         if (isPart) {
-            token.afterCapture?.(captureResult, token, this);
+            token.afterCapture?.(captureResult, this.share, token, this);
         }
         if (!this.infinite || this.tokenPosition < this.tokens.length - 1) {
             this.tokenPosition++;
@@ -204,6 +222,7 @@ class RGXWalker {
         const clone = new RGXWalker(this.source, (0, immutability_utils_1.extClone)(this.tokens, (0, immutability_utils_1.depthDecrement)(1)), {
             startingSourcePosition: this.sourcePosition,
             reduced: (0, immutability_utils_1.extClone)(this.reduced, (0, immutability_utils_1.depthDecrement)(1)),
+            share: (0, immutability_utils_1.extClone)(this.share, (0, immutability_utils_1.depthDecrement)(1)),
             infinite: this.infinite,
             looping: this.looping
         });

package/dist/walker/part.d.ts

@@ -1,6 +1,7 @@
 import { RGXToken } from "../types";
 import type { RGXWalker } from "./base";
 import { CloneDepth } from "@ptolemy2002/immutability-utils";
+import { RGXPartValidationFailedError, RGXRegexNotMatchedAtPositionError } from "../errors";
 export type RGXPartControl = "skip" | "stop" | "silent" | void;
 export type RGXCapture<T = unknown> = {
     raw: string;
@@ -11,29 +12,33 @@ export type RGXCapture<T = unknown> = {
     branch: number;
     groups: Record<string, string> | null;
 };
-export type RGXPartOptions<R, T = string> = {
+export type RGXPartOptions<R, S = unknown, T = string> = {
     id: string;
     rawTransform: (captured: string) => string;
     transform: (captured: string) => T;
-    validate: (captured: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => boolean | string;
-    beforeCapture: ((part: RGXPart<R, T>, walker: RGXWalker<R>) => RGXPartControl) | null;
-    afterCapture: ((capture: RGXCapture<T>, part: RGXPart<R, T>, walker: RGXWalker<R>) => void) | null;
+    validate: (captured: RGXCapture<T>, share: S, part: RGXPart<R, S, T>, walker: RGXWalker<R, S>) => boolean | string;
+    beforeCapture: ((share: S, part: RGXPart<R, S, T>, walker: RGXWalker<R, S>) => RGXPartControl) | null;
+    afterCapture: ((capture: RGXCapture<T>, share: S, part: RGXPart<R, S, T>, walker: RGXWalker<R, S>) => void) | null;
+    afterFailure: ((e: RGXRegexNotMatchedAtPositionError, share: S, part: RGXPart<R, S, T>, walker: RGXWalker<R, S>) => void) | null;
+    afterValidationFailure: ((e: RGXPartValidationFailedError, share: S, part: RGXPart<R, S, T>, walker: RGXWalker<R, S>) => void) | null;
 };
-export declare class RGXPart<R, T = string> {
+export declare class RGXPart<R, S = unknown, T = string> {
     id: string | null;
     token: RGXToken;
-    readonly rawTransform: RGXPartOptions<R, T>["rawTransform"];
-    readonly transform: RGXPartOptions<R, T>["transform"];
+    readonly rawTransform: RGXPartOptions<R, S, T>["rawTransform"];
+    readonly transform: RGXPartOptions<R, S, T>["transform"];
     private readonly _validate;
-    readonly beforeCapture: RGXPartOptions<R, T>["beforeCapture"];
-    readonly afterCapture: RGXPartOptions<R, T>["afterCapture"];
-    static check: (value: unknown) => value is RGXPart<unknown, unknown>;
-    static assert: (value: unknown) => asserts value is RGXPart<unknown, unknown>;
-    constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, T>>);
-    hasId(): this is RGXPart<R, T> & {
+    readonly beforeCapture: RGXPartOptions<R, S, T>["beforeCapture"];
+    readonly afterCapture: RGXPartOptions<R, S, T>["afterCapture"];
+    readonly afterFailure: RGXPartOptions<R, S, T>["afterFailure"];
+    readonly afterValidationFailure: RGXPartOptions<R, S, T>["afterValidationFailure"];
+    static check: (value: unknown) => value is RGXPart<unknown, unknown, unknown>;
+    static assert: (value: unknown) => asserts value is RGXPart<unknown, unknown, unknown>;
+    constructor(token: RGXToken, options?: Partial<RGXPartOptions<R, S, T>>);
+    hasId(): this is RGXPart<R, S, T> & {
         id: string;
     };
-    validate(capture: RGXCapture<T>, walker: RGXWalker<R>): void;
-    clone(depth?: CloneDepth): RGXPart<R, T>;
+    validate(capture: RGXCapture<T>, share: S, walker: RGXWalker<R, S>): void;
+    clone(depth?: CloneDepth): RGXPart<R, S, T>;
 }
-export declare function rgxPart<R, T = string>(...args: ConstructorParameters<typeof RGXPart<R, T>>): RGXPart<R, T>;
+export declare function rgxPart<R, S = unknown, T = string>(...args: ConstructorParameters<typeof RGXPart<R, S, T>>): RGXPart<R, S, T>;

package/dist/walker/part.js

@@ -15,12 +15,14 @@ class RGXPart {
         this._validate = options.validate ?? (() => true);
         this.beforeCapture = options.beforeCapture ?? null;
         this.afterCapture = options.afterCapture ?? null;
+        this.afterFailure = options.afterFailure ?? null;
+        this.afterValidationFailure = options.afterValidationFailure ?? null;
     }
     hasId() {
         return this.id !== null;
     }
-    validate(capture, walker) {
-        const result = this._validate(capture, this, walker);
+    validate(capture, share, walker) {
+        const result = this._validate(capture, share, this, walker);
         if (result === true)
             return;
         const message = typeof result === "string" ? result : "Part Validation Failed";

package/package.json

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