hexapdf 1.2.0 → 1.4.0

data/lib/hexapdf/font/true_type/subsetter.rb

@@ -63,6 +63,16 @@ module HexaPDF
         def use_glyph(glyph_id)
           return @glyph_map[glyph_id] if @glyph_map.key?(glyph_id)
           @last_id += 1
+          # Handle codes for ASCII characters \r (13), (, ) (40, 41) and \ (92) specially so that
+          # they never appear in the output (PDF serialization would need to escape them)
+          if @last_id == 13 || @last_id == 40 || @last_id == 92
+            @glyph_map[:"s#{@last_id}"] = @last_id
+            if @last_id == 40
+              @last_id += 1
+              @glyph_map[:"s#{@last_id}"] = @last_id
+            end
+            @last_id += 1
+          end
           @glyph_map[glyph_id] = @last_id
         end
 
@@ -107,7 +117,7 @@ module HexaPDF
           locations = []
 
           @glyph_map.each_key do |old_gid|
-            glyph = orig_glyf[old_gid]
+            glyph = orig_glyf[old_gid.kind_of?(Symbol) ? 0 : old_gid]
             locations << table.size
             data = glyph.raw_data
             if glyph.compound?
@@ -166,7 +176,10 @@ module HexaPDF
         # Adds the components of compound glyphs to the subset.
         def add_glyph_components
           glyf = @font[:glyf]
-          @glyph_map.keys.each {|gid| glyf[gid].components&.each {|cgid| use_glyph(cgid) } }
+          @glyph_map.keys.each do |gid|
+            next if gid.kind_of?(Symbol)
+            glyf[gid].components&.each {|cgid| use_glyph(cgid) }
+          end
         end
 
       end

data/lib/hexapdf/layout/box.rb

@@ -166,6 +166,11 @@ module HexaPDF
           @status == :overflow
         end
 
+        # Sets the result status to failure.
+        def failure!
+          @status = :failure
+        end
+
         # Returns +true+ if fitting was a failure.
         def failure?
           @status == :failure

data/lib/hexapdf/layout/container_box.rb

@@ -44,21 +44,22 @@ module HexaPDF
     # under the :container name.
     #
     # The box does not support the value :flow for the style property position, so the child boxes
-    # are laid out in the current region only. Since the boxes should be laid out together, if any
-    # box doesn't fit, the whole container doesn't fit. Splitting the container is also not possible
-    # for the same reason.
+    # are laid out in the current region only.
     #
-    # By default the child boxes are laid out from top to bottom by default. By appropriately
-    # setting the style properties 'mask_mode', 'align' and 'valign', it is possible to lay out the
-    # children bottom to top, left to right, or right to left:
+    # If #splitable is +false+ (the default) and if any box doesn't fit, the whole container doesn't
+    # fit.
+    #
+    # By default the child boxes are laid out from top to bottom. By appropriately setting the style
+    # properties 'mask_mode', 'align' and 'valign', it is possible to lay out the children bottom to
+    # top, left to right, or right to left:
     #
     # * The standard top-to-bottom layout:
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-dark"})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue"})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-light"})
+    #       container.box(height: 20, style: {background_color: "hp-blue-dark"})
+    #       container.box(height: 20, style: {background_color: "hp-blue"})
+    #       container.box(height: 20, style: {background_color: "hp-blue-light"})
     #     end
     #
     # * The bottom-to-top layout (using valign = :bottom to fill up from the bottom and mask_mode =
@@ -66,12 +67,12 @@ module HexaPDF
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-dark",
-    #                                                mask_mode: :fill_horizontal, valign: :bottom})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue",
-    #                                                mask_mode: :fill_horizontal, valign: :bottom})
-    #       container.box(:base, height: 20, style: {background_color: "hp-blue-light",
-    #                                                mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(height: 20, style: {background_color: "hp-blue-dark",
+    #                                         mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(height: 20, style: {background_color: "hp-blue",
+    #                                         mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(height: 20, style: {background_color: "hp-blue-light",
+    #                                         mask_mode: :fill_horizontal, valign: :bottom})
     #     end
     #
     # * The left-to-right layout (using mask_mode = :fill_vertical to fill the area to the top and
