hexapdf 0.1.0

data/lib/hexapdf/utils/object_hash.rb

@@ -0,0 +1,130 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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.
+#++
+
+module HexaPDF
+  module Utils
+
+    # There are some structures in a PDF file, for example cross reference tables, that index data
+    # based on object and generation numbers. However, there is a restriction that in such
+    # structures the object numbers must be unique, e.g. there may not be entries for [1, 0] and
+    # \[1, 1] at the same time.
+    #
+    # This class can be used for storing/retrieving data for such structures.
+    class ObjectHash
+
+      include Enumerable
+
+      # The biggest object number that is stored in the object hash or zero if no objects are
+      # stored.
+      attr_reader :max_oid
+
+      # Creates a new object hash.
+      def initialize
+        @table = {}
+        @oids = {}
+        @max_oid = 0
+      end
+
+      # :call-seq:
+      #   objhash[oid, gen] = data
+      #
+      # Sets the data for the given object and generation numbers.
+      #
+      # If there is already an entry for the given object number (even if the generation number is
+      # different), this entry will be removed.
+      def []=(oid, gen, data)
+        @table[oid] = data
+        @oids[oid] = gen
+        @max_oid = oid if oid > @max_oid
+      end
+
+      # :call-seq:
+      #   objhash[oid]        -> data or nil
+      #   objhash[oid, gen]   -> data or nil
+      #
+      # Returns the data for the given object number, or for the given object and generation
+      # numbers.
+      #
+      # If there is no such data, +nil+ is returned.
+      def [](oid, gen = nil)
+        (gen.nil? || gen_for_oid(oid) == gen || nil) && @table[oid]
+      end
+
+      # :call-seq:
+      #   objhash.gen_for_oid(oid)    -> Integer or nil
+      #
+      # Returns the generation number that is stored along the given object number, or +nil+ if
+      # the object number is not used.
+      def gen_for_oid(oid)
+        @oids[oid]
+      end
+
+      # :call-seq:
+      #   objhash.entry?(oid)        -> true or false
+      #   objhash.entry?(oid, gen)   -> true or false
+      #
+      # Returns +true+ if there is an entry for the given object number, or for the given object
+      # and generation numbers.
+      def entry?(oid, gen = nil)
+        (gen ? gen_for_oid(oid) == gen : @oids.key?(oid))
+      end
+
+      # Deletes the entry for the given object number.
+      def delete(oid)
+        @table.delete(oid)
+        @oids.delete(oid)
+        @max_oid = oids.max || 0 if oid == @max_oid
+      end
+
+      # :call-seq:
+      #   objhash.each {|oid, gen, data| block }   -> objhash
+      #   objhash.each                             -> Enumerator
+      #
+      # Calls the given block once for every entry, passing an array consisting of the object and
+      # generation number and the associated data as arguments.
+      def each
+        return to_enum(__method__) unless block_given?
+        @oids.keys.each {|oid| yield(oid, @oids[oid], @table[oid]) if @table.key?(oid)}
+        self
+      end
+
+      # Returns all used object numbers as an array.
+      def oids
+        @oids.keys
+      end
+      private :oids
+
+    end
+
+  end
+end

data/lib/hexapdf/utils/pdf_doc_encoding.rb

