@bcts/dcbor-pattern 1.0.0-alpha.11

package/src/format.ts

@@ -0,0 +1,299 @@
+/**
+ * Format Module for dcbor-pattern
+ *
+ * This module provides formatting utilities for displaying paths returned by
+ * pattern matching. Unlike `bc-envelope-pattern` which supports digest URs and
+ * envelope URs, this module focuses on CBOR diagnostic notation formatting.
+ *
+ * ## Features
+ *
+ * - **Diagnostic formatting**: Format CBOR elements using either standard or
+ *   flat diagnostic notation
+ * - **Path indentation**: Automatically indent nested path elements
+ * - **Truncation support**: Optionally truncate long representations with
+ *   ellipsis
+ * - **Flexible options**: Choose whether to show all elements or just the
+ *   final destination
+ *
+ * @module format
+ */
+
+import { type Cbor, summary, diagnosticOpt } from "@bcts/dcbor";
+
+/**
+ * A Path is a sequence of CBOR values representing the traversal from root
+ * to a matched element.
+ */
+export type Path = Cbor[];
+
+/**
+ * A builder that provides formatting options for each path element.
+ */
+export enum PathElementFormat {
+  /**
+   * Diagnostic summary format, with optional maximum length for truncation.
+   */
+  DiagnosticSummary = "diagnostic_summary",
+
+  /**
+   * Flat diagnostic format (single line), with optional maximum length for
+   * truncation.
+   */
+  DiagnosticFlat = "diagnostic_flat",
+}
+
+/**
+ * Options for formatting paths.
+ */
+export interface FormatPathsOpts {
+  /**
+   * Whether to indent each path element.
+   * If true, each element will be indented by 4 spaces per level.
+   * @default true
+   */
+  readonly indent: boolean;
+
+  /**
+   * Format for each path element.
+   * @default PathElementFormat.DiagnosticSummary
+   */
+  readonly elementFormat: PathElementFormat;
+
+  /**
+   * Maximum length for element representation before truncation.
+   * If undefined, no truncation is applied.
+   */
+  readonly maxLength: number | undefined;
+
+  /**
+   * If true, only the last element of each path will be formatted.
+   * This is useful for displaying only the final destination of a path.
+   * If false, all elements will be formatted.
+   * @default false
+   */
+  readonly lastElementOnly: boolean;
+}
+
+/**
+ * Default formatting options.
+ */
+export const DEFAULT_FORMAT_OPTS: FormatPathsOpts = {
+  indent: true,
+  elementFormat: PathElementFormat.DiagnosticSummary,
+  maxLength: undefined,
+  lastElementOnly: false,
+} as const;
+
+/**
+ * Creates formatting options with builder pattern.
+ */
+export class FormatPathsOptsBuilder {
+  #opts: FormatPathsOpts;
+
+  constructor() {
+    this.#opts = { ...DEFAULT_FORMAT_OPTS };
+  }
+
+  /**
+   * Creates a new builder with default options.
+   */
+  static new(): FormatPathsOptsBuilder {
+    return new FormatPathsOptsBuilder();
+  }
+
+  /**
+   * Sets whether to indent each path element.
+   */
+  indent(indent: boolean): FormatPathsOptsBuilder {
+    this.#opts = { ...this.#opts, indent };
+    return this;
+  }
+
+  /**
+   * Sets the format for each path element.
+   */
+  elementFormat(format: PathElementFormat): FormatPathsOptsBuilder {
+    this.#opts = { ...this.#opts, elementFormat: format };
+    return this;
+  }
+
+  /**
+   * Sets the maximum length for element representation.
+   */
+  maxLength(length: number | undefined): FormatPathsOptsBuilder {
+    this.#opts = { ...this.#opts, maxLength: length };
+    return this;
+  }
+
+  /**
+   * Sets whether to format only the last element of each path.
+   */
+  lastElementOnly(lastOnly: boolean): FormatPathsOptsBuilder {
+    this.#opts = { ...this.#opts, lastElementOnly: lastOnly };
+    return this;
+  }
+
+  /**
+   * Builds the options object.
+   */
+  build(): FormatPathsOpts {
+    return this.#opts;
+  }
+}
+
+/**
+ * Truncates a string to the specified maximum length, appending an ellipsis if
+ * truncated.
+ *
+ * @internal
+ * @param s - The string to truncate
+ * @param maxLength - Maximum length, or undefined for no truncation
+ * @returns The possibly truncated string
+ */
+const truncateWithEllipsis = (s: string, maxLength?: number): string => {
+  if (maxLength === undefined || s.length <= maxLength) {
+    return s;
+  }
+  if (maxLength > 1) {
+    return `${s.slice(0, maxLength - 1)}…`;
+  }
+  return "…";
+};
+
+/**
+ * Format a single CBOR element according to the specified format.
+ *
+ * @internal
+ * @param cbor - The CBOR value to format
+ * @param format - The format to use
+ * @param maxLength - Maximum length before truncation
+ * @returns The formatted string
+ */
+const formatCborElement = (cbor: Cbor, format: PathElementFormat, maxLength?: number): string => {
+  let diagnostic: string;
+
+  // Use the diagnostic functions from @bcts/dcbor
+  if (format === PathElementFormat.DiagnosticSummary) {
+    // summary() provides a compact representation with summarizers
+    diagnostic = summary(cbor);
+  } else {
+    // diagnosticOpt with flat: true provides a single-line representation
+    diagnostic = diagnosticOpt(cbor, { flat: true });
+  }
+
+  return truncateWithEllipsis(diagnostic, maxLength);
+};
+
+/**
+ * Format each path element on its own line, each line successively indented by
+ * 4 spaces. Options can be provided to customize the formatting.
+ *
+ * @param path - The path to format
+ * @param opts - Formatting options
+ * @returns The formatted path string
+ */
+export const formatPathOpt = (path: Path, opts: FormatPathsOpts = DEFAULT_FORMAT_OPTS): string => {
+  if (opts.lastElementOnly) {
+    // Only format the last element, no indentation.
+    const lastElement = path[path.length - 1];
+    if (lastElement !== undefined) {
+      return formatCborElement(lastElement, opts.elementFormat, opts.maxLength);
+    }
+    return "";
+  }
+
+  // Multi-line output with indentation for diagnostic formats.
+  const lines: string[] = [];
+  for (let index = 0; index < path.length; index++) {
+    const element = path[index];
+    const indent = opts.indent ? " ".repeat(index * 4) : "";
+    const content = formatCborElement(element, opts.elementFormat, opts.maxLength);
+    lines.push(`${indent}${content}`);
+  }
+  return lines.join("\n");
+};
+
+/**
+ * Format each path element on its own line, each line successively indented by
+ * 4 spaces.
+ *
+ * @param path - The path to format
+ * @returns The formatted path string
+ */
+export const formatPath = (path: Path): string => {
+  return formatPathOpt(path, DEFAULT_FORMAT_OPTS);
+};
+
+/**
+ * Format multiple paths with captures in a structured way.
+ * Captures come first, sorted lexicographically by name, with their name
+ * prefixed by '@'. Regular paths follow after all captures.
+ *
+ * @param paths - The paths to format
+ * @param captures - Named capture groups and their paths
+ * @param opts - Formatting options
+ * @returns The formatted string
+ */
+export const formatPathsWithCaptures = (
+  paths: Path[],
+  captures: Map<string, Path[]>,
+  opts: FormatPathsOpts = DEFAULT_FORMAT_OPTS,
+): string => {
+  const result: string[] = [];
+
+  // First, format all captures, sorted lexicographically by name
+  const captureNames = Array.from(captures.keys()).sort();
+
+  for (const captureName of captureNames) {
+    const capturePaths = captures.get(captureName);
+    if (capturePaths !== undefined) {
+      result.push(`@${captureName}`);
+      for (const path of capturePaths) {
+        const formattedPath = formatPathOpt(path, opts);
+        // Add indentation to each line of the formatted path
+        for (const line of formattedPath.split("\n")) {
+          if (line.length > 0) {
+            result.push(`    ${line}`);
+          }
+        }
+      }
+    }
+  }
+
+  // Then, format all regular paths
+  for (const path of paths) {
+    const formattedPath = formatPathOpt(path, opts);
+    for (const line of formattedPath.split("\n")) {
+      if (line.length > 0) {
+        result.push(line);
+      }
+    }
+  }
+
+  return result.join("\n");
+};
+
+/**
+ * Format multiple paths with custom formatting options.
+ *
+ * @param paths - The paths to format
+ * @param opts - Formatting options
+ * @returns The formatted string
+ */
+export const formatPathsOpt = (
+  paths: Path[],
+  opts: FormatPathsOpts = DEFAULT_FORMAT_OPTS,
+): string => {
+  // Call formatPathsWithCaptures with empty captures
+  return formatPathsWithCaptures(paths, new Map(), opts);
+};
+
+/**
+ * Format multiple paths with default options.
+ *
+ * @param paths - The paths to format
+ * @returns The formatted string
+ */
+export const formatPaths = (paths: Path[]): string => {
+  return formatPathsOpt(paths, DEFAULT_FORMAT_OPTS);
+};

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @bcts/dcbor-pattern - Pattern matching for dCBOR (Deterministic CBOR)
+ *
+ * This is a 1:1 TypeScript port of bc-dcbor-pattern-rust.
+ *
+ * @module dcbor-pattern
+ */
+
+// Core types
+export * from "./error";
+export * from "./reluctance";
+export * from "./interval";
+export * from "./quantifier";
+export * from "./format";
+
+// Pattern types
+export * from "./pattern";
+
+// Parsing
+export * from "./parse";

