hexapdf 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1388a344a539c7273603549e014c635c4864af4de8665a260b15ac66d19ac461
-  data.tar.gz: 471e0f4933ac37348ac5ed217446031e742099de26773b25bb23c49fc8480a05
+  metadata.gz: d6f11a38da2472389966c1d103b86e46ba8cd858d2927b1a65f441f56e2e7dd5
+  data.tar.gz: 74ff92dcb6ede9f137303afc7c8b9d08e0baa42b0ab0b7d4436777e6db617ea4
 SHA512:
-  metadata.gz: 0ab8c16c85475e68f12faea47f8dbf7e167ebdc864d11fb1151e107af1d3678b867ad0d7a6184155e1b55ed1469d3e7443f39184e0250974f5a7df9a920adb99
-  data.tar.gz: 43c80b555018068baf314d6ed7d6a03ae0a359f2e8be498341985ecb75879fd414d066d7c356b47fb896ec0e4aa74c2044f6a5e7965922de1136ddacf409765f
+  metadata.gz: 468e0a5a24e06574b4a802408daafbdb59b3a1dc460ad2b6bf9f543088d1210d8295b843847819a872436ea4c380df85240822e28b548dd88b55f74b30ff8ab3
+  data.tar.gz: 29e95def1e7ccf0d55bca3cf5ad4d95a070d5910a0e1b8645d2884e0e5022367c63e14e2df3ecc0bac7cdfc329d88698c01060dc8005e1c1025a0c8337367afc

data/CHANGELOG.md