@@ -0,0 +1,93 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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.
+#++
+
+module HexaPDF
+  module Utils
+
+    # Implements encoding conversion functions for the PDFDocEncoding.
+    #
+    # The PDFDocEncoding is used, together with UTF-16BE, for strings outside content streams.
+    # When a PDF file is loaded and a text string in a PDF object does not start with the UTF-16BE
+    # BOM U+FEFF, it is automatically converted to UTF-8 on access.
+    #
+    # The same is done for text strings in UTF-16BE encoding. Therefore all text strings can be
+    # assumed to be in UTF-8.
+    #
+    # When a PDF file is written, text strings are automatically encoded in either PDFDocEncoding
+    # or UTF-16BE depending on the characters in the text string.
+    #
+    # See: PDF1.7 s7.9.2, D.1, D.3
+    module PDFDocEncoding
+
+      # :nodoc:
+      CHARACTER_MAP = %W[\uFFFD \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD
+                         \uFFFD \u0009 \u000A \uFFFD \uFFFD \u000D \uFFFD \uFFFD
+                         \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD \uFFFD
+                         \u02D8 \u02C7 \u02C6 \u02D9 \u02DD \u02DB \u02DA \u02DC
+                         \u0020 \u0021 \u0022 \u0023 \u0024 \u0025 \u0026 \u0027
+                         \u0028 \u0029 \u002a \u002b \u002c \u002d \u002e \u002f
+                         \u0030 \u0031 \u0032 \u0033 \u0034 \u0035 \u0036 \u0037
+                         \u0038 \u0039 \u003a \u003b \u003c \u003d \u003e \u003f
+                         \u0040 \u0041 \u0042 \u0043 \u0044 \u0045 \u0046 \u0047
+                         \u0048 \u0049 \u004a \u004b \u004c \u004d \u004e \u004f
+                         \u0050 \u0051 \u0052 \u0053 \u0054 \u0055 \u0056 \u0057
+                         \u0058 \u0059 \u005a \u005b \u005c \u005d \u005e \u005f
+                         \u0060 \u0061 \u0062 \u0063 \u0064 \u0065 \u0066 \u0067
+                         \u0068 \u0069 \u006a \u006b \u006c \u006d \u006e \u006f
+                         \u0070 \u0071 \u0072 \u0073 \u0074 \u0075 \u0076 \u0077
+                         \u0078 \u0079 \u007a \u007b \u007c \u007d \u007e \uFFFD
+                         \u2022 \u2020 \u2021 \u2026 \u2014 \u2013 \u0192 \u2044
+                         \u2039 \u203a \u2212 \u2030 \u201e \u201c \u201d \u2018
+                         \u2019 \u201a \u2122 \ufb01 \ufb02 \u0141 \u0152 \u0160
+                         \u0178 \u017d \u0131 \u0142 \u0153 \u0161 \u017e \uFFFD
+                         \u20ac \u00a1 \u00a2 \u00a3 \u00a4 \u00a5 \u00a6 \u00a7
+                         \u00a8 \u00a9 \u00aa \u00ab \u00ac \uFFFD \u00ae \u00af
+                         \u00b0 \u00b1 \u00b2 \u00b3 \u00b4 \u00b5 \u00b6 \u00b7
+                         \u00b8 \u00b9 \u00ba \u00bb \u00bc \u00bd \u00be \u00bf
+                         \u00c0 \u00c1 \u00c2 \u00c3 \u00c4 \u00c5 \u00c6 \u00c7
+                         \u00c8 \u00c9 \u00ca \u00cb \u00cc \u00cd \u00ce \u00cf
+                         \u00d0 \u00d1 \u00d2 \u00d3 \u00d4 \u00d5 \u00d6 \u00d7
+                         \u00d8 \u00d9 \u00da \u00db \u00dc \u00dd \u00de \u00df
+                         \u00e0 \u00e1 \u00e2 \u00e3 \u00e4 \u00e5 \u00e6 \u00e7
+                         \u00e8 \u00e9 \u00ea \u00eb \u00ec \u00ed \u00ee \u00ef
+                         \u00f0 \u00f1 \u00f2 \u00f3 \u00f4 \u00f5 \u00f6 \u00f7
+                         \u00f8 \u00f9 \u00fa \u00fb \u00fc \u00fd \u00fe \u00ff]
+
+      # Converts the given string to UTF-8, assuming it contains bytes in PDFDocEncoding.
+      def self.convert_to_utf8(str)
+        str.each_byte.with_object('') {|byte, result| result << CHARACTER_MAP[byte]}
+      end
+
+    end
+  end
+end

data/lib/hexapdf/utils/sorted_tree_node.rb

