hexapdf 0.24.2 → 0.25.0

data/lib/hexapdf/type/outline.rb

@@ -0,0 +1,122 @@
+# -*- 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'
+
+module HexaPDF
+  module Type
+
+    # Represents the root of the PDF's document outline containing a hierarchy of outline items
+    # (sometimes called bookmarks) in a linked list.
+    #
+    # The document outline usually contains items for the sections of the document, so that clicking
+    # on an item opens the page where the section starts (the section header is). Most PDF viewers
+    # are able to display the outline to aid in navigation, though not all apply the optional
+    # attributes like the text color.
+    #
+    # The outline dictionary is linked via the /Outlines entry from the Type::Catalog and can
+    # directly be accessed via HexaPDF::Document#outline.
+    #
+    # Here is an example for creating an outline:
+    #
+    #   doc = HexaPDF::Document.new
+    #   5.times { doc.pages.add }
+    #   doc.outline.add_item("Section 1", destination: 0) do |sec1|
+    #     sec1.add_item("Page 2", destination: doc.pages[1])
+    #     sec1.add_item("Page 3", destination: 2)
+    #     sec1.add_item("Section 1.1", text_color: "red", flags: [:bold]) do |sec11|
+    #       sec11.add_item("Page 4", destination: 3)
+    #     end
+    #   end
+    #
+    # See: PDF1.7 s12.3.3
+    class Outline < Dictionary
+
+      define_type :Outlines
+
+      define_field :Type,  type: Symbol, default: type
+      define_field :First, type: :XXOutlineItem, indirect: true
+      define_field :Last,  type: :XXOutlineItem, indirect: true
+      define_field :Count, type: Integer
+
+      # Adds a new top-level outline item.
+      #
+      # See OutlineItem#add_item for details on the available options since this method just passes
+      # all arguments through to it.
+      def add_item(title, **options, &block)
+        self[:Count] ||= 0
+        self_as_item.add_item(title, **options, &block)
+      end
+
+      # :call-seq:
+      #   outline.each_item {|item| block }   -> item
+      #   outline.each_item                   -> Enumerator
+      #
+      # Iterates over all items of the outline.
+      #
+      # The items are yielded in-order, yielding first the item itself and then its descendants.
+      def each_item(&block)
+        self_as_item.each_item(&block)
+      end
+
+      private
+
+      # Represents the outline dictionary as an outline item dictionary to make use of some of its
+      # methods.
+      def self_as_item
+        @self_as_item ||= document.wrap(self, type: :XXOutlineItem)
+      end
+
+      # Makes sure the required values are set.
+      def perform_validation
+        super
+        first = self[:First]
+        last = self[:Last]
+        if (first && !last) || (!first && last)
+          yield('Outline dictionary is missing an endpoint reference', true)
+          node, dir = first ? [first, :Next] : [last, :Prev]
+          node = node[dir] while node.key?(dir)
+          self[dir == :Next ? :Last : :First] = node
+        elsif !first && !last && self[:Count]
+          yield('Outline dictionary key /Count set but no items exist', true)
+          delete(:Count)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/outline_item.rb

