hexapdf 0.1.0 → 0.2.0

data/lib/hexapdf/configuration.rb

@@ -142,7 +142,7 @@ module HexaPDF
   #      {"font_name": {variant: file_name, variant2: file_name2, ...}, ...}
   #
   #    Once a font is registered in this way, the font name together with a variant name can be used
-  #    with the HexaPDF::FontUtils#load method to load the font.
+  #    with the HexaPDF::Document::Fonts#load method to load the font.
   #
   #    For best compatibility, the following variant names should be used:
   #

data/lib/hexapdf/content/canvas.rb

@@ -1258,7 +1258,7 @@ module HexaPDF
       # See: PDF1.7 s8.8, s.8.10.1
       def xobject(obj, at:, width: nil, height: nil)
         unless obj.kind_of?(HexaPDF::Stream)
-          obj = context.document.utils.add_image(obj)
+          obj = context.document.images.add(obj)
         end
 
         if obj[:Subtype] == :Image

data/lib/hexapdf/content/processor.rb

@@ -295,7 +295,7 @@ module HexaPDF
         EMC: :end_marked_content,
         BX: :begin_compatibility_section,
         EX: :end_compatibility_section,
-      }
+      }.freeze
 
       # Mapping from operator name (Symbol) to a callable object.
       #

data/lib/hexapdf/dictionary.rb

@@ -88,7 +88,7 @@ module HexaPDF
     #
     # version:: Specifies the minimum version of the PDF specification needed for this value.
     def self.define_field(name, type:, required: false, default: nil, indirect: nil,
-      version: '1.2')
+                          version: '1.2')
       @fields ||= {}
       @fields[name] = Field.new(type, required, default, indirect, version)
     end
@@ -141,7 +141,9 @@ module HexaPDF
                value[name] = field.default
              end
       value[name] = data = document.deref(data) if data.kind_of?(HexaPDF::Reference)
-      data = data.value if data.class == HexaPDF::Object
+      if data.class == HexaPDF::Object || (data.kind_of?(HexaPDF::Object) && data.value.nil?)
+        data = data.value
+      end
       self[name] = data = field.convert(data, document) if field && field.convert?(data)
       data
     end
@@ -242,12 +244,8 @@ module HexaPDF
       each_set_key_or_required_field do |name, field|
         obj = key?(name) && self[name] || nil
 
-        # Validate direct PDF objects and those possibly nested within a hash
-        if obj.kind_of?(HexaPDF::Object) && !obj.indirect?
-          obj.validate(&block)
-        elsif obj.kind_of?(Hash)
-          validate_hash(obj, &block)
-        end
+        # Validate nested objects
+        validate_nested(obj, &block)
 
         # The checks below need a valid field definition
         next if field.nil?
@@ -287,17 +285,6 @@ module HexaPDF
       end
     end
 
-    # Validates all nested values of the given hash.
-    def validate_hash(hash, &block)
-      hash.each_value do |obj|
-        if obj.kind_of?(HexaPDF::Object) && !obj.indirect?
-          obj.validate(&block)
-        elsif obj.kind_of?(Hash)
-          validate_hash(obj, &block)
-        end
-      end
-    end
-
   end
 
 end

data/lib/hexapdf/dictionary_fields.rb

@@ -65,7 +65,7 @@ module HexaPDF
   module DictionaryFields
 
     # This constant should *always* be used for boolean fields.
-    Boolean = [TrueClass, FalseClass]
+    Boolean = [TrueClass, FalseClass].freeze
 
     # PDFByteString is used for defining fields with strings in binary encoding.
     PDFByteString = Class.new { private_class_method :new }

data/lib/hexapdf/document.rb

@@ -45,9 +45,7 @@ require 'hexapdf/encryption'
 require 'hexapdf/writer'
 require 'hexapdf/importer'
 require 'hexapdf/image_loader'
-require 'hexapdf/document_utils'
-require 'hexapdf/font_utils'
-
+require 'hexapdf/font_loader'
 
 # == HexaPDF API Documentation
 #
@@ -69,6 +67,11 @@ module HexaPDF
   # that there are no convenience methods for higher PDF functionality whatsoever.
   class Document
 
+    autoload(:Pages, 'hexapdf/document/pages')
+    autoload(:Fonts, 'hexapdf/document/fonts')
+    autoload(:Images, 'hexapdf/document/images')
+    autoload(:Files, 'hexapdf/document/files')
+
     # :call-seq:
     #   Document.open(filename, **docargs)                   -> doc
     #   Document.open(filename, **docargs) {|doc| block}     -> obj
@@ -415,15 +418,26 @@ module HexaPDF
       @listeners[name] && @listeners[name].each {|obj| obj.call(*args)}
     end
 
-    # Returns a DocumentUtils object that provides convenience methods for often used
-    # functionality like adding images.
-    def utils
-      @utils ||= DocumentUtils.new(self)
+    # Returns the Pages object that provides convenience methods for working with pages.
+    #
+    # Also see: HexaPDF::Type::PageTreeNode
+    def pages
+      @pages ||= Pages.new(self)
+    end
+
+    # Returns the Images object that provides convenience methods for working with images.
+    def images
+      @images ||= Images.new(self)
     end
 
