caracal 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3357d1a61526623b3acb0ead4e0b990ce1c70026ea321ba014415947380daec9
-  data.tar.gz: 5be1b9e7bec559c1199c2c17befe1238c3ab522c1ef1fdb3a49a58e3b102c67f
+  metadata.gz: c06f9a2d1fafe9fc3cbc91db5bab3d08a374ef0b688ff188a200e175f0c72073
+  data.tar.gz: 7dd9194ecb1a0d84e9e5953a334f0fc5754fbd696305e8fa21a8563f95c2a3fa
 SHA512:
-  metadata.gz: ad771cd941a199997acf1138bd1d426e5f2a4d1d5feb2065366a85de09a5f31295f9eee3a97b7264732e27b09706c722e4532f0a2164f73c00d3b3543623eddc
-  data.tar.gz: d89fe871c0f5569292adfd8ec6a5c044bf1096ecb95e711b2c55a9a4aa1324317d757f5ab8057d20582ff0ccd3c5b6f150c5b5a25a3a4aed81634a495ce32ad2
+  metadata.gz: 56a868f230d4ae1ad7ab96f1e001aca3efac537026cf3e23f66936e18f8779e692fccc52c1118a55b25a5750e8aeda51e7e347c16b37264c598682cc9aba0748
+  data.tar.gz: '02099d9534ed1c0d950028f7dc937e47394082d2f05a4909f554a68a052f1d58f8ed84be30a55f2e91a15e240dc805b65b2e42ac1104b6989965b797ad573f98'

data/.github/workflows/push_gem.yml

@@ -0,0 +1,29 @@
+name: Push gem
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  push:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    environment: release
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: ruby
+
+      - uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+#### v1.6.0
+
+* Enhancements
+  * Added `header` and `footer`, which accept the same content as the document body: paragraphs, images, tables and links. Images and links resolve through each part's own relationships. (@benjaminketron, @jamesridgway, @dlauer)
+  * Added the `field` paragraph method, which inserts a `:page` or `:numpages` field, so a footer can read "Page 2 of 7". (@benjaminketron, @jamesridgway, @dlauer)
+  * Added a different first page: `header first: true` and `footer first: true` give the first page its own header or footer, or leave it blank when called without a block, and `page_numbers first_page: false` leaves the number off the first page. (@dlauer)
+  * Added the `start` option to `page_numbers`, which sets the number of the first page. (@dlauer)
+  * `img` now accepts `data:` and `ppi:` as options, not only inside its block. Previously the options were silently dropped and the image was read from the path instead. (@victorpolko, @dlauer)
+  * `keep_next`, `header_rows`, the list style `restart` and the page number `size` are likewise accepted as options. (@dlauer)
+  * Entries read from documents embedded with `iframe` are capped by `IFrameModel.max_entry_size` (50MB by default), so a small upload cannot expand into an arbitrarily large allocation. (@dlauer)
+  * Raised the nokogiri floor to 1.16.2 and added source, changelog and issue tracker links to the gem metadata. (@dlauer)
+
+* Changes
+  * `footer` and `page_numbers` now combine, with the page number rendered below the footer content. Previously `page_numbers` replaced the footer.
+  * `header` and `footer` raise `InvalidModelError` when given an empty block.
+
+* Bug Fixes
+  * Page numbers are rendered as a complete complex field, so viewers that do not evaluate fields, such as WPS Office, show the number rather than "PAGE". (@dlauer)
+  * Text added to a list item after a nested list now appears after that list, aligned with the item's text, rather than before it. An item can also hold more than one nested list. (@dlauer)
+  * Documents written with rubyzip 3 no longer carry zip64 records, which LibreOffice 7.4 and earlier refuse to open. (@dlauer)
+
+
 #### v1.5.0
 
 * Enhancements

data/README.md

@@ -321,14 +321,61 @@ Page numbers can be added to the footer via the `page_numbers` method.  The meth
 docx.page_numbers true do
   align        :right  # sets the alignment. accepts :left, :center, and :right.
   label        'Page'  # sets the text that will go to the left of the page number. Defaults to nil.