@@ -79,12 +80,12 @@ module HexaPDF
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-dark",
-    #                                               mask_mode: :fill_vertical})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue",
-    #                                               mask_mode: :fill_vertical})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-light",
-    #                                               mask_mode: :fill_vertical})
+    #       container.box(width: 20, style: {background_color: "hp-blue-dark",
+    #                                        mask_mode: :fill_vertical})
+    #       container.box(width: 20, style: {background_color: "hp-blue",
+    #                                        mask_mode: :fill_vertical})
+    #       container.box(width: 20, style: {background_color: "hp-blue-light",
+    #                                        mask_mode: :fill_vertical})
     #     end
     #
     # * The right-to-left layout (using align = :right to fill up from the right and mask_mode =
@@ -92,18 +93,42 @@ module HexaPDF
     #
     #     #>pdf-composer100
     #     composer.container do |container|
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-dark",
-    #                                               mask_mode: :fill_vertical, align: :right})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue",
-    #                                               mask_mode: :fill_vertical, align: :right})
-    #       container.box(:base, width: 20, style: {background_color: "hp-blue-light",
-    #                                               mask_mode: :fill_vertical, align: :right})
+    #       container.box(width: 20, style: {background_color: "hp-blue-dark",
+    #                                        mask_mode: :fill_vertical, align: :right})
+    #       container.box(width: 20, style: {background_color: "hp-blue",
+    #                                        mask_mode: :fill_vertical, align: :right})
+    #       container.box(width: 20, style: {background_color: "hp-blue-light",
+    #                                        mask_mode: :fill_vertical, align: :right})
     #     end
     class ContainerBox < Box
 
       # The child boxes of this ContainerBox. They need to be finalized before #fit is called.
       attr_reader :children
 
+      # Specifies whether the container box allows splitting its content.
+      #
+      # If splitting is not allowed (the default), all child boxes must fit together into one
+      # region.
+      #
+      # Examples:
+      #
+      #   # Fails with an error because the content of the container box is too big
+      #   composer.column do |col|
+      #     col.container do |container|
+      #       container.lorem_ipsum
+      #     end
+      #   end
+      #
+      # ---
+      #
+      #   #>pdf-composer
+      #   composer.column do |col|
+      #     col.container(splitable: true) do |container|
+      #       container.lorem_ipsum
+      #     end
+      #   end
+      attr_reader :splitable
+
       # Creates a new container box, optionally accepting an array of child boxes.
       #
       # Example:
@@ -117,9 +142,10 @@ module HexaPDF
       #     container.text("here", mask_mode: :fill_vertical, valign: :bottom)
       #   end
       #   composer.text("Another paragraph")
-      def initialize(children: [], **kwargs)
+      def initialize(children: [], splitable: false, **kwargs)
         super(**kwargs)
         @children = children
+        @splitable = splitable
       end
 
       # Returns +true+ if no box was fitted into the container.
@@ -144,9 +170,18 @@ module HexaPDF
           end
           update_content_height { @box_fitter.content_heights.max }
           fit_result.success!
+        elsif !@box_fitter.fit_results.empty? && @splitable
+          fit_result.overflow!
         end
       end
 
+      # Splits the content of the container box. This method is called from Box#split.
+      def split_content
+        box = create_split_box
+        box.instance_variable_set(:@children, @box_fitter.remaining_boxes)
+        [self, box]
+      end
+
       # Draws the children onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
         dx = x - @fit_x

data/lib/hexapdf/layout/style.rb

@@ -150,14 +150,15 @@ module HexaPDF
         end
 
         # :call-seq:
-        #   quad.set(value)
-        #   quad.set(array)
-        #   quad.set(quad)
+        #   quad.set(value)     -> quad
+        #   quad.set(array)     -> quad
+        #   quad.set(hash)      -> quad
+        #   quad.set(quad)      -> quad
         #
