@bcts/dcbor-pattern 1.0.0-alpha.11

package/src/pattern/match-registry.ts

@@ -0,0 +1,137 @@
+/**
+ * Late-binding registry for pattern matching functions.
+ * This avoids circular dependencies between pattern modules.
+ *
+ * @module pattern/match-registry
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Path } from "../format";
+
+// Forward declare Pattern type to avoid circular import
+// The actual Pattern type is defined in ./index.ts
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Pattern = any;
+
+/**
+ * Match result with paths and captures.
+ */
+export interface MatchResultInternal {
+  readonly paths: Path[];
+  readonly captures: Map<string, Path[]>;
+}
+
+/**
+ * Registry for the pattern matching function.
+ * This gets set by pattern/index.ts after all modules are loaded.
+ */
+export let matchFn: ((pattern: Pattern, haystack: Cbor) => boolean) | undefined;
+
+/**
+ * Registry for the pattern paths function.
+ * This gets set by pattern/index.ts after all modules are loaded.
+ */
+export let pathsFn: ((pattern: Pattern, haystack: Cbor) => Path[]) | undefined;
+
+/**
+ * Registry for the pattern paths with captures function (VM-based).
+ * This gets set by pattern/index.ts after all modules are loaded.
+ */
+export let pathsWithCapturesFn:
+  | ((pattern: Pattern, haystack: Cbor) => MatchResultInternal)
+  | undefined;
+
+/**
+ * Registry for the direct pattern paths with captures function (non-VM).
+ * This is used by the VM to avoid infinite recursion.
+ */
+export let pathsWithCapturesDirectFn:
+  | ((pattern: Pattern, haystack: Cbor) => MatchResultInternal)
+  | undefined;
+
+/**
+ * Sets the pattern matching function.
+ * Called by pattern/index.ts during module initialization.
+ */
+export const setMatchFn = (fn: (pattern: Pattern, haystack: Cbor) => boolean): void => {
+  matchFn = fn;
+};
+
+/**
+ * Sets the pattern paths function.
+ * Called by pattern/index.ts during module initialization.
+ */
+export const setPathsFn = (fn: (pattern: Pattern, haystack: Cbor) => Path[]): void => {
+  pathsFn = fn;
+};
+
+/**
+ * Sets the pattern paths with captures function.
+ * Called by pattern/index.ts during module initialization.
+ */
+export const setPathsWithCapturesFn = (
+  fn: (pattern: Pattern, haystack: Cbor) => MatchResultInternal,
+): void => {
+  pathsWithCapturesFn = fn;
+};
+
+/**
+ * Sets the direct pattern paths with captures function (non-VM).
+ * Called by pattern/index.ts during module initialization.
+ */
+export const setPathsWithCapturesDirectFn = (
+  fn: (pattern: Pattern, haystack: Cbor) => MatchResultInternal,
+): void => {
+  pathsWithCapturesDirectFn = fn;
+};
+
+/**
+ * Matches a pattern against a CBOR value using the registered function.
+ * @throws Error if the match function hasn't been registered yet.
+ */
+export const matchPattern = (pattern: Pattern, haystack: Cbor): boolean => {
+  if (matchFn === undefined) {
+    throw new Error("Pattern match function not initialized");
+  }
+  return matchFn(pattern, haystack);
+};
+
+/**
+ * Gets paths for a pattern against a CBOR value using the registered function.
+ * @throws Error if the paths function hasn't been registered yet.
+ */
+export const getPatternPaths = (pattern: Pattern, haystack: Cbor): Path[] => {
+  if (pathsFn === undefined) {
+    throw new Error("Pattern paths function not initialized");
+  }
+  return pathsFn(pattern, haystack);
+};
+
+/**
+ * Gets paths with captures for a pattern against a CBOR value (VM-based).
+ * @throws Error if the function hasn't been registered yet.
+ */
+export const getPatternPathsWithCaptures = (
+  pattern: Pattern,
+  haystack: Cbor,
+): MatchResultInternal => {
+  if (pathsWithCapturesFn === undefined) {
+    throw new Error("Pattern paths with captures function not initialized");
+  }
+  return pathsWithCapturesFn(pattern, haystack);
+};
+
+/**
+ * Gets paths with captures directly without the VM (non-recursive).
+ * This is used by the VM to avoid infinite recursion.
+ * @throws Error if the function hasn't been registered yet.
+ */
+export const getPatternPathsWithCapturesDirect = (
+  pattern: Pattern,
+  haystack: Cbor,
+): MatchResultInternal => {
+  if (pathsWithCapturesDirectFn === undefined) {
+    throw new Error("Direct pattern paths with captures function not initialized");
+  }
+  return pathsWithCapturesDirectFn(pattern, haystack);
+};