-  size:        24      # sets the label and number size simultaneously. units in half points.
-  label_size:  24      # sets the label size only. units in half points.
-  number_size: 20      # sets the number size only. units in half points.
+  size         24      # sets the label and number size simultaneously. units in half points.
+  label_size   24      # sets the label size only. units in half points.
+  number_size  20      # sets the number size only. units in half points.
 end
 ```
 
 The `size` option and the `label_size` and `number_size` options are mutually exclusive.
 
+The `start` option sets the number of the first page, which is useful when the document continues another one, or has a cover page you don't want counted. It also applies to `field :page` in a custom footer, so it can be set without showing the built-in page number:
+
+```ruby
+docx.page_numbers true, start: 0   # the cover page is page 0, so the next page is page 1
+docx.page_numbers start: 12        # number from 12 without the built-in page number
+```
+
+### Headers and Footers
+
+A header or footer that appears on every page can be added with the `header` and `footer` methods. Their blocks accept the same paragraph, list, table, rule and image methods as the document body.
+
+```ruby
+docx.header do
+  img 'logo.png', width: 120, height: 32, align: :right
+  p 'Quarterly Report', align: :center
+end
+
+docx.footer do
+  p align: :center do
+    text 'Page '
+    field :page
+    text ' of '
+    field :numpages
+  end
+end
+```
+
+If you also turn on `page_numbers`, the page number is rendered below the footer content.
+
+*Headers and footers must contain content. Calling `header` or `footer` with an empty block raises an `InvalidModelError`.*
+
+#### Different First Page
+
+Pass `first: true` to give the first page its own header or footer, such as a cover page. Without a block, it leaves the first page's header or footer blank. Use `first_page: false` to leave the page number off the first page.
+
+```ruby
+docx.header first: true do       # replaces the header on the first page only
+  p 'Annual Report 2026', align: :center, size: 36
+end
+
+docx.header first: true          # no header on the first page
+docx.footer first: true          # no footer content on the first page
+
+docx.page_numbers true, first_page: false   # no page number on the first page
+```
+
+When the first page has its own header or footer, any part you don't set for it falls back to the default. So `first_page: false` on its own hides only the page number, and the default header and footer content still appear.
 
 ### Fonts
 
@@ -446,6 +493,16 @@ docx.p do
 end
 ```
 
+Fields that Word fills in can be added with the `field` method. It accepts `:page` (the current page number) and `:numpages` (the total number of pages), along with the same formatting options as `text`.
+
+```ruby
+docx.p do
+  text 'Page '
+  field :page, bold: true
+  text ' of '
+  field :numpages
+end
+```
 
 ### Links
 
@@ -575,7 +632,7 @@ docx.ul do
 end
 ```
 
-Lists can nested as many levels deep as you wish and mixed in any combination.
+Lists can be nested as many levels deep as you wish and mixed in any combination. An item can contain more than one nested list. Text that follows a nested list renders after it, as an unnumbered paragraph aligned with the item's text.
 
 ```ruby
 docx.ul do
@@ -624,6 +681,7 @@ Images can be added by using the `img` method.  The method accepts several optio
 ```ruby
 docx.img 'https://www.example.com/logo.png' do
   data    raw_data  # sets the file data directly instead of opening the url
+  ppi     72        # sets the pixels per inch used to convert width and height. defaults to 72.
   width   396       # sets the image width. units specified in pixels.
   height  216       # sets the image height. units specified in pixels.
   align   :right    # controls the justification of the image. default is :left.
@@ -634,6 +692,16 @@ docx.img 'https://www.example.com/logo.png' do
 end
 ```
 
+Every setting can also be passed as an option instead of in a block:
+
+```ruby
+docx.img 'logo.png', data: File.binread('path/to/logo.png'), width: 396, height: 216
+```
+
+*Note: `data` must be the raw bytes of the image, not Base64. Caracal writes it
+into the document unchanged, so Base64-encoded data produces a corrupt image.
+Read files with `File.binread` so line endings are not translated on Windows.*
+
 *Note: If you provide the image data, you should still supply a URL. I know this
 is a bit hacky, but it allows the library to key the image more effectively and
 Caracal needs a file extension to apply to the renamed media file. This seemed

