diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a91a8fb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Build and Test Commands + +```bash +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`, `b`, `i`, `u`, `ul`, `ol`, `li`, `table`, `tr`, `td`). Uses a format stack for nested formatting and target tracking for content placement. + +- **Nodes** (`lib/ezdoc/nodes/`): Document element representations (Paragraph, Run, List, ListItem, Table, TableRow, TableCell). All inherit from `Nodes::Base`. + +- **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 + - `ContentTypes`: [Content_Types].xml + - `Relationships`: .rels files + - `Numbering`: numbering.xml for lists + +### Data Flow + +1. User calls DSL methods on Document +2. Builder creates Node objects, pushed to Document's `@nodes` array +3. On save, Package creates ZIP with XML generators producing each required file +4. 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. diff --git a/README.md b/README.md index 8c877f2..f5be899 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,53 @@ Ezdoc::Document.create("output.docx") do |doc| end ``` +### Images + +Images can be added to paragraphs, table cells, and list items. Supports PNG and JPEG formats. + +```ruby +Ezdoc::Document.create("output.docx") do |doc| + # Simple image (uses native dimensions) + doc.p do + doc.image "photo.png" + end + + # Image with explicit dimensions (inches, cm, or pixels) + doc.p do + doc.image "logo.png", width: "2in", height: "1in" + end + + # Specify only width (height auto-calculated to maintain aspect ratio) + doc.p do + doc.image "banner.jpg", width: "5cm" + end + + # Image with text in the same paragraph + doc.p do + doc.text "Company Logo: " + doc.image "logo.png", width: "0.5in", height: "0.5in" + end + + # Image in a table cell + doc.table do + doc.tr do + doc.td "Product" + doc.td do + doc.image "product.jpg", width: "1in", height: "1in" + end + end + end + + # Image in a list item + doc.ul do + doc.li do + doc.image "icon.png", width: "16px", height: "16px" + doc.text " List item with icon" + end + end +end +``` + ### Complete Example ```ruby @@ -169,6 +216,7 @@ end | `tr { }` | Table row | | `td(text)` | Table cell with text | | `td { }` | Table cell with block content | +| `image(path, width:, height:)` | Insert image (PNG/JPEG). Dimensions: `"2in"`, `"5cm"`, `"100px"`, or integer pixels | ## Development diff --git a/ezdoc.gemspec b/ezdoc.gemspec index ed2dd56..77c4f8c 100644 --- a/ezdoc.gemspec +++ b/ezdoc.gemspec @@ -15,6 +15,7 @@ Gem::Specification.new do |spec| spec.files = Dir.glob("{lib}/**/*") + %w[README.md LICENSE.txt] spec.require_paths = ["lib"] + spec.add_dependency "fastimage", "~> 2.4" spec.add_dependency "nokogiri", "~> 1.18" spec.add_dependency "rubyzip", "~> 2.3" diff --git a/lib/ezdoc.rb b/lib/ezdoc.rb index 129deb6..4ec96f5 100644 --- a/lib/ezdoc.rb +++ b/lib/ezdoc.rb @@ -5,12 +5,14 @@ require "nokogiri" require_relative "ezdoc/version" require_relative "ezdoc/nodes/base" require_relative "ezdoc/nodes/run" +require_relative "ezdoc/nodes/image" require_relative "ezdoc/nodes/paragraph" require_relative "ezdoc/nodes/list" require_relative "ezdoc/nodes/list_item" require_relative "ezdoc/nodes/table" require_relative "ezdoc/nodes/table_row" require_relative "ezdoc/nodes/table_cell" +require_relative "ezdoc/image_dimensions" require_relative "ezdoc/xml/content_types" require_relative "ezdoc/xml/relationships" require_relative "ezdoc/xml/document_xml" diff --git a/lib/ezdoc/builder.rb b/lib/ezdoc/builder.rb index d3a8aea..4c81506 100644 --- a/lib/ezdoc/builder.rb +++ b/lib/ezdoc/builder.rb @@ -16,6 +16,12 @@ module Ezdoc @current_target.add_run(Nodes::Run.new(value, **current_formatting)) end + def image(path, width: nil, height: nil) + validate_image_path!(path) + img = register_image(path, width: width, height: height) + @current_target.add_run(img) + end + def b(&block) with_format(:bold, &block) end @@ -110,5 +116,14 @@ module Ezdoc underline: @format_stack.include?(:underline) } end + + def validate_image_path!(path) + raise ArgumentError, "Image file not found: #{path}" unless File.exist?(path) + + ext = File.extname(path).downcase + return if %w[.png .jpg .jpeg].include?(ext) + + raise ArgumentError, "Unsupported image format: #{ext}. Use PNG or JPEG." + end end end diff --git a/lib/ezdoc/document.rb b/lib/ezdoc/document.rb index 6fffd1b..d6a3dda 100644 --- a/lib/ezdoc/document.rb +++ b/lib/ezdoc/document.rb @@ -21,6 +21,7 @@ module Ezdoc @current_table = nil @current_row = nil @num_id_counter = 0 + @images = {} end def save(path) @@ -30,5 +31,26 @@ module Ezdoc def lists @nodes.select { |n| n.is_a?(Nodes::List) } end + + def images + @images.values + end + + def register_image(path, width: nil, height: nil) + return @images[path] if @images[path] + + rid = next_image_rid + width_emu, height_emu = ImageDimensions.calculate_emus(path, width: width, height: height) + image = Nodes::Image.new(path, rid: rid, width_emu: width_emu, height_emu: height_emu) + @images[path] = image + image + end + + private + + def next_image_rid + base = lists.any? ? 2 : 1 + "rId#{base + @images.size}" + end end end diff --git a/lib/ezdoc/image_dimensions.rb b/lib/ezdoc/image_dimensions.rb new file mode 100644 index 0000000..42faae7 --- /dev/null +++ b/lib/ezdoc/image_dimensions.rb @@ -0,0 +1,55 @@ +# frozen_string_literal: true + +require "fastimage" + +module Ezdoc + class ImageDimensions + EMUS_PER_INCH = 914_400 + DEFAULT_DPI = 96 + + def self.read(path) + FastImage.size(path) || raise(ArgumentError, "Could not read image dimensions: #{path}") + end + + def self.calculate_emus(path, width: nil, height: nil) + native_width, native_height = read(path) + calculate_dimensions_emu(native_width, native_height, width, height) + end + + def self.calculate_dimensions_emu(native_width, native_height, width, height) + if width && height + [parse_dimension(width), parse_dimension(height)] + elsif width + w = parse_dimension(width) + ratio = native_height.to_f / native_width + [w, (w * ratio).to_i] + elsif height + h = parse_dimension(height) + ratio = native_width.to_f / native_height + [(h * ratio).to_i, h] + else + pixels_to_emus(native_width, native_height) + end + end + + def self.parse_dimension(value) + case value + when Integer + pixels_to_emus(value, 0).first + when /\A(\d+(?:\.\d+)?)\s*in\z/i + (::Regexp.last_match(1).to_f * EMUS_PER_INCH).to_i + when /\A(\d+(?:\.\d+)?)\s*cm\z/i + (::Regexp.last_match(1).to_f * 360_000).to_i + when /\A(\d+(?:\.\d+)?)\s*px\z/i, /\A(\d+)\z/ + pixels_to_emus(::Regexp.last_match(1).to_i, 0).first + else + raise ArgumentError, "Invalid dimension format: #{value}. Use '2in', '5cm', '100px', or integer pixels." + end + end + + def self.pixels_to_emus(width_px, height_px) + emu_per_pixel = EMUS_PER_INCH / DEFAULT_DPI + [(width_px * emu_per_pixel).to_i, (height_px * emu_per_pixel).to_i] + end + end +end diff --git a/lib/ezdoc/nodes/image.rb b/lib/ezdoc/nodes/image.rb new file mode 100644 index 0000000..78ca2e7 --- /dev/null +++ b/lib/ezdoc/nodes/image.rb @@ -0,0 +1,38 @@ +# frozen_string_literal: true + +module Ezdoc + module Nodes + class Image < Base + attr_reader :path, :width_emu, :height_emu, :rid, :filename + + EMUS_PER_INCH = 914_400 + EMUS_PER_CM = 360_000 + DEFAULT_DPI = 96 + + def initialize(path, rid:, width_emu:, height_emu:) + super() + @path = path + @rid = rid + @width_emu = width_emu + @height_emu = height_emu + @filename = "image#{rid.delete_prefix("rId")}.#{extension}" + end + + def extension + case File.extname(@path).downcase + when ".png" then "png" + when ".jpg", ".jpeg" then "jpeg" + else raise ArgumentError, "Unsupported image format: #{File.extname(@path)}" + end + end + + def content_type + extension == "png" ? "image/png" : "image/jpeg" + end + + def doc_pr_id + rid.delete_prefix("rId").to_i + end + end + end +end diff --git a/lib/ezdoc/package.rb b/lib/ezdoc/package.rb index f5af348..cef8547 100644 --- a/lib/ezdoc/package.rb +++ b/lib/ezdoc/package.rb @@ -16,6 +16,12 @@ module Ezdoc zipfile.get_output_stream("word/document.xml") { |f| f.write(document_xml) } zipfile.get_output_stream("word/numbering.xml") { |f| f.write(numbering_xml) } if lists? + + images.each do |image| + zipfile.get_output_stream("word/media/#{image.filename}") do |f| + f.write(File.binread(image.path)) + end + end end end @@ -25,8 +31,12 @@ module Ezdoc @document.lists.any? end + def images + @document.images + end + def content_types_xml - Xml::ContentTypes.new(has_numbering: lists?).to_xml + Xml::ContentTypes.new(has_numbering: lists?, images: images).to_xml end def relationships_xml @@ -34,7 +44,7 @@ module Ezdoc end def document_relationships_xml - Xml::DocumentRelationships.new(has_numbering: lists?).to_xml + Xml::DocumentRelationships.new(has_numbering: lists?, images: images).to_xml end def document_xml diff --git a/lib/ezdoc/xml/content_types.rb b/lib/ezdoc/xml/content_types.rb index d7e429c..f04fa34 100644 --- a/lib/ezdoc/xml/content_types.rb +++ b/lib/ezdoc/xml/content_types.rb @@ -5,8 +5,9 @@ module Ezdoc class ContentTypes NAMESPACE = "http://schemas.openxmlformats.org/package/2006/content-types" - def initialize(has_numbering: false) + def initialize(has_numbering: false, images: []) @has_numbering = has_numbering + @images = images end def to_xml @@ -14,6 +15,11 @@ module Ezdoc xml.Types(xmlns: NAMESPACE) do xml.Default(Extension: "rels", ContentType: "application/vnd.openxmlformats-package.relationships+xml") xml.Default(Extension: "xml", ContentType: "application/xml") + + image_extensions.each do |ext, content_type| + xml.Default(Extension: ext, ContentType: content_type) + end + xml.Override( PartName: "/word/document.xml", ContentType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml" @@ -28,6 +34,16 @@ module Ezdoc end builder.to_xml end + + private + + def image_extensions + extensions = {} + @images.each do |image| + extensions[image.extension] ||= image.content_type + end + extensions + end end end end diff --git a/lib/ezdoc/xml/document_xml.rb b/lib/ezdoc/xml/document_xml.rb index cb053dc..f67e2b5 100644 --- a/lib/ezdoc/xml/document_xml.rb +++ b/lib/ezdoc/xml/document_xml.rb @@ -5,7 +5,10 @@ module Ezdoc class DocumentXml NAMESPACES = { "xmlns:w" => "http://schemas.openxmlformats.org/wordprocessingml/2006/main", - "xmlns:r" => "http://schemas.openxmlformats.org/officeDocument/2006/relationships" + "xmlns:r" => "http://schemas.openxmlformats.org/officeDocument/2006/relationships", + "xmlns:wp" => "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing", + "xmlns:a" => "http://schemas.openxmlformats.org/drawingml/2006/main", + "xmlns:pic" => "http://schemas.openxmlformats.org/drawingml/2006/picture" }.freeze def initialize(nodes) @@ -60,6 +63,15 @@ module Ezdoc end def render_run(xml, run) + case run + when Nodes::Image + render_image(xml, run) + when Nodes::Run + render_text_run(xml, run) + end + end + + def render_text_run(xml, run) xml["w"].r do if run.bold || run.italic || run.underline xml["w"].rPr do @@ -72,6 +84,45 @@ module Ezdoc end end + def render_image(xml, image) + xml["w"].r do + xml["w"].drawing do + xml["wp"].inline(distT: "0", distB: "0", distL: "0", distR: "0") do + xml["wp"].extent(cx: image.width_emu.to_s, cy: image.height_emu.to_s) + xml["wp"].docPr(id: image.doc_pr_id.to_s, name: image.filename) + xml["wp"].cNvGraphicFramePr do + xml["a"].graphicFrameLocks(noChangeAspect: "1") + end + xml["a"].graphic do + xml["a"].graphicData(uri: "http://schemas.openxmlformats.org/drawingml/2006/picture") do + xml["pic"].pic do + xml["pic"].nvPicPr do + xml["pic"].cNvPr(id: "0", name: image.filename) + xml["pic"].cNvPicPr + end + xml["pic"].blipFill do + xml["a"].blip("r:embed" => image.rid) + xml["a"].stretch do + xml["a"].fillRect + end + end + xml["pic"].spPr do + xml["a"].xfrm do + xml["a"].off(x: "0", y: "0") + xml["a"].ext(cx: image.width_emu.to_s, cy: image.height_emu.to_s) + end + xml["a"].prstGeom(prst: "rect") do + xml["a"].avLst + end + end + end + end + end + end + end + end + end + def render_table(xml, table) xml["w"].tbl do xml["w"].tblPr do diff --git a/lib/ezdoc/xml/relationships.rb b/lib/ezdoc/xml/relationships.rb index 521cb1f..68b5dfa 100644 --- a/lib/ezdoc/xml/relationships.rb +++ b/lib/ezdoc/xml/relationships.rb @@ -21,9 +21,11 @@ module Ezdoc class DocumentRelationships NAMESPACE = "http://schemas.openxmlformats.org/package/2006/relationships" + IMAGE_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" - def initialize(has_numbering: false) + def initialize(has_numbering: false, images: []) @has_numbering = has_numbering + @images = images end def to_xml @@ -36,6 +38,14 @@ module Ezdoc Target: "numbering.xml" ) end + + @images.each do |image| + xml.Relationship( + Id: image.rid, + Type: IMAGE_TYPE, + Target: "media/#{image.filename}" + ) + end end end builder.to_xml diff --git a/test/fixtures/test.jpg b/test/fixtures/test.jpg new file mode 100644 index 0000000..e1d578e Binary files /dev/null and b/test/fixtures/test.jpg differ diff --git a/test/fixtures/test.png b/test/fixtures/test.png new file mode 100644 index 0000000..a4a812f Binary files /dev/null and b/test/fixtures/test.png differ diff --git a/test/image_test.rb b/test/image_test.rb new file mode 100644 index 0000000..9ca7906 --- /dev/null +++ b/test/image_test.rb @@ -0,0 +1,204 @@ +# frozen_string_literal: true + +require "test_helper" + +class ImageTest < Minitest::Test + include EzdocTestHelpers + + def setup + @png_path = File.expand_path("fixtures/test.png", __dir__) + @jpeg_path = File.expand_path("fixtures/test.jpg", __dir__) + end + + def test_image_in_paragraph + xml = create_doc_and_read_xml do |doc| + doc.p do + doc.image @png_path + end + end + + assert_includes xml, "" + assert_includes xml, "" + assert_includes xml, 'r:embed="rId' + end + + def test_image_in_table_cell + xml = create_doc_and_read_xml do |doc| + doc.table do + doc.tr do + doc.td do + doc.image @png_path + end + end + end + end + + assert_includes xml, "" + assert_includes xml, "" + end + + def test_image_in_list_item + xml = create_doc_and_read_xml do |doc| + doc.ul do + doc.li do + doc.image @png_path + end + end + end + + assert_includes xml, "" + assert_includes xml, "" + end + + def test_image_with_explicit_dimensions_inches + xml = create_doc_and_read_xml do |doc| + doc.p do + doc.image @png_path, width: "2in", height: "1in" + end + end + + # 2 inches = 1828800 EMUs + assert_includes xml, 'cx="1828800"' + # 1 inch = 914400 EMUs + assert_includes xml, 'cy="914400"' + end + + def test_image_with_explicit_dimensions_cm + xml = create_doc_and_read_xml do |doc| + doc.p do + doc.image @png_path, width: "5cm", height: "3cm" + end + end + + # 5 cm = 1800000 EMUs + assert_includes xml, 'cx="1800000"' + # 3 cm = 1080000 EMUs + assert_includes xml, 'cy="1080000"' + end + + def test_image_file_embedded_in_docx + files = nil + Tempfile.create(["test", ".docx"]) do |file| + Ezdoc::Document.create(file.path) do |doc| + doc.p { doc.image @png_path } + end + Zip::File.open(file.path) do |zip| + files = zip.entries.map(&:name) + end + end + + assert(files.any? { |f| f.start_with?("word/media/image") }) + end + + def test_image_relationships_generated + xml_files = create_doc_and_read_all_xml do |doc| + doc.p { doc.image @png_path } + end + + rels = xml_files["word/_rels/document.xml.rels"] + assert_includes rels, "relationships/image" + assert_includes rels, "media/image" + end + + def test_image_content_type_registered + xml_files = create_doc_and_read_all_xml do |doc| + doc.p { doc.image @png_path } + end + + content_types = xml_files["[Content_Types].xml"] + assert_includes content_types, 'Extension="png"' + assert_includes content_types, "image/png" + end + + def test_jpeg_content_type_registered + xml_files = create_doc_and_read_all_xml do |doc| + doc.p { doc.image @jpeg_path } + end + + content_types = xml_files["[Content_Types].xml"] + assert_includes content_types, 'Extension="jpeg"' + assert_includes content_types, "image/jpeg" + end + + def test_invalid_image_path_raises_error + assert_raises(ArgumentError) do + Tempfile.create(["test", ".docx"]) do |file| + Ezdoc::Document.create(file.path) do |doc| + doc.p { doc.image "/nonexistent/image.png" } + end + end + end + end + + def test_unsupported_format_raises_error + Tempfile.create(["test", ".gif"]) do |gif_file| + gif_file.write("GIF89a") + gif_file.flush + + assert_raises(ArgumentError) do + Tempfile.create(["test", ".docx"]) do |docx_file| + Ezdoc::Document.create(docx_file.path) do |doc| + doc.p { doc.image gif_file.path } + end + end + end + end + end + + def test_same_image_used_multiple_times_deduplication + files = nil + Tempfile.create(["test", ".docx"]) do |file| + Ezdoc::Document.create(file.path) do |doc| + doc.p { doc.image @png_path } + doc.p { doc.image @png_path } + doc.p { doc.image @png_path } + end + Zip::File.open(file.path) do |zip| + files = zip.entries.map(&:name).select { |f| f.start_with?("word/media/") } + end + end + + # Should only have one image file despite being used 3 times + assert_equal 1, files.size + end + + def test_multiple_different_images + files = nil + Tempfile.create(["test", ".docx"]) do |file| + Ezdoc::Document.create(file.path) do |doc| + doc.p { doc.image @png_path } + doc.p { doc.image @jpeg_path } + end + Zip::File.open(file.path) do |zip| + files = zip.entries.map(&:name).select { |f| f.start_with?("word/media/") } + end + end + + assert_equal 2, files.size + end + + def test_image_with_text_in_same_paragraph + xml = create_doc_and_read_xml do |doc| + doc.p do + doc.text "Before image: " + doc.image @png_path + doc.text " After image" + end + end + + assert_includes xml, "Before image: " + assert_includes xml, "After image" + assert_includes xml, "" + end + + def test_image_dimensions_read_from_file + xml = create_doc_and_read_xml do |doc| + doc.p { doc.image @png_path } + end + + # 200x200 pixels at 96 DPI = 200 * (914400 / 96) = 1905000 EMUs + assert_includes xml, 'cx="1905000"' + assert_includes xml, 'cy="1905000"' + end +end diff --git a/test/test_helper.rb b/test/test_helper.rb index 80dd0c0..ff07b73 100644 --- a/test/test_helper.rb +++ b/test/test_helper.rb @@ -26,7 +26,9 @@ module EzdocTestHelpers Ezdoc::Document.create(file.path, &block) Zip::File.open(file.path) do |zip| zip.each do |entry| - result[entry.name] = zip.read(entry.name).force_encoding("UTF-8") if entry.name.end_with?(".xml") + if entry.name.end_with?(".xml") || entry.name.end_with?(".rels") + result[entry.name] = zip.read(entry.name).force_encoding("UTF-8") + end end end end