package/src/pattern/matcher.ts

@@ -0,0 +1,388 @@
+/**
+ * Matcher interface for dCBOR pattern matching.
+ *
+ * @module pattern/matcher
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Path } from "../format";
+import type { Instr, Program } from "./vm";
+import type { Pattern } from "./index";
+import type { StructurePattern } from "./structure";
+import type { MetaPattern } from "./meta";
+
+/**
+ * Result of pattern matching with captures.
+ */
+export interface MatchWithCaptures {
+  readonly paths: Path[];
+  readonly captures: Map<string, Path[]>;
+}
+
+/**
+ * Interface for objects that can match against CBOR values.
+ *
+ * This interface defines the contract for all pattern types in the system.
+ * Implementations handle matching, path collection, and VM bytecode compilation.
+ */
+export interface Matcher {
+  /**
+   * Return all matching paths along with any named captures.
+   *
+   * @param haystack - The CBOR value to match against
+   * @returns A tuple of paths and captures map
+   */
+  pathsWithCaptures(haystack: Cbor): MatchWithCaptures;
+
+  /**
+   * Return only the matching paths, discarding any captures.
+   *
+   * @param haystack - The CBOR value to match against
+   * @returns Array of paths to matching elements
+   */
+  paths(haystack: Cbor): Path[];
+
+  /**
+   * Check if the pattern matches the given CBOR value.
+   *
+   * @param haystack - The CBOR value to test
+   * @returns true if the pattern matches
+   */
+  matches(haystack: Cbor): boolean;
+
+  /**
+   * Compile this pattern into VM bytecode.
+   *
+   * @param code - The instruction array to append to
+   * @param literals - The literals array to append to
+   * @param captures - The capture names array
+   */
+  compile(code: Instr[], literals: Pattern[], captures: string[]): void;
+
+  /**
+   * Recursively collect all capture names from this pattern.
+   *
+   * @param names - The array to collect names into
+   */
+  collectCaptureNames(names: string[]): void;
+
+  /**
+   * Check if the pattern display is "complex" (requires parentheses).
+   *
+   * @returns true if the pattern requires grouping
+   */
+  isComplex(): boolean;
+
+  /**
+   * Format the pattern as a string.
+   */
+  toString(): string;
+}
+
+/**
+ * Default implementation helpers for Matcher.
+ */
+export const MatcherDefaults = {
+  /**
+   * Default paths implementation using pathsWithCaptures.
+   */
+  paths(matcher: Pick<Matcher, "pathsWithCaptures">, haystack: Cbor): Path[] {
+    return matcher.pathsWithCaptures(haystack).paths;
+  },
+
+  /**
+   * Default matches implementation using paths.
+   */
+  matches(matcher: Pick<Matcher, "paths">, haystack: Cbor): boolean {
+    return matcher.paths(haystack).length > 0;
+  },
+
+  /**
+   * Default pathsWithCaptures throws not implemented.
+   */
+  pathsWithCaptures(_haystack: Cbor): MatchWithCaptures {
+    throw new Error("pathsWithCaptures not implemented");
+  },
+
+  /**
+   * Default compile throws not implemented.
+   */
+  compile(_code: Instr[], _literals: Pattern[], _captures: string[]): void {
+    throw new Error("compile not implemented");
+  },
+
+  /**
+   * Default collectCaptureNames does nothing.
+   */
+  collectCaptureNames(_names: string[]): void {
+    // Default implementation does nothing
+  },
+
+  /**
+   * Default isComplex returns false.
+   */
+  isComplex(): boolean {
+    return false;
+  },
+};
+
+/**
+ * Compiles a pattern into a VM program.
+ *
+ * @param pattern - The pattern to compile
+ * @returns A compiled program ready for execution
+ */
+export const compilePattern = (pattern: Pattern): Program => {
+  const code: Instr[] = [];
+  const literals: Pattern[] = [];
+  const captureNames: string[] = [];
+
+  // Collect all capture names first
+  collectPatternCaptureNames(pattern, captureNames);
+
+  // Compile the pattern
+  compilePatternToCode(pattern, code, literals, captureNames);
+
+  // Add final Accept instruction
+  code.push({ type: "Accept" });
+
+  return {
+    code,
+    literals,
+    captureNames,
+  };
+};
+
+/**
+ * Recursively collects capture names from a pattern.
+ */
+const collectPatternCaptureNames = (pattern: Pattern, names: string[]): void => {
+  switch (pattern.kind) {
+    case "Value":
+      // Value patterns don't have captures
+      break;
+    case "Structure":
+      // Structure patterns may have element patterns with captures
+      collectStructurePatternCaptureNames(pattern.pattern, names);
+      break;
+    case "Meta":
+      collectMetaPatternCaptureNames(pattern.pattern, names);
+      break;
+  }
+};
+
+/**
+ * Collects capture names from structure patterns.
+ */
+const collectStructurePatternCaptureNames = (pattern: StructurePattern, names: string[]): void => {
+  switch (pattern.type) {
+    case "Array":
+      if (pattern.pattern.variant === "Elements") {
+        collectPatternCaptureNames(pattern.pattern.pattern, names);
+      }
+      break;
+    case "Map":
+      if (pattern.pattern.variant === "Constraints") {
+        for (const constraint of pattern.pattern.constraints) {
+          // Constraints are tuples: [keyPattern, valuePattern]
+          collectPatternCaptureNames(constraint[0], names);
+          collectPatternCaptureNames(constraint[1], names);
+        }
+      }
+      break;
+    case "Tagged":
+      // Tagged patterns (Tag, Name, Regex variants) have a `pattern` property
+      if (pattern.pattern.variant !== "Any") {
+        collectPatternCaptureNames(pattern.pattern.pattern, names);
+      }
+      break;
+  }
+};
+
+/**
+ * Collects capture names from meta patterns.
+ */
+const collectMetaPatternCaptureNames = (pattern: MetaPattern, names: string[]): void => {
+  switch (pattern.type) {
+    case "Capture":
+      if (!names.includes(pattern.pattern.name)) {
+        names.push(pattern.pattern.name);
+      }
+      collectPatternCaptureNames(pattern.pattern.pattern, names);
+      break;
+    case "And":
+      for (const p of pattern.pattern.patterns) {
+        collectPatternCaptureNames(p, names);
+      }
+      break;
+    case "Or":
+      for (const p of pattern.pattern.patterns) {
+        collectPatternCaptureNames(p, names);
+      }
+      break;
+    case "Not":
+      collectPatternCaptureNames(pattern.pattern.pattern, names);
+      break;
+    case "Repeat":
+      collectPatternCaptureNames(pattern.pattern.pattern, names);
+      break;
+    case "Search":
+      collectPatternCaptureNames(pattern.pattern.pattern, names);
+      break;
+    case "Sequence":
+      for (const p of pattern.pattern.patterns) {
+        collectPatternCaptureNames(p, names);
+      }
+      break;
+    case "Any":
+      // Any patterns don't have captures
+      break;
+  }
+};
+
+/**
+ * Compiles a pattern to VM bytecode.
+ */
+const compilePatternToCode = (
+  pattern: Pattern,
+  code: Instr[],
+  literals: Pattern[],
+  captureNames: string[],
+): void => {
+  switch (pattern.kind) {
+    case "Value":
+      // Value patterns use MatchPredicate
+      literals.push(pattern);
+      code.push({ type: "MatchPredicate", literalIndex: literals.length - 1 });
+      break;
+    case "Structure":
+      // Structure patterns use MatchStructure
+      literals.push(pattern);
+      code.push({ type: "MatchStructure", literalIndex: literals.length - 1 });
+      break;
+    case "Meta":
+      compileMetaPattern(pattern.pattern, code, literals, captureNames);
+      break;
+  }
+};
+
+/**
+ * Compiles meta patterns to VM bytecode.
+ */
+const compileMetaPattern = (
+  pattern: MetaPattern,
+  code: Instr[],
+  literals: Pattern[],
+  captureNames: string[],
+): void => {
+  switch (pattern.type) {
+    case "Any":
+      // Any matches everything - compile as predicate
+      literals.push({ kind: "Meta", pattern });
+      code.push({ type: "MatchPredicate", literalIndex: literals.length - 1 });
+      break;
+
+    case "And": {
+      // All patterns must match
+      for (const p of pattern.pattern.patterns) {
+        compilePatternToCode(p, code, literals, captureNames);
+      }
+      break;
+    }
+
+    case "Or": {
+      // Use splits to try each alternative
+      const patterns = pattern.pattern.patterns;
+      if (patterns.length === 0) break;
+      if (patterns.length === 1) {
+        compilePatternToCode(patterns[0], code, literals, captureNames);
+        break;
+      }
+
+      // Create split chain for alternatives
+      const jumpAddrs: number[] = [];
+      for (let i = 0; i < patterns.length - 1; i++) {
+        const splitAddr = code.length;
+        code.push({ type: "Split", a: 0, b: 0 }); // Placeholder
+
+        // First alternative starts right after split
+        (code[splitAddr] as { type: "Split"; a: number; b: number }).a = code.length;
+        compilePatternToCode(patterns[i], code, literals, captureNames);
+        jumpAddrs.push(code.length);
+        code.push({ type: "Jump", address: 0 }); // Jump to end, placeholder
+
+        // Second alternative address
+        (code[splitAddr] as { type: "Split"; a: number; b: number }).b = code.length;
+      }
+      // Last pattern
+      compilePatternToCode(patterns[patterns.length - 1], code, literals, captureNames);
+
+      // Fix up jump addresses
+      const endAddr = code.length;
+      for (const addr of jumpAddrs) {
+        (code[addr] as { type: "Jump"; address: number }).address = endAddr;
+      }
+      break;
+    }
+
+    case "Not": {
+      // Store the inner pattern and use NotMatch instruction
+      literals.push(pattern.pattern.pattern);
+      code.push({ type: "NotMatch", patternIndex: literals.length - 1 });
+      break;
+    }
+
+    case "Repeat": {
+      literals.push(pattern.pattern.pattern);
+      code.push({
+        type: "Repeat",
+        patternIndex: literals.length - 1,
+        quantifier: pattern.pattern.quantifier,
+      });
+      break;
+    }
+
+    case "Capture": {
+      const captureIndex = captureNames.indexOf(pattern.pattern.name);
+      code.push({ type: "CaptureStart", captureIndex });
+      compilePatternToCode(pattern.pattern.pattern, code, literals, captureNames);
+      code.push({ type: "CaptureEnd", captureIndex });
+      break;
+    }
+
+    case "Search": {
+      // Build capture map for the search pattern
+      const captureMap: [string, number][] = [];
+      const innerNames: string[] = [];
+      collectPatternCaptureNames(pattern.pattern.pattern, innerNames);
+      for (const name of innerNames) {
+        const idx = captureNames.indexOf(name);
+        if (idx >= 0) {
+          captureMap.push([name, idx]);
+        }
+      }
+
+      literals.push(pattern.pattern.pattern);
+      code.push({
+        type: "Search",
+        patternIndex: literals.length - 1,
+        captureMap,
+      });
+      break;
+    }
+
+    case "Sequence": {
+      const patterns = pattern.pattern.patterns;
+      if (patterns.length === 0) break;
+
+      compilePatternToCode(patterns[0], code, literals, captureNames);
+
+      for (let i = 1; i < patterns.length; i++) {
+        code.push({ type: "ExtendSequence" });
+        compilePatternToCode(patterns[i], code, literals, captureNames);
+        code.push({ type: "CombineSequence" });
+      }
+      break;
+    }
+  }
+};

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

