hexapdf 0.11.9 → 0.13.0

data/lib/hexapdf/cli/merge.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -122,7 +122,7 @@ module HexaPDF
 
         # Assemble pages
         target = (@initial_empty ? HexaPDF::Document.new : @files.first.file)
-        page_tree = target.add(Type: :Pages)
+        page_tree = target.add({Type: :Pages})
         import_pages(page_tree)
         target.catalog[:Pages] = page_tree
         remove_unused_pages(target)

data/lib/hexapdf/cli/modify.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/cli/optimize.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/cli/split.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/cli/watermark.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/composer.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -297,7 +297,7 @@ module HexaPDF
       style ||= base_style
       style = style.dup.update(**options) unless options.empty?
       style.font(base_style.font) unless style.font?
-      style.font(@document.fonts.add(style.font)) unless style.font.respond_to?(:dict)
+      style.font(@document.fonts.add(style.font)) unless style.font.respond_to?(:pdf_object)
       style
     end
 

data/lib/hexapdf/configuration.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -48,8 +48,9 @@ module HexaPDF
   # easily be changed.
   #
   # Some options are defined as global options because they are needed on the class level - see
-  # HexaPDF::GlobalConfiguration. Other options can be configured for individual documents as they
-  # allow to fine-tune some behavior - see HexaPDF::DefaultDocumentConfiguration.
+  # HexaPDF::GlobalConfiguration[index.html#GlobalConfiguration]. Other options can be configured for
+  # individual documents as they allow to fine-tune some behavior - see
+  # HexaPDF::DefaultDocumentConfiguration[index.html#DefaultDocumentConfiguration].
   #
   # A configuration option name is dot-separted to provide a hierarchy of option names. For
   # example, io.chunk_size.
@@ -144,6 +145,43 @@ module HexaPDF
   #
   # The following options are provided:
   #
+  # acro_form.appearance_generator::
+  #    The class that should be used for generating appearances for AcroForm fields. If the value is
+  #    a String, it should contain the name of a constant to such a class.
+  #
+  #    See HexaPDF::Type::AcroForm::AppearanceGenerator
+  #
+  # acro_form.create_appearances::
+  #    A boolean specifying whether an AcroForm field's appearances should automatically be
+  #    generated if they are missing.
+  #
+  # acro_form.text_field.default_width::
+  #    A number specifying the default width of AcroForm text fields which should be auto-sized.
+  #
+  # acro_form.default_font_size::
+  #    A number specifying the default font size of AcroForm text fields which should be auto-sized.
+  #
+  # acro_form.fallback_font::
+  #    The font that should be used when a variable text field references a font that cannot be used.
+  #
+  #    Can either be the name of a font, like 'Helvetica', or an array consisting of the font name
+  #    and a hash of font options, like ['Helvetica', variant: :italic]. If set to +nil+, the use of
+  #    the fallback font is disabled.
+  #
+  #    Default is 'Helvetica'.
+  #
+  # acro_form.on_invalid_value::
+  #    Callback hook when an invalid value is set for certain types of AcroForm fields.
+  #
+  #    The value needs to be an object that responds to \#call(field, value) where +field+ is the
+  #    AcroForm field on which the value is set and +value+ is the invalid value. The returned value
+  #    is used instead of the invalid value.
+  #
+  #    The default implementation raises an error.
+  #
+  # acro_form.text_field.default_width::
+  #    A number specifying the default width of AcroForm text fields which should be auto-sized.
+  #
   # document.auto_decrypt::
   #    A boolean determining whether the document should be decrypted automatically when parsed.
   #
@@ -296,6 +334,20 @@ module HexaPDF
   #    The value needs to be an object that responds to \#call(document, message, position) and
   #    returns +true+ if an error should be raised.
   #
+  # parser.try_xref_reconstruction::
+  #    A boolean specifying whether non-recoverable parsing errors should lead to reconstructing the
+  #    main cross-reference table.
+  #
+  #    The reconstructed cross-reference table might make damaged files usable but there is no way
+  #    to ensure that the reconstructed file is equal to the undamaged original file (though
+  #    generally it works out).
+  #
+  #    There is also the possibility that reconstructing doesn't work because the algorithm has to
+  #    assume that the PDF was written in a certain way (which is recommended by the PDF
+  #    specification).
+  #
+  #    Defaults to +true+.
+  #
   # sorted_tree.max_leaf_node_size::
   #    The maximum number of nodes that should be in a leaf node of a node tree.
   #
