hexapdf 0.1.0

data/lib/hexapdf/revision.rb

@@ -0,0 +1,206 @@
+# -*- 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/utils/object_hash'
+
+module HexaPDF
+
+  # Embodies one revision of a PDF file, either the initial version or an incremental update.
+  #
+  # The purpose of a Revision object is to manage the objects and the trailer of one revision.
+  # These objects can either be added manually or loaded from a cross-reference section or stream.
+  # Since a PDF file can be incrementally updated, it can have multiple revisions.
+  #
+  # If a revision doesn't have an associated cross-reference section, it wasn't created from a PDF
+  # file.
+  #
+  # See: PDF1.7 s7.5.6, Revisions
+  class Revision
+
+    include Enumerable
+
+    # The trailer dictionary
+    attr_reader :trailer
+
+    # The callable object responsible for loading objects.
+    attr_accessor :loader
+
+    # :call-seq:
+    #   Revision.new(trailer)                                           -> revision
+    #   Revision.new(trailer, xref_section: section, loader: loader)    -> revision
+    #   Revision.new(trailer, xref_section: section) {|entry| block }   -> revision
+    #
+    # Creates a new Revision object.
+    #
+    # Options:
+    #
+    # xref_section::
+    #   An XRefSection object that contains information on how to load objects. If this option is
+    #   specified, then a +loader+ or a block also needs to be specified!
+    #
+    # loader::
+    #   The loader object needs to respond to +call+ taking a cross-reference entry and returning
+    #   the loaded object. If no +xref_section+ is supplied, this value is not used.
+    #
+    #   If a block is given, it is used instead of the loader object.
+    def initialize(trailer, xref_section: nil, loader: nil, &block)
+      @trailer = trailer
+      @loader = xref_section && (block || loader)
+      @xref_section = xref_section || XRefSection.new
+      @objects = HexaPDF::Utils::ObjectHash.new
+    end
+
+    # Returns the next free object number for adding an object to this revision.
+    def next_free_oid
+      ((a = @xref_section.max_oid) < (b = @objects.max_oid) ? b : a) + 1
+    end
+
+    # :call-seq:
+    #   revision.object(ref)    -> obj or nil
+    #   revision.object(oid)    -> obj or nil
+    #
+    # Returns the object for the given reference or object number if such an object is available
+    # in this revision, or +nil+ otherwise.
+    #
+    # If the revision has an entry but one that is pointing to a free entry in the cross-reference
+    # section, an object representing PDF null is returned.
+    def object(ref)
+      if ref.respond_to?(:oid)
+        oid = ref.oid
+        gen = ref.gen
+      else
+        oid = ref
+      end
+
+      if @objects.entry?(oid, gen)
+        @objects[oid, gen]
+      elsif (xref_entry = @xref_section[oid, gen])
+        load_object(xref_entry)
+      else
+        nil
+      end
+    end
+
+    # :call-seq:
+    #   revision.object?(ref)    -> true or false
+    #   revision.object?(oid)    -> true or false
+    #
+    # Returns +true+ if the revision contains an object
+    #
+    # * for the exact reference if the argument responds to :oid, or else
+    # * for the given object number.
+    def object?(ref)
+      if ref.respond_to?(:oid)
+        @objects.entry?(ref.oid, ref.gen) || @xref_section.entry?(ref.oid, ref.gen)
+      else
+        @objects.entry?(ref) || @xref_section.entry?(ref)
+      end
+    end
+
+    # :call-seq:
+    #   revision.add(obj)   -> obj
+    #
+    # Adds the given object (needs to be a HexaPDF::Object) to this revision and returns it.
+    def add(obj)
+      if object?(obj.oid)
+        raise HexaPDF::Error, "A revision can only contain one object with a given object number"
+      elsif !obj.indirect?
+        raise HexaPDF::Error, "A revision can only contain indirect objects"
+      end
+      add_without_check(obj)
+    end
+
+    # :call-seq:
+    #   revision.delete(ref, mark_as_free: true)
+    #   revision.delete(oid, mark_as_free: true)
+    #
+    # Deletes the object specified either by reference or by object number from this revision by
+    # marking it as free.
+    #
+    # If the +mark_as_free+ option is set to +false+, the object is really deleted.
+    def delete(ref_or_oid, mark_as_free: true)
+      return unless object?(ref_or_oid)
+      ref_or_oid = ref_or_oid.oid if ref_or_oid.respond_to?(:oid)
+
+      obj = object(ref_or_oid)
+      obj.data.value = nil
+      if mark_as_free
+        add_without_check(HexaPDF::Object.new(nil, oid: obj.oid, gen: obj.gen))
+      else
+        @xref_section.delete(ref_or_oid)
+        @objects.delete(ref_or_oid)
+      end
+    end
+
+    # :call-seq:
+    #   revision.each {|obj| block }   -> revision
+    #   revision.each                  -> Enumerator
+    #
+    # Calls the given block once for every object of the revision.
+    #
+    # Objects that are loadable via an associated cross-reference section but are currently not,
+    # are loaded automatically.
+    def each
+      return to_enum(__method__) unless block_given?
+
+      if defined?(@all_objects_loaded)
+        @objects.each {|_oid, _gen, data| yield(data)}
+      else
+        seen = {}
+        @objects.each {|oid, _gen, data| seen[oid] = true; yield(data)}
+        @xref_section.each do |oid, _gen, data|
+          next if seen.key?(oid)
+          yield(@objects[oid] || load_object(data))
+        end
+        @all_objects_loaded = true
+      end
+
+      self
+    end
+
+    private
+
+    # Loads a single object from the associated cross-reference section.
+    def load_object(xref_entry)
+      add_without_check(@loader.call(xref_entry))
+    end
+
+    # Adds the object to the available objects of this revision and returns it.
+    def add_without_check(obj)
+      @objects[obj.oid, obj.gen] = obj
+    end
+
+  end
+
+end

