@bcts/dcbor-pattern 1.0.0-alpha.11

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

@@ -0,0 +1,72 @@
+/**
+ * Sequence pattern for dCBOR pattern matching.
+ * Matches a sequence of patterns in order.
+ *
+ * @module pattern/meta/sequence-pattern
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Path } from "../../format";
+import type { Pattern } from "../index";
+
+/**
+ * A pattern that matches a sequence of patterns in order.
+ * Used primarily for matching array elements.
+ */
+export interface SequencePattern {
+  readonly variant: "Sequence";
+  readonly patterns: Pattern[];
+}
+
+/**
+ * Creates a SequencePattern with the given patterns.
+ */
+export const sequencePattern = (patterns: Pattern[]): SequencePattern => ({
+  variant: "Sequence",
+  patterns,
+});
+
+/**
+ * Tests if a CBOR value matches this sequence pattern.
+ *
+ * Note: Sequence patterns are used within array patterns for matching
+ * consecutive elements. When used standalone (not within an array),
+ * they return false/empty as the actual sequence matching logic is
+ * handled by the VM and array pattern matching.
+ */
+export const sequencePatternMatches = (_pattern: SequencePattern, _haystack: Cbor): boolean => {
+  // Sequence patterns are meant for array element matching.
+  // When used standalone, they don't match any single CBOR value.
+  // The VM handles actual sequence matching within arrays.
+  return false;
+};
+
+/**
+ * Returns paths to matching values.
+ *
+ * Note: Sequence patterns return empty paths when used directly.
+ * The actual sequence matching is handled by the VM within array contexts.
+ */
+export const sequencePatternPaths = (_pattern: SequencePattern, _haystack: Cbor): Path[] => {
+  // Sequence patterns return empty paths when used directly.
+  // This matches Rust behavior where sequence matching is VM-based.
+  return [];
+};
+
+/**
+ * Formats a SequencePattern as a string.
+ */
+export const sequencePatternDisplay = (
+  pattern: SequencePattern,
+  patternDisplay: (p: Pattern) => string,
+): string => {
+  const parts = pattern.patterns.map(patternDisplay);
+  return parts.join(", ");
+};
+
+/**
+ * Gets the patterns in this sequence.
+ */
+export const sequencePatternPatterns = (pattern: SequencePattern): Pattern[] => {
+  return pattern.patterns;
+};

package/src/pattern/structure/array-pattern/assigner.ts

