hexapdf 0.1.0

data/lib/hexapdf/type/xref_stream.rb

@@ -0,0 +1,204 @@
+# -*- 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.
+#++
+
+require 'hexapdf/error'
+require 'hexapdf/stream'
+require 'hexapdf/xref_section'
+require 'hexapdf/type/trailer'
+
+module HexaPDF
+  module Type
+
+    # Represents PDF type XRef, cross-reference streams.
+    #
+    # A cross-reference stream is used as a more compact representation for an cross-reference
+    # section and trailer dictionary. The trailer dictionary is incorporated into the stream
+    # dictionary and the cross-reference section entries are stored in the stream itself,
+    # compressed to save space.
+    #
+    # == How are Cross-reference Streams Used?
+    #
+    # Cross-reference stream objects are only used when parsing or writing a PDF document.
+    #
+    # When a file is read and a cross-reference stream is found, it is loaded and its information is
+    # stored in a HexaPDF::Revision object. So from a user's perspective nothing changes when a
+    # cross-reference stream instead of a cross-reference section and trailer is encountered.
+    #
+    # This also means that all information stored in a cross-reference stream between parsing and
+    # writing is discarded when the PDF document gets written!
+    #
+    # Upon writing a revision it is checked whether that revision contains a cross-reference
+    # stream object. If it does the cross-reference stream object is updated with the
+    # cross-reference section and trailer information and then written. Otherwise a normal
+    # cross-reference section plus trailer are written.
+    #
+    # See: PDF1.7 s7.5.8
+    class XRefStream < HexaPDF::Stream
+
+      define_field :Type,  type: Symbol, default: :XRef, required: true, indirect: false, version: '1.5'
+      # Size is not required because it will be auto-filled before the object is written
+      define_field :Size,  type: Integer, indirect: false
+      define_field :Index, type: Array, indirect: false
+      define_field :Prev,  type: Integer, indirect: false
+      # W is not required because it will be auto-filled on #update_with_xref_section_and_trailer
+      define_field :W,     type: Array, indirect: false
+
+
+      # Returns an XRefSection that represents the content of this cross-reference stream.
+      #
+      # Each invocation returns a new XRefSection object based on the current data in the
+      # associated stream and dictionary.
+      def xref_section
+        index = self[:Index] || [0, self[:Size]]
+        parse_xref_section(index, self[:W])
+      end
+
+      # Returns a hash with the entries that represent the file trailer part of the
+      # cross-reference stream's dictionary.
+      #
+      # See: Type::Trailer
+      def trailer
+        Trailer.each_field.with_object({}) do |(name, _data), hash|
+          hash[name] = value[name] if key?(name)
+        end
+      end
+
+      # Makes this cross-reference stream represent the data in the given HexaPDF::XRefSection and
+      # Type::Trailer.
+      #
+      # The given cross-reference section is *not* stored but only used to rewrite the associated
+      # stream to reflect the cross-reference section. The dictionary is updated with the
+      # information from the trailer and the needed entries for the cross-reference section.
+      #
+      # If there are changes to the cross-reference section or trailer, this method has to be
+      # invoked again.
+      def update_with_xref_section_and_trailer(xref_section, trailer)
+        value.replace(trailer)
+        value[:Type] = :XRef
+        write_xref_section_to_stream(xref_section)
+        set_filter(:FlateDecode, Columns: value[:W].inject(:+), Predictor: 12)
+      end
+
+      private
+
+      TYPE_FREE       = 0 #:nodoc:
+      TYPE_IN_USE     = 1 #:nodoc:
+      TYPE_COMPRESSED = 2 #:nodoc:
+
+      # Parses the stream and returns the resulting HexaPDF::XRefSection object.
+      def parse_xref_section(index, w)
+        xref = XRefSection.new
+
+        entry_size = w.inject(:+)
+        data = stream
+        pos_in_data = 0
+
+        index.each_slice(2) do |first_oid, number_of_entries|
+          number_of_entries.times do |i|
+            oid = first_oid + i
+
+            # Default for first field: type 1
+            type_field = (w[0] == 0 ? TYPE_IN_USE : bytes_to_int(data, pos_in_data, w[0]))
+            # No default available for second field
+            field2 = bytes_to_int(data, pos_in_data + w[0], w[1])
+            # Default for third field is 0 for type 1, otherwise it needs to be specified!
+            field3 = bytes_to_int(data, pos_in_data + w[0] + w[1], w[2])
+
+            case type_field
+            when TYPE_IN_USE
+              xref.add_in_use_entry(oid, field3, field2)
+            when TYPE_FREE
+              xref.add_free_entry(oid, field3)
+            when TYPE_COMPRESSED
+              xref.add_compressed_entry(oid, field2, field3)
+            else
+              nil # Ignore entry as per PDF1.7 s7.5.8.3
+            end
+            pos_in_data += entry_size
+          end
+        end
+
+        xref
+      end
+
+      # Converts +length+ bytes from the +start+ index from the +string+ to an integer.
+      #
+      # The bytes are converted in the big-endian way. If +length+ is zero, zero is returned.
+      def bytes_to_int(string, start, length)
+        result = 0
+        end_index = start + length
+        while start < end_index
+          result = (result << 8) | string.getbyte(start)
+          start += 1
+        end
+        result
+      end
+
+      # Writes the given cross-reference section to the stream and sets the correct /W and /Index
+      # entries for the written data.
+      def write_xref_section_to_stream(xref_section)
+        value[:W], pack_string = calculate_w_entry_and_pack_string(xref_section[oid, gen].pos)
+        value[:Index] = []
+
+        stream = ''.b
+        xref_section.each_subsection do |entries|
+          value[:Index] << entries.first.oid << entries.length
+          entries.each do |entry|
+            data = if entry.in_use?
+                     [TYPE_IN_USE, entry.pos, entry.gen]
+                   elsif entry.free?
+                     [TYPE_FREE, 0, 65535]
+                   elsif entry.compressed?
+                     [TYPE_COMPRESSED, entry.objstm, entry.pos]
+                   else
+                     raise HexaPDF::Error, "Unsupported cross-reference entry #{entry}"
+                   end
+            stream << data.pack(pack_string)
+          end
+        end
+        self.stream = stream
+      end
+
+      # Returns the /W entry depending on the given maximal number for the second field as well as
+      # the appropriate entry packing string.
+      def calculate_w_entry_and_pack_string(max_number)
+        middle = Math.log(max_number, 255).ceil
+        middle = 4 if middle == 3
+        pack_string = "C#{'-CnNN'[middle]}n"
+        [[1, middle, 2], pack_string]
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type.rb