data/caracal.gemspec

@@ -6,13 +6,19 @@ require 'caracal/version'
 Gem::Specification.new do |spec|
   spec.name          = 'caracal'
   spec.version       = Caracal::VERSION
-  spec.authors       = ['Urvin LLC', 'John Dugan', 'Dave Lauer']
-  spec.email         = ['jpdugan@gmail.com', 'dave@plia.com']
+  spec.authors       = ['Urvin LLC', 'Dave Lauer']
+  spec.email         = ['dave@plia.com']
   spec.summary       = %q{ Fast, professional Microsoft Word (docx) writer for Ruby. }
   spec.description   = %q{ Caracal is a pure Ruby Microsoft Word generation library that produces professional quality MSWord documents (docx) using a simple, HTML-style DSL. }
   spec.homepage      = 'https://github.com/urvin-compliance/caracal'
   spec.license       = 'MIT'
 
+  spec.metadata      = {
+    'source_code_uri' => 'https://github.com/urvin-compliance/caracal',
+    'changelog_uri'   => 'https://github.com/urvin-compliance/caracal/blob/master/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/urvin-compliance/caracal/issues'
+  }
+
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
@@ -20,7 +26,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 3.1'
 
-  spec.add_dependency 'nokogiri', '~> 1.6'
+  spec.add_dependency 'nokogiri', '>= 1.16.2', '< 2.0'
   spec.add_dependency 'rubyzip',  '>= 1.1.6', '< 4.0'
   spec.add_dependency 'tilt',     '>= 1.4'
 

data/lib/caracal/core/footer.rb

@@ -0,0 +1,50 @@
+require 'caracal/core/models/footer_model'
+require 'caracal/errors'
+
+
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to adding a
+    # footer on every page of the document.
+    #
+    module Footer
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          # With `first: true` the footer replaces the default one on the
+          # first page only. Without a block it leaves the first page's
+          # footer blank.
+          #
+          def footer(*args, &block)
+            options = Caracal::Utilities.extract_options!(args)
+            first   = options.delete(:first)
+
+            model = Caracal::Core::Models::FooterModel.new(options, &block)
+            if first
+              @first_footer_content = model
+            elsif model.valid?
+              @footer_content = model
+            else
+              raise Caracal::Errors::InvalidModelError, 'footer must contain at least one paragraph, list, table, rule or image.'
+            end
+            model
+          end
+
+          def footer_content
+            @footer_content
+          end
+
+          def first_footer_content
+            @first_footer_content
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/caracal/core/header.rb

@@ -0,0 +1,49 @@
+require 'caracal/core/models/header_model'
+require 'caracal/errors'
+
+
+module Caracal
+  module Core
+
+    # This module encapsulates all the functionality related to adding a header
+    # to every page of the document.
+    #
+    module Header
+      def self.included(base)
+        base.class_eval do
+
+          #-------------------------------------------------------------
+          # Public Methods
+          #-------------------------------------------------------------
+
+          # With `first: true` the header replaces the default one on the
+          # first page only. Without a block it leaves the first page's
+          # header blank.
+          #
+          def header(*args, &block)
+            options = Caracal::Utilities.extract_options!(args)
+            first   = options.delete(:first)
+
+            model = Caracal::Core::Models::HeaderModel.new(options, &block)
+            if first
+              @first_header_content = model
+            elsif model.valid?
+              @header_content = model
+            else
+              raise Caracal::Errors::InvalidModelError, 'header must contain at least one paragraph, list, table, rule or image.'
+            end
+            model
+          end
+
+          def header_content
+            @header_content
+          end
+
+          def first_header_content
+            @first_header_content
+          end
+        end
+      end
+    end
+  end
+end

data/lib/caracal/core/models/field_model.rb