@@ -0,0 +1,373 @@
+# -*- 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/utils/bit_field'
+require 'hexapdf/content/color_space'
+
+module HexaPDF
+  module Type
+
+    # Represents an outline item dictionary.
+    #
+    # An item has a title and some optional attributes: the action that is activated when clicking
+    # (either a simple destination or an explicit action object), the text color, and flags (whether
+    # the text should appear bold and/or italic).
+    #
+    # Additionally, items may have child items which makes it possible to create a hierarchy of
+    # items.
+    #
+    # If no destination/action is set, the item just acts as kind of a header. It usually only makes
+    # sense to do this when the item has children.
+    #
+    # Outline item dictionaries are connected together in the form of a linked list using the /Next
+    # and /Prev keys. Each item may have descendant items. If so, the /First and /Last keys point to
+    # respectively the first and last descendant items.
+    #
+    # Since many dictionary keys need to be kept up-to-date when manipulating the outline item tree,
+    # it is not recommended to manually do this but to rely on the provided convenience methods.
+    #
+    # See: PDF1.7 s12.3.3
+    class OutlineItem < Dictionary
+
+      extend Utils::BitField
+
+      define_type :XXOutlineItem
+
+      define_field :Title,  type: String, required: true
+      define_field :Parent, type: Dictionary, required: true, indirect: true
+      define_field :Prev,   type: :XXOutlineItem, indirect: true
+      define_field :Next,   type: :XXOutlineItem, indirect: true
+      define_field :First,  type: :XXOutlineItem, indirect: true
+      define_field :Last,   type: :XXOutlineItem, indirect: true
+      define_field :Count,  type: Integer
+      define_field :Dest,   type: [Symbol, PDFByteString, PDFArray]
+      define_field :A,      type: :Action, version: '1.1'
+      define_field :SE,     type: Dictionary, indirect: true
+      define_field :C,      type: PDFArray, default: [0, 0, 0], version: '1.4'
+      define_field :F,      type: Integer, default: 0, version: '1.4'
+
+      ##
+      # :method: flags
+      #
+      # Returns an array of flag names representing the set bit flags for /F.
+      #
+      # The available flags are:
+      #
+      # :italic or 0:: The text is displayed in italic.
+      # :bold or 1:: The text is displayed in bold.
+      #
+
+      ##
+      # :method: flagged?
+      # :call-seq:
+      #   flagged?(flag)
+      #
+      # Returns +true+ if the given flag is set on /F. The argument can either be the flag name or
+      # the bit index.
+      #
+      # See #flags for the list of available flags.
+      #
+
+      ##
+      # :method: flag
+      # :call-seq:
+      #   flag(*flags, clear_existing: false)
+      #
+      # Sets the given flags on /F, given as flag names or bit indices. If +clear_existing+ is
+      # +true+, all prior flags will be cleared.
+      #
+      # See #flags for the list of available flags.
+      #
+
+      ##
+      # :method: unflag
+      # :call-seq:
+      #   flag(*flags)
+      #
+      # Clears the given flags from /F, given as flag names or bit indices.
+      #
+      # See #flags for the list of available flags.
+      #
+      bit_field(:flags, {italic: 0, bold: 1},
+                lister: "flags", getter: "flagged?", setter: "flag", unsetter: "unflag",
+                value_getter: "self[:F]", value_setter: "self[:F]")
+
+      # :call-seq:
+      #   item.title          -> title
+      #   item.title(value)   -> title
+      #
+      # Returns the item's title if no argument is given. Otherwise sets the title to the given
+      # value.
+      def title(value = nil)
+        if value
+          self[:Title] = value
+        else
+          self[:Title]
+        end
+      end
+
+      # :call-seq:
+      #   item.text_color               -> color
+      #   item.text_color(color)        -> color
+      #
+      # Returns the item's text color as HexaPDF::Content::ColorSpace::DeviceRGB::Color object if no
+      # argument is given. Otherwise sets the text color, see
+      # HexaPDF::Content::ColorSpace.device_color_from_specification for possible +color+ values.
+      #
+      # Note: The color *has* to be an RGB color.
+      def text_color(color = nil)
+        if color
+          color = HexaPDF::Content::ColorSpace.device_color_from_specification(color)
+          unless color.color_space.family == :DeviceRGB
+            raise ArgumentError, "The given argument is not a valid RGB color"
+          end
+          self[:C] = color.components
+        else
+          Content::ColorSpace.prenormalized_device_color(self[:C])
+        end
+      end
+
+      # :call-seq:
+      #   item.destination             -> destination
+      #   item.destination(value)      -> destination
+      #
+      # Returns the item's destination if no argument is given. Otherwise sets the destination to
+      # the given value (see HexaPDF::Document::Destinations#use_or_create for the posssible
+      # values).
+      #
+      # If an action is set, the destination has to be unset; and vice versa. So when setting a
+      # destination value, the action is automatically deleted.
+      def destination(value = nil)
+        if value
+          delete(:A)
+          self[:Dest] = document.destinations.use_or_create(value)
+        else
+          self[:Dest]
+        end
+      end
+
+      # :call-seq:
+      #   item.action             -> action
+      #   item.action(value)      -> action
+      #
+      # Returns the item's action if no argument is given. Otherwise sets the action to
+      # the given value (needs to be a valid HexaPDF::Type::Action dictionary).
+      #
+      # If an action is set, the destination has to be unset; and vice versa. So when setting an
+      # action value, the destination is automatically deleted.
+      def action(value = nil)
+        if value
+          delete(:Dest)
+          self[:A] = value
+        else
+          self[:A]
+        end
+      end
+
+      # Adds, as child to this item, a new outline item with the given title that performs the
+      # provided action on clicking. Returns the newly added item.
+      #
+      # If neither :destination nor :action is specified, the outline item has no associated action.
+      # This is only meaningful if the new item will have children as it then acts just as a
+      # container.
+      #
+      # If a block is specified, the newly created item is yielded.
+      #
+      # destination::
+      #
+      #     Specifies the destination that should be activated when clicking on the outline item.
+      #     See HexaPDF::Document::Destinations#use_or_create for details. The argument :action
+      #     takes precedence if it is also specified,
+      #
+      # action::
+      #
+      #     Specifies the action that should be taken when clicking on the outline item. See
+      #     HexaPDF::Type::Action for details. If the argument :destination is also specified, the
+      #     :action argument takes precedence.
+      #
+      # position::
+      #
+      #     The position where the new child item should be inserted. Can either be:
+      #
+      #     +:first+:: Insert as first item
+      #     +:last+:: Insert as last item (default)
+      #     Integer:: When non-negative inserts before, otherwise after, the item at the given
+      #               zero-based index.
+      #
+      # open::
+      #
+      #     Specifies whether the outline item should be open (i.e. one or more children are shown)
+      #     or closed. Default: +true+.
+      #
+      # text_color::
+      #
+      #     The text color of the outline item text which needs to be a valid RGB color (see
+      #     #text_color for details). If not set, the text appears in black.
+      #
+      # flags::
+      #
+      #     An array of font variants (possible values are :bold and :italic) to set for the outline
+      #     item text, see #flags for detail. Default is to use no variant.
+      #
+      # Examples:
+      #
+      #   doc.destinations.add("Title") do |item|                  # no action, just container
+      #     item.add("Second subitem", destination: doc.pages[1])  # links to page 2
+      #     item.add("First subitem", position: :first, destination: doc.pages[0])
+      #   end
+      def add_item(title, destination: nil, action: nil, position: :last, open: true,
+                   text_color: nil, flags: nil) # :yield: item
+        item = document.add({Parent: self}, type: :XXOutlineItem)
+        item.title(title)
+        if action
+          item.action(action)
+        else
+          item.destination(destination)
+        end
+        item.text_color(text_color) if text_color
+        item.flag(*flags) if flags
+        item[:Count] = 0 if open # Count=0 means open if items are later added
+
+        unless position == :last || position == :first || position.kind_of?(Integer)
+          raise ArgumentError, "position must be :first, :last, or an integer"
+        end
+        if self[:First]
+          case position
+          when :last, -1
+            item[:Prev] = self[:Last]
+            self[:Last][:Next] = item
+            self[:Last] = item
+          when :first, 0
+            item[:Next] = self[:First]
+            self[:First][:Prev] = item
+            self[:First] = item
+          when Integer
+            temp, direction = if position > 0
+                                [self[:First], :Next]
+                              else
+                                position = -position - 2
+                                [self[:Last], :Prev]
+                              end
+            position.times { temp &&= temp[direction] }
+            raise ArgumentError, "position out of bounds" if temp.nil?
+            item[:Prev] = temp[:Prev]
+            item[:Next] = temp
+            temp[:Prev] = item
+            item[:Prev][:Next] = item
+          end
+        else
+          self[:First] = self[:Last] = item
+        end
+
+        # Re-calculate /Count entries
+        temp = self
+        while temp
+          if !temp.key?(:Count) || temp[:Count] < 0
+            temp[:Count] = (temp[:Count] || 0) - 1
+            break
+          else
+            temp[:Count] += 1
+          end
+          temp = temp[:Parent]
+        end
+
+        yield(item) if block_given?
+
+        item
+      end
+
+      # :call-seq:
+      #   item.each_item {|descendant_item| block }   -> item
+      #   item.each_item                              -> Enumerator
+      #
+      # Iterates over all descendant items of this one.
+      #
+      # The items are yielded in-order, yielding first the item itself and then its descendants.
+      def each_item(&block)
+        return to_enum(__method__) unless block_given?
+
+        item = self[:First]
+        while item
+          yield(item)
+          item.each_item(&block)
+          item = item[:Next]
+        end
+
+        self
+      end
+
+      private
+
+      def perform_validation # :nodoc:
+        super
+        first = self[:First]
+        last = self[:Last]
+        if (first && !last) || (!first && last)
+          yield('Outline item dictionary is missing an endpoint reference', true)
+          node, dir = first ? [first, :Next] : [last, :Prev]
+          node = node[dir] while node.key?(dir)
+          self[dir == :Next ? :Last : :First] = node
+        elsif !first && !last && self[:Count] != 0
+          yield('Outline item dictionary key /Count set but no descendants exist', true)
+          delete(:Count)
+        end
+
+        prev_item = self[:Prev]
+        if prev_item && (prev_item_next = prev_item[:Next]) != self
+          if prev_item_next
+            yield('Outline item /Prev points to item whose /Next points somewhere else', false)
+          else
+            yield('Outline item /Prev points to item without /Next', true)
+            prev_item[:Next] = self
+          end
+        end
+
+        next_item = self[:Next]
+        if next_item && (next_item_prev = next_item[:Prev]) != self
+          if next_item_prev
+            yield('Outline item /Next points to item whose /Prev points somewhere else', false)
+          else
+            yield('Outline item /Next points to item without /Prev', true)
+            next_item[:Prev] = self
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type.rb

