hexapdf 0.1.0

data/lib/hexapdf/type/page_tree_node.rb

@@ -0,0 +1,269 @@
+# -*- 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/dictionary'
+
+module HexaPDF
+  module Type
+
+    # Represents a node in the page tree of the PDF's document.
+    #
+    # The page tree is a tree structure containing page tree nodes for the root and intermediate
+    # nodes and page objects for the leaf nodes (see Page). The root node of the page tree is
+    # linked via the /Pages entry in the Catalog.
+    #
+    # All operations except #add_page on the page tree are rather expensive because page tree
+    # nodes and page objects can be mixed. This means that for finding a page at a specific index
+    # we have to go through all objects that come before it.
+    #
+    # Page indices are zero-based, not one-based. Therefore the first page has an index of 0!
+    #
+    # Since the page tree needs a certain structure it is not advised to directly modify page tree
+    # nodes. The validation feature can correct most problems but until the page tree is in order
+    # the methods may not work correctly!
+    #
+    # Newly created pages use the 'page.default_media_box' configuration option for the /MediaBox
+    # value. If an inherited /Resources dictionary does *not* exist, an empty one is created for
+    # the page.
+    #
+    # See: PDF1.7 s7.7.3.2, Page
+    class PageTreeNode < Dictionary
+
+      define_field :Type,   type: Symbol, required: true, default: :Pages
+      define_field :Parent, type: Dictionary, indirect: true
+      define_field :Kids,   type: Array, required: true, default: []
+      define_field :Count,  type: Integer, required: true, default: 0
+
+      # Inheritable page fields
+      define_field :Resources, type: :XXResources
+      define_field :MediaBox,  type: Rectangle
+      define_field :CropBox,   type: Rectangle
+      define_field :Rotate,    type: Integer
+
+
+      # Returns +true+ since page tree objects must always be indirect.
+      def must_be_indirect?
+        true
+      end
+
+      # Returns the number of pages under this page tree.
+      #
+      # *Note*: If this methods is not called on the root object of the page tree, the returned
+      # number is not the total number of pages in the document!
+      def page_count
+        self[:Count]
+      end
+
+      # Returns the page for the zero-based index or +nil+ if no such page exists.
+      #
+      # Negative indices count backwards from the end, i.e. -1 is the last page.
+      def page(index)
+        index = self[:Count] + index if index < 0
+        return nil if index < 0 || index >= self[:Count]
+
+        self[:Kids].each do |kid|
+          kid = document.deref(kid)
+          if kid.type == :Page
+            if index == 0
+              return kid
+            else
+              index -= 1
+            end
+          elsif index < kid[:Count]
+            return kid.page(index)
+          else
+            index -= kid[:Count]
+          end
+        end
+      end
+
+      # Inserts the page or a new empty page at the zero-based index and returns it.
+      #
+      # Negative indices count backwards from the end, i.e. -1 is the last page. When using
+      # negative indices, the page will be inserted after that element. So using an index of -1
+      # will insert the page after the last page.
+      #
+      # Must be called on the root of the page tree, otherwise the /Count entries are not
+      # correctly updated!
+      def insert_page(index, page = nil)
+        page ||= new_page
+        index = self[:Count] + index + 1 if index < 0
+
+        if index >= self[:Count]
+          self[:Kids] << page
+          page[:Parent] = self
+          page[:Resources] ||= {}
+        else
+          self[:Kids].each_with_index do |kid, kid_index|
+            kid = document.deref(kid)
+            if index == 0
+              self[:Kids].insert(kid_index, page)
+              page[:Parent] = self
+              break
+            elsif kid.type == :Page
+              index -= 1
+            elsif index <= kid[:Count]
+              kid.insert_page(index, page)
+              break
+            else
+              index -= kid[:Count]
+            end
+          end
+        end
+
+        self[:Count] += 1
+
+        page
+      end
+
+      # Adds the page or a new empty page at the end and returns it.
+      def add_page(page = nil)
+        insert_page(-1, page)
+      end
+
+      # Deletes the page at the position specified by the zero-based index and returns it. If an
+      # invalid index is specified, +nil+ is returned.
+      #
+      # Negative indices count backwards from the end, i.e. -1 is the last page.
+      #
+      # Must be called on the root of the page tree, otherwise the /Count entries are not
+      # correctly updated!
+      def delete_page(index)
+        index = self[:Count] + index if index < 0
+        return nil if index < 0 || index >= self[:Count]
+
+        page = nil
+        self[:Count] -= 1
+        self[:Kids].each_with_index do |kid, kid_index|
+          kid = document.deref(kid)
+          if kid.type == :Page && index == 0
+            page = self[:Kids].delete_at(kid_index)
+            document.delete(page)
+            break
+          elsif kid.type == :Page
+            index -= 1
+          elsif index < kid[:Count]
+            page = kid.delete_page(index)
+            if kid[:Count] == 0
+              self[:Kids].delete_at(kid_index)
+              document.delete(kid)
+            elsif kid[:Count] == 1
+              self[:Kids][kid_index] = kid[:Kids][0]
+              kid[:Kids][0][:Parent] = self
+              document.delete(kid)
+            end
+            break
+          else
+            index -= kid[:Count]
+          end
+        end
+
+        page
+      end
+
+      # :call-seq:
+      #   pages.each_page {|page| block }   -> pages
+      #   pages.each_page                   -> Enumerator
+      #
+      # Iterates over all pages that are beneath this page tree node, from the first to the last
+      # page.
+      def each_page(&block)
+        return to_enum(__method__) unless block_given?
+
+        self[:Kids].each do |kid|
+          kid = document.deref(kid)
+          if kid.type == :Page
+            yield(kid)
+          else
+            kid.each_page(&block)
+          end
+        end
+
+        self
+      end
+
+      private
+
+      # Returns a new page object, correctly initialized using the document's configuration
+      # options.
+      def new_page
+        media_box = config['page.default_media_box']
+        media_box = Page::PAPER_SIZE[media_box].dup if Page::PAPER_SIZE.key?(media_box)
+        document.add(Type: :Page, MediaBox: media_box)
+      end
+
+      # Ensures that the /Count and /Parent fields of the whole page tree are set up correctly and
+      # that there is at least one page node. This is therefore only done for the root node of the
+      # page tree!
+      def perform_validation
+        super
+        return if key?(:Parent)
+
+        validate_node = lambda do |node|
+          count = 0
+          node[:Kids].reject! do |kid|
+            kid = document.deref(kid)
+            if !kid.kind_of?(HexaPDF::Object) || kid.null? ||
+                (kid.type != :Page && kid.type != :Pages)
+              yield("Invalid object in page tree node", true)
+              next true
+            elsif kid.type == :Page
+              count += 1
+            else
+              count += validate_node.call(kid)
+            end
+            if kid[:Parent] != node
+              yield("Field Parent of page tree node (#{kid.oid},#{kid.gen}) is invalid", true)
+              kid[:Parent] = node
+            end
+            false
+          end
+          if node[:Count] != count
+            yield("Field Count of page tree node (#{node.oid},#{node.gen}) is invalid", true)
+            node[:Count] = count
+          end
+          count
+        end
+
+        validate_node.call(self)
+
+        if self[:Count] == 0
+          yield("A PDF document needs at least one page", true)
+          add_page.validate {|msg, correctable| yield(msg, correctable)}
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/resources.rb