package/src/interval.ts

@@ -0,0 +1,230 @@
+/**
+ * Provides an `Interval` type representing a range of values with a
+ * minimum and optional maximum.
+ *
+ * This module is used in the context of pattern matching for dCBOR items
+ * to represent cardinality specifications like `{n}`, `{n,m}`, or `{n,}`
+ * in pattern expressions.
+ *
+ * @module interval
+ */
+
+/**
+ * Represents an inclusive interval with a minimum value and an optional
+ * maximum value.
+ *
+ * When the maximum is `undefined`, the interval is considered unbounded above.
+ *
+ * @example
+ * ```typescript
+ * // Single value interval
+ * const exact = new Interval(3, 3);  // Matches exactly 3
+ *
+ * // Bounded range
+ * const range = new Interval(1, 5);  // Matches 1 to 5 inclusive
+ *
+ * // Unbounded range
+ * const unbounded = new Interval(2); // Matches 2 or more
+ * ```
+ */
+export class Interval {
+  readonly #min: number;
+  readonly #max: number | undefined;
+
+  /**
+   * Creates a new Interval.
+   *
+   * @param min - The minimum value (inclusive)
+   * @param max - The maximum value (inclusive), or undefined for unbounded
+   */
+  constructor(min: number, max?: number) {
+    this.#min = min;
+    this.#max = max;
+  }
+
+  /**
+   * Creates an interval from a range specification.
+   *
+   * @param start - The start of the range (inclusive)
+   * @param end - The end of the range (inclusive), or undefined for unbounded
+   * @returns A new Interval
+   */
+  static from(start: number, end?: number): Interval {
+    return new Interval(start, end);
+  }
+
+  /**
+   * Creates an interval for exactly n occurrences.
+   *
+   * @param n - The exact count
+   * @returns A new Interval with min = max = n
+   */
+  static exactly(n: number): Interval {
+    return new Interval(n, n);
+  }
+
+  /**
+   * Creates an interval for at least n occurrences.
+   *
+   * @param n - The minimum count
+   * @returns A new Interval with min = n and no maximum
+   */
+  static atLeast(n: number): Interval {
+    return new Interval(n, undefined);
+  }
+
+  /**
+   * Creates an interval for at most n occurrences.
+   *
+   * @param n - The maximum count
+   * @returns A new Interval with min = 0 and max = n
+   */
+  static atMost(n: number): Interval {
+    return new Interval(0, n);
+  }
+
+  /**
+   * Creates an interval for zero or more occurrences (0..).
+   *
+   * @returns A new Interval representing *
+   */
+  static zeroOrMore(): Interval {
+    return new Interval(0, undefined);
+  }
+
+  /**
+   * Creates an interval for one or more occurrences (1..).
+   *
+   * @returns A new Interval representing +
+   */
+  static oneOrMore(): Interval {
+    return new Interval(1, undefined);
+  }
+
+  /**
+   * Creates an interval for zero or one occurrence (0..=1).
+   *
+   * @returns A new Interval representing ?
+   */
+  static zeroOrOne(): Interval {
+    return new Interval(0, 1);
+  }
+
+  /**
+   * Returns the minimum value of the interval.
+   */
+  min(): number {
+    return this.#min;
+  }
+
+  /**
+   * Returns the maximum value of the interval, or `undefined` if unbounded.
+   */
+  max(): number | undefined {
+    return this.#max;
+  }
+
+  /**
+   * Checks if the given count falls within this interval.
+   *
+   * @param count - The count to check
+   * @returns true if count is within the interval
+   */
+  contains(count: number): boolean {
+    return count >= this.#min && (this.#max === undefined || count <= this.#max);
+  }
+
+  /**
+   * Checks if the interval represents a single value (i.e., min equals max).
+   */
+  isSingle(): boolean {
+    return this.#max !== undefined && this.#min === this.#max;
+  }
+
+  /**
+   * Checks if the interval is unbounded (i.e., has no maximum value).
+   */
+  isUnbounded(): boolean {
+    return this.#max === undefined;
+  }
+
+  /**
+   * Returns a string representation of the interval using standard range notation.
+   *
+   * @returns The range notation string
+   *
+   * @example
+   * ```typescript
+   * new Interval(3, 3).rangeNotation()  // "{3}"
+   * new Interval(1, 5).rangeNotation()  // "{1,5}"
+   * new Interval(2).rangeNotation()     // "{2,}"
+   * ```
+   */
+  rangeNotation(): string {
+    if (this.#max !== undefined && this.#min === this.#max) {
+      return `{${this.#min}}`;
+    }
+    if (this.#max !== undefined) {
+      return `{${this.#min},${this.#max}}`;
+    }
+    return `{${this.#min},}`;
+  }
+
+  /**
+   * Returns a string representation of the interval using shorthand notation
+   * where applicable.
+   *
+   * @returns The shorthand notation string
+   *
+   * @example
+   * ```typescript
+   * new Interval(0, 1).shorthandNotation()  // "?"
+   * new Interval(0).shorthandNotation()     // "*"
+   * new Interval(1).shorthandNotation()     // "+"
+   * new Interval(1, 5).shorthandNotation()  // "{1,5}"
+   * ```
+   */
+  shorthandNotation(): string {
+    // Check for optional (?)
+    if (this.#min === 0 && this.#max === 1) {
+      return "?";
+    }
+    // Check for single value
+    if (this.#max !== undefined && this.#min === this.#max) {
+      return `{${this.#min}}`;
+    }
+    // Check for bounded range
+    if (this.#max !== undefined) {
+      return `{${this.#min},${this.#max}}`;
+    }
+    // Check for zero or more (*)
+    if (this.#min === 0) {
+      return "*";
+    }
+    // Check for one or more (+)
+    if (this.#min === 1) {
+      return "+";
+    }
+    // General unbounded case
+    return `{${this.#min},}`;
+  }
+
+  /**
+   * Returns a string representation using range notation.
+   */
+  toString(): string {
+    return this.rangeNotation();
+  }
+
+  /**
+   * Checks equality with another Interval.
+   */
+  equals(other: Interval): boolean {
+    return this.#min === other.#min && this.#max === other.#max;
+  }
+}
+
+/**
+ * Default interval is exactly 1 occurrence.
+ */
+export const DEFAULT_INTERVAL = Interval.exactly(1);

