odf-report 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14183fe9ba54b5f98cd72cd48aa1277aa9d5b576c7980ae2bbfeef2346c9c49d
-  data.tar.gz: dcf77b2934897f3b490effdd62a1ee1effc2d13898523249b81b4be62be1eea9
+  metadata.gz: e779540093e247d2640705b1e099c7c651e2cef975468fa0970f69110223fa05
+  data.tar.gz: a14b575ef72783bd3f735db7824a8e2aeea122161d07535fa1ab632f5e98ad7e
 SHA512:
-  metadata.gz: 7eb665c1fe1f414dac1b5e3ef3714b398d207125b00589573f2e2e9a2d4632355f26bf968fe3eec53c7bdcdff92c3fe24f5216fe18a1e160ddd4c8947804390a
-  data.tar.gz: 237f77a79aa11754aff00d0973c696dc9f62a8ce65b6b57c1c101293b632ee0399025f13b04f9649feaeda1d63310b58ac83ac67d5565cc602c9b2bcd5be127c
+  metadata.gz: 050a25739018f420a6985a30633c889a9e9ac599b3eed318034690d1533e9d4208d5e48e3160fcd1375ea7c9677a13519f1036f7366ceca518d062c8cb2e7ae5
+  data.tar.gz: 6116ecfce938d03174b814d9ea27b72f0462c0cb8a19e105dc49440033b163e1365a6cad6f2bd292459ba409db60e1013d4b78d47486dcb60fd11f333ff781bb

data/CHANGELOG.md

@@ -18,10 +18,38 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 - None
 
+## 0.9.0
+
+### Refactored
+
+- Extracted shared DSL (`add_field`, `add_text`, `add_image`, `add_table`, `add_section`) into `Composable` module, included by both `Report` and `Nestable`
+- Unified `DataSource` to use lazy evaluation — `set_source` stores the record, `value` decides extraction strategy at read time
+- Broke up `Report#generate` into focused private methods (`replace_placeholders!`, `include_images`)
+- Simplified `Table` internals: renamed methods (`get_next_row` → `next_row`), removed redundant code
+- Cleaned up `Image`: single XPath lookup, `image_href` helper, removed unused parameters
+- Cleaned up `Template`: cached ZIP entries, renamed methods for clarity
+- Cleaned up `Text`: removed `attr_accessor`, simplified `find_text_node`
+- Cleaned up `Field`: removed dead code in `to_placeholder`
+- Cleaned up `Parser::Default`: tightened visibility, simplified `check_style`
+- Lazy-initialized all replacer arrays (no more `init_replacers`)
+
+### Testing
+
+- Added RSpec specs for nested tables, sub-sections, table headers, fields inside text, and rich text in sections/tables (19 → 38 examples)
+- Organized specs and templates into grouped subfolders (`tables/`, `sections/`, `texts/`, `images/`)
+- Decoupled spec templates from legacy test directory
+
+## 0.8.1
+
+### Fixed
+- \<br\> replacement in default text parser #130
+
 ## 0.8.0
 
-### Dependencies
+### Fixed
+- Use Nokogiri HTML5 parser for text nodes parsing #129
 
+### Dependencies
 - nokogiri >= 1.12.0 (was >= 1.10.0)
 
 ## 0.7.3