@@ -307,7 +359,16 @@ module HexaPDF
   # task.map::
   #    A mapping from task names to callable task objects. See HexaPDF::Task for more information.
   DefaultDocumentConfiguration =
-    Configuration.new('document.auto_decrypt' => true,
+    Configuration.new('acro_form.appearance_generator' => 'HexaPDF::Type::AcroForm::AppearanceGenerator',
+                      'acro_form.create_appearances' => true,
+                      'acro_form.default_font_size' => 10,
+                      'acro_form.fallback_font' => 'Helvetica',
+                      'acro_form.on_invalid_value' => proc do |field, value|
+                        raise HexaPDF::Error, "Invalid value #{value.inspect} for " \
+                          "#{field.concrete_field_type} field #{field.full_field_name}"
+                      end,
+                      'acro_form.text_field.default_width' => 100,
+                      'document.auto_decrypt' => true,
                       'encryption.aes' => 'HexaPDF::Encryption::FastAES',
                       'encryption.arc4' => 'HexaPDF::Encryption::FastARC4',
                       'encryption.filter_map' => {
@@ -326,12 +387,12 @@ module HexaPDF
                         Fl: 'HexaPDF::Filter::FlateDecode',
                         RunLengthDecode: 'HexaPDF::Filter::RunLengthDecode',
                         RL: 'HexaPDF::Filter::RunLengthDecode',
-                        CCITTFaxDecode: nil,
-                        CCF: nil,
-                        JBIG2Decode: nil,
-                        DCTDecode: 'HexaPDF::Filter::DCTDecode',
-                        DCT: 'HexaPDF::Filter::DCTDecode',
-                        JPXDecode: 'HexaPDF::Filter::JPXDecode',
+                        CCITTFaxDecode: 'HexaPDF::Filter::PassThrough',
+                        CCF: 'HexaPDF::Filter::PassThrough',
+                        JBIG2Decode: 'HexaPDF::Filter::PassThrough',
+                        DCTDecode: 'HexaPDF::Filter::PassThrough',
+                        DCT: 'HexaPDF::Filter::PassThrough',
+                        JPXDecode: 'HexaPDF::Filter::PassThrough',
                         Crypt: nil,
                         Encryption: 'HexaPDF::Filter::Encryption',
                       },
@@ -365,6 +426,7 @@ module HexaPDF
                       'page.default_media_box' => :A4,
                       'page.default_media_orientation' => :portrait,
                       'parser.on_correctable_error' => proc { false },
+                      'parser.try_xref_reconstruction' => true,
                       'sorted_tree.max_leaf_node_size' => 64,
                       'style.layers_map' => {
                         link: 'HexaPDF::Layout::Style::LinkLayer',
@@ -447,10 +509,13 @@ module HexaPDF
                         Action: 'HexaPDF::Type::Action',
                         XXLaunchActionWinParameters: 'HexaPDF::Type::Actions::Launch::WinParameters',
                         Annot: 'HexaPDF::Type::Annotation',
-                        XXAppearanceCharacteristics: 'HexaPDF::Type::Annotations::Widget::AppearanceCharacteristics',
+                        XXAppearanceCharacteristics: \
+                          'HexaPDF::Type::Annotations::Widget::AppearanceCharacteristics',
                         XXIconFit: 'HexaPDF::Type::IconFit',
                         XXAcroForm: 'HexaPDF::Type::AcroForm::Form',
                         XXAcroFormField: 'HexaPDF::Type::AcroForm::Field',
+                        XXAppearanceDictionary: 'HexaPDF::Type::Annotation::AppearanceDictionary',
+                        Border: 'HexaPDF::Type::Annotation::Border',
                       },
                       'object.subtype_map' => {
                         nil => {
@@ -492,6 +557,11 @@ module HexaPDF
                           Link: 'HexaPDF::Type::Annotations::Link',
                           Widget: 'HexaPDF::Type::Annotations::Widget',
                         },
+                        XXAcroFormField: {
+                          Tx: 'HexaPDF::Type::AcroForm::TextField',
+                          Btn: 'HexaPDF::Type::AcroForm::ButtonField',
+                          Ch: 'HexaPDF::Type::AcroForm::ChoiceField',
+                        },
                       })
 
 end

data/lib/hexapdf/content.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -44,6 +44,8 @@ module HexaPDF
     autoload(:Canvas, 'hexapdf/content/canvas')
     autoload(:Parser, 'hexapdf/content/parser')
     autoload(:Processor, 'hexapdf/content/processor')
+    autoload(:ColorSpace, 'hexapdf/content/color_space')
+    autoload(:Operator, 'hexapdf/content/operator')
 
   end
 

data/lib/hexapdf/content/canvas.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -1607,13 +1607,13 @@ module HexaPDF
       # See: PDF1.7 s9.2.2
       def font(name = nil, size: nil, **options)
         if name
-          @font = (name.respond_to?(:dict) ? name : context.document.fonts.add(name, **options))
+          @font = (name.respond_to?(:pdf_object) ? name : context.document.fonts.add(name, **options))
           if size
             font_size(size)
           else
             size = font_size
             raise HexaPDF::Error, "No valid font size set" if size <= 0
-            invoke_font_operator(@font.dict, size)
+            invoke_font_operator(@font.pdf_object, size)
           end
           self
         else
@@ -1644,7 +1644,7 @@ module HexaPDF
           unless @font
             raise HexaPDF::Error, "A font needs to be set before the font size can be set"
           end
-          invoke_font_operator(@font.dict, size)
+          invoke_font_operator(@font.pdf_object, size)
           self
         else
           graphics_state.font_size
@@ -1855,7 +1855,7 @@ module HexaPDF
         elsif spec.length == 1 && spec[0].respond_to?(:color_space)
           spec[0]
         else
-          resources.color_space(color_space_for_components(spec)).color(*spec)
+          resources.color_space(ColorSpace.for_components(spec)).color(*spec)
         end
       end
 
@@ -1993,19 +1993,6 @@ module HexaPDF
         end
       end
 
-      # Returns the name of the device color space that should be used for creating a color object
-      # from the components array.
-      def color_space_for_components(components)
-        case components.length
-        when 1 then :DeviceGray
-        when 3 then :DeviceRGB
-        when 4 then :DeviceCMYK
-        else
-          raise ArgumentError, "Invalid number of color components, 1|3|4 expected, " \
-            "#{components.length} given"
-        end
-      end
-
       # Utility method that abstracts the implementation of a graphics state parameter
       # getter/setter method with a call sequence of:
       #

data/lib/hexapdf/content/color_space.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2019 Thomas Leitner
+# Copyright (C) 2014-2020 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -35,6 +35,7 @@
 #++
 
 require 'hexapdf/error'
+require 'hexapdf/configuration'
 
 module HexaPDF
   module Content
@@ -71,14 +72,18 @@ module HexaPDF
     #   Returns the PDF name of the color space family this color space belongs to.
     #
     # #definition::
-    #   Returns the color space definition as array.
+    #   Returns the color space definition as array or symbol.
     #
     # #default_color::
     #   Returns the default color for this color space.
     #
     # #color(*args)::
-    #   Returns the color corresponding to the given arguments. The number and types of the
-    #   arguments differ from one color space to another.
+    #   Returns the color corresponding to the given arguments which may be normalized to conform to
+    #   the PDF spec. The number and types of the arguments differ from one color space to another.
+    #
+    # #prenormalized_color(*args)::
+    #   Returns the color corresponding to the given arguments without applying value normalization.
+    #   The number and types of the arguments differ from one color space to another.
     #
     # The class representing a color in the color space needs to respond to the following methods:
     #
@@ -91,6 +96,52 @@ module HexaPDF
     # See: PDF1.7 s8.6
     module ColorSpace
 
+      # :call-seq:
+      #   ColorSpace.device_color_from_specification(gray)           => color
+      #   ColorSpace.device_color_from_specification(r, g, b)        => color
+      #   ColorSpace.device_color_from_specification(c, m, y, k)     => color
+      #   ColorSpace.device_color_from_specification(string)         => color
+      #   ColorSpace.device_color_from_specification(array)          => color
+      #
+      # Creates a device color object from the given color specification.
+      #
+      # There are several ways to define the color that should be used:
+      #
+      # * A single numeric argument specifies a gray color (see DeviceGray::Color).
+      # * Three numeric arguments specify an RGB color (see DeviceRGB::Color).
+      # * A string in the format "RRGGBB" where "RR" is the hexadecimal number for the red, "GG"
+      #   for the green and "BB" for the blue color value also specifies an RGB color.
+      # * Four numeric arguments specify a CMYK color (see DeviceCMYK::Color).
+      # * An array is treated as if its items were specified separately as arguments.
+      #
+      # Note that it makes a difference whether integer or float values are used because the given
+      # values are first normalized - see DeviceGray#color, DeviceRGB#color and DeviceCMYK#color.
+      def self.device_color_from_specification(*spec)
+        spec.flatten!
+        spec = spec[0].scan(/../).map!(&:hex) if spec.length == 1 && spec[0].kind_of?(String)
+        GlobalConfiguration.constantize('color_space.map', for_components(spec)).new.color(*spec)
+      end
+
+      # Returns a device color object for the given components array without applying value
+      # normalization.
+      def self.prenormalized_device_color(components)
+        GlobalConfiguration.constantize('color_space.map', for_components(components)).new.
+          prenormalized_color(*components)
+      end
+
+      # Returns the name of the device color space that should be used for creating a color object
+      # from the components array.
+      def self.for_components(components)
+        case components.length
+        when 1 then :DeviceGray
+        when 3 then :DeviceRGB
+        when 4 then :DeviceCMYK
+        else
+          raise ArgumentError, "Invalid number of color components, 1|3|4 expected, " \
+            "#{components.length} given"
+        end
+      end
+
       # This module includes utility functions that are useful for all color classes.
       module ColorUtils
 
@@ -103,9 +154,10 @@ module HexaPDF
         # * If the color value is less than 0.0, it is set to 0.0.
         def normalize_value(value, upper)
           value = value.to_f / upper if value.kind_of?(Integer)
-          (value < 0 ? 0.0 : (value > 1 ? 1.0 : value))
+          value.clamp(0, 1)
         end
         private :normalize_value
+        module_function :normalize_value
 
         # Compares this color to another one by looking at their associated color spaces and their
         # components.
@@ -137,6 +189,7 @@ module HexaPDF
         def color(*args)
           Color.new(self, *args)
         end
+        alias prenormalized_color color
 
         # Returns the PDF color space family this color space belongs to.
         def family
@@ -189,8 +242,22 @@ module HexaPDF
           Color.new(0.0, 0.0, 0.0)
         end
 
-        # Returns the color object for the given red, green and blue components.
+        # Returns the color object for the red, green and blue components.
+        #
+        # Color values can either be integers in the range from 0 to 255 or floating point numbers
+        # between 0.0 and 1.0. The integer color values are automatically normalized to the
+        # DeviceRGB color value range of 0.0 to 1.0.
         def color(r, g, b)
+          Color.new(ColorUtils.normalize_value(r, 255),
+                    ColorUtils.normalize_value(g, 255),
+                    ColorUtils.normalize_value(b, 255))
+        end
+
+        # Returns the color object for the red, green and blue components without applying value
+        # normalization.
+        #
+        # See: #color
+        def prenormalized_color(r, g, b)
           Color.new(r, g, b)
         end
 
@@ -198,13 +265,10 @@ module HexaPDF
         def family
           :DeviceRGB
         end
+        alias definition family
 
         # A color in the DeviceRGB color space.
         #
-        # Color values can either be integers in the range from 0 to 255 or floating point numbers
-        # between 0.0 and 1.0. The integer color values are automatically normalized to the
-        # DeviceRGB color value range of 0.0 to 1.0.
-        #
         # See: PDF1.7 s8.6.4.3
         class Color
 
@@ -212,12 +276,11 @@ module HexaPDF
 
           # Initializes the color with the +r+ (red), +g+ (green) and +b+ (blue) components.
           #
-          # Each argument has to be either an integer between 0 and 255 or a float between 0.0 and
-          # 1.0.
+          # Each argument has to be a float between 0.0 and 1.0.
           def initialize(r, g, b)
-            @r = normalize_value(r, 255)
-            @g = normalize_value(g, 255)
-            @b = normalize_value(b, 255)
+            @r = r
+            @g = g
+            @b = b
           end
 
           # Returns the DeviceRGB color space module.
@@ -251,7 +314,20 @@ module HexaPDF
         end
 
         # Returns the color object for the given cyan, magenta, yellow and black components.
+        #
+        # Color values can either be integers in the range from 0 to 100 or floating point numbers
+        # between 0.0 and 1.0. The integer color values are automatically normalized to the
+        # DeviceCMYK color value range of 0.0 to 1.0.
         def color(c, m, y, k)
+          Color.new(ColorUtils.normalize_value(c, 100), ColorUtils.normalize_value(m, 100),
+                    ColorUtils.normalize_value(y, 100), ColorUtils.normalize_value(k, 100))
+        end
+
+        # Returns the color object for the cyan, magenta, yellow and black components without
+        # applying value normalization.
+        #
+        # See: #color
+        def prenormalized_color(c, m, y, k)
           Color.new(c, m, y, k)
         end
 
@@ -259,13 +335,10 @@ module HexaPDF
         def family
           :DeviceCMYK
         end
+        alias definition family
 
         # A color in the DeviceCMYK color space.
         #
-        # Color values can either be integers in the range from 0 to 100 or floating point numbers
-        # between 0.0 and 1.0. The integer color values are automatically normalized to the
-        # DeviceCMYK color value range of 0.0 to 1.0.
-        #
         # See: PDF1.7 s8.6.4.4
         class Color
 
@@ -274,13 +347,12 @@ module HexaPDF
           # Initializes the color with the +c+ (cyan), +m+ (magenta), +y+ (yellow) and +k+ (black)
           # components.
           #
-          # Each argument has to be either an integer between 0 and 100 or a float between 0.0 and
-          # 1.0.
+          # Each argument has to be a float between 0.0 and 1.0.
           def initialize(c, m, y, k)
-            @c = normalize_value(c, 100)
-            @m = normalize_value(m, 100)
-            @y = normalize_value(y, 100)
-            @k = normalize_value(k, 100)
+            @c = c
+            @m = m
+            @y = y
+            @k = k
           end
 
           # Returns the DeviceCMYK color space module.
@@ -314,7 +386,18 @@ module HexaPDF
         end
 
         # Returns the color object for the given gray component.
+        #
+        # Color values can either be integers in the range from 0 to 255 or floating point numbers
+        # between 0.0 and 1.0. The integer color values are automatically normalized to the
+        # DeviceGray color value range of 0.0 to 1.0.
         def color(gray)
+          Color.new(ColorUtils.normalize_value(gray, 255))
+        end
+
+        # Returns the color object for the gray component without applying value normalization.
+        #
+        # See: #color
+        def prenormalized_color(gray)
           Color.new(gray)
         end
 
@@ -322,13 +405,10 @@ module HexaPDF
         def family
           :DeviceGray
         end
+        alias definition family
 
         # A color in the DeviceGray color space.
         #
-        # Color values can either be integers in the range from 0 to 255 or floating point numbers
-        # between 0.0 and 1.0. The integer color values are automatically normalized to the
-        # DeviceGray color value range of 0.0 to 1.0.
-        #
         # See: PDF1.7 s8.6.4.2
         class Color
 
@@ -336,10 +416,9 @@ module HexaPDF
 
           # Initializes the color with the +gray+ component.
           #
-          # The argument +gray+ has to be either an integer between 0 and 255 or a float between
-          # 0.0 and 1.0.
+          # The argument +gray+ has to be a float between 0.0 and 1.0.
           def initialize(gray)
-            @gray = normalize_value(gray, 255)
+            @gray = gray
           end
 
           # Returns the DeviceGray color space module.