hexapdf 0.41.0 → 0.43.0

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

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.
@@ -126,7 +126,7 @@ module HexaPDF
       end
 
       # Returns +true+ if all boxes were successfully fitted.
-      def fit_successful?
+      def success?
         @remaining_boxes.empty?
       end
 

data/lib/hexapdf/layout/column_box.rb

@@ -186,7 +186,7 @@ module HexaPDF
 
           children.each {|box| @box_fitter.fit(box) }
 
-          fit_successful = @box_fitter.fit_successful?
+          fit_successful = @box_fitter.success?
           initial_fit_successful = fit_successful if initial_fit_successful.nil?
 
           if fit_successful
@@ -211,7 +211,7 @@ module HexaPDF
         @draw_pos_x = frame.x + reserved_width_left
         @draw_pos_y = frame.y - @height + reserved_height_bottom
 
-        @box_fitter.fit_successful?
+        @box_fitter.success?
       end
 
       private

data/lib/hexapdf/layout/container_box.rb

@@ -137,7 +137,7 @@ module HexaPDF
         @box_fitter = BoxFitter.new([my_frame])
         children.each {|box| @box_fitter.fit(box) }
 
-        if @box_fitter.fit_successful?
+        if @box_fitter.success?
           update_content_width do
             result = @box_fitter.fit_results.max_by {|r| r.mask.x + r.mask.width }
             children.empty? ? 0 : result.mask.x + result.mask.width - my_frame.left

data/lib/hexapdf/layout/line.rb

@@ -173,6 +173,10 @@ module HexaPDF
       attr_accessor :items
 
       # An optional horizontal offset that should be taken into account when positioning the line.
+      #
+      # This offset always describes the offset from the left side (and not, for example, the offset
+      # from the right side of another line even if those two lines are actually on the same
+      # horizontal level).
       attr_accessor :x_offset
 
       # An optional vertical offset that should be taken into account when positioning the line.

data/lib/hexapdf/layout/list_box.rb

@@ -248,14 +248,14 @@ module HexaPDF
           top -= item_result.height + item_spacing
           height -= item_result.height + item_spacing
 
-          break if !box_fitter.fit_successful? || height <= 0
+          break if !box_fitter.success? || height <= 0
         end
 
         @height = @results.sum(&:height) + (@results.count - 1) * item_spacing + reserved_height
 
         @draw_pos_x = frame.x + reserved_width_left
         @draw_pos_y = frame.y - @height + reserved_height_bottom
-        @all_items_fitted = @results.all? {|r| r.box_fitter.fit_successful? } &&
+        @all_items_fitted = @results.all? {|r| r.box_fitter.success? } &&
           @results.size == @children.size
         @fit_successful = @all_items_fitted || (@initial_height > 0 && style.overflow == :truncate)
       end

data/lib/hexapdf/layout/table_box.rb

@@ -233,7 +233,7 @@ module HexaPDF
             @preferred_width = max_x_result.x + max_x_result.box.width + reserved_width
             @height = @preferred_height = box_fitter.content_heights[0] + reserved_height
             @fit_results = box_fitter.fit_results
-            @fit_successful = box_fitter.fit_successful?
+            @fit_successful = box_fitter.success?
           else
             @preferred_width = reserved_width
             @height = @preferred_height = reserved_height

data/lib/hexapdf/layout/text_box.rb

@@ -52,6 +52,7 @@ module HexaPDF
         @tl = TextLayouter.new(style)
         @items = items
         @result = nil
+        @x_offset = 0
       end
 
       # Returns the text that will be drawn.
@@ -80,7 +81,7 @@ module HexaPDF
           (@initial_height > 0 && @initial_height > available_height)
 
         frame = frame.child_frame(box: self)
-        @width = @height = 0
+        @width = @x_offset = @height = 0
         @result = if style.position == :flow
                     @tl.fit(@items, frame.width_specification, frame.shape.bbox.height,
                             apply_first_text_indent: !split_box?, frame: frame)
@@ -93,6 +94,14 @@ module HexaPDF
                   end
         @width += if @initial_width > 0 || style.text_align == :center || style.text_align == :right
                     width
+                  elsif style.position == :flow
+                    min_x = +Float::INFINITY
+                    max_x = -Float::INFINITY
+                    @result.lines.each do |line|
+                      min_x = [min_x, line.x_offset].min
+                      max_x = [max_x, line.x_offset + line.width].max
+                    end
+                    min_x.finite? ? (@x_offset = min_x; max_x - min_x) : 0
                   else
                     @result.lines.max_by(&:width)&.width || 0
                   end
@@ -125,6 +134,11 @@ module HexaPDF
         end
       end
 
+      # :nodoc:
+      def draw(canvas, x, y)
+        super(canvas, x + @x_offset, y)
+      end
+
       # :nodoc:
       def empty?
         super && (!@result || @result.lines.empty?)
@@ -142,7 +156,7 @@ module HexaPDF
         end
 
         return if @result.lines.empty?