-        # Sets all values of the quad.
+        # Sets all values of the quad and returns it.
         #
-        # * If a single value is provided that is neither a Quad nor an array, it is handled as if
-        #   an array with one value was given.
+        # * If a single value is provided that is neither a Quad nor an array nor a hash, it is
+        #   handled as if an array with one value was given.
         #
         # * If a Quad is provided, its values are used.
         #
@@ -170,6 +171,9 @@ module HexaPDF
         #     third value.
         #   * Four or more values: Top is set to the first, right to the second, bottom to the third
         #     and left to the fourth value.
+        #
+        # * If a hash is provided, the keys +:top+, +:bottom+, +:left+ and +:right+ are used to set
+        #   the respective value. All unspecified keys that have not been set before are set to 0.
         def set(obj)
           case obj
           when Quad
@@ -182,9 +186,15 @@ module HexaPDF
             @bottom = obj[2] || obj[0]
             @left = obj[3] || obj[1] || obj[0]
             @right = obj[1] || obj[0]
+          when Hash
+            @top = obj[:top] || @top || 0
+            @bottom = obj[:bottom] || @bottom || 0
+            @left = obj[:left] || @left || 0
+            @right = obj[:right] || @right || 0
           else
             @top = @bottom = @left = @right = obj
           end
+          self
         end
 
         # Returns +true+ if the quad effectively contains only one value.
@@ -398,6 +408,9 @@ module HexaPDF
       # bottom-left corner of the box during the drawing operations.
       class Layers
 
+        # The array holding all raw layer definitions.
+        attr_reader :layers
+
         # Creates a new Layers object popuplated with the given +layers+.
         def initialize(layers = nil)
           @layers = []
@@ -603,11 +616,36 @@ module HexaPDF
       #   style.update(**properties)    -> style
       #
       # Updates the style's properties using the key-value pairs specified by the +properties+ hash.
+      #
+      # Also see: #merge
       def update(**properties)
         properties.each {|key, value| send(key, value) }
         self
       end
 
+      # Yields all set properties.
+      def each_property # :yield: property, value
+        return to_enum(__method__) unless block_given?
+        instance_variables.each do |iv|
+          (val = PROPERTIES[iv]) && yield(val, instance_variable_get(iv))
+        end
+      end
+
+      # :call-seq:
+      #   style.merge(other_style)   -> style
+      #
+      # Merges the set properties of the +other_style+ object into this one.
+      #
+      # Note that merging is done on a per-property basis. So if a complex property is set on
+      # +other_style+ and also on +self+, the +other_style+ value completely overwrites the one from
+      # +self+.
+      #
+      # Also see: #update
+      def merge(other)
+        other.each_property {|property, value| send(property, value) }
+        self
+      end
+
       ##
       # :method: font
       # :call-seq:
@@ -615,8 +653,9 @@ module HexaPDF
       #
       # The font to be used, must be set to a valid font wrapper object before it can be used.
       #
-      # HexaPDF::Composer handles this property specially in that it resolves a set string or array
-      # to a font wrapper object before doing anything else with the style object.
+      # HexaPDF::Document::Layout handles this property - together with #font_bold and #font_italic
+      # - specially in that it resolves a set string or array to a font wrapper object before doing
+      # anything else with the style object.
       #
       # This is the only style property without a default value!
       #
@@ -633,6 +672,48 @@ module HexaPDF
       #   composer.text("Courier Bold", font: "Courier bold")
       #   composer.text("Courier Bold also", font: ["Courier", variant: :bold])
 