package/src/parse/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Parsing module for dCBOR patterns.
+ *
+ * This module provides the parser for dCBOR pattern expressions,
+ * converting string representations into Pattern AST nodes.
+ *
+ * @module parse
+ */
+
+export * from "./token";
+export * from "./value";
+export * from "./structure";
+export * from "./meta";
+export * from "./parse-registry";
+
+import type { Pattern } from "../pattern";
+import type { Result } from "../error";
+import { Ok, Err } from "../error";
+import { Lexer } from "./token";
+import { parseOr } from "./meta/or-parser";
+import { setParseOrFn } from "./parse-registry";
+
+// Register the parseOr function with the parse registry
+// This breaks the circular dependency between meta and structure parsers
+setParseOrFn(parseOr);
+
+/**
+ * Parses a complete dCBOR pattern expression.
+ *
+ * @param input - The pattern string to parse
+ * @returns A Result containing the parsed Pattern or an error
+ *
+ * @example
+ * ```typescript
+ * const result = parse("number");
+ * if (result.ok) {
+ *   console.log(result.value);
+ * }
+ * ```
+ */
+export const parse = (input: string): Result<Pattern> => {
+  const result = parsePartial(input);
+  if (!result.ok) {
+    return result;
+  }
+
+  const [pattern, consumed] = result.value;
+  if (consumed < input.length) {
+    // There's extra data after the pattern
+    return Err({
+      type: "ExtraData",
+      span: { start: consumed, end: input.length },
+    });
+  }
+
+  return Ok(pattern);
+};
+
+/**
+ * Parses a partial dCBOR pattern expression, returning the parsed pattern
+ * and the number of characters consumed.
+ *
+ * Unlike `parse()`, this function succeeds even if additional characters
+ * follow the first pattern. The returned index points to the first unparsed
+ * character after the pattern.
+ *
+ * @param input - The pattern string to parse
+ * @returns A Result containing a tuple of [Pattern, consumedLength] or an error
+ *
+ * @example
+ * ```typescript
+ * const result = parsePartial("true rest");
+ * if (result.ok) {
+ *   const [pattern, consumed] = result.value;
+ *   console.log(consumed); // 4 or 5 (includes whitespace)
+ * }
+ * ```
+ */
+export const parsePartial = (input: string): Result<[Pattern, number]> => {
+  if (input.trim().length === 0) {
+    return Err({ type: "EmptyInput" });
+  }
+
+  const lexer = new Lexer(input);
+  const patternResult = parseOr(lexer);
+
+  if (!patternResult.ok) {
+    return patternResult;
+  }
+
+  // Calculate consumed bytes
+  const consumed = lexer.position();
+
+  return Ok([patternResult.value, consumed]);
+};

package/src/parse/meta/and-parser.ts

@@ -0,0 +1,47 @@
+/**
+ * AND pattern parser.
+ *
+ * @module parse/meta/and-parser
+ */
+
+import type { Lexer } from "../token";
+import type { Pattern } from "../../pattern";
+import type { Result } from "../../error";
+import { Ok } from "../../error";
+import { and } from "../../pattern";
+import { parseNot } from "./not-parser";
+
+/**
+ * Parse an AND pattern.
+ */
+export const parseAnd = (lexer: Lexer): Result<Pattern> => {
+  const patterns: Pattern[] = [];
+  const first = parseNot(lexer);
+  if (!first.ok) {
+    return first;
+  }
+  patterns.push(first.value);
+
+  while (true) {
+    const peeked = lexer.peekToken();
+    if (peeked?.ok !== true) {
+      break;
+    }
+    if (peeked.value.type !== "And") {
+      break;
+    }
+    lexer.next(); // consume the AND token
+
+    const next = parseNot(lexer);
+    if (!next.ok) {
+      return next;
+    }
+    patterns.push(next.value);
+  }
+
+  if (patterns.length === 1) {
+    return Ok(patterns[0]);
+  }
+
+  return Ok(and(...patterns));
+};