@@ -0,0 +1,339 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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.
+#++
+
+module HexaPDF
+  module Utils
+
+    # Provides the convenience methods that are used for name trees and number trees.
+    #
+    # The provided methods require two methods defined in the including class so that they work
+    # correctly:
+    #
+    # leaf_node_container_name::
+    #   Defines the dictionary entry name that contains the leaf node entries.
+    #
+    #   For example, for name trees this would be :Names.
+    #
+    # key_type::
+    #   Defines the class that is used for the keys in the tree.
+    #
+    #   The class defined this way is used for making sure that only valid keys are used.
+    #
+    #   For example, for name trees this would be String.
+    #
+    # See: HexaPDF::NameTreeNode, HexaPDF::NumberTreeNode
+    module SortedTreeNode
+
+      # Tree nodes must always be indirect.
+      #
+      # Note: There is no requirement that the root node of a tree must be indirect. However, making
+      # it indirect simplifies the implementation and is not against the spec.
+      def must_be_indirect?
+        true
+      end
+
+      # :call-seq:
+      #   tree.add_entry(key, data, overwrite: true)           -> true or false
+      #
+      # Adds a new tree entry (key-data pair) to the sorted tree and returns +true+ if it was
+      # successfully added.
+      #
+      # If the option +overwrite+ is +true+, an existing entry is overwritten. Otherwise an error is
+      # raised.
+      #
+      # This method has to be invoked on the root node of the tree!
+      def add_entry(key, data, overwrite: true)
+        if key?(:Limits)
+          raise HexaPDF::Error, "Adding a new tree entry is only allowed via the root node"
+        elsif !key.kind_of?(key_type)
+          raise ArgumentError, "A key must be a #{key_type} object, not a #{key.class}"
+        end
+
+        container_name = leaf_node_container_name
+
+        if (!key?(:Kids) && !key?(container_name)) ||
+            (value[:Kids] && self[:Kids].empty?)
+          value.delete(:Kids)
+          value[container_name] = []
+        end
+
+        if key?(container_name)
+          result = insert_pair(self[container_name], key, data, overwrite: overwrite)
+          split_if_needed(self, self)
+        else
+          stack = []
+          path_to_key(self, key, stack)
+
+          result = insert_pair(stack.last[container_name], key, data, overwrite: overwrite)
+          stack.last[:Limits] = stack.last[container_name].values_at(0, -2)
+          stack.reverse_each.inject do |nested_node, node|
+            nested_lower = nested_node[:Limits][0]
+            nested_upper = nested_node[:Limits][1]
+            if node[:Limits][0] > nested_lower
+              node[:Limits][0] = nested_lower
+            elsif node[:Limits][1] < nested_upper
+              node[:Limits][1] = nested_upper
+            end
+            node
+          end
+
+          split_if_needed(stack[-2] || self, stack[-1])
+        end
+
+        result
+      end
+
+      # Deletes the entry specified by the +key+ from the tree and returns the data. If the tree
+      # doesn't contain the key, +nil+ is returned.
+      #
+      # This method has to be invoked on the root node of the tree!
+      def delete_entry(key)
+        if key?(:Limits)
+          raise HexaPDF::Error, "Deleting a tree entry is only allowed via the root node"
+        end
+
+        stack = [self]
+        path_to_key(self, key, stack)
+        container_name = leaf_node_container_name
+
+        return unless stack.last[container_name]
+        index = find_in_leaf_node(stack.last[container_name], key)
+        return unless stack.last[container_name][index] == key
+
+        value = stack.last[container_name].delete_at(index)
+        document.delete(value) if value.kind_of?(HexaPDF::Object)
+        value = stack.last[container_name].delete_at(index)
+
+        stack.last[:Limits] = stack.last[container_name].values_at(0, -2) if stack.last[:Limits]
+
+        stack.reverse_each.inject do |nested_node, node|
+          if (!nested_node[container_name] || nested_node[container_name].empty?) &&
+              (!nested_node[:Kids] || nested_node[:Kids].empty?)
+            node[:Kids].delete_at(node[:Kids].index {|n| document.deref(n) == nested_node})
+            document.delete(nested_node)
+          end
+          if node[:Kids].size > 0 && node[:Limits]
+            node[:Limits][0] = document.deref(node[:Kids][0])[:Limits][0]
+            node[:Limits][1] = document.deref(node[:Kids][-1])[:Limits][1]
+          end
+          node
+        end
+
+        value
+      end
+
+      # Finds and returns the associated entry for the key, or returns +nil+ if no such key is
+      # found.
+      def find_entry(key)
+        container_name = leaf_node_container_name
+        node = self
+        result = nil
+
+        while result.nil?
+          if node.key?(container_name)
+            index = find_in_leaf_node(node[container_name], key)
+            if node[container_name][index] == key
+              result = document.deref(node[container_name][index + 1])
+            end
+          elsif node.key?(:Kids)
+            index = find_in_intermediate_node(node[:Kids], key)
+            node = document.deref(node[:Kids][index])
+            break unless key >= node[:Limits][0] && key <= node[:Limits][1]
+          else
+            break
+          end
+        end
+
+        result
+      end
+
+      # :call-seq:
+      #   node.each_entry {|key, data| block }   -> node
+      #   node.each_entry                        -> Enumerator
+      #
+      # Calls the given block once for each entry (key-data pair) of the sorted tree.
+      def each_entry
+        return to_enum(__method__) unless block_given?
+
+        container_name = leaf_node_container_name
+        stack = [self]
+        until stack.empty?
+          node = document.deref(stack.pop)
+          if node.key?(container_name)
+            data = node[container_name]
+            index = 0
+            while index < data.length
+              yield(data[index], document.deref(data[index + 1]))
+              index += 2
+            end
+          elsif node.key?(:Kids)
+            stack.concat(node[:Kids].reverse)
+          end
+        end
+
+        self
+      end
+
+      private
+
+      # Starting from node traverses the tree to the node where the key is located or, if not
+      # present, where it would be located and adds the nodes to the stack.
+      def path_to_key(node, key, stack)
+        return unless node.key?(:Kids)
+        index = find_in_intermediate_node(node[:Kids], key)
+        stack << document.deref(node[:Kids][index])
+        path_to_key(stack.last, key, stack)
+      end
+
+      # Returns the index into the /Kids array where the entry for +key+ is located or, if not
+      # present, where it would be located.
+      def find_in_intermediate_node(array, key)
+        left = 0
+        right = array.length - 1
+        while left < right
+          mid = (left + right) / 2
+          limits = document.deref(array[mid])[:Limits]
+          if limits[1] < key
+            left = mid + 1
+          elsif limits[0] > key
+            right = mid - 1
+          else
+            left = right = mid
+          end
+        end
+        left
+      end
+
+      # Inserts the key-data pair into array at the correct position and returns +true+ if the
+      # key-data pair was successfully inserted.
+      #
+      # An existing entry for the key is only overwritten if the option +overwrite+ is +true+.
+      def insert_pair(array, key, data, overwrite: true)
+        index = find_in_leaf_node(array, key)
+        return false if array[index] == key && !overwrite
+
+        if array[index] == key
+          array[index + 1] = data
+        else
+          array.insert(index, key, data)
+        end
+
+        true
+      end
+
+      # Returns the index into the array where the entry for +key+ is located or, if not present,
+      # where it would be located.
+      def find_in_leaf_node(array, key)
+        left = 0
+        right = array.length - 1
+        while left <= right
+          mid = ((left + right) / 2) & ~1 # mid must be even because of [key val key val...]
+          if array[mid] < key
+            left = mid + 2
+          elsif array[mid] > key
+            right = mid - 2
+          else
+            left = mid
+            right = left - 1
+          end
+        end
+        left
+      end
+
+      # Splits the leaf node if it contains the maximum number of entries.
+      def split_if_needed(parent, leaf_node)
+        container_name = leaf_node_container_name
+        max_size = config['sorted_tree.max_leaf_node_size'] * 2
+        return unless leaf_node[container_name].size >= max_size
+
+        split_point = (max_size / 2) & ~1
+        if parent == leaf_node
+          node1 = document.add(document.wrap({}, type: self.class))
+          node2 = document.add(document.wrap({}, type: self.class))
+          node1[container_name] = leaf_node[container_name][0, split_point]
+          node1[:Limits] = node1[container_name].values_at(0, -2)
+          node2[container_name] = leaf_node[container_name][split_point..-1]
+          node2[:Limits] = node2[container_name].values_at(0, -2)
+          parent.delete(container_name)
+          parent[:Kids] = [node1, node2]
+        else
+          node1 = document.add(document.wrap({}, type: self.class))
+          node1[container_name] = leaf_node[container_name].slice!(split_point..-1)
+          node1[:Limits] = node1[container_name].values_at(0, -2)
+          leaf_node[:Limits][1] = leaf_node[container_name][-2]
+          index = 1 + parent[:Kids].index {|o| document.deref(o) == leaf_node}
+          parent[:Kids].insert(index, node1)
+        end
+      end
+
+      # Validates the sorted tree node.
+      def perform_validation
+        super
+        container_name = leaf_node_container_name
+
+        # All kids entries must be indirect objects
+        if key?(:Kids)
+          self[:Kids].each do |kid|
+            unless (kid.kind_of?(HexaPDF::Object) && kid.indirect?) ||
+                kid.kind_of?(HexaPDF::Reference)
+              yield("Child entries of sorted tree nodes must be indirect objects", false)
+            end
+          end
+        end
+
+        # All keys of the container must be lexically ordered strings and the container must be
+        # correctly formatted
+        if key?(container_name)
+          container = self[container_name]
+          if container.length.odd?
+            yield("Sorted tree leaf node contains odd number of entries", false)
+          end
+          index = 0
+          old = nil
+          while index < container.length
+            key = document.unwrap(container[index])
+            if !key.kind_of?(key_type)
+              yield("A key must be a #{key_type} object, not a #{key.class}", false)
+            elsif old && old > key
+              yield("Sorted tree leaf node entries are not correctly sorted", false)
+            end
+            old = key
+            index += 2
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/version.rb

@@ -0,0 +1,39 @@
+# -*- encoding: utf-8 -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2016 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.
+#++
+
+module HexaPDF
+
+  # The version of HexaPDF.
+  VERSION = '0.1.0'
+
+end