@bcts/envelope-pattern 1.0.0-alpha.12

package/src/pattern/leaf/text-pattern.ts

@@ -0,0 +1,165 @@
+/**
+ * @bcts/envelope-pattern - Text pattern matching
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust text_pattern.rs
+ *
+ * @module envelope-pattern/pattern/leaf/text-pattern
+ */
+
+import type { Envelope } from "@bcts/envelope";
+import {
+  type TextPattern as DCBORTextPattern,
+  textPatternAny,
+  textPatternValue,
+  textPatternRegex,
+  textPatternPaths as dcborTextPatternPaths,
+  textPatternDisplay,
+} from "@bcts/dcbor-pattern";
+import type { Path } from "../../format";
+import type { Matcher } from "../matcher";
+import { compileAsAtomic } from "../matcher";
+import type { Instr } from "../vm";
+import type { Pattern } from "../index";
+
+// Forward declaration for Pattern factory
+let createLeafTextPattern: ((pattern: TextPattern) => Pattern) | undefined;
+
+export function registerTextPatternFactory(factory: (pattern: TextPattern) => Pattern): void {
+  createLeafTextPattern = factory;
+}
+
+/**
+ * Pattern for matching text values.
+ *
+ * This is a wrapper around dcbor_pattern::TextPattern that provides
+ * envelope-specific integration.
+ *
+ * Corresponds to the Rust `TextPattern` struct in text_pattern.rs
+ */
+export class TextPattern implements Matcher {
+  readonly #inner: DCBORTextPattern;
+
+  private constructor(inner: DCBORTextPattern) {
+    this.#inner = inner;
+  }
+
+  /**
+   * Creates a new TextPattern that matches any text.
+   */
+  static any(): TextPattern {
+    return new TextPattern(textPatternAny());
+  }
+
+  /**
+   * Creates a new TextPattern that matches the specific text.
+   */
+  static value(value: string): TextPattern {
+    return new TextPattern(textPatternValue(value));
+  }
+
+  /**
+   * Creates a new TextPattern that matches text matching the regex.
+   */
+  static regex(pattern: RegExp): TextPattern {
+    return new TextPattern(textPatternRegex(pattern));
+  }
+
+  /**
+   * Creates a new TextPattern from a dcbor-pattern TextPattern.
+   */
+  static fromDcborPattern(dcborPattern: DCBORTextPattern): TextPattern {
+    return new TextPattern(dcborPattern);
+  }
+
+  /**
+   * Gets the underlying dcbor-pattern TextPattern.
+   */
+  get inner(): DCBORTextPattern {
+    return this.#inner;
+  }
+
+  pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
+    // For leaf envelopes, extract the CBOR and delegate to dcbor-pattern
+    const cbor = haystack.asLeaf();
+    if (cbor !== undefined) {
+      // Delegate to dcbor-pattern for CBOR matching
+      const dcborPaths = dcborTextPatternPaths(this.#inner, cbor);
+
+      // For simple leaf patterns, if dcbor-pattern found matches, return the envelope
+      if (dcborPaths.length > 0) {
+        const envelopePaths: Path[] = [[haystack]];
+        return [envelopePaths, new Map<string, Path[]>()];
+      }
+    }
+
+    return [[], new Map<string, Path[]>()];
+  }
+
+  paths(haystack: Envelope): Path[] {
+    return this.pathsWithCaptures(haystack)[0];
+  }
+
+  matches(haystack: Envelope): boolean {
+    return this.paths(haystack).length > 0;
+  }
+
+  compile(code: Instr[], literals: Pattern[], captures: string[]): void {
+    if (createLeafTextPattern === undefined) {
+      throw new Error("TextPattern factory not registered");
+    }
+    compileAsAtomic(createLeafTextPattern(this), code, literals, captures);
+  }
+
+  isComplex(): boolean {
+    return false;
+  }
+
+  toString(): string {
+    return textPatternDisplay(this.#inner);
+  }
+
+  /**
+   * Equality comparison.
+   */
+  equals(other: TextPattern): boolean {
+    if (this.#inner.variant !== other.#inner.variant) {
+      return false;
+    }
+    switch (this.#inner.variant) {
+      case "Any":
+        return true;
+      case "Value":
+        return (
+          (this.#inner as { value: string }).value === (other.#inner as { value: string }).value
+        );
+      case "Regex":
+        return (
+          (this.#inner as { pattern: RegExp }).pattern.source ===
+          (other.#inner as { pattern: RegExp }).pattern.source
+        );
+    }
+  }
+
+  /**
+   * Hash code for use in Maps/Sets.
+   */
+  hashCode(): number {
+    let hash = 0;
+    switch (this.#inner.variant) {
+      case "Any":
+        hash = 1;
+        break;
+      case "Value": {
+        const val = (this.#inner as { value: string }).value;
+        for (let i = 0; i < val.length; i++) {
+          hash = hash * 31 + val.charCodeAt(i);
+        }
+        break;
+      }
+      case "Regex":
+        hash = 3 * 31 + (this.#inner as { pattern: RegExp }).pattern.source.length;
+        break;
+    }
+    return hash;
+  }
+}

package/src/pattern/matcher.ts

@@ -0,0 +1,88 @@
+/**
+ * @bcts/envelope-pattern - Matcher interface
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust matcher.rs
+ *
+ * @module envelope-pattern/pattern/matcher
+ */
+
+import type { Envelope } from "@bcts/envelope";
+import type { Path } from "../format";
+import type { Pattern } from "./index";
+import type { Instr } from "./vm";
+
+/**
+ * Matcher interface for pattern matching against envelopes.
+ *
+ * Corresponds to the Rust `Matcher` trait in matcher.rs
+ */
+export interface Matcher {
+  /**
+   * Return all matching paths along with any named captures.
+   */
+  pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>];
+
+  /**
+   * Return only the matching paths, discarding any captures.
+   */
+  paths(haystack: Envelope): Path[];
+
+  /**
+   * Returns true if the pattern matches the haystack.
+   */
+  matches(haystack: Envelope): boolean;
+
+  /**
+   * Compile this pattern to bytecode.
+   */
+  compile(code: Instr[], literals: Pattern[], captures: string[]): void;
+
+  /**
+   * Returns true if the Display of the matcher is complex,
+   * i.e. contains nested patterns or other complex structures
+   * that require its text rendering to be surrounded by grouping
+   * parentheses.
+   */
+  isComplex(): boolean;
+}
+
+/**
+ * Default implementations for Matcher methods.
+ */
+export const MatcherDefaults = {
+  /**
+   * Default implementation of paths() - calls pathsWithCaptures and discards captures.
+   */
+  paths(matcher: Matcher, haystack: Envelope): Path[] {
+    return matcher.pathsWithCaptures(haystack)[0];
+  },
+
+  /**
+   * Default implementation of matches() - checks if paths() returns any results.
+   */
+  matches(matcher: Matcher, haystack: Envelope): boolean {
+    return matcher.paths(haystack).length > 0;
+  },
+
+  /**
+   * Default implementation of isComplex() - returns false.
+   */
+  isComplex(): boolean {
+    return false;
+  },
+};
+
+/**
+ * Helper to compile a pattern as an atomic predicate match.
+ * Pushes the pattern into literals and emits a single MatchPredicate instruction.
+ */
+export function compileAsAtomic(
+  pat: Pattern,
+  code: Instr[],
+  literals: Pattern[],
+  _captures: string[],
+): void {
+  const idx = literals.length;
+  literals.push(pat);
+  code.push({ type: "MatchPredicate", literalIndex: idx });
+}

package/src/pattern/meta/and-pattern.ts

@@ -0,0 +1,109 @@
+/**
+ * @bcts/envelope-pattern - And pattern matching
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust and_pattern.rs
+ *
+ * @module envelope-pattern/pattern/meta/and-pattern
+ */
+
+import type { Envelope } from "@bcts/envelope";
+import type { Path } from "../../format";
+import type { Matcher } from "../matcher";
+import type { Instr } from "../vm";
+import type { Pattern } from "../index";
+
+// Forward declaration for Pattern factory (used for late binding)
+export let createMetaAndPattern: ((pattern: AndPattern) => Pattern) | undefined;
+
+export function registerAndPatternFactory(factory: (pattern: AndPattern) => Pattern): void {
+  createMetaAndPattern = factory;
+}
+
+/**
+ * A pattern that matches if all contained patterns match.
+ *
+ * Corresponds to the Rust `AndPattern` struct in and_pattern.rs
+ */
+export class AndPattern implements Matcher {
+  readonly #patterns: Pattern[];
+
+  private constructor(patterns: Pattern[]) {
+    this.#patterns = patterns;
+  }
+
+  /**
+   * Creates a new AndPattern with the given patterns.
+   */
+  static new(patterns: Pattern[]): AndPattern {
+    return new AndPattern(patterns);
+  }
+
+  /**
+   * Gets the patterns.
+   */
+  patterns(): Pattern[] {
+    return this.#patterns;
+  }
+
+  pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
+    const allMatch = this.#patterns.every((pattern) => {
+      const matcher = pattern as unknown as Matcher;
+      return matcher.matches(haystack);
+    });
+
+    const paths = allMatch ? [[haystack]] : [];
+    return [paths, new Map<string, Path[]>()];
+  }
+
+  paths(haystack: Envelope): Path[] {
+    return this.pathsWithCaptures(haystack)[0];
+  }
+
+  matches(haystack: Envelope): boolean {
+    return this.paths(haystack).length > 0;
+  }
+
+  compile(code: Instr[], literals: Pattern[], captures: string[]): void {
+    // Each pattern must match at this position
+    for (const pattern of this.#patterns) {
+      const matcher = pattern as unknown as Matcher;
+      matcher.compile(code, literals, captures);
+    }
+  }
+
+  isComplex(): boolean {
+    // The pattern is complex if it contains more than one pattern, or if
+    // the one pattern is complex itself.
+    return (
+      this.#patterns.length > 1 || this.#patterns.some((p) => (p as unknown as Matcher).isComplex())
+    );
+  }
+
+  toString(): string {
+    return this.#patterns
+      .map((p) => (p as unknown as { toString(): string }).toString())
+      .join(" & ");
+  }
+
+  /**
+   * Equality comparison.
+   */
+  equals(other: AndPattern): boolean {
+    if (this.#patterns.length !== other.#patterns.length) {
+      return false;
+    }
+    for (let i = 0; i < this.#patterns.length; i++) {
+      if (this.#patterns[i] !== other.#patterns[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Hash code for use in Maps/Sets.
+   */
+  hashCode(): number {
+    return this.#patterns.length;
+  }
+}

package/src/pattern/meta/any-pattern.ts

@@ -0,0 +1,81 @@
+/**
+ * @bcts/envelope-pattern - Any pattern matching
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust any_pattern.rs
+ *
+ * @module envelope-pattern/pattern/meta/any-pattern
+ */
+
+import type { Envelope } from "@bcts/envelope";
+import type { Path } from "../../format";
+import type { Matcher } from "../matcher";
+import { compileAsAtomic } from "../matcher";
+import type { Instr } from "../vm";
+import type { Pattern } from "../index";
+
+// Forward declaration for Pattern factory
+let createMetaAnyPattern: ((pattern: AnyPattern) => Pattern) | undefined;
+
+export function registerAnyPatternFactory(factory: (pattern: AnyPattern) => Pattern): void {
+  createMetaAnyPattern = factory;
+}
+
+/**
+ * A pattern that matches any element.
+ *
+ * Corresponds to the Rust `AnyPattern` struct in any_pattern.rs
+ */
+export class AnyPattern implements Matcher {
+  private constructor() {
+    // Empty constructor - AnyPattern is a singleton-like pattern with no state
+  }
+
+  /**
+   * Creates a new AnyPattern.
+   */
+  static new(): AnyPattern {
+    return new AnyPattern();
+  }
+
+  pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
+    // Always return a path containing the envelope itself.
+    return [[[haystack]], new Map<string, Path[]>()];
+  }
+
+  paths(haystack: Envelope): Path[] {
+    return this.pathsWithCaptures(haystack)[0];
+  }
+
+  matches(_haystack: Envelope): boolean {
+    return true;
+  }
+
+  compile(code: Instr[], literals: Pattern[], captures: string[]): void {
+    if (createMetaAnyPattern === undefined) {
+      throw new Error("AnyPattern factory not registered");
+    }
+    compileAsAtomic(createMetaAnyPattern(this), code, literals, captures);
+  }
+
+  isComplex(): boolean {
+    return false;
+  }
+
+  toString(): string {
+    return "*";
+  }
+
+  /**
+   * Equality comparison.
+   */
+  equals(_other: AnyPattern): boolean {
+    return true; // All AnyPattern instances are equal
+  }
+
+  /**
+   * Hash code for use in Maps/Sets.
+   */
+  hashCode(): number {
+    return 0;
+  }
+}

package/src/pattern/meta/capture-pattern.ts

@@ -0,0 +1,111 @@
+/**
+ * @bcts/envelope-pattern - Capture pattern matching
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust capture_pattern.rs
+ *
+ * @module envelope-pattern/pattern/meta/capture-pattern
+ */
+
+import type { Envelope } from "@bcts/envelope";
+import type { Path } from "../../format";
+import type { Matcher } from "../matcher";
+import type { Instr } from "../vm";
+import type { Pattern } from "../index";
+
+// Forward declaration for Pattern factory (used for late binding)
+export let createMetaCapturePattern: ((pattern: CapturePattern) => Pattern) | undefined;
+
+export function registerCapturePatternFactory(factory: (pattern: CapturePattern) => Pattern): void {
+  createMetaCapturePattern = factory;
+}
+
+/**
+ * A pattern that captures a match with a name.
+ *
+ * Corresponds to the Rust `CapturePattern` struct in capture_pattern.rs
+ */
+export class CapturePattern implements Matcher {
+  readonly #name: string;
+  readonly #pattern: Pattern;
+
+  private constructor(name: string, pattern: Pattern) {
+    this.#name = name;
+    this.#pattern = pattern;
+  }
+
+  /**
+   * Creates a new CapturePattern with the given name and pattern.
+   */
+  static new(name: string, pattern: Pattern): CapturePattern {
+    return new CapturePattern(name, pattern);
+  }
+
+  /**
+   * Gets the name of the capture.
+   */
+  name(): string {
+    return this.#name;
+  }
+
+  /**
+   * Gets the inner pattern.
+   */
+  pattern(): Pattern {
+    return this.#pattern;
+  }
+
+  pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
+    const matcher = this.#pattern as unknown as Matcher;
+    const [paths, caps] = matcher.pathsWithCaptures(haystack);
+
+    if (paths.length > 0) {
+      const existing = caps.get(this.#name) ?? [];
+      caps.set(this.#name, [...existing, ...paths]);
+    }
+
+    return [paths, caps];
+  }
+
+  paths(haystack: Envelope): Path[] {
+    return this.pathsWithCaptures(haystack)[0];
+  }
+
+  matches(haystack: Envelope): boolean {
+    return this.paths(haystack).length > 0;
+  }
+
+  compile(code: Instr[], literals: Pattern[], captures: string[]): void {
+    const id = captures.length;
+    captures.push(this.#name);
+    code.push({ type: "CaptureStart", captureIndex: id });
+    const matcher = this.#pattern as unknown as Matcher;
+    matcher.compile(code, literals, captures);
+    code.push({ type: "CaptureEnd", captureIndex: id });
+  }
+
+  isComplex(): boolean {
+    return false;
+  }
+
+  toString(): string {
+    return `@${this.#name}(${(this.#pattern as unknown as { toString(): string }).toString()})`;
+  }
+
+  /**
+   * Equality comparison.
+   */
+  equals(other: CapturePattern): boolean {
+    return this.#name === other.#name && this.#pattern === other.#pattern;
+  }
+
+  /**
+   * Hash code for use in Maps/Sets.
+   */
+  hashCode(): number {
+    let hash = 0;
+    for (const char of this.#name) {
+      hash = (hash * 31 + char.charCodeAt(0)) | 0;
+    }
+    return hash;
+  }
+}

package/src/pattern/meta/group-pattern.ts

@@ -0,0 +1,110 @@
+/**
+ * @bcts/envelope-pattern - Group/repeat pattern matching
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust repeat_pattern.rs
+ *
+ * @module envelope-pattern/pattern/meta/group-pattern
+ */
+
+import type { Envelope } from "@bcts/envelope";
+import { Quantifier } from "@bcts/dcbor-pattern";
+import type { Path } from "../../format";
+import type { Matcher } from "../matcher";
+import type { Instr } from "../vm";
+import type { Pattern } from "../index";
+
+// Forward declaration for Pattern factory (used for late binding)
+export let createMetaGroupPattern: ((pattern: GroupPattern) => Pattern) | undefined;
+
+export function registerGroupPatternFactory(factory: (pattern: GroupPattern) => Pattern): void {
+  createMetaGroupPattern = factory;
+}
+
+/**
+ * A pattern that matches with repetition.
+ *
+ * Corresponds to the Rust `GroupPattern` struct in repeat_pattern.rs
+ */
+export class GroupPattern implements Matcher {
+  readonly #pattern: Pattern;
+  readonly #quantifier: Quantifier;
+
+  private constructor(pattern: Pattern, quantifier: Quantifier) {
+    this.#pattern = pattern;
+    this.#quantifier = quantifier;
+  }
+
+  /**
+   * Creates a new GroupPattern with the specified sub-pattern and quantifier.
+   */
+  static repeat(pattern: Pattern, quantifier: Quantifier): GroupPattern {
+    return new GroupPattern(pattern, quantifier);
+  }
+
+  /**
+   * Creates a new GroupPattern with a quantifier that matches exactly once.
+   */
+  static new(pattern: Pattern): GroupPattern {
+    return new GroupPattern(pattern, Quantifier.exactly(1));
+  }
+
+  /**
+   * Gets the sub-pattern of this group pattern.
+   */
+  pattern(): Pattern {
+    return this.#pattern;
+  }
+
+  /**
+   * Gets the quantifier of this group pattern.
+   */
+  quantifier(): Quantifier {
+    return this.#quantifier;
+  }
+
+  pathsWithCaptures(_haystack: Envelope): [Path[], Map<string, Path[]>] {
+    throw new Error(
+      "GroupPattern does not support pathsWithCaptures directly; use compile instead",
+    );
+  }
+
+  paths(haystack: Envelope): Path[] {
+    return this.pathsWithCaptures(haystack)[0];
+  }
+
+  matches(haystack: Envelope): boolean {
+    // GroupPattern needs VM execution
+    const matcher = this.#pattern as unknown as Matcher;
+    return matcher.matches(haystack);
+  }
+
+  compile(code: Instr[], literals: Pattern[], _captures: string[]): void {
+    const idx = literals.length;
+    literals.push(this.#pattern);
+    code.push({ type: "Repeat", patternIndex: idx, quantifier: this.#quantifier });
+  }
+
+  isComplex(): boolean {
+    return true;
+  }
+
+  toString(): string {
+    const formattedRange = this.#quantifier.toString();
+    return `(${(this.#pattern as unknown as { toString(): string }).toString()})${formattedRange}`;
+  }
+
+  /**
+   * Equality comparison.
+   */
+  equals(other: GroupPattern): boolean {
+    return this.#pattern === other.#pattern && this.#quantifier.equals(other.#quantifier);
+  }
+
+  /**
+   * Hash code for use in Maps/Sets.
+   */
+  hashCode(): number {
+    // Simple hash based on quantifier min/max
+    return this.#quantifier.min() * 31 + (this.#quantifier.max() ?? 0);
+  }
+}