@@ -73,6 +73,8 @@ module HexaPDF
     autoload(:IconFit, 'hexapdf/type/icon_fit')
     autoload(:AcroForm, 'hexapdf/type/acro_form')
     autoload(:Signature, 'hexapdf/type/signature')
+    autoload(:Outline, 'hexapdf/type/outline')
+    autoload(:OutlineItem, 'hexapdf/type/outline_item')
 
   end
 

data/lib/hexapdf/version.rb

@@ -37,6 +37,6 @@
 module HexaPDF
 
   # The version of HexaPDF.
-  VERSION = '0.24.2'
+  VERSION = '0.25.0'
 
 end

data/test/hexapdf/document/test_destinations.rb

@@ -8,6 +8,27 @@ describe HexaPDF::Document::Destinations::Destination do
     HexaPDF::Document::Destinations::Destination.new(dest)
   end
 
+  describe "self.valid?" do
+    before do
+      @klass = HexaPDF::Document::Destinations::Destination
+    end
+
+    it "validates the type" do
+      assert(@klass.valid?([5, :Fit]))
+      refute(@klass.valid?([5, :FitNone]))
+    end
+
+    it "validates the page entry" do
+      assert(@klass.valid?([5, :Fit]))
+      refute(@klass.valid?([HexaPDF::Dictionary.new({Type: :Page}), :FitNone]))
+    end
+
+    it "validates the arguments" do
+      assert(@klass.valid?([5, :FitH, 5]))
+      refute(@klass.valid?([5, :FitH, :other]))
+    end
+  end
+
   it "can be asked whether the referenced page is in a remote document" do
     assert(destination([5, :Fit]).remote?)
     refute(destination([HexaPDF::Dictionary.new({}), :Fit]).remote?)