-    # Returns the FontUtils object that provides convenience methods for working with fonts.
+    # Returns the Files object that provides convenience methods for working with files.
+    def files
+      @files ||= Files.new(self)
+    end
+
+    # Returns the Fonts object that provides convenience methods for working with fonts.
     def fonts
-      @font_utils ||= FontUtils.new(self)
+      @fonts ||= Fonts.new(self)
     end
 
     # Executes the given task and returns its result.
@@ -449,13 +463,6 @@ module HexaPDF
       trailer.catalog
     end
 
-    # Returns the root node of the document's page tree.
-    #
-    # See: HexaPDF::Type::PageTreeNode
-    def pages
-      catalog.pages
-    end
-
     # Returns the PDF document's version as string (e.g. '1.4').
     #
     # This method takes the file header version and the catalog's /Version key into account. If a

data/lib/hexapdf/document/files.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
+  class Document
+
+    # This class provides methods for managing file specifications of a PDF file.
+    #
+    # Note that for a given PDF file not all file specifications may be found, e.g. when a file
+    # specification is only a string. Therefore this module can only handle those file
+    # specifications that are indirect file specification dictionaries with the /Type key set.
+    class Files
+
+      include Enumerable
+
+      # Creates a new Files object for the given PDF document.
+      def initialize(document)
+        @document = document
+      end
+
+      # :call-seq:
+      #   files.add(filename, name: File.basename(filename), description: nil, embed: true) -> file_spec
+      #   files.add(io, name:, description: nil)                      -> file_spec
+      #
+      # Adds the file or IO to the PDF document and returns the corresponding file specification
+      # object.
+      #
+      # Options:
+      #
+      # name::
+      #     The name that should be used for the file path. This name is also for registering the
+      #     file in the EmbeddedFiles name tree.
+      #
+      # description::
+      #     A description of the file.
+      #
+      # embed::
+      #     When an IO object is given, it is always embedded and this option is ignored.
+      #
+      #     When a filename is given and this option is +true+, then the file is embedded. Otherwise
+      #     only a reference to it is stored.
+      #
+      # See: HexaPDF::Type::FileSpecification
+      def add(file_or_io, name: nil, description: nil, embed: true)
+        name ||= File.basename(file_or_io) if file_or_io.kind_of?(String)
+        if name.nil?
+          raise ArgumentError, "The name argument is mandatory when given an IO object"
+        end
+
+        spec = @document.add(Type: :Filespec)
+        spec.path = name
+        spec[:Desc] = description if description
+        spec.embed(file_or_io, name: name, register: true) if embed || !file_or_io.kind_of?(String)
+        spec
+      end
+
+      # :call-seq:
+      #   files.each(search: false) {|file_spec| block }   -> files
+      #   files.each(search: false)                        -> Enumerator
+      #
+      # Iterates over indirect file specification dictionaries of the PDF.
+      #
+      # By default, only the file specifications in their standard locations, namely in the
+      # EmbeddedFiles name tree and in the page annotations, are returned. If the +search+ option is
+      # +true+, then all indirect objects are searched for file specification dictionaries which can
+      # be much slower.
+      def each(search: false)
+        return to_enum(__method__, search: search) unless block_given?
+
+        if search
+          @document.each(current: false) do |obj|
+            yield(obj) if obj.type == :Filespec
+          end
+        else
+          seen = {}
+          tree = @document.catalog[:Names] && @document.catalog[:Names][:EmbeddedFiles]
+          tree.each_entry do |_, spec|
+            seen[spec] = true
+            yield(spec)
+          end if tree
+
+          @document.pages.each do |page|
+            next unless page[:Annots]
+            page[:Annots].each do |annot|
+              annot = @document.deref(annot)
+              next unless annot[:Subtype] == :FileAttachment
+              spec = @document.deref(annot[:FS])
+              yield(spec) unless seen.key?(spec)
+              seen[spec] = true
+            end
+          end
+        end
+
+        self
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/{font_utils.rb → document/fonts.rb}

@@ -35,55 +35,57 @@ require 'hexapdf/configuration'
 require 'hexapdf/font_loader'
 
 module HexaPDF
+  class Document
 
-  # This class provides utility functions for working with fonts. It is available through the
-  # HexaPDF::Document#fonts method.
-  class FontUtils
+    # This class provides utility functions for working with fonts. It is available through the
+    # HexaPDF::Document#fonts method.
+    class Fonts
 
-    # Creates a new FontUtils object for the given PDF document.
-    def initialize(document)
-      @document = document
-      @loaded_fonts_cache = {}
-    end
+      # Creates a new Fonts object for the given PDF document.
+      def initialize(document)
+        @document = document
+        @loaded_fonts_cache = {}
+      end
 