@@ -0,0 +1,131 @@
+require 'caracal/core/models/base_model'
+
+
+module Caracal
+  module Core
+    module Models
+
+      # This class encapsulates the logic needed to store and render a
+      # field, such as the current page number, inside a paragraph.
+      #
+      class FieldModel < BaseModel
+
+        #--------------------------------------------------
+        # Configuration
+        #--------------------------------------------------
+
+        # constants
+        const_set(:TYPE_MAP, { page: 'PAGE', numpages: 'NUMPAGES' })
+
+        # accessors
+        attr_reader :field_type
+        attr_reader :field_style
+        attr_reader :field_font
+        attr_reader :field_color
+        attr_reader :field_size
+        attr_reader :field_bold
+        attr_reader :field_italic
+        attr_reader :field_underline
+        attr_reader :field_bgcolor
+        attr_reader :field_highlight_color
+        attr_reader :field_vertical_align
+
+        #-------------------------------------------------------------
+        # Public Class Methods
+        #-------------------------------------------------------------
+
+        def self.formatted_type(type)
+          TYPE_MAP.fetch(type.to_s.to_sym)
+        end
+
+
+        #-------------------------------------------------------------
+        # Public Instance Methods
+        #-------------------------------------------------------------
+
+        #========== GETTERS ===============================
+
+        def formatted_type
+          self.class.formatted_type(field_type)
+        end
+
+        # .run_attributes
+        def run_attributes
+          {
+            style:            field_style,
+            font:             field_font,
+            color:            field_color,
+            size:             field_size,
+            bold:             field_bold,
+            italic:           field_italic,
+            underline:        field_underline,
+            bgcolor:          field_bgcolor,
+            highlight_color:  field_highlight_color,
+            vertical_align:   field_vertical_align
+          }
+        end
+
+
+        #========== SETTERS ===============================
+
+        # booleans
+        [:bold, :italic, :underline].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@field_#{ m }", !!value)
+          end
+        end
+
+        # integers
+        [:size].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@field_#{ m }", value.to_i)
+          end
+        end
+
+        # strings
+        [:bgcolor, :color, :font, :highlight_color, :style, :type].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@field_#{ m }", value.to_s)
+          end
+        end
+
+        # symbols
+        [:vertical_align].each do |m|
+          define_method "#{ m }" do |value|
+            instance_variable_set("@field_#{ m }", value.to_s.to_sym)
+          end
+        end
+
+
+        #========== VALIDATION ============================
+
+        def valid?
+          TYPE_MAP.key?(field_type.to_s.to_sym)
+        end
+
+
+        #--------------------------------------------------
+        # Private Methods
+        #--------------------------------------------------
+        private
+
+        def option_keys
+          [:type, :style, :font, :color, :size, :bold, :italic, :underline, :bgcolor, :highlight_color, :vertical_align]
+        end
+
+        def method_missing(method, *args, &block)
+          # I'm on the fence with respect to this implementation. We're ignoring
+          # :method_missing errors to allow syntax flexibility for paragraph-type
+          # models.  The issue is the syntax format of those models--the way we pass
+          # the content value as a special argument--coupled with the model's
+          # ability to accept nested instructions.
+          #
+          # By ignoring method missing errors here, we can pass the entire paragraph
+          # block in the initial, built-in call to :text.
+        end
+
+      end
+
+    end
+  end
+end

data/lib/caracal/core/models/footer_model.rb

@@ -0,0 +1,43 @@
+require 'caracal/core/models/base_model'
+
+
+module Caracal
+  module Core
+    module Models
+
+      # This class holds the contents of the footer that appears on
+      # every page of the document.
+      #
+      class FooterModel < BaseModel
+
+        #-------------------------------------------------------------
+        # Public Methods
+        #-------------------------------------------------------------
+
+        #=============== DATA ACCESSORS =======================
+
+        def contents
+          @contents ||= []
+        end
+
+        # Images and links in the footer are registered with the document,
+        # which numbers them and writes the media, but Word resolves them
+        # against the footer part's own relationships. The renderer collects
+        # them here so they can be written to that part.
+        #
+        def relationships
+          @relationships ||= []
+        end
+
+
+        #=============== VALIDATION ===========================
+
+        def valid?
+          contents.size > 0
+        end
+
+      end
+
+    end
+  end
+end

data/lib/caracal/core/models/header_model.rb