@@ -0,0 +1,67 @@
+# -*- 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
+
+  # == Overview
+  #
+  # The Type module contains implementations of the types defined in the PDF specification.
+  #
+  # Each type class is derived from either the Dictionary class or the Stream class, depending on
+  # whether the type has an associated stream.
+  module Type
+
+    autoload(:XRefStream, 'hexapdf/type/xref_stream')
+    autoload(:ObjectStream, 'hexapdf/type/object_stream')
+    autoload(:Trailer, 'hexapdf/type/trailer')
+    autoload(:Info, 'hexapdf/type/info')
+    autoload(:Catalog, 'hexapdf/type/catalog')
+    autoload(:ViewerPreferences, 'hexapdf/type/viewer_preferences')
+    autoload(:PageTreeNode, 'hexapdf/type/page_tree_node')
+    autoload(:Page, 'hexapdf/type/page')
+    autoload(:Names, 'hexapdf/type/names')
+    autoload(:FileSpecification, 'hexapdf/type/file_specification')
+    autoload(:EmbeddedFile, 'hexapdf/type/embedded_file')
+    autoload(:Resources, 'hexapdf/type/resources')
+    autoload(:GraphicsStateParameter, 'hexapdf/type/graphics_state_parameter')
+    autoload(:Image, 'hexapdf/type/image')
+    autoload(:Form, 'hexapdf/type/form')
+    autoload(:Font, 'hexapdf/type/font')
+    autoload(:FontDescriptor, 'hexapdf/type/font_descriptor')
+    autoload(:FontSimple, 'hexapdf/type/font_simple')
+    autoload(:FontType1, 'hexapdf/type/font_type1')
+    autoload(:FontTrueType, 'hexapdf/type/font_true_type')
+
+  end
+
+end