data/lib/hexapdf/revisions.rb

@@ -0,0 +1,194 @@
+# -*- 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/parser'
+require 'hexapdf/revision'
+require 'hexapdf/type/trailer'
+
+module HexaPDF
+
+  # Manages the revisions of a PDF document.
+  #
+  # A PDF document has one revision when it is created. Later, new revisions are added when changes
+  # are made. This allows for adding information/content to a PDF file without changing the original
+  # content.
+  #
+  # The order of the revisions is important. In HexaPDF the oldest revision always has index 0 and
+  # the newest revision the highest index. This is also the order in which the revisions get
+  # written.
+  #
+  # See: PDF1.7 s7.5.6, HexaPDF::Revision
+  class Revisions
+
+    class << self
+
+      # Loads all revisions for the document from the given IO and returns the created Revisions
+      # object.
+      #
+      # If the +io+ object is +nil+, an empty Revisions object is returned.
+      def from_io(document, io)
+        return new(document) if io.nil?
+
+        parser = Parser.new(io, document)
+        object_loader = lambda {|xref_entry| parser.load_object(xref_entry)}
+        revision_loader = lambda do |offset|
+          xref_section, trailer = parser.load_revision(offset)
+          Revision.new(document.wrap(trailer, type: :XXTrailer), xref_section: xref_section,
+                       loader: object_loader)
+        end
+
+        revisions = [revision_loader.call(parser.startxref_offset)]
+
+        i = revisions.length - 1
+        while i >= 0
+          # PDF1.7 s7.5.5 states that :Prev needs to be indirect, Adobe's reference 3.4.4 says it
+          # should be direct. Adobe's POV is followed here. Same with :XRefStm.
+          xrefstm = revisions[i].trailer.value[:XRefStm]
+          prev = revisions[i].trailer.value[:Prev]
+          new_revisions = [(revision_loader.call(prev) if prev),
+                           (revision_loader.call(xrefstm) if xrefstm)].compact
+          revisions.insert(i, *new_revisions)
+          i += new_revisions.length - 1
+        end
+
+        document.version = parser.file_header_version
+        new(document, initial_revisions: revisions)
+      end
+
+    end
+
+    include Enumerable
+
+    # Creates a new revisions object for the given PDF document.
+    #
+    # Options:
+    #
+    # initial_revisions::
+    #     An array of revisions that should initially be used. If this option is not specified, a
+    #     single empty revision is added.
+    def initialize(document, initial_revisions: nil)
+      @document = document
+      @revisions = []
+      if initial_revisions
+        @revisions += initial_revisions
+      else
+        add
+      end
+    end
+
+    # Returns the revision at the specified index.
+    def revision(index)
+      @revisions[index]
+    end
+    alias :[] :revision
+
+    # Returns the current revision.
+    def current
+      @revisions.last
+    end
+
+    # Returns the number of HexaPDF::Revision objects managed by this object.
+    def size
+      @revisions.size
+    end
+
+    # Adds a new empty revision to the document and returns it.
+    def add
+      if @revisions.empty?
+        trailer = {}
+      else
+        trailer = current.trailer.value.dup
+        trailer.delete(:Prev)
+        trailer.delete(:XRefStm)
+      end
+
+      rev = Revision.new(@document.wrap(trailer, type: :XXTrailer))
+      @revisions.push(rev)
+      rev
+    end
+
+    # :call-seq:
+    #   revisions.delete(index)    -> rev or nil
+    #   revisions.delete(oid)      -> rev or nil
+    #
+    # Deletes a revision from the document, either by index or by specifying the revision object
+    # itself.
+    #
+    # Returns the deleted revision object, or +nil+ if the index was out of range or no matching
+    # revision was found.
+    #
+    # Regarding the index: The oldest revision has index 0 and the current revision the highest
+    # index!
+    def delete(index_or_rev)
+      if @revisions.length == 1
+        raise HexaPDF::Error, "A document must have a least one revision, can't delete last one"
+      elsif index_or_rev.kind_of?(Integer)
+        @revisions.delete_at(index_or_rev)
+      else
+        @revisions.delete(index_or_rev)
+      end
+    end
+
+    # :call-seq:
+    #   revisions.merge(range = 0..-1)    -> revisions
+    #
+    # Merges the revisions specified by the given range into one. Objects from newer revisions
+    # overwrite those from older ones.
+    def merge(range = 0..-1)
+      @revisions[range].reverse.each_cons(2) do |rev, prev_rev|
+        prev_rev.trailer.value.replace(rev.trailer.value)
+        rev.each do |obj|
+          prev_rev.delete(obj.oid, mark_as_free: false)
+          prev_rev.add(obj)
+        end
+      end
+      _first, *other = *@revisions[range]
+      other.each {|rev| @revisions.delete(rev)}
+      self
+    end
+
+    # :call-seq:
+    #   revisions.each {|rev| block }   -> revisions
+    #   revisions.each                  -> Enumerator
+    #
+    # Iterates over all revisions from oldest to current one.
+    def each(&block)
+      return to_enum(__method__) unless block_given?
+      @revisions.each(&block)
+      self
+    end
+
+  end
+
+end