@@ -0,0 +1,56 @@
+/**
+ * And pattern for dCBOR pattern matching.
+ * Matches if all contained patterns match.
+ *
+ * @module pattern/meta/and-pattern
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Path } from "../../format";
+import type { Pattern } from "../index";
+import { matchPattern } from "../match-registry";
+
+/**
+ * A pattern that matches if all contained patterns match.
+ */
+export interface AndPattern {
+  readonly variant: "And";
+  readonly patterns: Pattern[];
+}
+
+/**
+ * Creates an AndPattern with the given patterns.
+ */
+export const andPattern = (patterns: Pattern[]): AndPattern => ({
+  variant: "And",
+  patterns,
+});
+
+/**
+ * Tests if a CBOR value matches this and pattern.
+ * All patterns must match.
+ */
+export const andPatternMatches = (pattern: AndPattern, haystack: Cbor): boolean => {
+  return pattern.patterns.every((p: Pattern) => matchPattern(p, haystack));
+};
+
+/**
+ * Returns paths to matching values.
+ */
+export const andPatternPaths = (pattern: AndPattern, haystack: Cbor): Path[] => {
+  if (andPatternMatches(pattern, haystack)) {
+    return [[haystack]];
+  }
+  return [];
+};
+
+/**
+ * Formats an AndPattern as a string.
+ */
+export const andPatternDisplay = (
+  pattern: AndPattern,
+  patternDisplay: (p: Pattern) => string,
+): string => {
+  const parts = pattern.patterns.map(patternDisplay);
+  return parts.join(" & ");
+};

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