data/lib/hexapdf/utils/bit_field.rb

@@ -0,0 +1,87 @@
+# -*- 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
+
+    # This module is intended to be used to extend class objects. It provides the method #bit_field
+    # for declaring a bit field.
+    module BitField
+
+      # Creates a bit field for managing the integer attribute +name+.
+      #
+      # The +mapping+ argument specifies the mapping of names to bit indices which allows one to use
+      # either the bit name or its index when getting or setting. When using an unknown bit name or
+      # bit index, an error is raised.
+      #
+      # The calling class needs to respond to \#name and \#name= because these methods are used to
+      # get and set the raw integer value.
+      #
+      # After invoking the method the calling class has three new instance methods:
+      #
+      # * NAME_values which returns an array of bit names representing the set bits.
+      # * NAME_include?(bit) which returns true if the given bit is set.
+      # * set_NAME(*bits, clear_existing: false) for setting the given bits.
+      #
+      # The method names can be overridden using the arguments +lister+, +getter+ and +setter+.
+      def bit_field(name, mapping, lister: "#{name}_values", getter: "#{name}_include?",
+                    setter: "set_#{name}")
+        bit_names = mapping.keys
+        mapping.default_proc = proc do |h, k|
+          if h.value?(k)
+            h[k] = k
+          else
+            raise ArgumentError, "Invalid bit field name or index '#{k}' for #{self.name}##{name}"
+          end
+        end
+        value_getter = name
+        value_setter = "#{name}="
+
+        define_method(lister) do
+          bit_names.map {|n| send(getter, n) ? n : nil}.compact
+        end
+        define_method(getter) do |bit|
+          (send(value_getter) || 0)[mapping[bit]] == 1
+        end
+        define_method(setter) do |*bits, clear_existing: false|
+          send(value_setter, 0) if clear_existing || send(value_getter).nil?
+          result = send(value_getter)
+          bits.each {|bit| result |= 1 << mapping[bit]}
+          send(value_setter, result)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/utils/bit_stream.rb

