hexapdf 0.43.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24f6839e903fd945678915625b1e2ef6a12221f29a82cf1c7a6d8bcea38af288
-  data.tar.gz: 2f8309e2ef2406dd279e00643bf7fbf73ded63a1076c0067684a356fea8ee89e
+  metadata.gz: 3b30b54b90222fbcc5469b23153efc4b15083797f527af6c5b34b3f6e161832d
+  data.tar.gz: 969c67ab85591e3b7ccad17023bd3bc820ea5effa4c01e53d254915ab1626d71
 SHA512:
-  metadata.gz: 8c6ddd8ec6f19d39daa9a6422fdb3595d255b528fb93ca7907ef12dab0eca23c74de9fcfc27d02c15b3a9d3c24d47c7f7db6ea472f4c1ed34c2b7c06d4a8a351
-  data.tar.gz: 1d77c2da70d9048cbef6935afacde40fb6d4041414fce571a331a4bee33b0e3ee2ff59bb28eee02e515798c3c156a57f42f139356e946f64e878ea962756a1d8
+  metadata.gz: b60934dd6534ccd019953b278fa188b77996634b3e3878332302b9a2acccfd13b493b57432cff2113b7cc7727f028f24301c2d050f9b908c1b43cf66fbdeebfd
+  data.tar.gz: fdd792109306bc7cf0e30bb2da770e58e81e333843e3c785a9a31873a296b7d027121b467b54a80405332735e99bdaf6b0d167c9eaf08dbc04a26922b890bb51

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.44.0 - 2024-06-05
+
+### Added
+
+* Support for specifying the MIME type when embedding files
+* Support for adding custom XMP metadata
+
+### Changed
+
+* **Breaking change**: Refactored the box implementation of the document layout
+  system
+
+### Fixed
+
+* Parsing of invalid files with garbage bytes at the end
+
+
 ## 0.43.0 - 2024-05-26
 
 ### Added

data/examples/030-pdfa.rb

@@ -8,6 +8,7 @@
 # Usage:
 # : `ruby pdfa.rb`
 #
+
 require 'hexapdf'
 
 HexaPDF::Composer.create('pdfa.pdf') do |composer|

data/lib/hexapdf/composer.rb

@@ -425,6 +425,7 @@ module HexaPDF
           if draw_box
             @frame.draw(@canvas, result)
             drawn_on_page = true
+            (box = draw_box; break) unless box
           elsif !@frame.find_next_region
             unless drawn_on_page
               raise HexaPDF::Error, "Box doesn't fit on empty page"

data/lib/hexapdf/document/files.rb

@@ -70,6 +70,9 @@ module HexaPDF
       # description::
       #     A description of the file.
       #
+      # mime_type::
+      #     The MIME type that should be set for embedded files (so only used if +embed+ is +true+).
+      #
       # embed::
       #     When an IO object is given, it is always embedded and this option is ignored.
       #
@@ -77,7 +80,7 @@ module HexaPDF
       #     only a reference to it is stored.
       #
       # See: HexaPDF::Type::FileSpecification
-      def add(file_or_io, name: nil, description: nil, embed: true)
+      def add(file_or_io, name: nil, description: nil, mime_type: nil, embed: true)
         name ||= File.basename(file_or_io) if file_or_io.kind_of?(String)
         if name.nil?
           raise ArgumentError, "The name argument is mandatory when given an IO object"
@@ -86,7 +89,9 @@ module HexaPDF
         spec = @document.add({Type: :Filespec})
         spec.path = name
         spec[:Desc] = description if description
-        spec.embed(file_or_io, name: name, register: true) if embed || !file_or_io.kind_of?(String)
+        if embed || !file_or_io.kind_of?(String)
+          spec.embed(file_or_io, name: name, mime_type: mime_type, register: true)
+        end
         spec
       end
 

data/lib/hexapdf/document/metadata.rb

@@ -161,6 +161,7 @@ module HexaPDF
         @properties = PREDEFINED_PROPERTIES.transform_values(&:dup)
         @default_language = document.catalog[:Lang] || 'x-default'
         @metadata = Hash.new {|h, k| h[k] = {} }
+        @custom_metadata = []
         write_info_dict(true)
         write_metadata_stream(true)
         @document.register_listener(:complete_objects, &method(:write_metadata))
@@ -248,6 +249,16 @@ module HexaPDF
         end
       end
 
+      # Adds the given +data+ string as custom metadata to the XMP document.
+      #
+      # The +data+ string must contain a fully valid 'rdf:Description' element.
+      #
+      # Using this method allows adding metadata like PDF/A schema definitions for which there is no
+      # direct support by HexaPDF.
+      def custom_metadata(data)
+        @custom_metadata << data
+      end
+
       # :call-seq:
       #   metadata.delete
       #   metadata.delete(ns_prefix)