@@ -0,0 +1,43 @@
+/**
+ * Any pattern for dCBOR pattern matching.
+ * Always matches any CBOR value.
+ *
+ * @module pattern/meta/any-pattern
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Path } from "../../format";
+
+/**
+ * A pattern that always matches any CBOR value.
+ */
+export interface AnyPattern {
+  readonly variant: "Any";
+}
+
+/**
+ * Creates an AnyPattern.
+ */
+export const anyPattern = (): AnyPattern => ({ variant: "Any" });
+
+/**
+ * Tests if a CBOR value matches this any pattern.
+ * Always returns true.
+ */
+export const anyPatternMatches = (_pattern: AnyPattern, _haystack: Cbor): boolean => {
+  return true;
+};
+
+/**
+ * Returns paths to matching values.
+ */
+export const anyPatternPaths = (_pattern: AnyPattern, haystack: Cbor): Path[] => {
+  return [[haystack]];
+};
+
+/**
+ * Formats an AnyPattern as a string.
+ */
+export const anyPatternDisplay = (_pattern: AnyPattern): string => {
+  return "*";
+};

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

@@ -0,0 +1,57 @@
+/**
+ * Capture pattern for dCBOR pattern matching.
+ * Captures matched values with a name.
+ *
+ * @module pattern/meta/capture-pattern
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Path } from "../../format";
+import type { Pattern } from "../index";
+import { matchPattern } from "../match-registry";
+
+/**
+ * A pattern that captures matched values with a name.
+ */
+export interface CapturePattern {
+  readonly variant: "Capture";
+  readonly name: string;
+  readonly pattern: Pattern;
+}
+
+/**
+ * Creates a CapturePattern with the given name and inner pattern.
+ */
+export const capturePattern = (name: string, pattern: Pattern): CapturePattern => ({
+  variant: "Capture",
+  name,
+  pattern,
+});
+
+/**
+ * Tests if a CBOR value matches this capture pattern.
+ * Capture itself doesn't affect matching - it delegates to inner pattern.
+ */
+export const capturePatternMatches = (pattern: CapturePattern, haystack: Cbor): boolean => {
+  return matchPattern(pattern.pattern, haystack);
+};
+
+/**
+ * Returns paths to matching values.
+ */
+export const capturePatternPaths = (pattern: CapturePattern, haystack: Cbor): Path[] => {
+  if (capturePatternMatches(pattern, haystack)) {
+    return [[haystack]];
+  }
+  return [];
+};
+
+/**
+ * Formats a CapturePattern as a string.
+ */
+export const capturePatternDisplay = (
+  pattern: CapturePattern,
+  patternDisplay: (p: Pattern) => string,
+): string => {
+  return `@${pattern.name}(${patternDisplay(pattern.pattern)})`;
+};