@@ -0,0 +1,43 @@
+require 'caracal/core/models/base_model'
+
+
+module Caracal
+  module Core
+    module Models
+
+      # This class holds the contents of the header that appears on
+      # every page of the document.
+      #
+      class HeaderModel < BaseModel
+
+        #-------------------------------------------------------------
+        # Public Methods
+        #-------------------------------------------------------------
+
+        #=============== DATA ACCESSORS =======================
+
+        def contents
+          @contents ||= []
+        end
+
+        # Images and links in the header are registered with the document,
+        # which numbers them and writes the media, but Word resolves them
+        # against the header part's own relationships. The renderer collects
+        # them here so they can be written to that part.
+        #
+        def relationships
+          @relationships ||= []
+        end
+
+
+        #=============== VALIDATION ===========================
+
+        def valid?
+          contents.size > 0
+        end
+
+      end
+
+    end
+  end
+end

data/lib/caracal/core/models/iframe_model.rb

@@ -1,11 +1,12 @@
 require 'tempfile'
 require 'caracal/core/models/base_model'
+require 'caracal/errors'
 
 module Caracal
   module Core
     module Models
 
-      # This class handles block options passed to the img method.
+      # This class handles block options passed to the iframe method.
       #
       class IFrameModel < BaseModel
 
@@ -13,6 +14,9 @@ module Caracal
         # Configuration
         #--------------------------------------------------
 
+        # constants
+        const_set(:DEFAULT_MAX_ENTRY_SIZE, 50 * 1024 * 1024)   # 50MB
+
         # accessors
         attr_reader :iframe_url
         attr_reader :iframe_data
@@ -26,6 +30,37 @@ module Caracal
         end
 
 
+        #--------------------------------------------------
+        # Class Methods
+        #--------------------------------------------------
+
+        # The largest single entry Caracal will read out of an embedded
+        # document. Zip entries expand to many times their stored size, so
+        # without a limit a small file can exhaust memory. Set to nil to
+        # disable the check.
+        #
+        def self.max_entry_size
+          defined?(@max_entry_size) ? @max_entry_size : DEFAULT_MAX_ENTRY_SIZE
+        end
+
+        def self.max_entry_size=(value)
+          @max_entry_size = value
+        end
+
+        # This method reads a single entry from an embedded document,
+        # refusing anything larger than :max_entry_size.
+        #
+        def self.read_entry(entry)
+          limit = max_entry_size
+
+          if limit && entry.size > limit
+            raise Caracal::Errors::InvalidModelError, "iframe entry #{ entry.name } is #{ entry.size } bytes, over the #{ limit } byte limit."
+          end
+
+          entry.get_input_stream.read
+        end
+
+
         #--------------------------------------------------
         # Public Methods
         #--------------------------------------------------
@@ -36,12 +71,12 @@ module Caracal
           ::Zip::File.open(file) do |zip|
             # locate relationships xml
             entry      = zip.glob('word/_rels/document.xml.rels').first
-            content    = entry.get_input_stream.read
+            content    = self.class.read_entry(entry)
             rel_xml    = Nokogiri::XML(content)
 
             # locate document xml
             entry      = zip.glob('word/document.xml').first
-            content    = entry.get_input_stream.read
+            content    = self.class.read_entry(entry)
             doc_xml    = Nokogiri::XML(content)
 
             # master nodesets
@@ -75,7 +110,7 @@ module Caracal
               p_node  = node.children[0].children[0]
               p_id    = p_node.attributes['id'].to_s.to_i
               p_name  = p_node.attributes['name'].to_s
-              p_data  = zip.glob(r_media).first.get_input_stream.read
+              p_data  = self.class.read_entry(zip.glob(r_media).first)
 
               # register relationship
               array << { id: r_id, type: 'image', target: p_name, data: p_data }

data/lib/caracal/core/models/image_model.rb

@@ -115,7 +115,7 @@ module Caracal
         private
         
         def option_keys
-          [:url, :width, :height, :align, :top, :bottom, :left, :right]
+          [:url, :data, :ppi, :width, :height, :align, :top, :bottom, :left, :right]
         end
         
         def pixels_to_emus(value, ppi)