@@ -0,0 +1,95 @@
+/**
+ * Sequence assigner for array pattern matching.
+ *
+ * Handles element-to-pattern assignment logic, encapsulating the complex logic
+ * for mapping array elements to sequence patterns.
+ *
+ * @module pattern/structure/array-pattern/assigner
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Pattern } from "../../index";
+import { hasRepeatPatternsInSlice } from "./helpers";
+import { GenericBacktracker, BooleanBacktrackState, AssignmentBacktrackState } from "./backtrack";
+
+/**
+ * Helper class for handling element-to-pattern assignment logic.
+ * Encapsulates the complex logic for mapping array elements to sequence
+ * patterns that was previously duplicated between matching and capture
+ * collection.
+ */
+export class SequenceAssigner {
+  readonly #patterns: Pattern[];
+  readonly #arr: Cbor[];
+  readonly #matchFn: (pattern: Pattern, value: Cbor) => boolean;
+
+  constructor(
+    patterns: Pattern[],
+    arr: Cbor[],
+    matchFn: (pattern: Pattern, value: Cbor) => boolean,
+  ) {
+    this.#patterns = patterns;
+    this.#arr = arr;
+    this.#matchFn = matchFn;
+  }
+
+  /**
+   * Check if the sequence can match against the array elements (boolean result).
+   */
+  canMatch(): boolean {
+    // Simple case: if no patterns, then empty array should match
+    if (this.#patterns.length === 0) {
+      return this.#arr.length === 0;
+    }
+
+    // Check if we have any repeat patterns that require backtracking
+    const hasRepeatPatterns = hasRepeatPatternsInSlice(this.#patterns);
+
+    // Simple case: if pattern count equals element count AND no repeat patterns
+    if (this.#patterns.length === this.#arr.length && !hasRepeatPatterns) {
+      // Try one-to-one matching
+      return this.#patterns.every((pattern, i) => this.#matchFn(pattern, this.#arr[i]));
+    }
+
+    // Complex case: use generic backtracking framework
+    const backtracker = new GenericBacktracker(this.#patterns, this.#arr, this.#matchFn);
+    const state = new BooleanBacktrackState();
+    return backtracker.backtrack(state, 0, 0);
+  }
+
+  /**
+   * Find the element-to-pattern assignments (returns assignment pairs).
+   */
+  findAssignments(): [number, number][] | undefined {
+    // Simple case: if no patterns, then empty array should match
+    if (this.#patterns.length === 0) {
+      return this.#arr.length === 0 ? [] : undefined;
+    }
+
+    // Check if we have any repeat patterns that require backtracking
+    const hasRepeatPatterns = hasRepeatPatternsInSlice(this.#patterns);
+
+    // Simple case: if pattern count equals element count AND no repeat patterns
+    if (this.#patterns.length === this.#arr.length && !hasRepeatPatterns) {
+      const assignments: [number, number][] = [];
+      for (let patternIdx = 0; patternIdx < this.#patterns.length; patternIdx++) {
+        const pattern = this.#patterns[patternIdx];
+        const element = this.#arr[patternIdx];
+        if (this.#matchFn(pattern, element)) {
+          assignments.push([patternIdx, patternIdx]);
+        } else {
+          return undefined; // Pattern doesn't match its corresponding element
+        }
+      }
+      return assignments;
+    }
+
+    // Complex case: use generic backtracking framework
+    const backtracker = new GenericBacktracker(this.#patterns, this.#arr, this.#matchFn);
+    const state = new AssignmentBacktrackState();
+    if (backtracker.backtrack(state, 0, 0)) {
+      return state.assignments;
+    }
+    return undefined;
+  }
+}

package/src/pattern/structure/array-pattern/backtrack.ts

@@ -0,0 +1,240 @@
+/**
+ * Generic backtracking framework for array pattern matching.
+ *
+ * This module provides a generic backtracking algorithm that can work with
+ * different types of state management (boolean matching vs assignment tracking).
+ *
+ * @module pattern/structure/array-pattern/backtrack
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Pattern } from "../../index";
+import type { RepeatPattern } from "../../meta/repeat-pattern";
+import { extractCaptureWithRepeat, calculateRepeatBounds, canRepeatMatch } from "./helpers";
+
+/**
+ * Generic backtracking state interface.
+ * Abstracts the differences between boolean matching and assignment tracking.
+ */
+export interface BacktrackState<T> {
+  /**
+   * Try to advance the state with a new assignment and return true if successful.
+   */
+  tryAdvance(patternIdx: number, elementIdx: number): boolean;
+
+  /**
+   * Backtrack by removing the last state change.
+   */
+  backtrack(): void;
+
+  /**
+   * Check if we've reached a successful final state.
+   */
+  isSuccess(
+    patternIdx: number,
+    elementIdx: number,
+    patternsLen: number,
+    elementsLen: number,
+  ): boolean;
+
+  /**
+   * Get the final result.
+   */
+  getResult(): T;
+}
+
+/**
+ * Boolean backtracking state - just tracks success/failure.
+ */
+export class BooleanBacktrackState implements BacktrackState<boolean> {
+  tryAdvance(_patternIdx: number, _elementIdx: number): boolean {
+    return true; // Always allow advancement for boolean matching
+  }
+
+  backtrack(): void {
+    // Nothing to backtrack for boolean state
+  }
+
+  isSuccess(
+    patternIdx: number,
+    elementIdx: number,
+    patternsLen: number,
+    elementsLen: number,
+  ): boolean {
+    return patternIdx >= patternsLen && elementIdx >= elementsLen;
+  }
+
+  getResult(): boolean {
+    return true; // If we get here, we succeeded
+  }
+}
+
+/**
+ * Assignment tracking backtracking state - collects pattern-element pairs.
+ */
+export class AssignmentBacktrackState implements BacktrackState<[number, number][]> {
+  readonly assignments: [number, number][] = [];
+
+  tryAdvance(patternIdx: number, elementIdx: number): boolean {
+    this.assignments.push([patternIdx, elementIdx]);
+    return true;
+  }
+
+  backtrack(): void {
+    this.assignments.pop();
+  }
+
+  isSuccess(
+    patternIdx: number,
+    elementIdx: number,
+    patternsLen: number,
+    elementsLen: number,
+  ): boolean {
+    return patternIdx >= patternsLen && elementIdx >= elementsLen;
+  }
+
+  getResult(): [number, number][] {
+    return this.assignments;
+  }
+
+  len(): number {
+    return this.assignments.length;
+  }
+
+  truncate(len: number): void {
+    this.assignments.length = len;
+  }
+}
+
+/**
+ * Generic backtracking algorithm that works with any BacktrackState.
+ */
+export class GenericBacktracker {
+  readonly #patterns: Pattern[];
+  readonly #arr: Cbor[];
+  readonly #matchFn: (pattern: Pattern, value: Cbor) => boolean;
+
+  constructor(
+    patterns: Pattern[],
+    arr: Cbor[],
+    matchFn: (pattern: Pattern, value: Cbor) => boolean,
+  ) {
+    this.#patterns = patterns;
+    this.#arr = arr;
+    this.#matchFn = matchFn;
+  }
+
+  /**
+   * Generic backtracking algorithm that works with any state type.
+   */
+  backtrack<T>(state: BacktrackState<T>, patternIdx: number, elementIdx: number): boolean {
+    // Base case: if we've matched all patterns
+    if (state.isSuccess(patternIdx, elementIdx, this.#patterns.length, this.#arr.length)) {
+      return true;
+    }
+
+    if (patternIdx >= this.#patterns.length) {
+      return false; // No more patterns but still have elements
+    }
+
+    const currentPattern = this.#patterns[patternIdx];
+
+    // Check if this is a repeat pattern
+    if (currentPattern.kind === "Meta" && currentPattern.pattern.type === "Repeat") {
+      const repeatPattern = currentPattern.pattern.pattern;
+      return this.tryRepeatBacktrack(repeatPattern, state, patternIdx, elementIdx);
+    }
+
+    // Check if this is a capture pattern
+    if (currentPattern.kind === "Meta" && currentPattern.pattern.type === "Capture") {
+      // Check if the capture pattern contains a repeat pattern
+      const repeatPattern = extractCaptureWithRepeat(currentPattern);
+      if (repeatPattern !== undefined) {
+        // Handle this like a repeat pattern
+        return this.tryRepeatBacktrack(repeatPattern, state, patternIdx, elementIdx);
+      }
+
+      // Handle as a normal single-element capture
+      if (elementIdx < this.#arr.length) {
+        const element = this.#arr[elementIdx];
+        const matches = this.#matchFn(currentPattern, element);
+
+        if (matches && state.tryAdvance(patternIdx, elementIdx)) {
+          if (this.backtrack(state, patternIdx + 1, elementIdx + 1)) {
+            return true;
+          }
+          // Backtracking is handled by the recursive call failing
+          state.backtrack();
+        }
+      }
+      return false;
+    }
+
+    // Non-repeat pattern: must match exactly one element
+    if (elementIdx < this.#arr.length) {
+      const element = this.#arr[elementIdx];
+      const matches = this.#matchFn(currentPattern, element);
+
+      if (matches && state.tryAdvance(patternIdx, elementIdx)) {
+        if (this.backtrack(state, patternIdx + 1, elementIdx + 1)) {
+          return true;
+        }
+        // Backtracking is handled by the recursive call failing
+        state.backtrack();
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Helper for repeat pattern backtracking with generic state.
+   */
+  private tryRepeatBacktrack<T>(
+    repeatPattern: RepeatPattern,
+    state: BacktrackState<T>,
+    patternIdx: number,
+    elementIdx: number,
+  ): boolean {
+    const quantifier = repeatPattern.quantifier;
+    const [minCount, maxCount] = calculateRepeatBounds(quantifier, elementIdx, this.#arr.length);
+
+    // Try different numbers of repetitions (greedy: start with max)
+    for (let repCount = maxCount; repCount >= minCount; repCount--) {
+      if (
+        elementIdx + repCount <= this.#arr.length &&
+        canRepeatMatch(repeatPattern, this.#arr, elementIdx, repCount, this.#matchFn)
+      ) {
+        // Record state for all consumed elements
+        let advancedCount = 0;
+        let canAdvance = true;
+        for (let i = 0; i < repCount; i++) {
+          if (!state.tryAdvance(patternIdx, elementIdx + i)) {
+            // If we can't advance, backtrack what we've added
+            // and try next repCount
+            for (let j = 0; j < advancedCount; j++) {
+              state.backtrack();
+            }
+            canAdvance = false;
+            break;
+          }
+          advancedCount++;
+        }
+
+        if (!canAdvance) {
+          continue;
+        }
+
+        // Try to match the rest of the sequence recursively
+        if (this.backtrack(state, patternIdx + 1, elementIdx + repCount)) {
+          return true;
+        }
+
+        // Backtrack: undo all the advances we made for this repCount
+        for (let i = 0; i < repCount; i++) {
+          state.backtrack();
+        }
+      }
+    }
+    return false;
+  }
+}

package/src/pattern/structure/array-pattern/helpers.ts

@@ -0,0 +1,140 @@
+/**
+ * Helper functions for array pattern matching.
+ *
+ * @module pattern/structure/array-pattern/helpers
+ */
+
+import type { Cbor } from "@bcts/dcbor";
+import type { Pattern } from "../../index";
+import type { RepeatPattern } from "../../meta/repeat-pattern";
+import type { Quantifier } from "../../../quantifier";
+
+/**
+ * Check if a pattern is a repeat pattern.
+ */
+export const isRepeatPattern = (pattern: Pattern): boolean => {
+  return pattern.kind === "Meta" && pattern.pattern.type === "Repeat";
+};
+
+/**
+ * Check if a pattern is a capture pattern containing a repeat pattern.
+ * Returns the inner repeat pattern if found.
+ */
+export const extractCaptureWithRepeat = (pattern: Pattern): RepeatPattern | undefined => {
+  if (pattern.kind === "Meta" && pattern.pattern.type === "Capture") {
+    const capturePattern = pattern.pattern.pattern;
+    const innerPattern = capturePattern.pattern;
+    if (innerPattern.kind === "Meta" && innerPattern.pattern.type === "Repeat") {
+      return innerPattern.pattern.pattern;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Extract any repeat pattern from a pattern, whether direct or within a capture.
+ */
+export const extractRepeatPattern = (pattern: Pattern): RepeatPattern | undefined => {
+  if (pattern.kind === "Meta") {
+    if (pattern.pattern.type === "Repeat") {
+      return pattern.pattern.pattern;
+    }
+    if (pattern.pattern.type === "Capture") {
+      const capturePattern = pattern.pattern.pattern;
+      const innerPattern = capturePattern.pattern;
+      if (innerPattern.kind === "Meta" && innerPattern.pattern.type === "Repeat") {
+        return innerPattern.pattern.pattern;
+      }
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Check if a slice of patterns contains any repeat patterns (direct or in captures).
+ */
+export const hasRepeatPatternsInSlice = (patterns: Pattern[]): boolean => {
+  return patterns.some((p) => extractRepeatPattern(p) !== undefined);
+};
+
+/**
+ * Calculate the bounds for repeat pattern matching based on quantifier and
+ * available elements.
+ */
+export const calculateRepeatBounds = (
+  quantifier: Quantifier,
+  elementIdx: number,
+  arrLen: number,
+): [number, number] => {
+  const minCount = quantifier.min();
+  const remainingElements = Math.max(0, arrLen - elementIdx);
+  const maxCount = Math.min(quantifier.max() ?? remainingElements, remainingElements);
+  return [minCount, maxCount];
+};
+
+/**
+ * Check if a repeat pattern can match a specific number of elements starting
+ * at elementIdx.
+ */
+export const canRepeatMatch = (
+  repeatPattern: RepeatPattern,
+  arr: Cbor[],
+  elementIdx: number,
+  repCount: number,
+  matchFn: (pattern: Pattern, value: Cbor) => boolean,
+): boolean => {
+  if (repCount === 0) {
+    return true; // Zero repetitions always match
+  }
+  for (let i = 0; i < repCount; i++) {
+    const element = arr[elementIdx + i];
+    if (!matchFn(repeatPattern.pattern, element)) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Build a simple array context path: [arrayCbor, element]
+ */
+export const buildSimpleArrayContextPath = (arrayCbor: Cbor, element: Cbor): Cbor[] => {
+  return [arrayCbor, element];
+};
+
+/**
+ * Build an extended array context path: [arrayCbor, element] + capturedPath
+ * (skip first element)
+ */
+export const buildExtendedArrayContextPath = (
+  arrayCbor: Cbor,
+  element: Cbor,
+  capturedPath: Cbor[],
+): Cbor[] => {
+  const arrayPath: Cbor[] = [arrayCbor, element];
+  if (capturedPath.length > 1) {
+    arrayPath.push(...capturedPath.slice(1));
+  }
+  return arrayPath;
+};
+
+/**
+ * Transform nested captures to include array context, extending allCaptures.
+ */
+export const transformCapturesWithArrayContext = (
+  arrayCbor: Cbor,
+  element: Cbor,
+  nestedCaptures: Map<string, Cbor[][]>,
+  allCaptures: Map<string, Cbor[][]>,
+): void => {
+  for (const [captureName, capturedPaths] of nestedCaptures) {
+    const arrayContextPaths: Cbor[][] = [];
+    for (const capturedPath of capturedPaths) {
+      const arrayPath = buildExtendedArrayContextPath(arrayCbor, element, capturedPath);
+      arrayContextPaths.push(arrayPath);
+    }
+    const existing = allCaptures.get(captureName) ?? [];
+    existing.push(...arrayContextPaths);
+    allCaptures.set(captureName, existing);
+  }
+};