+      ##
+      # :method: font_bold
+      # :call-seq:
+      #   font_bold(bold = false)
+      #
+      # Specifies whether the bold variant of the font is used.
+      #
+      # Note that this property only has affect if #font is not already set to a font wrapper
+      # object and if it is set explicitly (i.e. #font_bold? returns +true+).
+      #
+      # See #font, #font_italic
+      #
+      # Examples:
+      #
+      #   #>pdf-composer100
+      #   composer.text("Helvetica bold", font: "Helvetica", font_bold: true)
+      #
+      #   helvetica_bold = composer.document.fonts.add("Helvetica", variant: :bold)
+      #   composer.text("Helvetica bold", font: helvetica_bold, font_bold: false)
+      #   composer.text("Helvetica", font: ["Helvetica", {variant: :bold}], font_bold: false)
+
+      ##
+      # :method: font_italic
+      # :call-seq:
+      #   font_italic(bold = false)
+      #
+      # Specifies whether the italic variant of the font is used.
+      #
+      # Note that this property only has affect if #font is not already set to a font wrapper
+      # object and if it is set explicitly (i.e. #font_italic? returns +true+).
+      #
+      # See #font, #font_bold.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer100
+      #   composer.text("Helvetica italic", font: "Helvetica", font_italic: true)
+      #
+      #   helvetica_bold = composer.document.fonts.add("Helvetica", variant: :italic)
+      #   composer.text("Helvetica italic", font: helvetica_bold, font_italic: false)
+      #   composer.text("Helvetica", font: ["Helvetica", {variant: :italic}], font_italic: false)
+
       ##
       # :method: font_size
       # :call-seq:
@@ -1021,7 +1102,7 @@ module HexaPDF
       #
       # This method can set the line spacing in two ways:
       #
-      # * Using two positional arguments +type+ and +value+.
+      # * Using the positional, mandatory argument +type+ and the optional +value+.
       # * Or a hash with the keys +type+ and +value+.
       #
       # Note that the last line has no additional spacing after it by default. Set #last_line_gap
@@ -1422,8 +1503,33 @@ module HexaPDF
       #   composer.text("This is some longer text that does not appear in two lines.",
       #                 height: 15, overflow: :truncate)
 