@@ -0,0 +1,212 @@
+# -*- 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/configuration'
+require 'hexapdf/dictionary'
+require 'hexapdf/content/color_space'
+
+module HexaPDF
+  module Type
+
+    # Represents the resources needed by a content stream.
+    #
+    # See: PDF1.7 s7.8.3
+    class Resources < Dictionary
+
+      define_field :ExtGState, type: Dictionary
+      define_field :ColorSpace, type: Dictionary
+      define_field :Pattern, type: Dictionary
+      define_field :Shading, type: Dictionary, version: '1.3'
+      define_field :XObject, type: Dictionary
+      define_field :Font, type: Dictionary
+      define_field :ProcSet, type: Array
+      define_field :Properties, type: Dictionary, version: '1.2'
+
+      # Returns +:XXResources+.
+      def type
+        :XXResources
+      end
+
+      # Returns the color space stored under the given name.
+      #
+      # If the color space is not found, an error is raised.
+      #
+      # Note: The color spaces :DeviceGray, :DeviceRGB and :DeviceCMYK are returned without a
+      # lookup since they are fixed.
+      def color_space(name)
+        case name
+        when :DeviceRGB, :DeviceGray, :DeviceCMYK
+          GlobalConfiguration.constantize('color_space.map'.freeze, name).new
+        else
+          space_definition = self[:ColorSpace] && self[:ColorSpace][name]
+          if space_definition.nil?
+            raise HexaPDF::Error, "Color space '#{name}' not found in the resources"
+          elsif space_definition.kind_of?(Array)
+            space_definition.map! {|item| document.deref(item)}
+            space_family = space_definition[0]
+          else
+            space_family = space_definition
+            space_definition = [space_definition]
+          end
+
+          GlobalConfiguration.constantize('color_space.map'.freeze, space_family) do
+            HexaPDF::Content::ColorSpace::Universal
+          end.new(space_definition)
+        end
+      end
+
+      # Adds the color space to the resources and returns the name under which it is stored.
+      #
+      # If there already exists a color space with the same definition, it is reused. The device
+      # color spaces +:DeviceGray+, +:DeviceRGB+ and +:DeviceCMYK+ are never stored, their
+      # respective name is just returned.
+      def add_color_space(color_space)
+        family = color_space.family
+        return family if family == :DeviceRGB || family == :DeviceGray || family == :DeviceCMYK
+
+        definition = color_space.definition
+        self[:ColorSpace] = {} unless key?(:ColorSpace)
+        color_space_dict = self[:ColorSpace]
+
+        name, _value = color_space_dict.value.find do |_k, v|
+          v.map! {|item| document.deref(item)}
+          v == definition
+        end
+        unless name
+          name = create_resource_name(color_space_dict.value, 'CS')
+          color_space_dict[name] = definition
+        end
+        name
+      end
+
+      # Returns the XObject stored under the given name.
+      #
+      # If the XObject is not found, an error is raised.
+      def xobject(name)
+        object_getter(:XObject, name)
+      end
+
+      # Adds the XObject to the resources and returns the name under which it is stored.
+      #
+      # If there already exists a name for the given XObject, it is just returned.
+      def add_xobject(object)
+        object_setter(:XObject, 'XO'.freeze, object)
+      end
+
+      # Returns the graphics state parameter dictionary (see Type::GraphicsStateParameter) stored
+      # under the given name.
+      #
+      # If the dictionary is not found, an error is raised.
+      def ext_gstate(name)
+        object_getter(:ExtGState, name)
+      end
+
+      # Adds the graphics state parameter dictionary to the resources and returns the name under
+      # which it is stored.
+      #
+      # If there already exists a name for the given dictionary, it is just returned.
+      def add_ext_gstate(object)
+        object_setter(:ExtGState, 'GS'.freeze, object)
+      end
+
+      # Returns the font dictionary stored under the given name.
+      #
+      # If the dictionary is not found, an error is raised.
+      def font(name)
+        object_getter(:Font, name)
+      end
+
+      # Adds the font dictionary to the resources and returns the name under which it is stored.
+      #
+      # If there already exists a name for the given dictionary, it is just returned.
+      def add_font(object)
+        object_setter(:Font, 'F'.freeze, object)
+      end
+
+      private
+
+      # Helper method for returning an entry of a subdictionary.
+      def object_getter(dict_name, name)
+        obj = self[dict_name] && self[dict_name][name]
+        if obj.nil?
+          raise HexaPDF::Error, "No object called '#{name}' stored under /#{dict_name}"
+        end
+        obj
+      end
+
+      # Helper method for setting an entry of a subdictionary.
+      def object_setter(dict_name, prefix, object)
+        self[dict_name] = {} unless key?(dict_name)
+        dict = self[dict_name]
+        name, _value = dict.each.find {|_, dict_obj| dict_obj == object}
+        unless name
+          name = create_resource_name(dict.value, prefix)
+          dict[name] = object
+        end
+        name
+      end
+
+      # Returns a unique name that can be used to store a resource in the given hash.
+      def create_resource_name(hash, prefix)
+        n = hash.size + 1
+        while true
+          name = :"#{prefix}#{n}"
+          return name unless hash.key?(name)
+          n += 1
+        end
+      end
+
+      # Ensures that a valid procedure set is available.
+      def perform_validation
+        super
+        val = self[:ProcSet]
+        if !val
+          self[:ProcSet] = [:PDF, :Text, :ImageB, :ImageC, :ImageI]
+        else
+          val.reject! do |name|
+            case name
+            when :PDF, :Text, :ImageB, :ImageC, :ImageI
+              false
+            else
+              yield("Invalid page procedure set name /#{name}", true)
+              true
+            end
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/trailer.rb

