WoodML Parser (TypeScript)

Reference implementation of the WoodML parser for TypeScript/JavaScript.

Installation

npm install woodml-parser

CLI Usage

After installation, the woodml command is available:

# Parse and display project info
woodml parse project.woodml

# Generate a cut list
woodml cutlist project.woodml -f table

# Validate a file
woodml validate project.woodml

# Show project information
woodml info project.woodml -f json

# Generate SVG diagram
woodml diagram project.woodml -o diagram.svg

# Generate exploded view with blueprint colors
woodml diagram project.woodml -t exploded -c blueprint -o exploded.svg

# Generate cut list layout diagram
woodml diagram project.woodml -t cutlist -o cutlist.svg

CLI Options

• -o, --output <file> - Write output to file instead of stdout
• -f, --format <fmt> - Output format: json, text, table (default: text)
• -v, --verbose - Show detailed output
• -h, --help - Show help message

Diagram Options

• -t, --type <type> - Diagram type: parts, exploded, cutlist (default: parts)
• -c, --color <scheme> - Color scheme: default, blueprint, monochrome
• -w, --width <px> - SVG width in pixels (default: 800)
• --height <px> - SVG height in pixels (default: 600)

Library Usage

import {
  parse,
  parseAndResolve,
  validateDocument,
  generateCutList,
  formatCutList,
  calculateBoardFeet
} from 'woodml-parser';

// Parse a WoodML file
const doc = parse(woodmlSource);

// Parse and resolve all variables
const resolved = parseAndResolve(woodmlSource);

// Validate document
const errors = validateDocument(doc);

// Generate cut list
const cutList = generateCutList(resolved);
console.log(formatCutList(cutList));

// Calculate total board feet
const boardFeet = calculateBoardFeet(resolved);

Working with Dimensions

import {
  parseDimension,
  toInches,
  toMillimeters,
  formatImperial,
  formatMetric
} from 'woodml-parser';

// Parse various dimension formats
const dim1 = parseDimension('24"');        // 24 inches
const dim2 = parseDimension('3-1/2"');     // 3.5 inches
const dim3 = parseDimension("6'4\"");      // 76 inches
const dim4 = parseDimension('610mm');      // 610 millimeters
const dim5 = parseDimension('4/4');        // 1 inch (quarter notation)

// Convert between units
const inches = toInches(dim4);  // 24.0157...
const mm = toMillimeters(dim1); // 609.6

// Format for display
console.log(formatImperial(dim1)); // "2'"
console.log(formatMetric(dim4));   // "61cm"

Working with Formulas

import { createContext, evaluateFormula, resolveFormulas } from 'woodml-parser';

// Create a context with variables
const ctx = createContext({
  width: '24"',
  depth: '18"',
  height: '30"',
});

// Evaluate formulas
const area = evaluateFormula('$width * $depth', ctx);
const diagonal = evaluateFormula('diagonal($width, $depth)', ctx);

// Available functions:
// Math: min, max, abs, sqrt, round, floor, ceil, sin, cos, tan
// Woodworking: board_feet, square_feet, miter_angle, diagonal, golden_ratio

API Reference

Parser Functions

• parse(source: string): WoodMLDocument - Parse WoodML source
• parseAndResolve(source: string): ResolvedDocument - Parse and resolve variables
• validateDocument(doc: WoodMLDocument): ValidationError[] - Validate document

Cut List Functions

• generateCutList(doc: ResolvedDocument): CutListItem[] - Generate cut list
• formatCutList(items: CutListItem[]): string - Format as table
• calculateBoardFeet(doc: ResolvedDocument): number - Calculate total board feet

Unit Functions

• parseDimension(input: string): Dimension - Parse dimension string
• toInches(dim: Dimension): number - Convert to inches
• toMillimeters(dim: Dimension): number - Convert to millimeters
• formatImperial(dim: Dimension): string - Format as imperial
• formatMetric(dim: Dimension): string - Format as metric

SVG Generation

• generateSVG(doc, type?, options?) - Generate SVG diagram
• generatePartSVG(part, options?) - Generate SVG for single part
• SVGGenerator - Class for fine-grained control

import { parseAndResolve, generateSVG, SVGGenerator } from 'woodml-parser';

const doc = parseAndResolve(source);

// Quick generation
const svg = generateSVG(doc, 'parts', { colorScheme: 'blueprint' });

// Using the generator class
const generator = new SVGGenerator({
  width: 1200,
  height: 800,
  showDimensions: true,
  showGrain: true,
  colorScheme: 'default',
});

const partsDiagram = generator.generatePartsDiagram(doc);
const explodedView = generator.generateExplodedView(doc);
const cutlistLayout = generator.generateCutListDiagram(doc, 48, 96);

License

MIT