-      [
+      ##
+      # :method: box_options
+      # :call-seq:
+      #   box_options(**options)
+      #
+      # Contains initialization arguments for the box instance that is created with this
+      # style. Together with the other style properties this allows the complete specification of a
+      # box instance just via a Style instance.
+      #
+      # Note that this property is only used by the HexaPDF::Document::Layout methods when a box
+      # instance is created. If a box instance is created directly, this property has no effect.
+      #
+      # Examples:
+      #
+      #   #>pdf-composer100
+      #   composer.style(:my_list, box_options: {marker_type: :decimal, item_spacing: 15})
+      #   composer.list(style: :my_list) do |list|
+      #     list.text("This is some text.")
+      #     list.text("This is some other text.")
+      #   end
+
+
+      # :nodoc:
+      PROPERTIES = [
         [:font, "raise HexaPDF::Error, 'No font set'"],
+        [:font_bold, false],
+        [:font_italic, false],
         [:font_size, 10],
         [:line_height, nil],
         [:character_spacing, 0],
@@ -1434,10 +1540,10 @@ module HexaPDF
         [:text_rendering_mode, "Content::TextRenderingMode::FILL",
          {setter: "Content::TextRenderingMode.normalize(value)"}],
         [:subscript, false,
-         {setter: "value; superscript(false) if superscript",
+         {setter: "value; superscript(false) if value && superscript? && superscript",
           valid_values: [true, false]}],
         [:superscript, false,
-         {setter: "value; subscript(false) if subscript",
+         {setter: "value; subscript(false) if value && subscript? && subscript",
           valid_values: [true, false]}],
         [:underline, false, {valid_values: [true, false]}],
         [:strikeout, false, {valid_values: [true, false]}],
@@ -1457,15 +1563,17 @@ module HexaPDF
         [:text_valign, :top, {valid_values: [:top, :center, :bottom]}],
         [:text_indent, 0],
         [:line_spacing, "LineSpacing.new(type: :single)",
-         {setter: "LineSpacing.new(**(value.kind_of?(Symbol) || value.kind_of?(Numeric) ? " \
-           "{type: value, value: extra_arg} : value))",
+         {setter: "LineSpacing.new(**(value.kind_of?(Symbol) || value.kind_of?(Numeric) || " \
+           "value.kind_of?(LineSpacing) ? {type: value, value: extra_arg} : value))",
           extra_args: ", extra_arg = nil"}],
         [:last_line_gap, false, {valid_values: [true, false]}],
         [:fill_horizontal, nil],
         [:background_color, nil],
         [:background_alpha, 1],
-        [:padding, "Quad.new(0)", {setter: "Quad.new(value)"}],
-        [:margin, "Quad.new(0)", {setter: "Quad.new(value)"}],
+        [:padding, "Quad.new(0)",
+         {setter: "value.kind_of?(Hash) && @name ? @name.set(value) : Quad.new(value)"}],
+        [:margin, "Quad.new(0)",
+         {setter: "value.kind_of?(Hash) && @name ? @name.set(value) : Quad.new(value)"}],
         [:border, "Border.new", {setter: "Border.new(**value)"}],
         [:overlays, "Layers.new", {setter: "Layers.new(value)"}],
         [:underlays, "Layers.new", {setter: "Layers.new(value)"}],
@@ -1475,6 +1583,7 @@ module HexaPDF
         [:mask_mode, :default, {valid_values: [:default, :none, :box, :fill_horizontal,
                                                :fill_frame_horizontal, :fill_vertical, :fill]}],
         [:overflow, :error],
+        [:box_options, {}],
       ].each do |name, default, options = {}|
         default = default.inspect unless default.kind_of?(String)
         setter = options.delete(:setter) || "value"
@@ -1500,7 +1609,7 @@ module HexaPDF
           end
         EOF
         alias_method("#{name}=", name)
-      end
+      end.each_with_object({}) {|arr, hash| hash[:"@#{arr.first}"] = arr.first }
 
       ##
       # :method: text_segmentation_algorithm
@@ -1547,9 +1656,9 @@ module HexaPDF
 
       # The calculated text rise, taking superscript and subscript into account.
       def calculated_text_rise
-        if superscript
+        if superscript? && superscript
           text_rise + font_size * 0.33
-        elsif subscript
+        elsif subscript? && subscript
           text_rise - font_size * 0.20
         else
           text_rise
@@ -1558,7 +1667,7 @@ module HexaPDF
 
       # The calculated font size, taking superscript and subscript into account.
       def calculated_font_size
-        (superscript || subscript ? 0.583 : 1) * font_size
+        ((superscript? && superscript) || (subscript? && subscript) ? 0.583 : 1) * font_size
       end
 
       # Returns the correct offset from the baseline for the underline.

data/lib/hexapdf/layout/table_box.rb

@@ -126,6 +126,15 @@ module HexaPDF
     #           [layout.text('E'), layout.text('F')]]
     #  composer.column(height: 90) {|col| col.table(cells, header: header, footer: footer) }
     #
+    # While the width of a cell is determined by the #column_widths array, the height is
+    # automatically determined during fitting of the content. However, it is also possible to use a
+    # fixed height (only if the actual content is smaller or equal than it):
+    #
+    #  #>pdf-composer
+    #  cells = [[{content: layout.text('A'), height: 5}, layout.text('B')],
+    #           [{content: layout.text('C'), height: 40}, layout.text('D')]]
+    #  composer.table(cells)
+    #
     # The cells can be styled using a callable object for more complex styling:
     #
     #  #>pdf-composer
@@ -191,13 +200,14 @@ module HexaPDF
         attr_accessor :children
 
         # Creates a new Cell instance.
-        def initialize(row:, column:, children: nil, row_span: nil, col_span: nil, **kwargs)
+        def initialize(row:, column:, children: nil, min_height: nil, row_span: nil, col_span: nil, **kwargs)
           super(**kwargs, width: 0, height: 0)
           @children = children
           @row = row
           @column = column
           @row_span = row_span || 1
           @col_span = col_span || 1
+          @min_height = min_height
           style.border.width.set(1) unless style.border?
           style.border.draw_on_bounds = true
           style.padding.set(5) unless style.padding?
@@ -257,6 +267,11 @@ module HexaPDF
             @fit_results = []
             fit_result.success!
           end
+
+          if @min_height && @height < @min_height
+            @height = @preferred_height = @min_height
+            fit_result.failure! if available_height < @height
+          end
         end
 
         # Draws the content of the cell.
@@ -298,6 +313,8 @@ module HexaPDF
       #
       #   +:col_span+:: An integer specifying the number of columsn this cell should span.
       #
+      #   +:min_height+:: A number specifying the minimum height of the table cell.
+      #
       #   +:properties+:: A hash of properties (see Box#properties) to be set on the cell itself.
       #
       #   All other key-value pairs are taken to be cell styling information (like
@@ -513,11 +530,12 @@ module HexaPDF
                 children = content.delete(:content)
                 row_span = content.delete(:row_span)
                 col_span = content.delete(:col_span)
+                min_height = content.delete(:min_height)
                 properties = content.delete(:properties)
                 style = content
               end
               cell = Cell.new(children: children, row: row_index, column: col_index,
-                              row_span: row_span, col_span: col_span)
+                              row_span: row_span, col_span: col_span, min_height: min_height)
               cell_style_block&.call(cell)
               cell.style.update(**style) if style
               cell.properties.update(properties) if properties

data/lib/hexapdf/object.rb

@@ -305,8 +305,8 @@ module HexaPDF
       result
     rescue HexaPDF::Error
       raise
-    rescue StandardError
-      yield("Error: Unexpected value encountered", false, self) if block_given?
+    rescue StandardError => e
+      yield("Unexpected error encountered: #{e.message}", false, self) if block_given?
       false
     end
 

data/lib/hexapdf/pdf_array.rb

@@ -143,10 +143,32 @@ module HexaPDF
     #   array.reject! {|item| block }   -> array or nil
     #   array.reject!                   -> Enumerator
     #
-    # Deletes all elements from the array for which the block returns +true+. If no changes were
-    # done, returns +nil+.
+    # Deletes all elements from the array for which the block returns +true+ and returns +self+. If
+    # no changes were done, returns +nil+.
     def reject!
-      value.reject! {|item| yield(process_entry(item)) }
+      return to_enum(__method__) unless block_given?
+      value.reject! {|item| yield(process_entry(item)) } && self
+    end
+
+    # :call-seq:
+    #   array.map! {|item| block }   -> array
+    #   array.map!                   -> Enumerator
+    #
+    # Maps all elements from the array in-place to the respective return value of the block+ and
+    # returns +self+.
+    def map!
+      return to_enum(__method__) unless block_given?
+      value.map! {|item| yield(process_entry(item)) }
+      self
+    end
+
+    # :call-seq:
+    #   array.compact!   -> array or nil
+    #
+    # Removes all +nil+ elements from the array. Returns +self+ if any elements were removed, +nil+
+    # otherwise.
+    def compact!
+      value.compact! && self
     end
 
     # :call-seq:

data/lib/hexapdf/tokenizer.rb

@@ -278,6 +278,9 @@ module HexaPDF
 
     REFERENCE_RE = /[#{WHITESPACE}]+([+]?\d+)[#{WHITESPACE}]+R#{WHITESPACE_OR_DELIMITER_RE}/ # :nodoc:
 
+    WHITESPACE_OR_DELIMITER_LUT = [] # :nodoc:
+    (WHITESPACE + DELIMITER).each_byte {|x| WHITESPACE_OR_DELIMITER_LUT[x] = true }
+
     # Parses the number (integer or real) at the current position.
     #
     # See: PDF2.0 s7.3.3
@@ -285,7 +288,7 @@ module HexaPDF
       prepare_string_scanner(40)
       pos = self.pos
       if (tmp = @ss.scan_integer)
-        if @ss.eos? || @ss.match?(WHITESPACE_OR_DELIMITER_RE)
+        if @ss.eos? || WHITESPACE_OR_DELIMITER_LUT[@ss.peek_byte]
           # Handle object references, see PDF2.0 s7.3.10
           prepare_string_scanner(10)
           if @ss.scan(REFERENCE_RE)