-        @result.draw(canvas, x, y + content_height)
+        @result.draw(canvas, x - @x_offset, y + content_height)
       end
 
       # Creates a new TextBox instance for the items remaining after fitting the box.

data/lib/hexapdf/parser.rb

@@ -362,29 +362,32 @@ module HexaPDF
         pos = @io.pos
         lines = @io.read(step_size + 40).split(/[\r\n]+/)
 
-        eof_index = lines.rindex {|l| l.strip == '%%EOF' }
-        if !eof_index
-          eof_not_found = true
-        elsif lines[eof_index - 1].strip =~ /\Astartxref\s(\d+)\z/
-          startxref_offset = $1.to_i
-          startxref_mangled = true
-          break # we found it even if it the syntax is not entirely correct
-        elsif eof_index < 2 || lines[eof_index - 2].strip != "startxref"
-          startxref_missing = true
-        else
-          startxref_offset = lines[eof_index - 1].to_i
-          break # we found it
+        # Need to iterate through the whole lines array in case there are multiple %%EOF to try
+        eof_index = 0
+        while (eof_index = lines[0..(eof_index - 1)].rindex {|l| l.strip == '%%EOF' })
+          if lines[eof_index - 1].strip =~ /\Astartxref\s(\d+)\z/
+            startxref_offset = $1.to_i
+            startxref_mangled = true
+            break # we found it even if it the syntax is not entirely correct
+          elsif eof_index < 2 || lines[eof_index - 2].strip != "startxref"
+            startxref_missing = true
+          else
+            startxref_offset = lines[eof_index - 1].to_i
+            break # we found it
+          end
         end
+        eof_not_found ||= !eof_index
+        break if startxref_offset
       end
 
-      if eof_not_found
-        maybe_raise("PDF file trailer with end-of-file marker not found", pos: pos,
-                    force: !eof_index)
-      elsif startxref_mangled
+      if startxref_mangled
         maybe_raise("PDF file trailer keyword startxref on same line as value", pos: pos)
       elsif startxref_missing
         maybe_raise("PDF file trailer is missing startxref keyword", pos: pos,
-                    force: eof_index < 2 || lines[eof_index - 2].strip != "startxref")
+                    force: !startxref_offset)
+      elsif eof_not_found
+        maybe_raise("PDF file trailer with end-of-file marker not found", pos: pos,
+                    force: !startxref_offset)
       end
 
       @startxref_offset = startxref_offset

data/lib/hexapdf/type/acro_form/button_field.rb

@@ -165,14 +165,16 @@ module HexaPDF
         #                nothing is stored for them (e.g a no-op).
         #
         # Check boxes:: Provide +nil+ or +false+ as value to toggle all check box widgets off. If
-        #               there is only one possible value, +true+ may be used for checking the box,
-        #               i.e. toggling it to the on state. Otherwise provide the value (a Symbol or
-        #               an object responding to +#to_sym+) of the check box widget that should be
-        #               toggled on.
+        #               +true+ is provided, all check box widgets with the same name as the first
+        #               one are toggled on. Otherwise provide the value (a Symbol or an object
+        #               responding to +#to_sym+) of the check box widget that should be toggled on.
         #
         # Radio buttons:: To turn all radio buttons off, provide +nil+ as value. Otherwise provide
         #                 the value (a Symbol or an object responding to +#to_sym+) of a radio
         #                 button that should be turned on.
+        #
+        # Note that in most cases the field needs to already have widgets because the value is
+        # checked against the possibly allowed values which depend on the existing widgets.
         def field_value=(value)
           normalized_field_value_set(:V, value)
         end
@@ -303,7 +305,7 @@ module HexaPDF
                       elsif check_box?
                         if value == false
                           :Off
-                        elsif value == true && av.size == 1
+                        elsif value == true && av.size >= 1
                           av[0]
                         elsif av.include?(value.to_sym)
                           value.to_sym

data/lib/hexapdf/type/acro_form/form.rb

@@ -163,10 +163,21 @@ module HexaPDF
           field
         end
 
+        # Creates an untyped namespace field for creating hierarchies.
+        #
+        # Example:
+        #
+        #   form.create_namespace_field('text')
+        #   form.create_text_field('text.a1')
+        def create_namespace_field(name)
+          create_field(name)
+        end
+
         # Creates a new text field with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field:
         #
@@ -202,8 +213,9 @@ module HexaPDF
 
         # Creates a new multiline text field with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field, see
         # #create_text_field for details.
@@ -221,8 +233,9 @@ module HexaPDF
         # The +max_chars+ argument defines the maximum number of characters the comb text field can
         # accommodate.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field, see
         # #create_text_field for details.
@@ -238,8 +251,9 @@ module HexaPDF
 
         # Creates a new file select field with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field, see
         # #create_text_field for details.
@@ -254,8 +268,9 @@ module HexaPDF
 
         # Creates a new password field with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field, see
         # #create_text_field for details.
@@ -270,24 +285,33 @@ module HexaPDF
 
         # Creates a new check box with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