-    # :call-seq:
-    #   fonts.load(name, **options)            -> font
-    #
-    # Loads and returns the font (using the loaders specified with the configuration option
-    # 'font_loaders').
-    #
-    # If a font with the same parameters has been loaded before, the cached font object is used.
-    def load(name, **options)
-      font = @loaded_fonts_cache[[name, options]]
-      return font if font
+      # :call-seq:
+      #   fonts.load(name, **options)            -> font
+      #
+      # Loads and returns the font (using the loaders specified with the configuration option
+      # 'font_loaders').
+      #
+      # If a font with the same parameters has been loaded before, the cached font object is used.
+      def load(name, **options)
+        font = @loaded_fonts_cache[[name, options]]
+        return font if font
 
-      each_font_loader do |loader|
-        font = loader.call(@document, name, **options)
-        break if font
-      end
+        each_font_loader do |loader|
+          font = loader.call(@document, name, **options)
+          break if font
+        end
 
-      if font
-        @loaded_fonts_cache[[name, options]] = font
-      else
-        raise HexaPDF::Error, "The requested font '#{name}' couldn't be found"
+        if font
+          @loaded_fonts_cache[[name, options]] = font
+        else
+          raise HexaPDF::Error, "The requested font '#{name}' couldn't be found"
+        end
       end
-    end
 
-    private
+      private
 
-    # :call-seq:
-    #   fonts.each_font_loader {|loader| block}
-    #
-    # Iterates over all configured font loaders.
-    def each_font_loader
-      @document.config['font_loader'].each_index do |index|
-        loader = @document.config.constantize('font_loader', index) do
-          raise HexaPDF::Error, "Couldn't retrieve font loader ##{index} from configuration"
+      # :call-seq:
+      #   fonts.each_font_loader {|loader| block}
+      #
+      # Iterates over all configured font loaders.
+      def each_font_loader
+        @document.config['font_loader'].each_index do |index|
+          loader = @document.config.constantize('font_loader', index) do
+            raise HexaPDF::Error, "Couldn't retrieve font loader ##{index} from configuration"
+          end
+          yield(loader)
         end
-        yield(loader)
       end
+
     end
 
   end
-
 end

data/lib/hexapdf/document/images.rb

@@ -0,0 +1,117 @@
+# -*- 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/configuration'
+
+module HexaPDF
+  class Document
+
+    # This class provides methods for managing the images embedded in a PDF file. It is available
+    # through the HexaPDF::Document#images method.
+    #
+    # Images themselves are represented by the HexaPDF::Type::Image class.Since an image can be used
+    # as a mask for another image, not all image objects found in a PDF are really used as images.
+    # Such cases are all handled by this class automatically.
+    class Images
+
+      include Enumerable
+
+      # Creates a new Images object for the given PDF document.
+      def initialize(document)
+        @document = document
+      end
+
+      # :call-seq:
+      #   images.add(file)            -> image
+      #   images.add(io)              -> image
+      #
+      # Adds the image from the given file or IO to the PDF document and returns the image object.
+      #
+      # If the image has been added to the PDF before (i.e. if there is an image object with the
+      # same path name), the already existing image object is returned.
+      def add(file_or_io)
+        name = if file_or_io.kind_of?(String)
+                 file_or_io
+               elsif file_or_io.respond_to?(:to_path)
+                 file_or_io.to_path
+               end
+        if name
+          name = File.absolute_path(name)
+          image = find {|im| im.source_path == name}
+        end
+        unless image
+          image = image_loader_for(file_or_io).load(@document, file_or_io)
+          image.source_path = name
+        end
+        image
+      end
+
+      # :call-seq:
+      #   images.each {|image| block }   -> images
+      #   images.each                    -> Enumerator
+      #
+      # Iterates over all images in the PDF document.
+      #
+      # Note that only real images are yielded which means, for example, that images used as soft
+      # mask are not.
+      def each(&block)
+        images = @document.each(current: false).select do |obj|
+          next unless obj.kind_of?(HexaPDF::Dictionary)
+          obj[:Subtype] == :Image && !obj[:ImageMask]
+        end
+        masks = images.each_with_object([]) do |image, temp|
+          temp << image[:Mask] if image[:Mask].kind_of?(Stream)
+          temp << image[:SMask] if image[:SMask].kind_of?(Stream)
+        end
+        (images - masks).each(&block)
+      end
+
+      private
+
+      # Returns the image loader (see HexaPDF::ImageLoader) for the given file or IO stream or
+      # raises an error if no suitable image loader is found.
+      def image_loader_for(file_or_io)
+        GlobalConfiguration['image_loader'].each_index do |index|
+          loader = GlobalConfiguration.constantize('image_loader', index) do
+            raise HexaPDF::Error, "Couldn't retrieve image loader from configuration"
+          end
+          return loader if loader.handles?(file_or_io)
+        end
+
+        raise HexaPDF::Error, "Couldn't find suitable image loader"
+      end
+
+    end
+
+  end
+end