@@ -1,3 +1,53 @@
+## 0.23.0 - 2022-05-26
+
+### Added
+
+- [HexaPDF::Composer#create_stamp] for creating a form Xobject
+- [HexaPDF::Revision#reset_objects] for deleting all live loaded and added
+  objects
+- Support for removing or flattening annotations to the `hexapdf modify` command
+- Option to CLI command `hexapdf form` to allow generation of a template file
+- Support for centering a floating box in [HexaPDF::Layout::Frame]
+- [HexaPDF::Type::Catalog#names] for easier access to the name dictionary
+- [HexaPDF::Type::Names#destinations] for easier access to the destinations name
+  tree
+- [HexaPDF::Document::Destinations], accessible via
+  [HexaPDF::Document#destinations], as convenience interface for working with
+  destination arrays
+
+### Changed
+
+- **Breaking change**: Refactored the [HexaPDF::Document] interface for working
+  with objects and move parts into [HexaPDF::Revisions]
+- **Breaking change**: [HexaPDF::Layout::TextBox] to use whole available width
+  when aligning to the center or right
+- **Breaking change**: [HexaPDF::Layout::TextBox] to use whole available height
+  when vertically aligning to the center or bottom
+- CLI command `hexapdf inspect` to show the type of revisions, as well as the
+  number of objects per revision
+- [HexaPDF::Task::Optimize] to allow skipping invalid content stream operations
+- [HexaPDF::Composer#image] to allow using a form xobject in place of the image
+
+### Fixed
+
+- [HexaPDF::Writer#write] to write modified objects into the correct revision
+- [HexaPDF::Revisions::from_io] to correctly handle hybrid-reference files
+- [HexaPDF::Writer] to assign a valid object number to a created cross-reference
+  stream in all cases
+* [HexaPDF::Type::AcroForm::TextField] to validate the existence of a /MaxLen
+  value for comb text fields
+* [HexaPDF::Type::AcroForm::TextField#field_value=] to check for the existence
+  of /MaxLen when setting a value for a comb text field
+* [HexaPDF::Type::AcroForm::TextField#field_value=] to check the value against
+  /MaxLen
+* [HexaPDF::Layout::TextLayouter#fit] to not use style valign when doing
+  variable width layouting
+* [HexaPDF::Utils::SortedTreeNode#find_entry] to work in case of a node without
+  a container name or kids key
+* CLI command `hexapdf form` to allow setting array values when using a template
+* CLI command `hexapdf form` to allow setting file select fields
+
+
 ## 0.22.0 - 2022-03-26
 
 ### Added

data/lib/hexapdf/cli/form.rb

@@ -70,6 +70,9 @@ module HexaPDF
           @template = template
           @fill = true
         end
+        options.on('--generate-template', 'Print a template for use with --template') do
+          @generate_template = true
+        end
         options.on('--flatten', 'Flatten the form fields') do
           @flatten = true
         end
@@ -85,6 +88,7 @@ module HexaPDF
         @password = nil
         @fill = false
         @flatten = false
+        @generate_template = false
         @template = nil
         @need_appearances = nil
         @incremental = true
@@ -117,6 +121,15 @@ module HexaPDF
               doc.catalog.delete(:AcroForm)
               doc.delete(doc.acro_form)
             end
+          elsif @generate_template
+            unsupported_fields = [:signature_field, :password_field]
+            each_field(doc) do |_, _, field, _|
+              next if unsupported_fields.include?(field.concrete_field_type)
+              name = field.full_field_name.gsub(':', "\\:")
+              Array(field.field_value).each do |val|
+                puts "#{name}: #{val.to_s.gsub(/(\r|\r\n|\n)/, '\1  ')}"
+              end
+            end
           else
             list_form_fields(doc)
           end
@@ -220,8 +233,16 @@ module HexaPDF
           field_name = scanner.scan(/(\\:|[^:])*?:/)
           break unless field_name
           field_name.gsub!(/\\:/, ':')
+          field_name.chop!
           field_value = scanner.scan(/.*?(?=^\S|\z)/m)
-          data[field_name.chop] = field_value.strip.gsub(/^\s*/, '') if field_value
+          next unless field_value
+          field_value = field_value.strip.gsub(/^\s*/, '')
+          if data.key?(field_name)
+            data[field_name] = [data[field_name]] unless data[field_name].kind_of?(Array)
+            data[field_name] << field_value
+          else
+            data[field_name] = field_value
+          end
         end
         if !scanner.eos? && command_parser.verbosity_warning?
           $stderr.puts "Warning: Some template could not be parsed"
@@ -232,8 +253,8 @@ module HexaPDF
       # Applies the given value to the field.
       def apply_field_value(field, value)
         case field.concrete_field_type
-        when :single_line_text_field, :multiline_text_field, :comb_text_field, :combo_box,
-            :list_box, :editable_combo_box
+        when :single_line_text_field, :multiline_text_field, :comb_text_field, :file_select_field,
+            :combo_box, :list_box, :editable_combo_box
           field.field_value = value
         when :check_box
           field.field_value = case value
@@ -249,6 +270,8 @@ module HexaPDF
         else
           raise "Field type #{field.concrete_field_type} not yet supported"
         end
+      rescue
+        raise "Error while setting '#{field.full_field_name}': #{$!.message}"
       end
 
       # Iterates over all non-push button fields in page order. If a field appears on multiple

data/lib/hexapdf/cli/inspect.rb

@@ -229,10 +229,19 @@ module HexaPDF
               end
               IO.copy_stream(@doc.revisions.parser.io, $stdout, length, 0)
             else
-              puts "Document has #{@doc.revisions.size} revision#{@doc.revisions.size == 1 ? '' : 's'}"
-              revision_information do |_, index, count, signature, end_offset|
+              puts "Document has #{@doc.revisions.count} revision#{@doc.revisions.count == 1 ? '' : 's'}"
+              revision_information do |rev, index, count, signature, end_offset|
+                type = if rev.trailer[:XRefStm]
+                         "xref table + stream"
+                       elsif rev.trailer[:Type] == :XRef
+                         "xref stream"
+                       else
+                         "xref table"
+                       end
                 puts "Revision #{index + 1}"
+                puts "  Type      : #{type}"
                 puts "  Objects   : #{count}"
+                puts "  Size      : #{rev.trailer[:Size]}"
                 puts "  Signed    : yes" if signature
                 puts "  Byte range: 0-#{end_offset}"
               end
@@ -352,7 +361,7 @@ module HexaPDF
               buffer = buffer[-20..-1]
             end
           end
-          yield(rev, index, rev.next_free_oid - 1, sig, end_index)
+          yield(rev, index, rev.each.count, sig, end_index)
         end
       end
 

data/lib/hexapdf/cli/modify.rb

@@ -53,14 +53,15 @@ module HexaPDF
         super('modify', takes_commands: false)
         short_desc("Modify a PDF file")
         long_desc(<<~EOF)
-          This command modifies a PDF file. It can be used to select pages that should appear in
-          the output file and/or rotate them. The output file can also be encrypted/decrypted and
-          optimized in various ways.
+          This command modifies a PDF file. It can be used, for example, to select pages that should
+          appear in the output file and/or rotate them. The output file can also be
+          encrypted/decrypted and optimized in various ways.
         EOF
 
         @password = nil
         @pages = '1-e'
         @embed_files = []
+        @annotation_mode = nil
 
         options.on("--password PASSWORD", "-p", String,
                    "The password for decryption. Use - for reading from standard input.") do |pwd|
@@ -74,6 +75,10 @@ module HexaPDF
                    "used multiple times)") do |file|
           @embed_files << file
         end
+        options.on("--annotations MODE", [:remove, :flatten], "Handling of annotations (either " \
+                   "remove or flatten)") do |mode|
+          @annotation_mode = mode
+        end
         define_optimization_options
         define_encryption_options
       end
@@ -82,6 +87,7 @@ module HexaPDF
         maybe_raise_on_existing_file(out_file)
         with_document(in_file, password: @password, out_file: out_file) do |doc|
           arrange_pages(doc) unless @pages == '1-e'
+          handle_annotations(doc)
           @embed_files.each {|file| doc.files.add(file, embed: true) }
           apply_encryption_options(doc)
           apply_optimization_options(doc)
@@ -109,6 +115,20 @@ module HexaPDF
         doc.pages.add unless doc.pages.count > 0
       end
 
+      # Handles the annotations of all selected pages by doing nothing, removing them or flattening
+      # them.
+      def handle_annotations(doc)
+        return unless @annotation_mode
+
+        doc.pages.each do |page|
+          if @annotation_mode == :remove
+            page.delete(:Annots)
+          else
+            page.flatten_annotations
+          end
+        end
+      end
+
     end
 
   end

data/lib/hexapdf/composer.rb

@@ -313,7 +313,8 @@ module HexaPDF
 
     # Draws the given image at the current position.
     #
-    # The +file+ argument can be anything that is accepted by HexaPDF::Document::Images#add.
+    # The +file+ argument can be anything that is accepted by HexaPDF::Document::Images#add or a
+    # HexaPDF::Type::Form object.
     #
     # See #text for details on +width+, +height+, +style+ and +style_properties+.
     #
@@ -324,7 +325,7 @@ module HexaPDF
     #   composer.image(machu_picchu, height: 30)
     def image(file, width: 0, height: 0, style: nil, **style_properties)
       style = retrieve_style(style, style_properties)
-      image = document.images.add(file)
+      image = file.kind_of?(HexaPDF::Stream) ? file : document.images.add(file)
       draw_box(Layout::ImageBox.new(image, width: width, height: height, style: style))
     end
 
@@ -361,6 +362,27 @@ module HexaPDF
       end
     end
 
+    # Creates a stamp (Form XObject) which can be used like an image multiple times on a single page
+    # or on multiple pages.
+    #
+    # The width and the height of the stamp need to be set (frame.width/height or
+    # page.box.width/height might be good choices).
+    #
+    # Examples:
+    #
+    #   #>pdf-composer
+    #   stamp = composer.create_stamp(50, 50) do |canvas|
+    #     canvas.fill_color("red").line_width(5).
+    #       rectangle(10, 10, 30, 30).fill_stroke
+    #   end
+    #   composer.image(stamp, width: 20, height: 20)
+    #   composer.image(stamp, width: 50)
+    def create_stamp(width, height) # :yield: canvas
+      stamp = @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height]})
+      yield(stamp.canvas) if block_given?
+      stamp
+    end
+
     private
 
     # Creates the frame into which boxes are layed out when a new page is created.

data/lib/hexapdf/document/destinations.rb

@@ -0,0 +1,396 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2022 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
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/dictionary'
+require 'hexapdf/error'
+
+module HexaPDF
+  class Document
+
+    # This class provides methods for creating and managing the destinations of a PDF file.
+    #
+    # A destination describes a particular view of a PDF document, consisting of the page, the view
+    # location and a magnification factor. See Destination for details.
+    #
+    # Such destinations may be directly specified where needed, e.g. for link annotations, or they
+    # may be named and later referenced through the name. This class allows to create destinations
+    # with or without a name.
+    #
+    # See: PDF1.7 s12.3.2
+    class Destinations
+
+      # Wraps an explicit destination array to allow easy access to query its properties.
+      #
+      # A *destination array* has the form
+      #
+      #   [page, type, *arguments]
+      #
+      # where +page+ is either a page object or a page number (in case of a destination to a page in
+      # a remote PDF document), +type+ is the destination type (see below) and +arguments+ are the
+      # required arguments for the specific type of destination.
+      #
+      # == Destination Types
+      #
+      # There are eight different types of destinations, each taking different arguments. The
+      # arguments are marked up in the list below and are in the correct order for use in the
+      # destination array. The first name in the list is the PDF internal name, the second one the
+      # explicit, more descriptive one used by HexaPDF:
+      #
+      # :XYZ, :xyz::
+      #     Display the page with the given (+left+, +top+) coordinate at the upper-left corner of
+      #     the window and the specified magnification (+zoom+) factor. A +nil+ value for any
+      #     argument means not changing it from the current value.
+      #
+      # :Fit, :fit_page::
+      #     Display the page so that it fits horizontally and vertically within the window.
+      #
+      # :FitH, :fit_page_horizontal::
+      #     Display the page so that it fits horizontally within the window, with the given +top+
+      #     coordinate being at the top of the window. A +nil+ value for +top+ means not changing it
+      #     from the current value.
+      #
+      # :FitV, :fit_page_vertical::
+      #     Display the page so that it fits vertically within the window, with the given +left+
+      #     coordinate being at the left of the window. A +nil+ value for +left+ means not changing
+      #     it from the current value.
+      #
+      # :FitR, :fit_rectangle::
+      #     Display the page so that the rectangle specified by (+left+, +bottom+)-(+right+, +top+)
+      #     fits horizontally and vertically within the window.
+      #
+      # :FitB, :fit_bounding_box::
+      #     Display the page so that its bounding box fits horizontally and vertically within the
+      #     window.
+      #
+      # :FitBH, :fit_bounding_box_horizontal::
+      #     Display the page so that its bounding box fits horizontally within the window, with the
+      #     given +top+ coordinate being at the top of the window. A +nil+ value for +top+ means not
+      #     changing it from the current value.
+      #
+      # :FitBV, :fit_bounding_box_vertical::
+      #     Display the page so that its bounding box fits vertically within the window, with the
+      #     given +left+ coordinate being at the left of the window. A +nil+ value for +left+ means
+      #     not changing it from the current value.
+      class Destination
+
+        # :nodoc:
+        TYPE_MAPPING = {
+          XYZ: :xyz,
+          Fit: :fit_page,
+          FitH: :fit_page_horizontal,
+          FitV: :fit_page_vertical,
+          FitR: :fit_rectangle,
+          FitB: :fit_bounding_box,
+          FitBH: :fit_bounding_box_horizontal,
+          FitBV: :fit_bounding_box_vertical,
+        }
+
+        # :nodoc:
+        REVERSE_TYPE_MAPPING = Hash[*TYPE_MAPPING.flatten.reverse]
+
+        # Creates a new Destination for the given +destination+ which may be an explicit destination
+        # array or a dictionary with a /D entry (as allowed for a named destination).
+        def initialize(destination)
+          @destination = (destination.kind_of?(HexaPDF::Dictionary) ? destination[:D] : destination)
+        end
+
+        # Returns +true+ if the destination references a destination in a remote document.
+        def remote?
+          @destination[0].kind_of?(Numeric)
+        end
+
+        # Returns the referenced page.
+        #
+        # The return value is either a page object or, in case of a destination to a remote
+        # document, a page number.
+        def page
+          @destination[0]
+        end
+
+        # Returns the type of destination.
+        def type
+          TYPE_MAPPING[@destination[1]]
+        end
+
+        # Returns the argument +left+ if used by the destination, raises an error otherwise.
+        def left
+          case type
+          when :xyz, :fit_page_vertical, :fit_rectangle, :fit_bounding_box_vertical
+            @destination[2]
+          else
+            raise HexaPDF::Error, "No such argument for destination type #{type}"
+          end
+        end
+
+        # Returns the argument +top+ if used by the destination, raises an error otherwise.
+        def top
+          case type
+          when :xyz
+            @destination[3]
+          when :fit_page_horizontal, :fit_bounding_box_horizontal
+            @destination[2]
+          when :fit_rectangle
+            @destination[5]
+          else
+            raise HexaPDF::Error, "No such argument for destination type #{type}"
+          end
+        end
+
+        # Returns the argument +right+ if used by the destination, raises an error otherwise.
+        def right
+          case type
+          when :fit_rectangle
+            @destination[4]
+          else
+            raise HexaPDF::Error, "No such argument for destination type #{type}"
+          end
+        end
+
+        # Returns the argument +bottom+ if used by the destination, raises an error otherwise.
+        def bottom
+          case type
+          when :fit_rectangle
+            @destination[3]
+          else
+            raise HexaPDF::Error, "No such argument for destination type #{type}"
+          end
+        end
+
+        # Returns the argument +zoom+ if used by the destination, raises an error otherwise.
+        def zoom
+          case type
+          when :xyz
+            @destination[4]
+          else
+            raise HexaPDF::Error, "No such argument for destination type #{type}"
+          end
+        end
+
+      end
+
+      include Enumerable
+
+      # Creates a new Destinations object for the given PDF document.
+      def initialize(document)
+        @document = document
+      end
+
+      # :call-seq:
+      #   destinations.create_xyz(page, left: nil, top: nil, zoom: nil)            -> dest
+      #   destinations.create_xyz(page, name: nil, left: nil, top: nil, zoom: nil) -> name
+      #
+      # Creates a new xyz destination array for the given arguments and returns it or, in case
+      # a name is given, the name.
+      #
+      # The arguments +page+, +left+, +top+ and +zoom+ are described in detail in the Destination
+      # class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_xyz(page, name: nil, left: nil, top: nil, zoom: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:xyz), left, top, zoom]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_page(page)            -> dest
+      #   destinations.create_fit_page(page, name: nil) -> name
+      #
+      # Creates a new fit to page destination array for the given arguments and returns it or, in
+      # case a name is given, the name.
+      #
+      # The argument +page+ is described in detail in the Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_page(page, name: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_page)]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_page_horizontal(page, top: nil)            -> dest
+      #   destinations.create_fit_page_horizontal(page, name: nil, top: nil) -> name
+      #
+      # Creates a new fit page horizontal destination array for the given arguments and returns it
+      # or, in case a name is given, the name.
+      #
+      # The arguments +page and +top+ are described in detail in the Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_page_horizontal(page, name: nil, top: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_page_horizontal), top]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_page_vertical(page, left: nil)            -> dest
+      #   destinations.create_fit_page_vertical(page, name: nil, left: nil) -> name
+      #
+      # Creates a new fit page vertical destination array for the given arguments and returns it or,
+      # in case a name is given, the name.
+      #
+      # The arguments +page and +left+ are described in detail in the Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_page_vertical(page, name: nil, left: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_page_vertical), left]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_rectangle(page, left:, bottom:, right:, top:)            -> dest
+      #   destinations.create_fit_rectangle(page, name: nil, left:, bottom:, right:, top:) -> name
+      #
+      # Creates a new fit to rectangle destination array for the given arguments and returns it or,
+      # in case a name is given, the name.
+      #
+      # The arguments +page+, +left+, +bottom+, +right+ and +top+ are described in detail in the
+      # Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_rectangle(page, left:, bottom:, right:, top:, name: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_rectangle),
+                       left, bottom, right, top]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_bounding_box(page)            -> dest
+      #   destinations.create_fit_bounding_box(page, name: nil) -> name
+      #
+      # Creates a new fit to bounding box destination array for the given arguments and returns it
+      # or, in case a name is given, the name.
+      #
+      # The argument +page+ is described in detail in the Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_bounding_box(page, name: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_bounding_box)]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_bounding_box_horizontal(page, top: nil)            -> dest
+      #   destinations.create_fit_bounding_box_horizontal(page, name: nil, top: nil) -> name
+      #
+      # Creates a new fit bounding box horizontal destination array for the given arguments and
+      # returns it or, in case a name is given, the name.
+      #
+      # The arguments +page and +top+ are described in detail in the Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_bounding_box_horizontal(page, name: nil, top: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_bounding_box_horizontal), top]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.create_fit_bounding_box_vertical(page, left: nil)            -> dest
+      #   destinations.create_fit_bounding_box_vertical(page, name: nil, left: nil) -> name
+      #
+      # Creates a new fit bounding box vertical destination array for the given arguments and
+      # returns it or, in case a name is given, the name.
+      #
+      # The arguments +page and +left+ are described in detail in the Destination class description.
+      #
+      # If the argument +name+ is given, the created destination array is added to the destinations
+      # name tree under that name for reuse later, overwriting an existing entry if there is one.
+      def create_fit_bounding_box_vertical(page, name: nil, left: nil)
+        destination = [page, Destination::REVERSE_TYPE_MAPPING.fetch(:fit_bounding_box_vertical), left]
+        name ? (add(name, destination); name) : destination
+      end
+
+      # :call-seq:
+      #   destinations.add(name, destination)
+      #
+      # Adds the given +destination+ under +name+ to the destinations name tree.
+      #
+      # If the name does already exist, an error is raised.
+      def add(name, destination)
+        destinations.add_entry(name, destination)
+      end
+
+      # :call-seq:
+      #   destinations.delete(name)    -> destination
+      #
+      # Deletes the given destination from the destinations name tree and returns it or +nil+ if no
+      # destination was registered under that name.
+      def delete(name)
+        destinations.delete_entry(name)
+      end
+
+      # :call-seq:
+      #   destinations[name]    -> destination
+      #
+      # Returns the destination registered under the given +name+ or +nil+ if no destination was
+      # registered under that name.
+      def [](name)
+        destinations.find_entry(name)
+      end
+
+      # :call-seq:
+      #   destinations.each {|name, dest| block }  -> destinations
+      #   destinations.each                        -> Enumerator
+      #
+      # Iterates over all named destinations of the PDF, yielding the name and the destination
+      #  wrapped into a Destination object.
+      def each
+        return to_enum(__method__) unless block_given?
+
+        destinations.each_entry do |name, dest|
+          yield(name, Destination.new(dest))
+        end
+
+        self
+      end
+
+      private
+
+      # Returns the root of the destinations name tree.
+      def destinations
+        @document.catalog.names.destinations
+      end
+
+    end
+
+  end
+end