@@ -17,6 +38,10 @@ describe HexaPDF::Document::Destinations::Destination do
     assert_equal(:page, destination([:page, :Fit]).page)
   end
 
+  it "can validate a destination" do
+    assert(destination([5, :Fit]).valid?)
+  end
+
   describe "type :xyz" do
     before do
       @dest = destination([:page, :XYZ, :left, :top, :zoom])
@@ -201,6 +226,68 @@ describe HexaPDF::Document::Destinations do
     @page = @doc.pages.add
   end
 
+  describe "use_or_create" do
+    it "uses the given destination name if it exists" do
+      @doc.destinations.create(:fit_page, @page, name: "test")
+      assert_equal("test", @doc.destinations.use_or_create("test"))
+    end
+
+    it "fails if the given destination name doesn't exist" do
+      assert_raises(HexaPDF::Error) { @doc.destinations.use_or_create("test") }
+    end
+
+    it "uses the given destination array" do
+      dest = [@page, :Fit]
+      assert_same(dest, @doc.destinations.use_or_create(dest))
+    end
+
+    it "fails if the given destination array is not valid" do
+      assert_raises(HexaPDF::Error) { @doc.destinations.use_or_create([@page, :FitNone]) }
+    end
+
+    it "creates a fit page destination for a given page" do
+      assert_equal([@page, :Fit], @doc.destinations.use_or_create(@page))
+    end
+
+    it "fails if the given dictionary object is not a page object" do
+      assert_raises(HexaPDF::Error) { @doc.destinations.use_or_create(@doc.catalog) }
+    end
+
+    it "creates a fit page destination for a given page index" do
+      assert_equal([@page, :Fit], @doc.destinations.use_or_create(0))
+    end
+
+    it "fails if the given index is no a valid page index" do
+      assert_raises(ArgumentError) { @doc.destinations.use_or_create(-1) }
+      assert_raises(ArgumentError) { @doc.destinations.use_or_create(1) }
+    end
+
+    it "creates the destination using the provided details" do
+      dest = @doc.destinations.use_or_create(type: :fit_page_horizontal, page: @page, top: 10)
+      assert_equal([@page, :FitH, 10], dest)
+    end
+
+    it "fails creating a destination if the :type key is missing" do
+      assert_raises(ArgumentError) { @doc.destinations.use_or_create(page: @page) }
+    end
+
+    it "fails creating a destination if the :page key is missing" do
+      assert_raises(ArgumentError) { @doc.destinations.use_or_create(type: :fit_page) }
+    end
+
+    it "fails if the provided argument has an invalid type" do
+      assert_raises(ArgumentError) { @doc.destinations.use_or_create(:value) }
+    end
+  end
+
+  describe "create" do
+    it "creates the destination based on the given type" do
+      @doc.destinations.stub(:create_fit_page, [5, :Fit]) do
+        assert_equal([5, :Fit], @doc.destinations.create(:fit_page, 5))
+      end
+    end
+  end
+
   describe "create_xyz" do
     it "creates the destination" do
       dest = @doc.destinations.create_xyz(@page, left: 1, top: 2, zoom: 3)