@@ -469,7 +480,7 @@ module HexaPDF
           <?xpacket begin="\u{FEFF}" id="#{SecureRandom.uuid.tr('-', '')}"?>
           <x:xmpmeta xmlns:x="adobe:ns:meta/">
           <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
-          #{data}
+          #{data}#{@custom_metadata.empty? ? '' : "\n#{@custom_metadata.join("\n")}"}
           </rdf:RDF>
           </x:xmpmeta>
           <?xpacket end="r"?>

data/lib/hexapdf/layout/box.rb

@@ -61,9 +61,9 @@ module HexaPDF
     # instantiated from the common convenience method HexaPDF::Document::Layout#box. To use this
     # facility subclasses need to be registered with the configuration option 'layout.boxes.map'.
     #
-    # The methods #supports_position_flow?, #empty?, #fit or #fit_content, #split or #split_content,
-    # and #draw or #draw_content need to be customized according to the subclass's use case (also
-    # see the documentation of the methods besides the informatione below):
+    # The methods #supports_position_flow?, #empty?, #fit_content, #split_content, and #draw_content
+    # need to be customized according to the subclass's use case (also see the documentation of the
+    # methods besides the information below):
     #
     # #supports_position_flow?::
     #     If the subclass supports the value :flow of the 'position' style property, this method
@@ -72,25 +72,22 @@ module HexaPDF
     # #empty?::
     #     This method should return +true+ if the subclass won't draw anything when #draw is called.
     #
-    # #fit::
-    #     This method should return +true+ if fitting was successful. Additionally, the
-    #     @fit_successful instance variable needs to be set to the fit result as it is used in
-    #     #split.
+    # #fit_content::
+    #     This method determines whether the box fits into the available region and should set the
+    #     status of #fit_result appropriately.
     #
-    #     The default implementation provides code common to most use-cases and delegates the
-    #     specifics to the #fit_content method which needs to return +true+ if fitting was
-    #     successful.
+    #     It is called from the #fit method which should not be overridden in most cases. The
+    #     default implementations of both methods provide code common to all use-cases and delegates
+    #     the specifics to the subclass-specific #fit_content method.
     #
-    # #split::
-    #     This method splits the content so that the current region is used as good as possible. The
-    #     default implementation should be fine for most use-cases, so only #split_content needs to
-    #     be implemented. The method #create_split_box should be used for getting a basic cloned
-    #     box.
+    # #split_content::
+    #     This method is called from #split which handles the common cases based on the status of
+    #     the #fit_result. It needs to handle the case when only some part of the box fits. The
+    #     method #create_split_box should be used for getting a basic cloned box.
     #
-    # #draw::
-    #     This method draws the content and the default implementation already handles things like
-    #     drawing the border and background. So it should not be overridden. The box specific
-    #     drawing commands should be implemented in the #draw_content method.
+    # #draw_content::
+    #     This method draws the box specific content and is called from #draw which already handles
+    #     things like drawing the border and background. So #draw should usually not be overridden.
     #
     # This base class provides various private helper methods for use in the above methods:
     #
@@ -118,6 +115,104 @@ module HexaPDF
 
       include HexaPDF::Utils
 
