Kaukus/Notare
3
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add support for images #2

Merged
mathias234 merged 2 commits from feature/images into main 2025-12-02 10:45:52 +00:00
Conversation 0 Commits 2 Files Changed 16 +529 -6
16 changed files with 529 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
CLAUDE.md Normal file
View File

@@ -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.

48
README.md
View File

@@ -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

1
ezdoc.gemspec
View File

@@ -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"

2
lib/ezdoc.rb
View File

@@ -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"

15
lib/ezdoc/builder.rb
View File

@@ -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

22
lib/ezdoc/document.rb
View File

@@ -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

55
lib/ezdoc/image_dimensions.rb Normal file
View File

@@ -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

38
lib/ezdoc/nodes/image.rb Normal file
View File

@@ -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

14
lib/ezdoc/package.rb
View File

@@ -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

18
lib/ezdoc/xml/content_types.rb
View File

@@ -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

53
lib/ezdoc/xml/document_xml.rb
View File

@@ -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

12
lib/ezdoc/xml/relationships.rb
View File

@@ -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

BIN
test/fixtures/test.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 8.3 KiB

BIN
test/fixtures/test.png vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 71 KiB

204
test/image_test.rb Normal file
View File

@@ -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, "<w:drawing>"
assert_includes xml, "<wp:inline"
assert_includes xml, "<pic:pic>"
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, "<w:tc>"
assert_includes xml, "<w:drawing>"
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, "<w:numPr>"
assert_includes xml, "<w:drawing>"
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, "<w:drawing>"
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

4
test/test_helper.rb
View File

@@ -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