CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build and Test Commands

bundle install              # Install dependencies
bundle exec rake test       # Run tests
bundle exec rake rubocop    # Run linter
bundle exec rake            # Run both tests and linter

# Run a single test file
bundle exec ruby -Ilib:test test/paragraph_test.rb

# Run a specific test by name
bundle exec ruby -Ilib:test test/paragraph_test.rb -n test_paragraph_with_text

Architecture

Ezdoc is a Ruby gem for creating .docx files using a DSL. The gem generates valid Office Open XML (OOXML) documents.

Core Components

Document (lib/ezdoc/document.rb): Entry point via Document.create. Includes the Builder module and maintains a collection of nodes.
Builder (lib/ezdoc/builder.rb): DSL methods (p, text, h1-h6, b, i, u, ul, ol, li, table, tr, td, image). Uses a format stack for nested formatting and target tracking for content placement.
Nodes (lib/ezdoc/nodes/): Document element representations (Paragraph, Run, Image, List, ListItem, Table, TableRow, TableCell). All inherit from Nodes::Base.
Style (lib/ezdoc/style.rb): Style definitions with text properties (bold, italic, color, size, font) and paragraph properties (align, indent, spacing).
Package (lib/ezdoc/package.rb): Assembles the docx ZIP structure using rubyzip. Coordinates XML generation.
XML generators (lib/ezdoc/xml/): Generate OOXML-compliant XML:
- DocumentXml: Main content with paragraphs, lists, tables, images
- StylesXml: styles.xml with built-in and custom styles
- ContentTypes: [Content_Types].xml
- Relationships: .rels files
- Numbering: numbering.xml for lists
ImageDimensions (lib/ezdoc/image_dimensions.rb): Uses fastimage gem to read image dimensions for EMU calculations.

Data Flow

User calls DSL methods on Document
Builder creates Node objects, pushed to Document's @nodes array
On save, Package creates ZIP with XML generators producing each required file
XML generators use Nokogiri to build OOXML with proper namespaces

Testing

Tests use Minitest. EzdocTestHelpers module provides helpers that create temp documents and extract XML for assertions.

2.3 KiB Raw Permalink Blame History