+      # Stores the result of fitting a box in a frame.
+      class FitResult
+
+        # The box that was fitted into the frame.
+        attr_accessor :box
+
+        # The frame into which the box was fitted.
+        attr_accessor :frame
+
+        # The horizontal position where the box will be drawn.
+        attr_accessor :x
+
+        # The vertical position where the box will be drawn.
+        attr_accessor :y
+
+        # The rectangle (a Geom2D::Rectangle object) that will be removed from the frame when
+        # drawing the box.
+        attr_accessor :mask
+
+        # The status result of fitting the box in the frame.
+        #
+        # Allowed values are:
+        #
+        # +:failure+:: (default) Indicates fitting the box has failed.
+        # +:success+:: Indicates that the box was completely fitted.
+        # +:overflow+:: Indicates that only a part of the box was fitted.
+        attr_reader :status
+
+        # Initializes the result object for the given box and, optionally, frame.
+        def initialize(box, frame: nil)
+          @box = box
+          reset(frame)
+        end
+
+        # Resets the result object.
+        def reset(frame)
+          @frame = frame
+          @x = @y = @mask = nil
+          @status = :failure
+          self
+        end
+
+        # Sets the result status to success.
+        def success!
+          @status = :success
+        end
+
+        # Returns +true+ if fitting was successful.
+        def success?
+          @status == :success
+        end
+
+        # Sets the result status to overflow.
+        def overflow!
+          @status = :overflow
+        end
+
+        # Returns +true+ if only parts of the box were fitted.
+        def overflow?
+          @status == :overflow
+        end
+
+        # Returns +true+ if fitting was a failure.
+        def failure?
+          @status == :failure
+        end
+
+        # Draws the #box onto the canvas at (#x + *dx*, #y + *dy*).
+        #
+        # The relative offset (dx, dy) is useful when rendering results that were accumulated and
+        # then need to be moved because the container holding them changes its position.
+        #
+        # The configuration option "debug" can be used to add visual debug output with respect to
+        # box placement.
+        def draw(canvas, dx: 0, dy: 0)
+          return if box.height == 0 || box.width == 0
+          doc = canvas.context.document
+          if doc.config['debug']
+            name = (frame.parent_boxes + [box]).map do |box|
+              box.class.to_s.sub(/.*::/, '')
+            end.join('-') << "##{box.object_id}"
+            name = "#{name} (#{(x + dx).to_i},#{(y + dy).to_i}-#{mask.width.to_i}x#{mask.height.to_i})"
+            ocg = doc.optional_content.ocg(name)
+            canvas.optional_content(ocg) do
+              canvas.translate(dx, dy) do
+                canvas.fill_color("green").stroke_color("darkgreen").
+                  opacity(fill_alpha: 0.1, stroke_alpha: 0.2).
+                  draw(:geom2d, object: mask, path_only: true).fill_stroke
+              end
+            end
+            page = "Page #{canvas.context.index + 1}" rescue "XObject"
+            doc.optional_content.default_configuration.add_ocg_to_ui(ocg, path: ['Debug', page])
+          end
+          box.draw(canvas, x + dx, y + dy)
+        end
+
+      end
+
       # Creates a new Box object, using the provided block as drawing block (see ::new).
       #
       # If +content_box+ is +true+, the width and height are taken to mean the content width and
@@ -143,10 +238,15 @@ module HexaPDF
       # The height of the box, including padding and/or borders.
       attr_reader :height
 
+      # The FitResult instance holding the result after a call to #fit.
+      attr_reader :fit_result
+
       # The style to be applied.
       #
       # Only the following properties are used:
       #
+      # * Style#position
+      # * Style#overflow
       # * Style#background_color
       # * Style#background_alpha
       # * Style#padding
@@ -190,7 +290,7 @@ module HexaPDF
         @style = Style.create(style)
         @properties = properties || {}
         @draw_block = block
-        @fit_successful = false
+        @fit_result = FitResult.new(self)
         @split_box = false
       end
 
@@ -217,7 +317,7 @@ module HexaPDF
         height < 0 ? 0 : height
       end
 
-      # Fits the box into the *frame* and returns +true+ if fitting was successful.
+      # Fits the box into the *frame* and returns the #fit_result.
       #
       # The arguments +available_width+ and +available_height+ are the width and height of the
       # current region of the frame, adjusted for this box. The frame itself is provided as third
@@ -225,70 +325,68 @@ module HexaPDF
       #
       # The default implementation uses the given available width and height for the box width and
       # height if they were initially set to 0. Otherwise the intially specified dimensions are
-      # used. Then the #fit_content method is called which allows sub-classes to fit their content.
+      # used. The method returns early if the thus configured box already doesn't fit. Otherwise,
+      # the #fit_content method is called which allows sub-classes to fit their content.
       #
       # The following variables are set that may later be used during splitting or drawing:
       #
       # * (@fit_x, @fit_y): The lower-left corner of the content box where fitting was done. Can be
-      #   used to adjust the drawing position in #draw/#draw_content if necessary.
-      # * @fit_successful: +true+ if fitting was successful.
+      #   used to adjust the drawing position in #draw_content if necessary.
       def fit(available_width, available_height, frame)
+        @fit_result.reset(frame)
         @width = (@initial_width > 0 ? @initial_width : available_width)
         @height = (@initial_height > 0 ? @initial_height : available_height)
-        @fit_successful = float_compare(@width, available_width) <= 0 &&
-          float_compare(@height, available_height) <= 0
-        return unless @fit_successful
+        return @fit_result if style.position != :flow && (float_compare(@width, available_width) > 0 ||
+                                                          float_compare(@height, available_height) > 0)
 
-        @fit_successful = fit_content(available_width, available_height, frame)
+        fit_content(available_width, available_height, frame)
 
         @fit_x = frame.x + reserved_width_left
         @fit_y = frame.y - @height + reserved_height_bottom
 