+        #
+        # Before a field value other than +false+ can be assigned to the check box, a widget needs
+        # to be created.
         def create_check_box(name)
           create_field(name, :Btn, &:initialize_as_check_box)
         end
 
         # Creates a radio button with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
+        #
+        # Before a field value other than +nil+ can be assigned to the radio button, at least one
+        # widget needs to be created.
         def create_radio_button(name)
           create_field(name, :Btn, &:initialize_as_radio_button)
         end
 
         # Creates a combo box with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field:
         #
@@ -313,8 +337,9 @@ module HexaPDF
 
         # Creates a list box with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         #
         # The optional keyword arguments allow setting often used properties of the field:
         #
@@ -339,10 +364,77 @@ module HexaPDF
 
         # Creates a signature field with the given name and adds it to the form.
         #
-        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
-        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        # The +name+ may contain dots to signify a field hierarchy. If the parent fields don't
+        # already exist, they are created as pure namespace fields (see #create_namespace_field). If
+        # the +name+ doesn't contain dots, a top-level field is created.
         def create_signature_field(name)
-          create_field(name, :Sig) {}
+          create_field(name, :Sig)
+        end
+
+        # :call-seq:
+        #    form.delete_field(name)
+        #    form.delete_field(field)
+        #
+        # Deletes the field specified by the given name or via the given field object.
+        #
+        # If the field is a signature field, the associated signature dictionary is also deleted.
+        def delete_field(name_or_field)
+          field = (name_or_field.kind_of?(String) ? field_by_name(name_or_field) : name_or_field)
+          document.delete(field[:V]) if field.field_type == :Sig
+
+          to_delete = field.each_widget(direct_only: false).to_a
+          document.pages.each do |page|
+            next unless page.key?(:Annots)
+            page_annots = page[:Annots].to_a - to_delete
+            page[:Annots].value.replace(page_annots)
+          end
+          to_delete.each {|widget| document.delete(widget) }
+
+          if field[:Parent]
+            field[:Parent][:Kids].delete(field)
+          else
+            self[:Fields].delete(field)
+          end
+          document.delete(field)
+        end
+
+        # Fills form fields with the values from the given +data+ hash.
+        #
+        # The keys of the +data+ hash need to be full field names and the values are the respective
+        # values, usually in string form. It is possible to specify only some of the fields of the
+        # form.
+        #
+        # What kind of values are supported for a field depends on the field type:
+        #
+        # * For fields containing text (single/multiline/comb text fields, file select fields, combo
+        #   boxes and list boxes) the value needs to be a string and it is assigned as is.
+        #
+        # * For check boxes, the values "y"/"yes"/"t"/"true" are handled as assigning +true+ to the
+        #   field, the values "n"/"no"/"f"/"false" are handled as assigning +false+ to the field,
+        #   and every other string value is assigned as is. See ButtonField#field_value= for
+        #   details.
+        #
+        # * For radio buttons the value needs to be a String or a Symbol representing the name of
+        #   the radio button widget to select.
+        def fill(data)
+          data.each do |field_name, value|
+            field = field_by_name(field_name)
+            raise HexaPDF::Error, "AcroForm field named '#{field_name}' not found" unless field
+
+            case field.concrete_field_type
+            when :single_line_text_field, :multiline_text_field, :comb_text_field, :file_select_field,
+                :combo_box, :list_box, :editable_combo_box, :radio_button
+              field.field_value = value
+            when :check_box
+              field.field_value = case value
+                                  when /\A(?:y(es)?|t(rue)?)\z/ then true
+                                  when /\A(?:n(o)?|f(alse)?)\z/ then false
+                                  else value
+                                  end
+            else
+              raise HexaPDF::Error, "AcroForm field type #{field.concrete_field_type} not yet supported"
+            end
+          end
         end
 
         # Returns the dictionary containing the default resources for form field appearance streams.
@@ -440,23 +532,27 @@ module HexaPDF
 
         private
 
-        # Creates a new field with the full name +name+ and the field type +type+.
-        def create_field(name, type)
+        # Creates a new field with the full name +name+ and the optional field type +type+.
+        def create_field(name, type = nil)
           parent_name, _, name = name.rpartition('.')
           parent_field = parent_name.empty? ? nil : field_by_name(parent_name)
           if !parent_name.empty? && !parent_field
-            raise HexaPDF::Error, "Parent field '#{parent_name}' not found"
+            parent_field = create_namespace_field(parent_name)
           end
 
-          field = document.add({FT: type, T: name, Parent: parent_field},
-                               type: :XXAcroFormField, subtype: type)
+          field = if type
+                    document.add({FT: type, T: name, Parent: parent_field},
+                                 type: :XXAcroFormField, subtype: type)
+                  else
+                    document.add({T: name, Parent: parent_field}, type: :XXAcroFormField)
+                  end
           if parent_field
             (parent_field[:Kids] ||= []) << field
           else
             (self[:Fields] ||= []) << field
           end
 
-          yield(field)
+          yield(field) if block_given?
 
           field
         end