hexapdf 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f8bf550cff0d50567439c9942c97d6fc32e9fa9edab3bbff05ce854e22b0cc3
-  data.tar.gz: bab6243ec81278f278589fc90768dd7e2c6c73c0c314bd8ce0f17350f2d6cd73
+  metadata.gz: 9e41c50e1ddb3dc2b063e8a858ccf612fb069df46189d592dccec3778d58d738
+  data.tar.gz: cf62d302bd4728816c9920d09fcf27224004b6e70bc23b19d9a0f8b37dc27a3b
 SHA512:
-  metadata.gz: bfdfa30c16cae575fb028b9f804516601c56e02dfcf77b63452d63a9ce3ce28950661ef0de3b5a178fef7442fee51ef911e798b627f627e8f1991db6ae185691
-  data.tar.gz: aea9f97cb7465cc9592cab25e11c890efce3d10fa0c6c69dcaade78fc94a68fef1b1dd907f87c96f894840d913342d7183ad1efc6fd6d6e8be290759168af105
+  metadata.gz: 83afdc841024adb116efbeb75bd34c2feb71042cbccb368e32b220634f3f8122f1a29bf07d8b7532836953fe1d3edb0733cb6c31fd50177a28bddea9bcdee2a2
+  data.tar.gz: fa3e26f634fc7e3e6461ade1555a063bffbf52c4e956d802b4bee5d01290bc2415571501b4afa083aaefd9f514a38a10fb10546418dbd5b7ef9bfbd121abd37f

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.26.0 - 2022-10-14
+
+### Added
+
+* Support for page labels
+* [HexaPDF::Type::MarkInformation]
+
+### Changed
+
+* [HexaPDF::Rectangle] to recover from invalid values by defaulting to
+  `[0, 0, 0, 0]`
+
+### Fixed
+
+* [HexaPDF::DictionaryFields::PDFByteStringConverter] to duplicate the string
+  before conversion
+* [HexaPDF::Type::FileSpecification#path=] to duplicate the given string value
+  due to using it for two different fields
+
+
 ## 0.25.0 - 2022-10-02
 
 ### Added

data/lib/hexapdf/configuration.rb

@@ -588,6 +588,8 @@ module HexaPDF
                         TransformParams: 'HexaPDF::Type::Signature::TransformParams',
                         Outlines: 'HexaPDF::Type::Outline',
                         XXOutlineItem: 'HexaPDF::Type::OutlineItem',
+                        PageLabel: 'HexaPDF::Type::PageLabel',
+                        XXMarkInformation: 'HexaPDF::Type::MarkInformation',
                       },
                       'object.subtype_map' => {
                         nil => {

data/lib/hexapdf/dictionary_fields.rb

@@ -268,7 +268,7 @@ module HexaPDF
       # returns +nil+.
       def self.convert(str, _type, _document)
         return if !str.kind_of?(String) || str.encoding == Encoding::BINARY
-        str.force_encoding(Encoding::BINARY)
+        str.dup.force_encoding(Encoding::BINARY)
       end
 
     end

data/lib/hexapdf/document/pages.rb

@@ -41,8 +41,26 @@ module HexaPDF
 
     # This class provides methods for managing the pages of a PDF file.
     #
-    # It uses the methods of HexaPDF::Type::PageTreeNode underneath but provides a more convenient
-    # interface.
+    # For page manipulation it uses the methods of HexaPDF::Type::PageTreeNode underneath but
+    # provides a more convenient interface.
+    #
+    # == Page Labels
+    #
+    # In addition to page manipulation, the class provides methods for managing the page labels
+    # which are alternative descriptions for the pages. In contrast to the page indices which are
+    # fixed the page labels can be freely defined.
+    #
+    # The way this works is that one can assign page label objects (HexaPDF::Type::PageLabel) to
+    # page ranges via the /PageLabels number tree in the catalog. The page label objects specify how
+    # the pages in their range shall be labeled. See HexaPDF::Type::PageLabel for examples of page
+    # labels.
+    #
+    # To facilitate the easy use of page labels the following methods are provided:
+    #
+    # * #page_label
+    # * #each_labelling_range
+    # * #add_labelling_range
+    # * #delete_labelling_range
     class Pages
 
       include Enumerable
@@ -154,6 +172,85 @@ module HexaPDF
       alias size count
       alias length count
 
+      # Returns the constructed page label for the given page index.
+      #
+      # If no page labels are defined, +nil+ is returned.
+      #
+      # See HexaPDF::Type::PageLabel for examples.
+      def page_label(page_index)
+        raise(ArgumentError, 'Page index out of range') if page_index < 0 || page_index >= count
+        each_labelling_range do |index, count, label|
+          if page_index < index + count
+            return label.construct_label(page_index - index)
+          end
+        end
+      end
+
+      # :call-seq:
+      #   pages.each_labelling_range {|first_index, count, page_label| block }   -> pages
+      #   pages.each_labelling_range                                             -> Enumerator
+      #
+      # Iterates over all defined labelling ranges inorder, yielding the page index of the first
+      # page in the labelling range, the number of pages in the range, and the associated page label
+      # object.
+      #
+      # The last yielded count might be equal or lower than zero in case the document has fewer
+      # pages than anticipated by the labelling ranges.
+      def each_labelling_range
+        return to_enum(__method__) unless block_given?
+        return unless @document.catalog.page_labels
+
+        last_start = nil
+        last_label = nil
+        @document.catalog.page_labels.each_entry do |s1, p1|
+          yield(last_start, s1 - last_start, @document.wrap(last_label, type: :PageLabel)) if last_start
+          last_start = s1
+          last_label = p1
+        end
+        if last_start
+          yield(last_start, count - last_start, @document.wrap(last_label, type: :PageLabel))
+        end
+
+        self
+      end
+
+      # Adds a new labelling range starting at +start_index+ and returns it.
+      #
+      # See HexaPDF::Type::PageLabel for information on the arguments +numbering_style+, +prefix+,
+      # and +start_number+.
+      #
+      # If a labelling range already exists for the given +start_index+, its value will be
+      # overwritten.
+      #
+      # If there are no existing labelling ranges and the given +start_index+ isn't 0, a default
+      # labelling range using start index 0 and numbering style :decimal is added.
+      def add_labelling_range(start_index, numbering_style: nil, prefix: nil, start_number: nil)
+        page_label = @document.wrap({}, type: :PageLabel)
+        page_label.numbering_style(numbering_style) if numbering_style
+        page_label.prefix(prefix) if prefix
+        page_label.start_number(start_number) if start_number
+
+        labels = @document.catalog.page_labels(create: true)
+        labels.add_entry(start_index, page_label)
+        labels.add_entry(0, {S: :d}) unless labels.find_entry(0)
+
+        page_label
+      end
+
+      # Deletes the page labelling range starting at +start_index+ and returns the associated page
+      # label object.
+      #
+      # Note: The page label for the range starting at zero can only be deleted last!
+      def delete_labelling_range(start_index)
+        return unless (labels = @document.catalog.page_labels)
+        if start_index == 0 && labels.each_entry.first(2).size == 2
+          raise HexaPDF::Error, "Page labelling range starting at 0 must be deleted last"
+        end
+        page_label = labels.delete_entry(start_index)
+        @document.catalog.delete(:PageLabels) if start_index == 0
+        page_label
+      end
+
     end
 
   end

data/lib/hexapdf/rectangle.rb

@@ -116,12 +116,19 @@ module HexaPDF
 
     private
 
+    #:nodoc:
+    RECTANGLE_ERROR_MSG = "A PDF rectangle structure must contain an array of four numbers"
+
     # Ensures that the value is an array containing four numbers that specify the bottom left and
     # top right corner.
     def after_data_change
       super
       unless value.size == 4 && all? {|v| v.kind_of?(Numeric) }
-        raise ArgumentError, "A PDF rectangle structure must contain an array of four numbers"
+        if !document? ||
+            document.config['parser.on_correctable_error'].call(document, RECTANGLE_ERROR_MSG, 0)
+          raise ArgumentError, RECTANGLE_ERROR_MSG
+        end
+        value.replace([0, 0, 0, 0])
       end
       self[0], self[2] = self[2], self[0] if self[0] > self[2]
       self[1], self[3] = self[3], self[1] if self[1] > self[3]
@@ -130,7 +137,9 @@ module HexaPDF
     def perform_validation #:nodoc:
       super
       unless value.size == 4 && all? {|v| v.kind_of?(Numeric) }
-        yield("A PDF rectangle structure must contain an array of four numbers", false)
+        yield("A PDF rectangle structure must contain an array of four numbers; replacing " \
+          "it with [0, 0, 0, 0]", true)
+        value.replace([0, 0, 0, 0])
       end
     end
 

data/lib/hexapdf/type/catalog.rb

@@ -73,7 +73,7 @@ module HexaPDF
       define_field :AcroForm,          type: :XXAcroForm, version: '1.2'
       define_field :Metadata,          type: Stream,     indirect: true, version: '1.4'
       define_field :StructTreeRoot,    type: Dictionary, version: '1.3'
-      define_field :MarkInfo,          type: Dictionary, version: '1.4'
+      define_field :MarkInfo,          type: :XXMarkInformation, version: '1.4'
       define_field :Lang,              type: String,     version: '1.4'
       define_field :SpiderInfo,        type: Dictionary, version: '1.3'
       define_field :OutputIntents,     type: PDFArray,   version: '1.4'
@@ -132,6 +132,23 @@ module HexaPDF
         end
       end
 
+      # Returns the page labels number tree.
+      #
+      # * If a page labels number tree exists, the +create+ argument is not used.
+      #
+      # * If no page labels number tree exists and +create+ is +true+, a new one is created.
+      #
+      # * If no page labels number tree exists and +create+ is +false+, +nil+ is returned.
+      #
+      # See: HexaPDF::Document::Pages
+      def page_labels(create: false)
+        if (object = self[:PageLabels])
+          object
+        elsif create
+          self[:PageLabels] = document.wrap({}, type: NumberTreeNode)
+        end
+      end
+
       private
 
       # Ensures that there is a valid page tree.

data/lib/hexapdf/type/file_specification.rb

@@ -116,7 +116,8 @@ module HexaPDF
       #
       # Since the /Unix, /Mac and /DOS fields are obsolescent, only the /F and /UF fields are set.
       def path=(filename)
-        self[:UF] = self[:F] = filename
+        self[:UF] = filename
+        self[:F] = filename.b
         delete(:FS)
         delete(:Unix)
         delete(:Mac)

data/lib/hexapdf/type/mark_information.rb

@@ -0,0 +1,57 @@
+# -*- 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 mark information dictionary which provides some general information related to
+    # structured PDF documents.
+    #
+    # See: PDF1.7 s14.7.1
+    class MarkInformation < Dictionary
+
+      define_type :XXMarkInformation
+
+      define_field :Marked,         type: Boolean, default: false
+      define_field :UserProperties, type: Boolean, default: false
+      define_field :Suspects,       type: Boolean, default: false
+
+    end
+
+  end
+end

data/lib/hexapdf/type/page.rb

@@ -353,6 +353,14 @@ module HexaPDF
         idx
       end
 
+      # Returns the label of the page which is an optional, alternative description of the page
+      # index.
+      #
+      # See HexaPDF::Document::Pages for details.
+      def label
+        document.pages.page_label(index)
+      end
+
       # Returns all parent nodes of the page up to the root of the page tree.
       #
       # The direct parent is the first node in the array and the root node the last.

data/lib/hexapdf/type/page_label.rb

@@ -0,0 +1,222 @@
+# -*- 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 a page label dictionary.
+    #
+    # A page label dictionary contains information about the numbering style, the label prefix and
+    # the start number to construct page labels like 'A-1' or 'iii'. What is not stored is the page
+    # to which it is applied since that is stored in a number tree referenced through the
+    # /PageLabels entry in the document catalog.
+    #
+    # See HexaPDF::Document::Pages for details on how to create and manage page labels.
+    #
+    # Examples:
+    #
+    # * numbering style :decimal, prefix none, start number default value
+    #
+    #   1, 2, 3, 4, ...
+    #
+    # * numbering style :lowercase_letters, prefix 'Appendix ', start number 5
+    #
+    #   Appendix e, Appendix f, Appendix g, ...
+    #
+    # * numbering style :uppercase_roman, prefix none, start number 10
+    #
+    #   X, XI, XII, XIII, ...
+    #
+    # * numbering style :none, prefix 'Page', start number default value
+    #
+    #   Page, Page, Page, Page, ...
+    #
+    # * numbering style :none, prefix none, start number default value
+    #
+    #   "", "", "", ... (i.e. always the empty string)
+    #
+    # See: PDF1.7 s12.4.2, HexaPDF::Document::Pages, HexaPDF::Type::Catalog
+    class PageLabel < Dictionary
+
+      define_type :PageLabel
+
+      define_field :Type, type: Symbol, default: type
+      define_field :S,    type: Symbol, allowed_values: [:D, :R, :r, :A, :a]
+      define_field :P,    type: String
+      define_field :St,   type: Integer, default: 1
+
+      # Constructs the page label for the given index which needs to be relative to the page index
+      # of the first page in the associated labelling range.
+      #
+      # This method is usually not called directly but through HexaPDF::Document::Pages#page_label.
+      def construct_label(index)
+        label = (prefix || '').dup
+        number = start_number + index
+        case numbering_style
+        when :decimal
+          label + number.to_s
+        when :uppercase_roman
+          label + number_to_roman_numeral(number)
+        when :lowercase_roman
+          label + number_to_roman_numeral(number, lowercase: true)
+        when :uppercase_letters
+          label + number_to_letters(number)
+        when :lowercase_letters
+          label + number_to_letters(number, lowercase: true)
+        when :none
+          label
+        end
+      end
+
+      # :nodoc:
+      NUMBERING_STYLE_MAPPING = {
+        decimal: :D, D: :D,
+        uppercase_roman: :R, R: :R,
+        lowercase_roman: :r, r: :r,
+        uppercase_letters: :A, A: :A,
+        lowercase_letters: :a, a: :a,
+        none: nil
+      }
+
+      # :nodoc:
+      REVERSE_NUMBERING_STYLE_MAPPING = Hash[*NUMBERING_STYLE_MAPPING.flatten.reverse]
+
+      # :call-seq:
+      #   page_label.numbering_style             -> numbering_style
+      #   page_label.numbering_style(value)      -> numbering_style
+      #
+      # Returns the numbering style if no argument is given. Otherwise sets the numbering style to
+      # the given value.
+      #
+      # The following numbering styles are available:
+      #
+      # :none:: No numbering is done; the label only consists of the prefix.
+      # :decimal:: Decimal arabic numerals (1, 2, 3, 4, ...).
+      # :uppercase_roman:: Uppercase roman numerals (I, II, III, IV, ...)
+      # :lowercase_roman:: Lowercase roman numerals (i, ii, iii, iv, ...)
+      # :uppercase_letters:: Uppercase letters (A, B, C, D, ...)
+      # :lowercase_letters:: Lowercase letters (a, b, c, d, ...)
+      def numbering_style(value = nil)
+        if value
+          self[:S] = NUMBERING_STYLE_MAPPING.fetch(value) do
+            raise ArgumentError, "Invalid numbering style specified: #{value}"
+          end
+        else
+          REVERSE_NUMBERING_STYLE_MAPPING.fetch(self[:S], :none)
+        end
+      end
+
+      # :call-seq:
+      #   page_label.prefix             -> prefix
+      #   page_label.prefix(value)      -> prefix
+      #
+      # Returns the label prefix if no argument is given. Otherwise sets the label prefix to the
+      # given string value.
+      def prefix(value = nil)
+        if value
+          self[:P] = value
+        else
+          self[:P]
+        end
+      end
+
+      # :call-seq:
+      #   page_label.start_number             -> start_number
+      #   page_label.start_number(value)      -> start_number
+      #
+      # Returns the start number if no argument is given. Otherwise sets the start number to the
+      # given integer value.
+      def start_number(value = nil)
+        if value
+          if !value.kind_of?(Integer) || value < 1
+            raise ArgumentError, "Start number must be an integer greater than or equal to 1"
+          end
+          self[:St] = value
+        else
+          self[:St]
+        end
+      end
+
+      private
+
+      # :nodoc:
+      ALPHABET = ('A'..'Z').to_a
+
+      # Maps the given number to uppercase (or, if +lowercase+ is +true+, lowercase) letters (e.g. 1
+      # -> A, 27 -> AA, 28 -> AB, ...).
+      def number_to_letters(number, lowercase: false)
+        result = "".dup
+        while number > 0
+          number, rest = (number - 1).divmod(26)
+          result.prepend(ALPHABET[rest])
+        end
+        lowercase ? result.downcase : result
+      end
+
+      # :nodoc:
+      ROMAN_NUMERAL_MAPPING = {
+        1000 => "M",
+        900 => "CM",
+        500 => "D",
+        400 => "CD",
+        100 => "C",
+        90 => "XC",
+        50 => "L",
+        40 => "XL",
+        10 => "X",
+        9 => "IX",
+        5 => "V",
+        4 => "IV",
+        1 => "I",
+      }
+
+      # Maps the given number to an uppercase (or, if +lowercase+ is +true+, lowercase) roman
+      # numeral.
+      def number_to_roman_numeral(number, lowercase: false)
+        result = ROMAN_NUMERAL_MAPPING.inject("".dup) do |memo, (base, roman_numeral)|
+          next memo if number < base
+          quotient, number = number.divmod(base)
+          memo << roman_numeral * quotient
+        end
+        lowercase ? result.downcase : result
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type.rb

@@ -75,6 +75,8 @@ module HexaPDF
     autoload(:Signature, 'hexapdf/type/signature')
     autoload(:Outline, 'hexapdf/type/outline')
     autoload(:OutlineItem, 'hexapdf/type/outline_item')
+    autoload(:PageLabel, 'hexapdf/type/page_label')
+    autoload(:MarkInformation, 'hexapdf/type/mark_information')
 
   end
 

data/lib/hexapdf/version.rb

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

data/test/hexapdf/document/test_pages.rb

@@ -136,4 +136,90 @@ describe HexaPDF::Document::Pages do
       assert_equal(3, @doc.pages.count)
     end
   end
+
+  describe "page_label" do
+    it "returns the page label object for the given range start index" do
+      11.times { @doc.pages.add }
+      @doc.catalog[:PageLabels] = {Nums: [0, {S: :D}, 5, {S: :r, St: 2}, 10, {P: 'A-', S: :a}]}
+      assert_equal("1", @doc.pages.page_label(0))
+      assert_equal("5", @doc.pages.page_label(4))
+      assert_equal("ii", @doc.pages.page_label(5))
+      assert_equal("vi", @doc.pages.page_label(9))
+      assert_equal("A-a", @doc.pages.page_label(10))
+    end
+
+    it "fails if the page index is out of range" do
+      assert_raises(ArgumentError) { @doc.pages.page_label(-1) }
+      assert_raises(ArgumentError) { @doc.pages.page_label(0) }
+    end
+  end
+
+  describe "each_labelling_range" do
+    before do
+      10.times { @doc.pages.add }
+    end
+
+    it "returns no entries for an empty or non-existing /PageLabels entry" do
+      assert(@doc.pages.each_labelling_range.to_a.empty?)
+    end
+
+    it "works for a single page label entry" do
+      @doc.catalog[:PageLabels] = {Nums: [0, {S: :r}]}
+      result = @doc.pages.each_labelling_range.to_a
+      assert_equal([[0, 10, {S: :r}]], result.map {|s, c, l| [s, c, l.value]})
+      assert_equal(:lowercase_roman, result[0].last.numbering_style)
+    end
+
+    it "works for multiple page label entries" do
+      @doc.catalog[:PageLabels] = {Nums: [0, {S: :r}, 2, {S: :d}, 7, {S: :A}]}
+      result = @doc.pages.each_labelling_range.to_a
+      assert_equal([[0, 2, {S: :r}], [2, 5, {S: :d}], [7, 3, {S: :A}]],
+                   result.map {|s, c, l| [s, c, l.value]})
+    end
+
+    it "returns a zero or negative count for the last range if there aren't enough pages" do
+      assert_equal(10, @doc.pages.count)
+      @doc.catalog[:PageLabels] = {Nums: [0, {S: :d}, 10, {S: :r}]}
+      assert_equal(0, @doc.pages.each_labelling_range.to_a[-1][1])
+      @doc.catalog[:PageLabels][:Nums][2] = 11
+      assert_equal(-1, @doc.pages.each_labelling_range.to_a[-1][1])
+    end
+  end
+
+  describe "add_labelling_range" do
+    it "creates a new page label object for the given arguments" do
+      label = @doc.pages.add_labelling_range(5, numbering_style: :lowercase_roman,
+                                             start_number: 5, prefix: 'a')
+      assert_equal({S: :r, St: 5, P: 'a'}, label.value)
+      assert_equal(label, @doc.catalog.page_labels.find_entry(5))
+    end
+
+    it "adds an entry for the range starting at 0 if it doesn't exist" do
+      label = @doc.pages.add_labelling_range(5)
+      assert_equal([{S: :d}, label],
+                   @doc.catalog.page_labels[:Nums].value.values_at(1, 3))
+    end
+  end
+
+  describe "delete_labelling_range" do
+    before do
+      @doc.catalog[:PageLabels] = {Nums: [0, {S: :r}, 5, {S: :d}]}
+    end
+
+    it "deletes the labelling range for a given start index" do
+      label = @doc.pages.delete_labelling_range(5)
+      assert_equal({S: :d}, label)
+    end
+
+    it "deletes the labelling range for 0 if it is the last, together with the number tree" do
+      @doc.pages.delete_labelling_range(5)
+      label = @doc.pages.delete_labelling_range(0)
+      assert_equal({S: :r}, label)
+      assert_nil(@doc.catalog[:PageLabels])
+    end
+
+    it "fails if the range starting at zero is deleted when other ranges still exist" do
+      assert_raises(HexaPDF::Error) { @doc.pages.delete_labelling_range(0) }
+    end
+  end
 end

data/test/hexapdf/test_dictionary_fields.rb

@@ -156,8 +156,10 @@ describe HexaPDF::DictionaryFields do
     it "allows conversion to a binary string" do
       refute(@field.convert('test'.b, self))
 
-      str = @field.convert("test", self)
+      input = "test"
+      str = @field.convert(input, self)
       assert_equal('test', str)
+      refute_same(input, str)
       assert_equal(Encoding::BINARY, str.encoding)
     end
   end

data/test/hexapdf/test_rectangle.rb

@@ -6,11 +6,23 @@ require 'hexapdf/document'
 
 describe HexaPDF::Rectangle do
   describe "after_data_change" do
-    it "fails if the rectangle doesn't contain four numbers" do
+    it "fails if the rectangle doesn't contain four numbers, without document" do
       assert_raises(ArgumentError) { HexaPDF::Rectangle.new([1, 2, 3]) }
       assert_raises(ArgumentError) { HexaPDF::Rectangle.new([1, 2, 3, :a]) }
     end
 
+    it "fails if the rectangle doesn't contain four numbers, with document and strict mode" do
+      doc = HexaPDF::Document.new(config: {'parser.on_correctable_error' => lambda { true }})
+      assert_raises(ArgumentError) { HexaPDF::Rectangle.new([1, 2, 3], document: doc) }
+      assert_raises(ArgumentError) { HexaPDF::Rectangle.new([1, 2, 3, :a], document: doc) }
+    end
+
+    it "recovers if the rectangle doesn't contain four numbers, with document default mode" do
+      doc = HexaPDF::Document.new
+      assert_equal([0, 0, 0, 0], HexaPDF::Rectangle.new([1, 2, 3], document: doc).value)
+      assert_equal([0, 0, 0, 0], HexaPDF::Rectangle.new([1, 2, 3, :a], document: doc).value)
+    end
+
     it "normalizes the array values" do
       rect = HexaPDF::Rectangle.new([0, 1, 2, 3])
       assert_equal([0, 1, 2, 3], rect.value)
@@ -57,10 +69,12 @@ describe HexaPDF::Rectangle do
       assert(rect.validate)
 
       rect.value.shift
-      refute(rect.validate)
+      assert(rect.validate)
+      assert_equal([0, 0, 0, 0], rect.value)
 
-      rect.value.unshift(:A)
-      refute(rect.validate)
+      rect.value[-1] = :A
+      assert(rect.validate)
+      assert_equal([0, 0, 0, 0], rect.value)
     end
   end
 end

data/test/hexapdf/test_writer.rb

@@ -40,7 +40,7 @@ describe HexaPDF::Writer do
       219
       %%EOF
       3 0 obj
-      <</Producer(HexaPDF version 0.25.0)>>
+      <</Producer(HexaPDF version 0.26.0)>>
       endobj
       xref
       3 1
@@ -72,7 +72,7 @@ describe HexaPDF::Writer do
       141
       %%EOF
       6 0 obj
-      <</Producer(HexaPDF version 0.25.0)>>
+      <</Producer(HexaPDF version 0.26.0)>>
       endobj
       2 0 obj
       <</Length 10>>stream
@@ -206,7 +206,7 @@ describe HexaPDF::Writer do
       <</Type/Page/MediaBox[0 0 595 842]/Parent 2 0 R/Resources<<>>>>
       endobj
       5 0 obj
-      <</Producer(HexaPDF version 0.25.0)>>
+      <</Producer(HexaPDF version 0.26.0)>>
       endobj
       4 0 obj
       <</Root 1 0 R/Info 5 0 R/Size 6/Type/XRef/W[1 1 2]/Index[0 6]/Filter/FlateDecode/DecodeParms<</Columns 4/Predictor 12>>/Length 33>>stream

data/test/hexapdf/type/test_catalog.rb

@@ -54,6 +54,23 @@ describe HexaPDF::Type::Catalog do
     end
   end
 
+  describe "page_labels" do
+    it "returns an existing page labels number tree" do
+      @catalog[:PageLabels] = {Nums: []}
+      assert_equal({Nums: []}, @catalog.page_labels.value)
+    end
+
+    it "returns an existing page labels number tree even if create: true" do
+      obj = @catalog[:PageLabels] = {Nums: []}
+      assert_same(obj, @catalog.page_labels(create: true).value)
+    end
+
+    it "creates a new page labels number tree if create: true" do
+      tree = @catalog.page_labels(create: true)
+      assert_kind_of(HexaPDF::NumberTreeNode, tree)
+    end
+  end
+
   describe "validation" do
     it "creates the page tree if necessary" do
       refute(@catalog.validate(auto_correct: false))

data/test/hexapdf/type/test_file_specification.rb

@@ -37,6 +37,7 @@ describe HexaPDF::Type::FileSpecification do
     it "only sets /UF and /F, deleting /Mac, /Unix, /DOS entries if they exist" do
       @obj[:Unix] = @obj[:Mac] = @obj[:DOS] = 'a'
       @obj.path = 'file/test'
+      refute_same(@obj.value[:UF], @obj.value[:F])
       assert_equal('file/test', @obj[:UF])
       assert_equal('file/test', @obj[:F])
       refute(@obj.key?(:Unix))

data/test/hexapdf/type/test_page.rb

@@ -327,6 +327,14 @@ describe HexaPDF::Type::Page do
     end
   end
 
+  describe "label" do
+    it "returns the label for the page" do
+      5.times { @doc.pages.add }
+      @doc.pages.add_labelling_range(0, numbering_style: :uppercase_letters)
+      assert_equal(%w[A B C D E], @doc.pages.each.map(&:label))
+    end
+  end
+
   it "returns all ancestor page tree nodes of a page" do
     root = @doc.add({Type: :Pages})
     kid = @doc.add({Type: :Pages, Parent: root})

data/test/hexapdf/type/test_page_label.rb

@@ -0,0 +1,118 @@
+# -*- encoding: utf-8 -*-
+
+require 'test_helper'
+require 'hexapdf/document'
+require 'hexapdf/type/page_label'
+
+describe HexaPDF::Type::PageLabel do
+  before do
+    @doc = HexaPDF::Document.new
+    @page_label = @doc.wrap({Type: :PageLabel})
+  end
+
+  describe "construct_label" do
+    it "returns an empty label if nothing is set" do
+      assert_equal('', @page_label.construct_label(0))
+    end
+
+    it "returns the prefix if no numbering style is set" do
+      @page_label.prefix('hello')
+      assert_equal('hello', @page_label.construct_label(0))
+    end
+
+    it "works for decimal numbers" do
+      @page_label.numbering_style(:decimal)
+      assert_equal("10", @page_label.construct_label(9))
+    end
+
+    it "works for uppercase letters" do
+      @page_label.numbering_style(:uppercase_letters)
+      assert_equal("J", @page_label.construct_label(9))
+      assert_equal("AJ", @page_label.construct_label(35))
+    end
+
+    it "works for lowercase letters" do
+      @page_label.numbering_style(:lowercase_letters)
+      assert_equal("a", @page_label.construct_label(0))
+      assert_equal("aa", @page_label.construct_label(26))
+    end
+
+    it "works for uppercase roman numerals" do
+      @page_label.numbering_style(:uppercase_roman)
+      assert_equal("X", @page_label.construct_label(9))
+    end
+
+    it "works for lowercase roman numerals" do
+      @page_label.numbering_style(:lowercase_roman)
+      assert_equal("i", @page_label.construct_label(0))
+      assert_equal("iv", @page_label.construct_label(3))
+    end
+
+    it "combines the prefix with the numeric portion" do
+      @page_label.prefix('hello-')
+      @page_label.numbering_style(:decimal)
+      assert_equal('hello-1', @page_label.construct_label(0))
+      assert_equal('hello-101', @page_label.construct_label(100))
+    end
+  end
+
+  describe "numbering_style" do
+    it "returns the set numbering style" do
+      assert_equal(:none, @page_label.numbering_style)
+      @page_label[:S] = :D
+      assert_equal(:decimal, @page_label.numbering_style)
+    end
+
+    it "sets the numbering style to the given value" do
+      @page_label.numbering_style(:decimal)
+      assert_equal(:D, @page_label[:S])
+      @page_label.numbering_style(:none)
+      assert_nil(@page_label[:S])
+    end
+
+    it "returns :none for an unknown numbering style" do
+      @page_label[:S] = :d
+      assert_equal(:none, @page_label.numbering_style)
+    end
+
+    it "fails if the given value is not mapped to a numbering_style" do
+      assert_raises(ArgumentError) { @page_label.numbering_style("Nomad") }
+      assert_raises(ArgumentError) { @page_label.numbering_style(:unknown) }
+    end
+  end
+
+  describe "prefix" do
+    it "returns the set prefix" do
+      assert_nil(@page_label.prefix)
+      @page_label[:P] = 'Prefix'
+      assert_equal('Prefix', @page_label.prefix)
+    end
+
+    it "sets the prefix to the given value" do
+      @page_label.prefix('Hallo')
+      assert_equal('Hallo', @page_label[:P])
+    end
+  end
+
+  describe "start_number" do
+    it "returns the set start number" do
+      assert_equal(1, @page_label.start_number)
+      @page_label[:St] = 5
+      assert_equal(5, @page_label.start_number)
+    end
+
+    it "set the start number to the given value" do
+      @page_label.start_number(5)
+      assert_equal(5, @page_label[:St])
+    end
+
+    it "fails if the provided value is not an integer" do
+      assert_raises(ArgumentError) { @page_label.start_number("6") }
+    end
+
+    it "fails if the value is lower than 1" do
+      assert_raises(ArgumentError) { @page_label.start_number("-1") }
+      assert_raises(ArgumentError) { @page_label.start_number("0") }
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hexapdf
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Thomas Leitner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-10-02 00:00:00.000000000 Z
+date: 2022-10-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cmdparse
@@ -420,11 +420,13 @@ files:
 - lib/hexapdf/type/icon_fit.rb
 - lib/hexapdf/type/image.rb
 - lib/hexapdf/type/info.rb
+- lib/hexapdf/type/mark_information.rb
 - lib/hexapdf/type/names.rb
 - lib/hexapdf/type/object_stream.rb
 - lib/hexapdf/type/outline.rb
 - lib/hexapdf/type/outline_item.rb
 - lib/hexapdf/type/page.rb
+- lib/hexapdf/type/page_label.rb
 - lib/hexapdf/type/page_tree_node.rb
 - lib/hexapdf/type/resources.rb
 - lib/hexapdf/type/signature.rb
@@ -670,6 +672,7 @@ files:
 - test/hexapdf/type/test_outline.rb
 - test/hexapdf/type/test_outline_item.rb
 - test/hexapdf/type/test_page.rb
+- test/hexapdf/type/test_page_label.rb
 - test/hexapdf/type/test_page_tree_node.rb
 - test/hexapdf/type/test_resources.rb
 - test/hexapdf/type/test_signature.rb
@@ -703,7 +706,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.2.32
 signing_key: 
 specification_version: 4
 summary: HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby