hexapdf 0.42.0 → 0.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd69db2c04dc802784438f9038c9a6ab32dac0806edca43b6c59406bba9d7ea6
-  data.tar.gz: a51a510a6a98b547b2b11fb07804ca9039a666adf95b52f65db9b070c3ffe9c3
+  metadata.gz: 3b30b54b90222fbcc5469b23153efc4b15083797f527af6c5b34b3f6e161832d
+  data.tar.gz: 969c67ab85591e3b7ccad17023bd3bc820ea5effa4c01e53d254915ab1626d71
 SHA512:
-  metadata.gz: 714cba0b758960066498413b545dc7cf2806e1e483f99b017958450bfe29fd12aac1eef40f670d189f7cd7dab5784dd83e7b6f95533b97cf71c883dd9f307485
-  data.tar.gz: c93ceed7393b57fa5c6ca83141a8307b6015a1fa6907886b52c57bf72384d4d23ac8356adede0dabc35578cad5e1cef074f75c94e01e5c9532cadd0a688bbd57
+  metadata.gz: b60934dd6534ccd019953b278fa188b77996634b3e3878332302b9a2acccfd13b493b57432cff2113b7cc7727f028f24301c2d050f9b908c1b43cf66fbdeebfd
+  data.tar.gz: fdd792109306bc7cf0e30bb2da770e58e81e333843e3c785a9a31873a296b7d027121b467b54a80405332735e99bdaf6b0d167c9eaf08dbc04a26922b890bb51

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## 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
+
+* [HexaPDF::Type::AcroForm::Form#create_namespace_field] for creating a pure
+  namespace field
+* [HexaPDF::Type::AcroForm::Form#delete_field] for deleting fields
+
+### Changed
+
+* Minimum Ruby version to be 3.0
+* **Breaking change**: Renamed `HexaPDF::Layout::BoxFitter#fit_successful?` to
+  [HexaPDF::Layout::BoxFitter#success?]
+* **Breaking Change**: Removed HexaPDF::Dictionary#to_h
+* Form field creation methods of [HexaPDF::Type::AcroForm::Form] to
+  automatically create parent fields as namespace fields
+
+### Fixed
+
+* [HexaPDF::Layout::TextBox#fit] to correctly calculate width in case of flowing
+  text around other boxes
+* [HexaPDF::Layout::TextBox#draw] to correctly draw border, background... on
+  boxes using position 'flow'
+* Comparison of Hash with [HexaPDF::Dictionary] objects by implementing
+  `#to_hash`
+* Parsing of invalid files having multiple end-of-file markers with the last one
+  being invalid
+
+
 ## 0.42.0 - 2024-05-12
 
 ### Added

data/Rakefile

@@ -47,7 +47,7 @@ namespace :dev do
   end
 
   task :test_all do
-    versions = `rbenv versions --bare | grep -i ^2.7\\\\\\|^3.`.split("\n")
+    versions = `rbenv versions --bare | grep -i ^3.`.split("\n")
     versions.each do |version|
       sh "eval \"$(rbenv init -)\"; rbenv shell #{version} && ruby -v && rake test"
     end

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/dictionary.rb

@@ -228,9 +228,9 @@ module HexaPDF
       value.empty?
     end
 
-    # Returns a dup of the underlying hash.
-    def to_h
-      value.dup
+    # Returns a hash containing the preprocessed values (like in #[]).
+    def to_hash
+      value.each_with_object({}) {|(k, _), h| h[k] = self[k] }
     end
 
     private

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/document.rb

@@ -278,6 +278,14 @@ module HexaPDF
     # If the same argument is provided in multiple invocations, the import is done only once and
     # the previously imported object is returned.
     #
+    # Note: If you first create a PDF document from scratch and then want to import objects from it
+    # into another PDF document, you need to run the following on the source document:
+    #
+    #   doc.dispatch_message(:complete_objects)
+    #   doc.validate
+    #
+    # This ensures that the source document has all the necessary PDF structures set-up correctly.
+    #
     # See: Importer
     def import(obj)
       source = (obj.kind_of?(HexaPDF::Object) ? obj.document : nil)
@@ -617,13 +625,18 @@ module HexaPDF
     # writing the document.
     #
     # The security handler used for encrypting is selected via the +name+ argument. All other
-    # arguments are passed on the security handler.
+    # arguments are passed on to the security handler.
     #
     # If the document should not be encrypted, the +name+ argument has to be set to +nil+. This
     # removes the security handler and deletes the trailer's Encrypt dictionary.
     #
     # See: Encryption::SecurityHandler#set_up_encryption and
     # Encryption::StandardSecurityHandler::EncryptionOptions for possible encryption options.
+    #
+    # Examples:
+    #
+    #   document.encrypt(name: nil)  # remove the existing encryption
+    #   document.encrypt(algorithm: :aes, key_length: 256, permissions: [:print, :extract_content]
     def encrypt(name: :Standard, **options)
       if name.nil?
         trailer.delete(:Encrypt)

data/lib/hexapdf/encryption.rb

@@ -46,6 +46,23 @@ module HexaPDF
   #
   # This module contains all encryption and security related code to facilitate PDF encryption.
   #
+  # === Working With Encrypted Documents
+  #
+  # When a PDF document is opened, an encryption password can be specified. This is necessary if a
+  # user password is set on the file and optional otherwise (because the default password is
+  # automatically tried):
+  #
+  #   HexaPDF::Document.open(filename, decryption_opts: {password: 'somepassword'}) do |doc|
+  #   end
+  #
+  # To remove the encryption from a PDF document, use the following:
+  #
+  #   document.encrypt(name: nil)
+  #
+  # To encrypt a PDF document, use the same method but specify the required encryption options:
+  #
+  #   document.encrypt(algorithm: :aes, key_length: 256)
+  #
   #
   # === Security Handlers
   #

data/lib/hexapdf/layout/box.rb

@@ -35,6 +35,7 @@
 #++
 require 'hexapdf/layout/style'
 require 'geom2d/utils'
+require 'hexapdf/utils'
 
 module HexaPDF
   module Layout
@@ -60,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
@@ -71,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:
     #
@@ -117,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
@@ -142,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
@@ -189,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
 
@@ -216,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
@@ -224,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
@@ -380,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.
@@ -394,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
@@ -421,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

@@ -47,8 +47,8 @@ module HexaPDF
     #
     # * Then use the #fit method to fit boxes one after the other. No drawing is done.
     #
-    # * Once all boxes have been fitted, the #fit_results, #remaining_boxes and #fit_successful?
-    #   methods can be used to get the result:
+    # * Once all boxes have been fitted, the #fit_results, #remaining_boxes and #success? methods
+    #   can be used to get the result:
     #
     #   - If there are no remaining boxes, all boxes were successfully fitted into the frames.
     #   - If there are remaining boxes but no fit results, the first box could not be fitted.
@@ -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
@@ -126,7 +127,7 @@ module HexaPDF
       end
 
       # Returns +true+ if all boxes were successfully fitted.
-      def fit_successful?
+      def success?
         @remaining_boxes.empty?
       end