caracal 1.4.1 → 1.6.0

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,10 +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
 
@@ -12,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
@@ -25,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
         #--------------------------------------------------
@@ -35,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
@@ -74,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 }
@@ -88,13 +124,11 @@ module Caracal
 
         def file
           @file ||= begin
-            if iframe_url.nil?
-              file = Tempfile.new('iframe')
-              file.write iframe_data
-              file.rewind
-            else
-              file = open(iframe_url)
-            end
+            content = iframe_url.to_s.empty? ? iframe_data : ::Caracal::Utilities.read_resource(iframe_url)
+            file    = Tempfile.new(['iframe', '.docx'])
+            file.binmode
+            file.write content
+            file.close    # flushes the write; rubyzip reopens by path
             file
           end
         end

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)

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

@@ -17,7 +17,7 @@ module Caracal
         #-------------------------------------------------------------
 
         # accessors
-        attr_accessor :nested_list
+        attr_writer :continuation
 
         # readers (create aliases for superclass methods to conform
         # to expected naming convention.)
@@ -54,6 +54,51 @@ module Caracal
         end
 
 
+        #=============== NESTED LISTS =========================
+
+        # This method returns the nested lists in the order they were
+        # added, each with the number of runs that came before it, so text
+        # after a nested list can be rendered after it.
+        #
+        def nested_lists
+          @nested_lists ||= []
+        end
+
+        def nested_list
+          (pair = nested_lists.last) && pair.last
+        end
+
+        def nested_list=(model)
+          nested_lists << [runs.size, model]
+        end
+
+        # This method returns whether this is the text that follows a
+        # nested list, which renders as an unnumbered paragraph indented
+        # with the item.
+        #
+        def continuation?
+          !!@continuation
+        end
+
+        # This method returns this item and everything nested in it in
+        # document order: the item's text up to its first nested list, the
+        # nested list's items, then any text that follows, and so on.
+        #
+        def recursive_items
+          return [self] if nested_lists.empty?
+
+          items = []
+          start = 0
+          nested_lists.each do |(index, list)|
+            items << segment(start...index, items.any?) if items.empty? || index > start
+            items.concat(list.recursive_items)
+            start = index
+          end
+          items << segment(start...runs.size, true) if runs.size > start
+          items
+        end
+
+
         #=============== SUB-METHODS ===========================
 
         # .ol
@@ -62,7 +107,7 @@ module Caracal
 
           model = Caracal::Core::Models::ListModel.new(options, &block)
           if model.valid?
-            @nested_list = model
+            self.nested_list = model
           else
             raise Caracal::Errors::InvalidModelError, 'Ordered lists require at least one list item.'
           end
@@ -75,7 +120,7 @@ module Caracal
 
           model = Caracal::Core::Models::ListModel.new(options, &block)
           if model.valid?
-            @nested_list = model
+            self.nested_list = model
           else
             raise Caracal::Errors::InvalidModelError, 'Unordered lists require at least one list item.'
           end
@@ -97,6 +142,15 @@ module Caracal
         #-------------------------------------------------------------
         private
 
+        # This method returns a copy of the item holding only the given runs.
+        def segment(range, continuation)
+          copy = dup
+          copy.instance_variable_set(:@runs, runs[range])
+          copy.instance_variable_set(:@nested_lists, [])
+          copy.continuation = continuation
+          copy
+        end
+
         def option_keys
           [:type, :level, :content, :style, :color, :size, :bold, :italic, :underline, :bgcolor]
         end

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

@@ -61,13 +61,7 @@ module Caracal
         # item within this list's tree.
         #
         def recursive_items
-          items.map do |model|
-            if model.nested_list.nil?
-              model
-            else
-              [model, model.nested_list.recursive_items]
-            end
-          end.flatten
+          items.flat_map(&:recursive_items)
         end
         
         

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

@@ -108,7 +108,7 @@ module Caracal
         private
         
         def option_keys
-          [:type, :level, :format, :value, :align, :left, :indent, :start]
+          [:type, :level, :format, :value, :align, :left, :indent, :start, :restart]
         end
         
       end

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

@@ -24,6 +24,8 @@ module Caracal
         attr_reader :page_number_label_size
         attr_reader :page_number_number_size
         attr_reader :page_number_show
+        attr_reader :page_number_first
+        attr_reader :page_number_start
 
         # initialization
         def initialize(options={}, &block)
@@ -32,6 +34,8 @@ module Caracal
           @page_number_label_size   = nil
           @page_number_number_size  = nil
           @page_number_show         = DEFAULT_PAGE_NUMBER_SHOW
+          @page_number_first        = true
+          @page_number_start        = nil
 
           super options, &block
         end
@@ -65,6 +69,15 @@ module Caracal
           @page_number_show = !!value
         end
 