@@ -0,0 +1,148 @@
+# -*- 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.
+#++
+
+require 'hexapdf/error'
+
+module HexaPDF
+  module Utils
+
+    # Helper class for reading variable length integers from a bit stream.
+    #
+    # This class allows one to read integers with a variable width of up to 16 bit from a bit
+    # stream using the #read method. The data from where these bits are read, can be set on
+    # intialization and additional data can later be appended.
+    class BitStreamReader
+
+      # Creates a new object, optionally providing the string from where the bits should be read.
+      def initialize(data = '')
+        @data = data.force_encoding(Encoding::BINARY)
+        @pos = 0
+        @bit_cache = 0
+        @available_bits = 0
+      end
+
+      # Appends some data to the string from where bits are read.
+      def append_data(str)
+        @data = @data[@pos, @data.length - @pos] << str
+        @pos = 0
+      end
+
+      # Returns the number of remaining bits that can be read.
+      def remaining_bits
+        (@data.length - @pos) * 8 + @available_bits
+      end
+
+      # Returns +true+ if +bits+ number of bits can be read.
+      def read?(bits)
+        fill_bit_cache
+        @available_bits >= bits
+      end
+
+      # Reads +bits+ number of bits.
+      #
+      # Raises an exception if not enough bits are available for reading.
+      def read(bits)
+        fill_bit_cache
+        raise HexaPDF::Error, "Not enough bits available for reading" if @available_bits < bits
+
+        @available_bits -= bits
+        result = @bit_cache >> @available_bits
+        @bit_cache &= (1 << @available_bits) - 1
+
+        result
+      end
+
+      private
+
+      LENGTH_TO_TYPE = {4 => 'N', 2 => 'n', 1 => 'C'} # :nodoc:
+      FOUR_TO_INFINITY = 4..Float::INFINITY # :nodoc:
+
+      # Fills the bit cache so that at least 16bit are available (if possible).
+      def fill_bit_cache
+        return unless @available_bits <= 16 && @pos != @data.size
+
+        l = case @data.size - @pos
+            when FOUR_TO_INFINITY then 4
+            when 2, 3 then 2
+            else 1
+            end
+        @bit_cache = (@bit_cache << 8 * l) | @data[@pos, l].unpack(LENGTH_TO_TYPE[l]).first
+        @pos += l
+        @available_bits += 8 * l
+      end
+
+    end
+
+    # Helper class for writing out variable length integers one after another as bit stream.
+    #
+    # This class allows one to write integers with a variable width of up to 16 bit to a bit
+    # stream using the #write method. Every time when at least 16 bits are available, the #write
+    # method returns those 16 bits as string and removes them from the internal cache.
+    #
+    # Once all data has been written, the #finalize method must be called to get the last
+    # remaining bits (again as a string).
+    class BitStreamWriter
+
+      def initialize # :nodoc:
+        @bit_cache = 0
+        @available_bits = 0
+      end
+
+      # Writes the integer +int+ with a width of +bits+ to the bit stream.
+      #
+      # Returns a 16bit binary string if enough bits are available or an empty binary string
+      # otherwise.
+      def write(int, bits)
+        @available_bits += bits
+        @bit_cache |= int << (32 - @available_bits)
+        if @available_bits >= 16
+          @available_bits -= 16
+          result = (@bit_cache >> 24).chr << ((@bit_cache >> 16) & 0xFF).chr
+          @bit_cache = (@bit_cache & 0xFFFF) << 16
+          result
+        else
+          ''.b
+        end
+      end
+
+      # Retrieves the final (zero padded) bits as a string.
+      def finalize
+        result = [@bit_cache].pack('N')[0...(@available_bits / 8.0).ceil]
+        initialize
+        result
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/utils/lru_cache.rb

@@ -0,0 +1,65 @@
+# -*- 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
+
+    # A simple least recently used (LRU) cache.
+    #
+    # The cache relies on the fact that Ruby's Hash class maintains insertion order. So deleting
+    # and re-inserting a key-value pair on access moves the key to the last position. When an
+    # entry is added and the cache is full, the first entry is removed.
+    class LRUCache
+
+      # Creates a new LRUCache that can hold +size+ entries.
+      def initialize(size)
+        @size = size
+        @cache = {}
+      end
+
+      # Returns the stored value for +key+ or +nil+ if no value was stored under the key.
+      def [](key)
+        (val = @cache.delete(key)).nil? ? nil : @cache[key] = val
+      end
+
+      # Stores the +value+ under the +key+.
+      def []=(key, value)
+        @cache.delete(key)
+        @cache[key] = value
+        @cache.shift if @cache.length > @size
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/utils/math_helpers.rb

@@ -0,0 +1,55 @@
+# -*- 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
+
+    # This module provides some mathematical helper functions.
+    module MathHelpers
+
+      module_function
+
+      # Converts degrees to radians.
+      def deg_to_rad(degrees)
+        degrees * Math::PI / 180
+      end
+
+      # Converts radians to degress.
+      def rad_to_deg(radians)
+        radians * 180 / Math::PI
+      end
+
+    end
+
+  end
+end