@@ -0,0 +1,128 @@
+# -*- 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/dictionary'
+require 'digest/md5'
+
+module HexaPDF
+  module Type
+
+    # Represents the PDF file trailer.
+    #
+    # The file trailer is the starting point for the PDF's object tree. It links to the Catalog
+    # (the main PDF document structure) and the Info dictionary and holds the information
+    # necessary for encrypting the PDF document.
+    #
+    # Since a PDF document can contain multiple revisions, each revision needs to have its own
+    # file trailer (see HexaPDF::Revision#trailer).
+    #
+    # When cross-reference streams are used the information that is normally stored in the file
+    # trailer is stored directly in the cross-reference stream dictionary. However, a
+    # HexaPDF::Revision object's trailer dictionary is always of this type. Only when a
+    # cross-reference stream is written is the trailer integrated into the stream's dictionary.
+    #
+    # See: PDF1.7 s7.5.5, s14.4
+    #      XRefStream
+    class Trailer < Dictionary
+
+      define_field :Size,    type: Integer, indirect: false # will be auto-set when written
+      define_field :Prev,    type: Integer
+      define_field :Root,    type: :Catalog, indirect: true
+      define_field :Encrypt, type: Dictionary
+      define_field :Info,    type: :XXInfo, indirect: true
+      define_field :ID,      type: Array
+      define_field :XRefStm, type: Integer, version: '1.5'
+
+      # Returns +:XXTrailer+.
+      def type
+        :XXTrailer
+      end
+
+      # Returns the document's Catalog (see Type::Catalog), creating it if needed.
+      def catalog
+        self[:Root] ||= document.add(Type: :Catalog)
+      end
+
+      # Returns the document's information dictionary (see Type::Info), creating it if needed.
+      def info
+        self[:Info] ||= document.add({}, type: :XXInfo)
+      end
+
+      # Sets the /ID field to an array of two copies of a random string and returns this array.
+      #
+      # See: PDF1.7 14.4
+      def set_random_id
+        value[:ID] = [Digest::MD5.digest(rand.to_s)] * 2
+      end
+
+      # Updates the second part of the /ID field (the first part should always be the same for a
+      # PDF file, the second part should change with each write).
+      def update_id
+        if !value[:ID]
+          set_random_id
+        else
+          value[:ID][1] = Digest::MD5.digest(rand.to_s)
+        end
+      end
+
+      private
+
+      # Validates the trailer.
+      def perform_validation
+        super
+        unless value[:ID]
+          msg = if value[:Encrypt]
+                  "ID field is required when an Encrypt dictionary is present"
+                else
+                  "ID field should always be set"
+                end
+          yield(msg, true)
+          set_random_id
+        end
+
+        unless value[:Root]
+          yield("A PDF document must have a Catalog dictionary", true)
+          value[:Root] = document.add(Type: :Catalog)
+          value[:Root].validate {|message, correctable| yield(message, correctable)}
+        end
+
+        if value[:Encrypt] && (!document.security_handler ||
+                               !document.security_handler.encryption_key_valid?)
+          yield("Encryption key doesn't match encryption dictionary", false)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/type/viewer_preferences.rb