+        # false leaves the page number off the first page
+        def first_page(value)
+          @page_number_first = !!value
+        end
+
+        def start(value)
+          @page_number_start = value.nil? ? nil : value.to_i
+        end
+
         def size(value)
           v = value.to_i
           @page_number_label_size  = (v == 0) ? nil : v
@@ -75,7 +88,9 @@ module Caracal
         #=============== VALIDATION ===========================
 
         def valid?
-          (!page_number_show || [:left, :center, :right].include?(page_number_align))
+          valid_align = (!page_number_show || [:left, :center, :right].include?(page_number_align))
+          valid_start = (page_number_start.nil? || page_number_start >= 0)
+          valid_align && valid_start
         end
 
 
@@ -85,7 +100,7 @@ module Caracal
         private
 
         def option_keys
-          [:align, :label, :label_size, :number_size, :show]
+          [:align, :label, :label_size, :number_size, :show, :size, :start, :first_page]
         end
 
       end

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

@@ -2,6 +2,7 @@ require 'caracal/core/models/base_model'
 require 'caracal/core/models/bookmark_model'
 require 'caracal/core/models/link_model'
 require 'caracal/core/models/text_model'
+require 'caracal/core/models/field_model'
 require 'caracal/errors'
 
 
@@ -27,6 +28,7 @@ module Caracal
         attr_reader :paragraph_italic
         attr_reader :paragraph_underline
         attr_reader :paragraph_bgcolor
+        attr_reader :paragraph_keep_next
 
         # initialization
         def initialize(options={}, &block)
@@ -63,7 +65,7 @@ module Caracal
         #========== SETTERS ===============================
 
         # booleans
-        [:bold, :italic, :underline].each do |m|
+        [:bold, :italic, :keep_next, :underline].each do |m|
           define_method "#{ m }" do |value|
             instance_variable_set("@paragraph_#{ m }", !!value)
           end
@@ -126,6 +128,20 @@ module Caracal
           model
         end
 
+        # .field
+        def field(*args, &block)
+          options = Caracal::Utilities.extract_options!(args)
+          options = options.merge({ type: args[0] })
+
+          model = Caracal::Core::Models::FieldModel.new(options, &block)
+          if model.valid?
+            runs << model
+          else
+            raise Caracal::Errors::InvalidModelError, ':field method must receive :page or :numpages.'
+          end
+          model
+        end
+
         # .link
         def link(*args, &block)
           options = Caracal::Utilities.extract_options!(args)
@@ -176,7 +192,7 @@ module Caracal
         private
 
         def option_keys
-          [:content, :style, :align, :color, :size, :bold, :italic, :underline, :bgcolor]
+          [:content, :style, :align, :color, :size, :bold, :italic, :underline, :bgcolor, :keep_next]
         end
 
       end

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

@@ -18,13 +18,24 @@ module Caracal
         TYPE_MAP = {
           font:       'http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable', 
           footer:     'http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer',
+          header:     'http://schemas.openxmlformats.org/officeDocument/2006/relationships/header',
           image:      'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image',
           link:       'http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink',
           numbering:  'http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering',
           setting:    'http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings',
           style:      'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles'
         }
-        
+
+        IMAGE_SIGNATURES = {
+          "\x89PNG\r\n\x1A\n".b  => 'png',
+          "\xFF\xD8\xFF".b       => 'jpeg',
+          'GIF8'.b               => 'gif',
+          'BM'.b                 => 'bmp',
+          "II*\x00".b            => 'tiff',
+          "MM\x00*".b            => 'tiff'
+        }
+        IMAGE_EXTENSIONS = %w(png jpeg jpg gif bmp tif tiff svg)
+
         # accessors
         attr_reader :relationship_id
         attr_reader :relationship_key
@@ -46,14 +57,27 @@ module Caracal
         
         def formatted_target
           if relationship_type == :image
-            ext = relationship_target.to_s.split('.').last
-            ext = ext.split('?').first
-            "media/image#{ relationship_id }.#{ ext }"
+            "media/image#{ relationship_id }.#{ image_extension }"
           else
             relationship_target
           end
         end
-        
+
+        # Prefers the type detected from the image bytes, then the
+        # extension of the target's path (ignoring any query string),
+        # and falls back to png so the part name is always valid.
+        #
+        def image_extension
+          data = relationship_data.to_s.b
+          if (match = IMAGE_SIGNATURES.find { |sig, _| data.start_with?(sig) })
+            return match.last
+          end
+
+          path = relationship_target.to_s.split(/[?#]/).first.to_s
+          ext  = File.extname(path).delete('.').downcase
+          IMAGE_EXTENSIONS.include?(ext) ? ext : 'png'
+        end
+
         def formatted_type
           TYPE_MAP.fetch(relationship_type)
         end