-        @fit_successful
+        @fit_result
       end
 
       # Tries to split the box into two, the first of which needs to fit into the current region of
-      # the frame, and returns the parts as array.
+      # the frame, and returns the parts as array. The method #fit needs to be called before this
+      # method to correctly set-up the #fit_result.
       #
       # If the first item in the result array is not +nil+, it needs to be this box and it means
       # that even when #fit fails, a part of the box may still fit. Note that #fit should not be
-      # called before #draw on the first box since it is already fitted. If not even a part of this
-      # box fits into the current region, +nil+ should be returned as the first array element.
+      # called again before #draw on the first box since it is already fitted. If not even a part of
+      # this box fits into the current region, +nil+ should be returned as the first array element.
       #
       # Possible return values:
       #
-      # [self]:: The box fully fits into the current region.
+      # [self, nil]:: The box fully fits into the current region.
       # [nil, self]:: The box can't be split or no part of the box fits into the current region.
       # [self, new_box]:: A part of the box fits and a new box is returned for the rest.
       #
-      # This default implementation provides the basic functionality based on the #fit result that
-      # should be sufficient for most subclasses; only #split_content needs to be implemented if
-      # necessary.
-      def split(available_width, available_height, frame)
-        if @fit_successful
-          [self, nil]
-        elsif (style.position != :flow &&
-               (float_compare(@width, available_width) > 0 ||
-                float_compare(@height, available_height) > 0)) ||
-            content_height == 0 || content_width == 0
-          [nil, self]
-        else
-          split_content(available_width, available_height, frame)
+      # This default implementation provides the basic functionality based on the status of the
+      # #fit_result that should be sufficient for most subclasses; only #split_content needs to be
+      # implemented if necessary.
+      def split
+        case @fit_result.status
+        when :overflow then (@initial_height > 0 ? [self, nil] : split_content)
+        when :failure  then [nil, self]
+        when :success  then [self, nil]
         end
       end
 
       # Draws the content of the box onto the canvas at the position (x, y).
       #
-      # The coordinate system is translated so that the origin is at the bottom left corner of the
-      # **content box** during the drawing operations when +@draw_block+ is used.
+      # When +@draw_block+ is used (the block specified when creating the box), the coordinate
+      # system is translated so that the origin is at the bottom left corner of the **content box**.
       #
-      # The block specified when creating the box is invoked with the canvas and the box as
-      # arguments. Subclasses can specify an on-demand drawing method by setting the +@draw_block+
-      # instance variable to +nil+ or a valid block. This is useful to avoid unnecessary set-up
-      # operations when the block does nothing.
-      #
-      # Alternatively, if a #draw_content method is defined, this method is called.
+      # Subclasses should not rely on the +@draw_block+ but implement the #draw_content method. The
+      # coordinates passed to it are also modified to represent the bottom left corner of the
+      # content box but the coordinate system is not translated.
       def draw(canvas, x, y)
+        if @fit_result.overflow? && @initial_height > 0 && style.overflow == :error
+          raise HexaPDF::Error, "Box with limited height doesn't completely fit and " \
+            "style property overflow is set to :error"
+        end
+
         if (oc = properties['optional_content'])
           canvas.optional_content(oc)
         end
@@ -381,12 +479,13 @@ module HexaPDF
 
       # Fits the content of the box and returns whether fitting was successful.
       #
-      # This is just a stub implementation that returns +true+. Subclasses should override it to
-      # provide the box specific behaviour.
+      # This is just a stub implementation that sets the #fit_result status to success if the
+      # content rectangle is not degenerate. Subclasses should override it to provide the box
+      # specific behaviour.
       #
       # See #fit for details.
       def fit_content(_available_width, _available_height, _frame)
-        true
+        fit_result.success! if content_width > 0 && content_height > 0
       end
 
       # Splits the content of the box.
@@ -395,12 +494,12 @@ module HexaPDF
       # the content when it didn't fit.
       #
       # Subclasses that support splitting content need to provide an appropriate implementation and
-      # use #create_split_box to create a cloned box to supply as the second argument.
-      def split_content(_available_width, _available_height, _frame)
+      # use #create_split_box to create a cloned box to supply as the second return argument.
+      def split_content
         [nil, self]
       end
 
-      # Draws the content of the box at position [x, y] which is the bottom-left corner of the
+      # Draws the content of the box at position [x, y] which is the bottom left corner of the
       # content box.
       #
       # This implementation uses the drawing block provided on initialization, if set, to draw the
@@ -422,7 +521,7 @@ module HexaPDF
         box = clone
         box.instance_variable_set(:@width, @initial_width)
         box.instance_variable_set(:@height, @initial_height)