@@ -0,0 +1,73 @@
+# -*- 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/dictionary'
+
+module HexaPDF
+  module Type
+
+    # Represents the PDF's viewer preferences dictionary which defines how a document should be
+    # presented on screen or in print.
+    #
+    # This dictionary is linked via the /ViewerPreferences entry from the Type::Catalog.
+    #
+    # See: PDF1.7 s12.2, Catalog
+    class ViewerPreferences < Dictionary
+
+      define_field :HideToolbar,           type: Boolean, default: false
+      define_field :HideMenubar,           type: Boolean, default: false
+      define_field :HideWindowUI,          type: Boolean, default: false
+      define_field :FitWindow,             type: Boolean, default: false
+      define_field :CenterWindow,          type: Boolean, default: false
+      define_field :DisplayDocTitle,       type: Boolean, default: false, version: '1.4'
+      define_field :NonFullScreenPageMode, type: Symbol,  default: :UseNone
+      define_field :Direction,             type: Symbol,  default: :L2R, version: '1.3'
+      define_field :ViewArea,              type: Symbol,  default: :CropBox, version: '1.4'
+      define_field :ViewClip,              type: Symbol,  default: :CropBox, version: '1.4'
+      define_field :PrintArea,             type: Symbol,  default: :CropBox, version: '1.4'
+      define_field :PrintClip,             type: Symbol,  default: :CropBox, version: '1.4'
+      define_field :PrintScaling,          type: Symbol,  default: :AppDefault, version: '1.6'
+      define_field :Duplex,                type: Symbol,  version: '1.7'
+      define_field :PickTrayByPDFSize,     type: Boolean, version: '1.7'
+      define_field :PrintPageRange,        type: Array,   version: '1.7'
+      define_field :NumCopies,             type: Integer, version: '1.7'
+
+      # Returns +:XXViewerPreferences+.
+      def type
+        :XXViewerPreferences
+      end
+
+    end
+
+  end
+end