data/test/hexapdf/encryption/test_security_handler.rb

@@ -351,8 +351,10 @@ describe HexaPDF::Encryption::SecurityHandler do
 
     it "doesn't encrypt strings in a document's Encrypt dictionary" do
       @document.trailer[:Encrypt] = @handler.dict
-      @document.trailer[:Encrypt][:Mine] = 'string'
-      assert_equal('string', @handler.encrypt_string('string', @document.trailer[:Encrypt]))
+      str = 'string'
+      result = @handler.encrypt_string(str, @document.trailer[:Encrypt])
+      assert_equal('string', result)
+      refute_same(str, result)
     end
 
     it "doesn't encrypt XRef streams" do

data/test/hexapdf/layout/test_style.rb

@@ -671,6 +671,7 @@ describe HexaPDF::Layout::Style do
     @style = HexaPDF::Layout::Style.new
     assert_raises(HexaPDF::Error) { @style.font }
     assert_equal(10, @style.font_size)
+    assert_nil(@style.line_height)
     assert_equal(0, @style.character_spacing)
     assert_equal(0, @style.word_spacing)
     assert_equal(100, @style.horizontal_scaling)

data/test/hexapdf/layout/test_text_layouter.rb

@@ -461,6 +461,12 @@ describe HexaPDF::Layout::TextLayouter do
       assert_equal(20 + 20 + 9 + 20 + 9, result.height)
     end
 
+    it "handles penalties with non-zero width at end of line if they don't fit" do
+      items = boxes([17.21, 9]) + [penalty(50, boxes([3.33]).first)] + boxes([30, 9])
+      result = @layouter.fit(items, 20.5, 100)
+      assert_equal(3, result.remaining_items.size)
+    end
+
     it "handles line breaks in combination with multiple parts per line" do
       items = boxes([20, 20]) + [penalty(-5000)] +
         boxes([20, 20], [20, 20], [20, 20]) + [penalty(-5000)] +

data/test/hexapdf/test_document.rb

@@ -562,6 +562,10 @@ describe HexaPDF::Document do
     end
   end
 
+  it "returns the document outline" do
+    assert_kind_of(HexaPDF::Type::Outline, @doc.outline)
+  end
+
   it "can be inspected and the output is not too large" do
     assert_match(/HexaPDF::Document:\d+/, @doc.inspect)
   end