-        box.instance_variable_set(:@fit_successful, nil)
+        box.instance_variable_set(:@fit_result, FitResult.new(box))
         box.instance_variable_set(:@split_box, split_box_value)
         box
       end

data/lib/hexapdf/layout/box_fitter.rb

@@ -111,6 +111,7 @@ module HexaPDF
               @content_heights[@frame_index] = [@content_heights[@frame_index],
                                                 @initial_frame_y[@frame_index] - result.mask.y].max
               @fit_results << result
+              break unless box
             elsif !current_frame.find_next_region
               @frame_index += 1
             end

data/lib/hexapdf/layout/column_box.rb

@@ -138,31 +138,29 @@ module HexaPDF
         super && (!@box_fitter || @box_fitter.fit_results.empty?)
       end
 
+      private
+
       # Fits the column box into the current region of the frame.
       #
-      # If the style property 'position' is set to :flow, the columns might not be rectangles but
-      # arbitrary (sets of) polygons since the +frame+s shape is taken into account.
-      def fit(available_width, available_height, frame)
-        return false if @initial_height > available_height || @initial_width > available_width
-
+      def fit_content(available_width, available_height, frame)
         initial_fit_successful = (@equal_height && @columns.size > 1 ? nil : false)
         tries = 0
-        @width = if style.position == :flow
-                   (@initial_width > 0 ? @initial_width : frame.width) - reserved_width
-                 else
-                   (@initial_width > 0 ? @initial_width : available_width) - reserved_width
-                 end
+        width = if style.position == :flow
+                  (@initial_width > 0 ? @initial_width : frame.width) - reserved_width
+                else
+                  (@initial_width > 0 ? @initial_width : available_width) - reserved_width
+                end
         height = if style.position == :flow
-                   (@initial_height > 0 ? @initial_height : frame.height) - reserved_height
+                   (@initial_height > 0 ? @initial_height : frame.y - frame.bottom) - reserved_height
                  else
                    (@initial_height > 0 ? @initial_height : available_height) - reserved_height
                  end
 
-        columns = calculate_columns(@width)
-        return false if columns.empty?
+        columns = calculate_columns(width)
+        return if columns.empty?
 
         left = (style.position == :flow ? frame.left : frame.x) + reserved_width_left
-        top = (style.position == :flow ? frame.bottom + frame.height : frame.y) - reserved_height_top
+        top = frame.y - reserved_height_top
         successful_height = height
         unsuccessful_height = 0
 
@@ -206,16 +204,16 @@ module HexaPDF
           tries += 1
         end
 
-        @width = columns[-1].sum + reserved_width
-        @height = (@initial_height > 0 ? @initial_height : @box_fitter.content_heights.max + reserved_height)
-        @draw_pos_x = frame.x + reserved_width_left
-        @draw_pos_y = frame.y - @height + reserved_height_bottom
+        update_content_width { columns[-1].sum }
+        update_content_height { @box_fitter.content_heights.max }
 
-        @box_fitter.success?
+        if @box_fitter.success?
+          fit_result.success!
+        elsif !@box_fitter.fit_results.empty?
+          fit_result.overflow!
+        end
       end
 
-      private
-
       # Calculates the x-coordinates and widths of all columns based on the given total available
       # width.
       #
@@ -241,7 +239,7 @@ module HexaPDF
       end
 
       # Splits the content of the column box. This method is called from Box#split.
-      def split_content(_available_width, _available_height, _frame)
+      def split_content
         box = create_split_box
         box.instance_variable_set(:@children, @box_fitter.remaining_boxes)
         [self, box]
@@ -249,8 +247,8 @@ module HexaPDF
 
       # Draws the child boxes onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
-        if style.position != :flow && (x != @draw_pos_x || y != @draw_pos_y)
-          canvas.translate(x - @draw_pos_x, y - @draw_pos_y) do
+        if style.position != :flow && (x != @fit_x || y != @fit_y)
+          canvas.translate(x - @fit_x, y - @fit_y) do
             @box_fitter.fit_results.each {|result| result.draw(canvas) }
           end
         else

data/lib/hexapdf/layout/container_box.rb

@@ -143,11 +143,11 @@ module HexaPDF
             children.empty? ? 0 : result.mask.x + result.mask.width - my_frame.left
           end
           update_content_height { @box_fitter.content_heights.max }
-          true
+          fit_result.success!
         end
       end
 
-      # Draws the image onto the canvas at position [x, y].
+      # Draws the children onto the canvas at position [x, y].
       def draw_content(canvas, x, y)
         dx = x - @fit_x
         dy = y - @fit_y