data/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Ruby gem that generates `.odt` (OpenDocument Text) files by taking a template and replacing placeholders with data. ODF files are ZIP archives containing XML; the gem uses `rubyzip` for ZIP manipulation and `nokogiri` for XML parsing.
+
+## Common Commands
+
+```bash
+bundle install              # Install dependencies
+bundle exec rspec           # Run RSpec test suite
+bundle exec rake test       # Run legacy test suite (test/ directory)
+bundle exec rspec spec/fields_spec.rb                        # Run single spec file
+bundle exec rspec spec/fields_spec.rb -e "some description"  # Run specific example
+standardrb                  # Lint check
+standardrb --fix            # Auto-fix lint issues
+bundle exec rake open       # Open generated test result .odt files
+```
+
+## Architecture
+
+**Processing pipeline:** `Report` collects replacement definitions via its block DSL (`add_field`, `add_table`, `add_section`, `add_image`, `add_text`). On `generate`, `Template` extracts `content.xml` and `styles.xml` from the ZIP, then each replacer modifies the Nokogiri XML in-place. Order: sections → tables → texts → fields → images. The result is written back to a new ZIP.
+
+**Key classes (all under `ODFReport` module in `lib/odf-report/`):**
+
+- `Report` — Main entry point and public API. Includes `Composable` for the DSL. `generate` delegates to `replace_placeholders!` (XML substitution) and `include_images` (ZIP + manifest updates).
+- `Template` — Handles .odt file I/O (ZIP read/write). Accepts file path or `io:` buffer. Caches the ZIP handle via `template_entries`.
+- `Composable` — Module included by both `Report` and `Nestable`. Provides `add_field`, `add_text`, `add_image`, `add_table`, `add_section`, `all_images`, and lazy-initialized arrays (`fields`, `texts`, `tables`, `sections`, `images`).
+- `Nestable` — Base class for `Table` and `Section`. Includes `Composable`. Adds `@name`, `@data_source`, `set_source`, `replace_with!`, and `wrap_with_ns`.
+- `Table` — Finds a named ODF table, clones its template row for each collection item.
+- `Section` — Finds a named ODF section, clones it for each collection item. Supports nesting.
+- `Field` — Replaces `[PLACEHOLDER]` text nodes in XML. Names are uppercased automatically.
+- `Text` — Extends Field; parses HTML content and inserts ODF paragraphs via `Parser::Default`.
+- `Image` — Replaces placeholder images (matched by draw frame name) with actual image files. Uses `image_href` class method for path building. Updates the ZIP manifest.
+- `DataSource` — Unified value/extraction model. When `set_source` is not called (Report path), `value` returns the literal. When `set_source` is called (Nestable path), `value` extracts from the record using `@field` as a lookup key. Supports hashes, method calls, method chains, methods with arguments, and block transforms.
+- `Parser::Default` — Converts HTML tags (`<br>`, `<p>`, `<strong>`, `<em>`, etc.) to ODF XML elements.
+
+## Testing
+
+Tests use RSpec 3.0. The `Inspector` helper class (defined in `spec/spec_helper.rb`) opens a generated .odt result file and provides:
+- `@data.text` — all text content as a string
+- `@data.xml` — parsed Nokogiri document for XPath queries
+
+Test pattern: `before(:context)` generates an .odt file into `spec/result/`, then `it` blocks verify content using `Inspector`. Legacy tests in `test/` follow a similar pattern with output to `test/result/`.
+
+## Code Style
+
+Uses **standardrb** (Ruby Standard). No custom rubocop config.

data/Gemfile

@@ -1,4 +1,4 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in odf-report.gemspec
 gemspec

data/README.md

@@ -1,7 +1,7 @@
 
 # ODF-REPORT
 
-Gem for generating .odt files by making strings, images, tables and sections replacements in a previously created .odt file.
+Gem for generating .odt files by making string, image, table and section replacements in a previously created .odt file.
 
 ## INSTALL
 
@@ -16,17 +16,18 @@ gem 'odf-report'
 
 First of all, you need a `.odt` file to serve as a template.
 Templates are normal .odt files with `[PLACEHOLDERS]` for *substitutions*.
-There are *four* kinds of substitutions available:
+There are *five* kinds of substitutions available:
 * fields
+* texts
 * tables
 * images
 * sections
 
 #### Fields
 
-It's just an upcase sentence, surrounded by brackets. It will be replaced by the value you supply.
+It's just an uppercase sentence, surrounded by brackets. It will be replaced by the value you supply.
 
