hexapdf 0.1.0

data/lib/hexapdf/serializer.rb

@@ -0,0 +1,326 @@
+# -*- 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 'time'
+require 'hexapdf/tokenizer'
+require 'hexapdf/filter'
+require 'hexapdf/utils/lru_cache'
+
+module HexaPDF
+
+  # Knows how to serialize Ruby objects for a PDF file.
+  #
+  # For normal serialization purposes, the #serialize or #serialize_to_io methods should be used.
+  # However, if the type of the object to be serialized is known, a specialized serialization
+  # method like #serialize_float can be used.
+  #
+  # Additionally, an object for encrypting strings and streams while serializing can be set via the
+  # #encrypter= method. The assigned object has to respond to #encrypt_string(str, ind_obj) (where
+  # the string is part of the indirect object; returns the encrypted string) and
+  # #encrypt_stream(stream) (returns a fiber that represents the encrypted stream).
+  #
+  #
+  # == How This Class Works
+  #
+  # The main public interface consists of the #serialize and #serialize_to_io methods which accept
+  # an object and return its serialized form. During serialization of this object it is accessible
+  # by individual serialization methods via the @object instance variable (useful if the object is a
+  # composed object).
+  #
+  # Internally, the #__serialize method is used for invoking the correct serialization method
+  # based on the class of a given object. It is also used for serializing individual parts of a
+  # composed object.
+  #
+  # Therefore the serializer contains one serialization method for each class it needs to
+  # serialize. The naming scheme of these methods is based on the class name: The full class name
+  # is converted to lowercase, the namespace separator '::' is replaced with a single underscore
+  # and the string "serialize_" is then prepended.
+  #
+  # Examples:
+  #
+  #   NilClass                 => serialize_nilclass
+  #   TrueClass                => serialize_trueclass
+  #   HexaPDF::Object          => serialize_hexapdf_object
+  #
+  # If no serialization method for a specific class is found, the ancestors classes are tried.
+  #
+  # See: PDF1.7 s7.3
+  class Serializer
+
+    # The encrypter to use for encrypting strings and streams. If +nil+, strings and streams are not
+    # encrypted.
+    #
+    # Default: +nil+
+    attr_accessor :encrypter
+
+    # Creates a new Serializer object.
+    def initialize
+      @dispatcher = Hash.new do |h, klass|
+        method = nil
+        klass.ancestors.each do |ancestor_klass|
+          method = "serialize_#{ancestor_klass.name.downcase.gsub(/::/, '_')}"
+          (h[klass] = method; break) if respond_to?(method, true)
+        end
+        method
+      end
+      @encrypter = false
+      @io = nil
+      @object = nil
+    end
+
+    # Returns the serialized form of the given object.
+    #
+    # For developers: While the object is serialized, methods can use the instance variable
+    # @object to obtain information about or use the object in case it is a composed object.
+    def serialize(obj)
+      @object = obj
+      __serialize(obj)
+    ensure
+      @object = nil
+    end
+
+    # Serializes the given object and writes it to the IO.
+    #
+    # Also see: #serialize
+    def serialize_to_io(obj, io)
+      @io = io
+      @io << serialize(obj).freeze
+    ensure
+      @io = nil
+    end
+
+    # Serializes the +nil+ value.
+    #
+    # See: PDF1.7 s7.3.9
+    def serialize_nilclass(_obj)
+      "null"
+    end
+
+    # Serializes the +true+ value.
+    #
+    # See: PDF1.7 s7.3.2
+    def serialize_trueclass(_obj)
+      "true"
+    end
+
+    # Serializes the +false+ value.
+    #
+    # See: PDF1.7 s7.3.2
+    def serialize_falseclass(_obj)
+      "false"
+    end
+
+    # Serializes a Numeric object (either Integer or Float).
+    #
+    # This method should be used for cases where it is known that the object is either an Integer
+    # or a Float.
+    #
+    # See: PDF1.7 s7.3.3
+    def serialize_numeric(obj)
+      obj.kind_of?(Integer) ? obj.to_s : serialize_float(obj)
+    end
+
+    # Serializes an Integer object.
+    #
+    # See: PDF1.7 s7.3.3
+    def serialize_integer(obj)
+      obj.to_s
+    end
+
+    # Serializes a Float object.
+    #
+    # See: PDF1.7 s7.3.3
+    def serialize_float(obj)
+      obj.abs < 0.0001 && obj != 0 ? sprintf("%.6f".freeze, obj) : obj.round(6).to_s
+    end
+
+    # The regexp matches all characters that need to be escaped and the substs hash contains the
+    # mapping from these characters to their escaped form.
+    #
+    # See PDF1.7 s7.3.5
+    NAME_SUBSTS = {} # :nodoc:
+    [0..32, 127..255, Tokenizer::DELIMITER.bytes, Tokenizer::WHITESPACE.bytes, [35]].each do |a|
+      a.each {|c| NAME_SUBSTS[c.chr] = "##{c.to_s(16).rjust(2, "0")}"}
+    end
+    NAME_REGEXP = /[^!-~&&[^##{Regexp.escape(Tokenizer::DELIMITER)}#{Regexp.escape(Tokenizer::WHITESPACE)}]]/ # :nodoc:
+    NAME_CACHE = Utils::LRUCache.new(1000) # :nodoc:
+
+    # Serializes a Symbol object (i.e. a PDF name object).
+    #
+    # See: PDF1.7 s7.3.5
+    def serialize_symbol(obj)
+      NAME_CACHE[obj] ||=
+        begin
+          str = obj.to_s.force_encoding(Encoding::BINARY)
+          str.gsub!(NAME_REGEXP) {|m| NAME_SUBSTS[m]}
+          "/#{str}"
+        end
+    end
+
+    BYTE_IS_DELIMITER = {40 => true, 47 => true, 60 => true, 91 => true, # :nodoc:
+                         41 => true, 62 => true, 93 => true}
+
+    # Serializes an Array object.
+    #
+    # See: PDF1.7 s7.3.6
+    def serialize_array(obj)
+      str = "["
+      index = 0
+      while index < obj.size
+        tmp = __serialize(obj[index])
+        str << " ".freeze unless BYTE_IS_DELIMITER[tmp.getbyte(0)] ||
+          BYTE_IS_DELIMITER[str.getbyte(-1)]
+        str << tmp
+        index += 1
+      end
+      str << "]".freeze
+    end
+
+    # Serializes a Hash object (i.e. a PDF dictionary object).
+    #
+    # See: PDF1.7 s7.3.7
+    def serialize_hash(obj)
+      str = "<<"
+      obj.each do |k, v|
+        next if v.nil? || (v.respond_to?(:null?) && v.null?)
+        str << __serialize(k)
+        tmp = __serialize(v)
+        str << " ".freeze unless BYTE_IS_DELIMITER[tmp.getbyte(0)] ||
+          BYTE_IS_DELIMITER[str.getbyte(-1)]
+        str << tmp
+      end
+      str << ">>".freeze
+    end
+
+    STRING_ESCAPE_MAP = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r"} # :nodoc:
+
+    # Serializes a String object.
+    #
+    # See: PDF1.7 s7.3.4
+    def serialize_string(obj)
+      if @encrypter && @object.kind_of?(HexaPDF::Object) && @object.indirect?
+        obj = encrypter.encrypt_string(obj, @object)
+      elsif obj.encoding != Encoding::BINARY && obj =~ /[^ -~\t\r\n]/
+        obj = "\xFE\xFF".b << obj.encode(Encoding::UTF_16BE).force_encoding(Encoding::BINARY)
+      elsif obj.encoding != Encoding::BINARY
+        obj = obj.b
+      end
+      "(" << obj.gsub(/[\(\)\\\r]/n) {|m| STRING_ESCAPE_MAP[m]} << ")".freeze
+    end
+
+    # The ISO PDF specification differs in respect to the supported date format. When converting
+    # to a date string, a format suitable for both is output.
+    #
+    # See: PDF1.7 s7.9.4, ADB1.7 3.8.3
+    def serialize_time(obj)
+      zone = obj.strftime("%z'")
+      if zone == "+0000'"
+        zone = ''
+      else
+        zone[3, 0] = "'"
+      end
+      serialize_string(obj.strftime("D:%Y%m%d%H%M%S#{zone}"))
+    end
+
+    # See: #serialize_time
+    def serialize_date(obj)
+      serialize_time(obj.to_time)
+    end
+
+    # See: #serialize_time
+    def serialize_datetime(obj)
+      serialize_time(obj.to_time)
+    end
+
+    private
+
+    # Uses #serialize_hexapdf_reference if it is an indirect object, otherwise just serializes
+    # the objects value.
+    def serialize_hexapdf_object(obj)
+      if obj.indirect? && obj != @object
+        serialize_hexapdf_reference(obj)
+      else
+        __serialize(obj.value)
+      end
+    end
+
+    # See: PDF1.7 s7.3.10
+    def serialize_hexapdf_reference(obj)
+      "#{obj.oid} #{obj.gen} R".freeze
+    end
+
+    # Serializes the streams dictionary and its stream.
+    #
+    # See: PDF1.7 s7.3.8
+    def serialize_hexapdf_stream(obj)
+      if !obj.indirect?
+        raise HexaPDF::Error, "Can't serialize PDF stream without object identifier"
+      elsif obj != @object
+        return serialize_hexapdf_reference(obj)
+      end
+
+      fiber = if @encrypter
+                encrypter.encrypt_stream(obj)
+              else
+                obj.stream_encoder
+              end
+
+      if @io && fiber.respond_to?(:length) && fiber.length >= 0
+        obj.value[:Length] = fiber.length
+        @io << __serialize(obj.value)
+        @io << "stream\n".freeze
+        while fiber.alive? && (data = fiber.resume)
+          @io << data.freeze
+        end
+        @io << "\nendstream".freeze
+
+        nil
+      else
+        data = Filter.string_from_source(fiber)
+        obj.value[:Length] = data.size
+
+        str = __serialize(obj.value)
+        str << "stream\n".freeze
+        str << data
+        str << "\nendstream".freeze
+      end
+    end
+
+    # Invokes the correct serialization method for the object.
+    def __serialize(obj)
+      send(@dispatcher[obj.class], obj)
+    end
+
+  end
+
+end

data/lib/hexapdf/stream.rb

@@ -0,0 +1,279 @@
+# -*- 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/dictionary'
+require 'hexapdf/filter'
+
+module HexaPDF
+
+  # Container for stream data that is more complex than a string.
+  #
+  # This helper class wraps all information necessary to read stream data by using a Fiber object
+  # (see HexaPDF::Filter). The underlying data either comes from an IO object, a file represented by
+  # its file name or a Fiber defined via a Proc object.
+  #
+  # Additionally, the #filter and #decode_parms can be set to indicate that the data returned from
+  # the Fiber needs to be post-processed. The +filter+ and +decode_parms+ are automatically
+  # normalized to arrays on assignment to ease further processing.
+  class StreamData
+
+    # The filter(s) that need to be applied for getting the decoded stream data.
+    attr_reader :filter
+
+    # The decoding parameters associated with the +filter+(s).
+    attr_reader :decode_parms
+
+    # :call-seq:
+    #   StreamData.new(io)          -> stream_data
+    #   StreamData.new(str)         -> stream_data
+    #   StreamData.new(proc)        -> stream_data
+    #   StreamData.new { block }    -> stream_data
+    #
+    # Creates a new StreamData object for the given +source+ and with the given options.
+    #
+    # The +source+ can be:
+    #
+    # * An IO stream which is read starting from a specific +offset+ for a specific +length+
+    #
+    # * A string which is interpreted as a file name and read starting from a specific +offset+
+    # * and for a specific +length+
+    #
+    # * A Proc object (that is converted to a Fiber when needed) in which case the +offset+ and
+    #   value is ignored. The Proc object can also be passed by using a block.
+    def initialize(source =  nil, offset: nil, length: nil, filter: nil, decode_parms: nil, &block)
+      if source.nil? && !block_given?
+        raise ArgumentError, "Either a source object or a block must be given"
+      end
+      @source = source || block
+      @offset = offset
+      @length = length
+      @filter = [filter].flatten.compact
+      @decode_parms = [decode_parms].flatten
+      freeze
+    end
+
+    # Returns a Fiber for getting at the data of the stream represented by this object.
+    def fiber(chunk_size = 0)
+      if @source.kind_of?(Proc)
+        FiberWithLength.new(@length, &@source)
+      elsif @source.kind_of?(String)
+        HexaPDF::Filter.source_from_file(@source, pos: @offset || 0, length: @length || -1,
+                                         chunk_size: chunk_size)
+      else
+        HexaPDF::Filter.source_from_io(@source, pos: @offset || 0, length: @length || -1,
+                                       chunk_size: chunk_size)
+      end
+    end
+
+  end
+
+  # Implements Stream objects of the PDF object system.
+  #
+  # == Stream Objects
+  #
+  # A stream may also be associated with a PDF object but only if the value is a PDF dictionary.
+  # This associated dictionary further describes the stream, like its length or how it is encoded.
+  #
+  # Such a stream object in PDF contains string data but of possibly unlimited length. Therefore
+  # it is used for large amounts of data like images, page descriptions or embedded files.
+  #
+  # The basic Object class cannot hold stream data, only this subclass contains the necessary
+  # methods to conveniently work with the stream data!
+  #
+  # See: PDF1.7 s7.3.8, Dictionary
+  class Stream < Dictionary
+
+    define_field :Length,       type: Integer # not required, will be auto-filled when writing
+    define_field :Filter,       type: [Symbol, Array]
+    define_field :DecodeParms,  type: [Dictionary, Hash, Array]
+    define_field :F,            type: :FileSpec, version: '1.2'
+    define_field :FFilter,      type: [Symbol, Array], version: '1.2'
+    define_field :FDecodeParms, type: [Dictionary, Hash, Array], version: '1.2'
+    define_field :DL,           type: Integer
+
+    # Stream objects must always be indirect.
+    def must_be_indirect?
+      true
+    end
+
+    # Assigns a new stream data object.
+    #
+    # The +stream+ argument can be a HexaPDF::StreamData object, a String object or +nil+.
+    #
+    # If +stream+ is +nil+, an empty binary string is used instead.
+    def stream=(stream)
+      data.stream = stream
+      after_data_change
+    end
+
+    # Returns the (possibly decoded) stream data as string.
+    #
+    # Note that modifications done to the returned string are not reflected in the Stream object
+    # itself. The modified string must explicitly be assigned via #stream= to take effect.
+    def stream
+      if data.stream.kind_of?(String)
+        data.stream.dup
+      else
+        HexaPDF::Filter.string_from_source(stream_decoder)
+      end
+    end
+
+    # Returns the raw stream object.
+    #
+    # The returned value can be of many different types (see #stream=). For working with the
+    # decoded stream contents use #stream.
+    def raw_stream
+      data.stream
+    end
+
+    # Returns the Fiber representing the unprocessed content of the stream.
+    def stream_source
+      if data.stream.kind_of?(String)
+        HexaPDF::Filter.source_from_string(data.stream)
+      else
+        data.stream.fiber(config['io.chunk_size'.freeze])
+      end
+    end
+
+    # Returns the decoder Fiber for the stream data.
+    #
+    # See the Filter module for more information on how to work with the fiber.
+    def stream_decoder
+      source = stream_source
+
+      if data.stream.kind_of?(StreamData)
+        data.stream.filter.zip(data.stream.decode_parms) do |filter, decode_parms|
+          source = filter_for_name(filter).decoder(source, decode_parms)
+        end
+      end
+
+      source
+    end
+
+    # Returns the encoder Fiber for the stream data.
+    #
+    # The two arguments can be used to add additional filters for *only* this returned encoder
+    # Fiber. They should normally *not* be used and are here for use by the encryption facilities.
+    #
+    # See the Filter module for more information on how to work with the fiber.
+    def stream_encoder(additional_filter = nil, additional_decode_parms = nil)
+      encoder_data = [additional_filter, document.unwrap(self[:Filter])].flatten.
+        zip([additional_decode_parms, document.unwrap(self[:DecodeParms])].flatten).
+        delete_if {|f, _| f.nil?}
+      source = stream_source
+
+      if data.stream.kind_of?(StreamData)
+        decoder_data = data.stream.filter.zip(data.stream.decode_parms)
+
+        while !decoder_data.empty? && !encoder_data.empty? && decoder_data.last == encoder_data.last
+          decoder_data.pop
+          encoder_data.pop
+        end
+
+        decoder_data.each do |filter, decode_parms|
+          source = filter_for_name(filter).decoder(source, decode_parms)
+        end
+      end
+
+      encoder_data.reverse!.each do |filter, decode_parms|
+        source = filter_for_name(filter).encoder(source, decode_parms)
+      end
+
+      source
+    end
+
+    # Sets the filters that should be used for encoding the stream.
+    #
+    # The arguments +filter+ as well as +decode_parms+ can either be a single items or arrays.
+    #
+    # The filters have to be specified in the *decoding order*! For example, if the filters would
+    # be [:A85, :Fl], the stream would first be encoded with the Flate and then with the ASCII85
+    # filter.
+    def set_filter(filter, decode_parms = nil)
+      if filter.nil? || (filter.kind_of?(Array) && filter.empty?)
+        delete(:Filter)
+      else
+        self[:Filter] = filter
+      end
+      if decode_parms.nil? || (decode_parms.kind_of?(Array) && decode_parms.empty?) ||
+          !key?(:Filter)
+        delete(:DecodeParms)
+      else
+        self[:DecodeParms] = decode_parms
+      end
+    end
+
+    private
+
+    # Makes sure that the stream data is either a String or a HexaPDF::StreamData object.
+    def after_data_change
+      super
+      data.stream ||= ''.b
+      unless data.stream.kind_of?(StreamData) || data.stream.kind_of?(String)
+        raise ArgumentError, "Object of class #{data.stream.class} cannot be used as stream value"
+      end
+    end
+
+    # Returns the filter object that corresponds to the given filter name.
+    #
+    # See: HexaPDF::Filter
+    def filter_for_name(filter_name)
+      GlobalConfiguration.constantize('filter.map', filter_name) do
+        raise HexaPDF::Error, "Unknown stream filter '#{filter_name}' encountered"
+      end
+    end
+
+    # :nodoc:
+    # A mapping from short name to long name for filters.
+    FILTER_MAP = {AHx: :ASCIIHexDecode, A85: :ASCII85Decode, LZW: :LZWDecode,
+                  Fl: :FlateDecode, RL: :RunLengthDecode, CCF: :CCITTFaxDecode, DCT: :DCTDecode}
+
+    # Validates the /Filter entry so that it contains only long-name filter names.
+    def perform_validation
+      super
+      if value[:Filter].kind_of?(Symbol) && FILTER_MAP.key?(value[:Filter])
+        yield("A stream's /Filter entry may only use long-form filter names", true)
+        value[:Filter] = FILTER_MAP[value[:Filter]]
+      elsif value[:Filter].kind_of?(Array)
+        value[:Filter].map! do |filter|
+          next filter unless FILTER_MAP.key?(filter)
+          yield("A stream's /Filter entry may only use long-form filter names", true)
+          FILTER_MAP[filter]
+        end
+      end
+    end
+
+  end
+
+end