-In the folowing example:
+In the following example:
 
 ```ruby
 report = ODFReport::Report.new("Users/john/my_template.odt") do |r|
@@ -35,20 +36,32 @@ report = ODFReport::Report.new("Users/john/my_template.odt") do |r|
 end
 ```
 
-All occurences of `[USER_NAME]` found in the file will be replaced by the value of `@user.name` whereas all `[ADDRESS]` 'es will contains `My new address`
+All occurrences of `[USER_NAME]` found in the file will be replaced by the value of `@user.name` whereas all `[ADDRESS]` 'es will contain `My new address`
 
 
+#### Texts (HTML formatted content)
+
+You can also use `add_text` to replace a placeholder with rich HTML content, which gets converted into ODF-formatted paragraphs with support for inline formatting (`<strong>`, `<em>`, `<u>`), headings, blockquotes, and line breaks.
+
+```ruby
+report = ODFReport::Report.new("my_template.odt") do |r|
+  r.add_text :description, '<p>A paragraph with <strong>bold</strong> and <em>italic</em> text.</p>'
+end
+```
+
+For full details on supported tags, required template styles, and examples, see the [Using add_text with HTML formatting](https://github.com/sandrods/odf-report/wiki/Using-add_text-with-HTML-formatting) wiki page.
+
 #### Tables
 
 To use table placeholders, you should create a Table in your document and give it a name. In OpenOffice, it's just a matter of right-clicking the table you just created, choose `Table Properties...` and type a name in the Name field.
 
 If you inform `header: true`, the first row will be treated as a *header* and left untouched. The remaining rows will be used as the template for the table.
 
-If you have more than one template row, they will be cycled. This is usefull for making zebra tables.
+If you have more than one template row, they will be cycled. This is useful for making zebra tables.
 
-As with **Field placeholders**, just insert a `[FIELD_NAME]` in each cell and let the magic takes place.
+As with **Field placeholders**, just insert a `[FIELD_NAME]` in each cell and let the magic take place.
 
-Taking the folowing example:
+Taking the following example:
 
 ```ruby
 report = ODFReport::Report.new("Users/john/my_template.odt") do |r|
@@ -77,9 +90,9 @@ Any format applied to the fields in the template will be preserved.
 
 #### Sections
 
-Sometimes, you have to repeat a whole chunk of a document, in a structure a lot more complex than a table. You can make a Section in your template and use it in this situations. Creating a Section in OpenOffice is as easy as select menu *Insert* and then *Section...*, and then choose a name for it.
+Sometimes, you have to repeat a whole chunk of a document, in a structure a lot more complex than a table. You can make a Section in your template and use it in these situations. Creating a Section in OpenOffice is as easy as selecting menu *Insert* and then *Section...*, and then choose a name for it.
 
-Sections are lot like Tables, in the sense that you can pass a collection and have that section repeated for each member of the collection. *But*, Sections can have anything inside it, even Tables *and nested Sections*, as long as you provide the appropriate data structure.
+Sections are a lot like Tables, in the sense that you can pass a collection and have that section repeated for each member of the collection. *But*, Sections can have anything inside them, even Tables *and nested Sections*, as long as you provide the appropriate data structure.
 
 Let's see an example:
 
@@ -107,7 +120,7 @@ Let's see an example:
         if invoice.status == 'CLOSED'
           invoice.total
         else
-          invoice.items.sum('product_value')}
+          invoice.items.sum('product_value')
         end
       end
 
@@ -217,15 +230,15 @@ report = ODFReport::Report.new(io: @template.attachment.read) do |r|
 
 **rubyzip**: manipulating the contents of the odt file, since it's actually a zip file.
 **nokogiri**: parsing and manipulating the document xml files.
-**mime-types**: identify images mime types
+**mime-types**: identify image MIME types
 
 #### TROUBLESHOOTING
 
 ##### Placeholder not replaced
 
-If your placeholder is not being replaced, the problem might come from OpenOffice/LibreOffice which, when a placeholder is edited,  add some markup that prevents odf-report from identifying the placeholder.
+If your placeholder is not being replaced, the problem might come from OpenOffice/LibreOffice which, when a placeholder is edited, adds some markup that prevents odf-report from identifying the placeholder.
 
-The golden rule is: NEVER edit the placeholders. If you want to change one, delete it an write again, including the []
+The golden rule is: NEVER edit the placeholders. If you want to change one, delete it and write again, including the []
 Example: if you have, say, [USER] in your template and you want to change to [USERNAME], you should not edit and type NAME.
 Delete the PLACEHOLDER [USER] and type [USERNAME].
 

data/Rakefile

@@ -1,9 +1,9 @@
 require "bundler/gem_tasks"
-require 'launchy'
+require "launchy"
 task :test do
-  Dir.glob('./test/*_test.rb').each { |file| require file}
+  Dir.glob("./test/*_test.rb").each { |file| require file }
 end
 
 task :open do
-  Dir.glob('./test/result/*.odt').each { |file| Launchy.open(file) }
+  Dir.glob("./test/result/*.odt").each { |file| Launchy.open(file) }
 end

data/lib/odf-report/composable.rb

@@ -0,0 +1,51 @@
+module ODFReport
+  module Composable
+    def add_field(name, value = nil, &block)
+      fields << Field.new({name: name, value: value}, &block)
+    end
+
+    def add_text(name, value = nil, &block)
+      texts << Text.new({name: name, value: value}, &block)
+    end
+
+    def add_image(name, value = nil, &block)
+      images << Image.new({name: name, value: value}, &block)
+    end
+
+    def add_table(table_name, collection, opts = {})
+      opts[:name] = table_name
+      opts[:value] = collection
+
+      tab = Table.new(opts)
+      tables << tab
+
+      yield(tab)
+    end
+
+    def add_section(section_name, collection, opts = {})
+      opts[:name] = section_name
+      opts[:value] = collection
+
+      sec = Section.new(opts)
+      sections << sec
+
+      yield(sec)
+    end
+
+    def all_images
+      (images.map(&:files) + sections.map(&:all_images) + tables.map(&:all_images)).flatten
+    end
+
+    private
+
+    def fields = @fields ||= []
+
+    def texts = @texts ||= []
+
+    def tables = @tables ||= []
+
+    def sections = @sections ||= []
+
+    def images = @images ||= []
+  end
+end

data/lib/odf-report/data_source.rb

@@ -1,65 +1,71 @@
 module ODFReport
   class DataSource
-
-    attr_reader :value
-
     def initialize(opts, &block)
-      @value      = opts[:value]      || opts[:collection]
-      @data_field = opts[:data_field] || opts[:collection_field] || opts[:name]
-      @block      = block
+      @value = opts[:value]
+      @field = opts[:value] || opts[:name]
+      @block = block
+    end
+
+    def value
+      if @record
+        extract_value_from(@record)
+      else
+        @value
+      end
     end
 
     def set_source(record)
-      @value = extract_value_from_item(record)
+      @record = record
     end
 
     def each(&block)
-      return unless @value
-      @value.each(&block)
+      return unless value
+      value.each(&block)
     end
 
     def empty?
-      @value.nil? || @value.empty?
+      value.nil? || value.empty?
     end
 
     private
 
-    def extract_value_from_item(record)
-
+    def extract_value_from(record)
       if @block
+        # Block transform: add_field(:name) { |item| item.name.upcase }
         @block.call(record)
 
       elsif record.is_a?(Hash)
-        key = @data_field
-        record[key] || record[key.to_s.downcase] || record[key.to_s.upcase] || record[key.to_s.downcase.to_sym]
+        # Hash lookup: tries symbol, lowercase string, uppercase string, lowercase symbol
+        record[@field] || record[@field.to_s.downcase] || record[@field.to_s.upcase] || record[@field.to_s.downcase.to_sym]
 
-      elsif @data_field.is_a?(Array)
-        execute_methods_on_item(record)
+      elsif @field.is_a?(Array)
+        # Method chain: add_field(:name, [:company, :name]) calls record.company.name
+        execute_methods_on(record)
 
-      elsif @data_field.is_a?(Hash) && record.respond_to?(@data_field.keys[0])
-        record.send(@data_field.keys[0], @data_field.values[0])
+      elsif @field.is_a?(Hash) && record.respond_to?(@field.keys[0])
+        # Method with argument: add_field(:name, {full_name: :upcase}) calls record.full_name(:upcase)
+        record.send(@field.keys[0], @field.values[0])
 
-      elsif record.respond_to?(@data_field)
-        record.send(@data_field)
+      elsif record.respond_to?(@field)
+        # Simple method call: add_field(:name, :email) calls record.email
+        record.send(@field)
 
       else
-        raise "Can't find [#{@data_field.to_s}] in this #{record.class}"
+        raise "Can't find [#{@field}] in this #{record.class}"
 
       end
-
     end
 
-    def execute_methods_on_item(record)
+    def execute_methods_on(record)
       tmp = record.dup
-      @data_field.each do |f|
-        if f.is_a?(Hash)
-          tmp = tmp.send(f.keys[0], f.values[0])
+      @field.each do |f|
+        tmp = if f.is_a?(Hash)
+          tmp.send(f.keys[0], f.values[0])
         else
-          tmp = tmp.send(f)
+          tmp.send(f)
         end
       end
       tmp
     end
-
   end
 end

data/lib/odf-report/field.rb

@@ -1,6 +1,5 @@
 module ODFReport
   class Field
-
     DELIMITERS = %w([ ])
 
     def initialize(opts, &block)
@@ -13,33 +12,26 @@ module ODFReport
       self
     end
 
-    def replace!(content, data_item = nil)
-
+    def replace!(content)
       txt = content.inner_html
 
       if txt.gsub!(to_placeholder, sanitize(@data_source.value))
         content.inner_html = txt
       end
-
     end
 
-  private
+    private
 
     def to_placeholder
-      if DELIMITERS.is_a?(Array)
-        "#{DELIMITERS[0]}#{@name.to_s.upcase}#{DELIMITERS[1]}"
-      else
-        "#{DELIMITERS}#{@name.to_s.upcase}#{DELIMITERS}"
-      end
+      "#{DELIMITERS[0]}#{@name.to_s.upcase}#{DELIMITERS[1]}"
     end
 
     def sanitize(txt)
       txt = html_escape(txt)
-      txt = odf_linebreak(txt)
-      txt
+      odf_linebreak(txt)
     end
 
-    HTML_ESCAPE = { '&' => '&amp;',  '>' => '&gt;',   '<' => '&lt;', '"' => '&quot;' }
+    HTML_ESCAPE = {"&" => "&amp;", ">" => "&gt;", "<" => "&lt;", '"' => "&quot;"}
 
     def html_escape(s)
       return "" unless s
@@ -50,6 +42,5 @@ module ODFReport
       return "" unless s
       s.to_s.gsub("\n", "<text:line-break/>")
     end
-
   end
 end

data/lib/odf-report/image.rb

@@ -1,6 +1,5 @@
 module ODFReport
   class Image < Field
-
     IMAGE_DIR_NAME = "Pictures"
 
     attr_reader :files
@@ -10,48 +9,47 @@ module ODFReport
       super
     end
 
-    def replace!(doc, data_item = nil)
-
+    def replace!(doc)
       frame = doc.xpath("//draw:frame[@draw:name='#{@name}']").first
-      image = doc.xpath("//draw:frame[@draw:name='#{@name}']/draw:image").first
+      return unless frame
 
+      image = frame.at_xpath("draw:image")
       return unless image
 
       file = @data_source.value
 
       if file
-        image.attribute('href').content = File.join(IMAGE_DIR_NAME, File.basename(file))
-        frame.attribute('name').content = SecureRandom.uuid
+        image.attribute("href").content = self.class.image_href(file)
+        frame.attribute("name").content = SecureRandom.uuid
 
         @files << file
       else
         frame.remove
       end
-      
     end
 
     def self.include_image_file(zip_file, image_file)
       return unless image_file
 
-      href = File.join(IMAGE_DIR_NAME, File.basename(image_file))
-
-      zip_file.update_file(href, File.read(image_file))
+      zip_file.update_file(image_href(image_file), File.read(image_file))
     end
 
     def self.include_manifest_entry(content, image_file)
       return unless image_file
 
-      return unless root_node = content.at("//manifest:manifest")
+      return unless (root_node = content.at("//manifest:manifest"))
 
-      href = File.join(IMAGE_DIR_NAME, File.basename(image_file))
+      href = image_href(image_file)
 
-      entry = content.create_element('manifest:file-entry')
-      entry['manifest:full-path']  = href
-      entry['manifest:media-type'] = MIME::Types.type_for(href)[0].content_type
+      entry = content.create_element("manifest:file-entry")
+      entry["manifest:full-path"] = href
+      entry["manifest:media-type"] = MIME::Types.type_for(href)[0].content_type
 
       root_node.add_child entry
-
     end
 
+    def self.image_href(file)
+      File.join(IMAGE_DIR_NAME, File.basename(file))
+    end
   end
 end

data/lib/odf-report/nestable.rb

@@ -1,65 +1,34 @@
 module ODFReport
   class Nestable
+    include Composable
 
     def initialize(opts)
       @name = opts[:name]
 
       @data_source = DataSource.new(opts)
-
-      @fields   = []
-      @texts    = []
-      @tables   = []
-      @sections = []
-      @images   = []
-
     end
 
+    alias_method :add_column, :add_field
+
     def set_source(data_item)
       @data_source.set_source(data_item)
       self
     end
 
-    def add_field(name, data_field=nil, &block)
-      opts = { name: name, data_field: data_field }
-      @fields << Field.new(opts, &block)
-    end
-    alias_method :add_column, :add_field
-
-    def add_text(name, data_field=nil, &block)
-      opts = {name: name, data_field: data_field}
-      @texts << Text.new(opts, &block)
-    end
-
-    def add_image(name, data_field=nil, &block)
-      opts = {name: name, data_field: data_field}
-      @images << Image.new(opts, &block)
-    end
-
-    def add_table(table_name, collection_field, opts={})
-      opts.merge!(name: table_name, collection_field: collection_field)
-      tab = Table.new(opts)
-      @tables << tab
-
-      yield(tab)
-    end
-
-    def add_section(section_name, collection_field, opts={})
-      opts.merge!(name: section_name, collection_field: collection_field)
-      sec = Section.new(opts)
-      @sections << sec
-
-      yield(sec)
-    end
-
-    def all_images
-      (@images.map(&:files) + @sections.map(&:all_images) + @tables.map(&:all_images)).flatten
-    end
-
     def wrap_with_ns(node)
       <<-XML
        <root xmlns:draw="a" xmlns:xlink="b" xmlns:text="c" xmlns:table="d">#{node.to_xml}</root>
       XML
     end
-    
+
+    def replace_with!(record, node)
+      tables.each { |t| t.set_source(record).replace!(node) }
+      sections.each { |s| s.set_source(record).replace!(node) }
+      texts.each { |t| t.set_source(record).replace!(node) }
+      fields.each { |f| f.set_source(record).replace!(node) }
+      images.each { |i| i.set_source(record).replace!(node) }
+    end
+
+    private
   end
 end