prawn 0.12.0 → 0.13.0

data/lib/pdf/core/filter_list.rb

@@ -0,0 +1,51 @@
+module PDF 
+  module Core
+    class FilterList
+      def initialize
+        @list = []
+      end
+
+      def <<(filter)
+        case filter
+        when Symbol
+          @list << [filter, nil]
+        when ::Hash
+          filter.each do |name, params|
+            @list << [name, params]
+          end
+        else
+          raise "Can not interpret input as filter: #{filter.inspect}"
+        end
+
+        self
+      end
+
+      def normalized
+        @list
+      end
+      alias_method :to_a, :normalized
+
+      def names
+        @list.map do |(name, _)|
+          name
+        end
+      end
+
+      def decode_params
+        @list.map do |(_, params)|
+          params
+        end
+      end
+
+      def inspect
+        @list.inspect
+      end
+
+      def each(&block)
+        @list.each do |filter|
+          block.call(filter)
+        end
+      end
+    end
+  end
+end

data/lib/pdf/core/filters.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+
+# prawn/core/filters.rb : Implements stream filters
+#
+# Copyright February 2013, Alexander Mankuta.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'zlib'
+
+module PDF
+  module Core
+    module Filters
+      module FlateDecode
+        def self.encode(stream, params = nil)
+          Zlib::Deflate.deflate(stream)
+        end
+
+        def self.decode(stream, params = nil)
+          Zlib::Inflate.inflate(stream)
+        end
+      end
+
+      # Pass through stub
+      module DCTDecode
+        def self.encode(stream, params = nil)
+          stream
+        end
+
+        def self.decode(stream, params = nil)
+          stream
+        end
+      end
+    end
+  end
+end

data/lib/pdf/core/graphics_state.rb

@@ -0,0 +1,68 @@
+# encoding: utf-8
+#
+# Implements graphics state saving and restoring
+#
+# Copyright January 2010, Michael Witrant. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details
+#
+
+
+module PDF
+  module Core
+    class GraphicStateStack
+      attr_accessor :stack
+
+      def initialize(previous_state = nil)
+        self.stack = [GraphicState.new(previous_state)]
+      end
+
+      def save_graphic_state(graphic_state = nil)
+        stack.push(GraphicState.new(graphic_state || current_state))
+      end
+
+      def restore_graphic_state
+        if stack.empty?
+          raise PDF::Core::Errors::EmptyGraphicStateStack,
+            "\n You have reached the end of the graphic state stack"
+        end
+        stack.pop
+      end
+
+      def current_state
+        stack.last
+      end
+
+      def present?
+        stack.size > 0
+      end
+
+      def empty?
+        stack.empty?
+      end
+
+    end
+
+    class GraphicState
+      attr_accessor :color_space, :dash, :cap_style, :join_style, :line_width, :fill_color, :stroke_color
+
+      def initialize(previous_state = nil)
+        @color_space = previous_state ? previous_state.color_space.dup : {}
+        @fill_color = previous_state ? previous_state.fill_color : "000000"
+        @stroke_color = previous_state ? previous_state.stroke_color : "000000"
+        @dash = previous_state ? previous_state.dash : { :dash => nil, :space => nil, :phase => 0 }
+        @cap_style = previous_state ? previous_state.cap_style : :butt
+        @join_style = previous_state ? previous_state.join_style : :miter
+        @line_width = previous_state ? previous_state.line_width : 1
+      end
+
+      def dash_setting
+        if @dash[:dash].kind_of?(Array)
+          "[#{@dash[:dash].join(' ')}] #{@dash[:phase]} d"
+        else
+          "[#{@dash[:dash]} #{@dash[:space]}] #{@dash[:phase]} d"
+        end
+      end
+    end
+  end
+end

data/lib/{prawn → pdf}/core/literal_string.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
-module Prawn
+module PDF
   module Core
     # This is used to differentiate strings that must be encoded as
     # a *literal* string, versus those that can be encoded in

data/lib/{prawn → pdf}/core/name_tree.rb

@@ -6,7 +6,7 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 #
-module Prawn
+module PDF
   module Core
     module NameTree #:nodoc:
       class Node #:nodoc:
@@ -98,6 +98,18 @@ module Prawn
           end
         end
 
+        # Returns a deep copy of this node, without copying expensive things
+        # like the ref to @document.
+        #
+        def deep_copy
+          node = dup
+          node.instance_variable_set("@children",
+                                     Marshal.load(Marshal.dump(children)))
+          node.instance_variable_set("@ref",
+                                     node.ref ? node.ref.deep_copy : nil)
+          node
+        end
+
         protected
 
           def split(node)
@@ -145,7 +157,7 @@ module Prawn
         attr_reader :value
 
         def initialize(name, value)
-          @name, @value = Prawn::Core::LiteralString.new(name), value
+          @name, @value = PDF::Core::LiteralString.new(name), value
         end
 
         def <=>(leaf)

data/lib/{prawn → pdf}/core/object_store.rb

@@ -1,6 +1,6 @@
 # encoding: utf-8
 
-# prawn/core/object_store.rb : Implements PDF object repository for Prawn
+# Implements PDF object repository
 #
 # Copyright August 2009, Brad Ediger.  All Rights Reserved.
 #
@@ -9,7 +9,7 @@
 
 require 'pdf/reader'
 
-module Prawn
+module PDF
   module Core
     class ObjectStore #:nodoc:
       include Enumerable
@@ -52,14 +52,14 @@ module Prawn
       end
 
       # Adds the given reference to the store and returns the reference object.
-      # If the object provided is not a Prawn::Core::Reference, one is created from the
+      # If the object provided is not a PDF::Core::Reference, one is created from the
       # arguments provided.
       #
       def push(*args, &block)
-        reference = if args.first.is_a?(Prawn::Core::Reference)
+        reference = if args.first.is_a?(PDF::Core::Reference)
           args.first
         else
-          Prawn::Core::Reference.new(*args, &block)
+          PDF::Core::Reference.new(*args, &block)
         end
 
         @objects[reference.identifier] = reference
@@ -141,27 +141,83 @@ module Prawn
       # Imports nothing and returns nil if the requested page number doesn't
       # exist. page_num is 1 indexed, so 1 indicates the first page.
       #
-      def import_page(filename, page_num)
+      def import_page(input, page_num)
         @loaded_objects = {}
-        unless File.file?(filename)
-          raise ArgumentError, "#{filename} does not exist"
+        if template_id = indexed_template(input, page_num)
+          return template_id
         end
 
-        hash = PDF::Reader::ObjectHash.new(filename)
+        io = if input.respond_to?(:seek) && input.respond_to?(:read)
+               input
+             elsif File.file?(input.to_s)
+               StringIO.new(File.binread(input.to_s))
+             else
+               raise ArgumentError, "input must be an IO-like object or a filename"
+             end
+
+                # unless File.file?(filename)
+        #   raise ArgumentError, "#{filename} does not exist"
+        # end
+
+        hash = indexed_hash(input, io)
         ref  = hash.page_references[page_num - 1]
 
-        ref.nil? ? nil : load_object_graph(hash, ref).identifier
+        if ref.nil?
+          nil
+        else
+          index_template(input, page_num, load_object_graph(hash, ref).identifier)
+        end
 
-      rescue PDF::Reader::MalformedPDFError, PDF::Reader::InvalidObjectError
-        msg = "Error reading template file. If you are sure it's a valid PDF, it may be a bug."
-        raise Prawn::Errors::TemplateError, msg
+      rescue PDF::Reader::MalformedPDFError, PDF::Reader::InvalidObjectError => e
+        msg = "Error reading template file. If you are sure it's a valid PDF, it may be a bug.\n#{e.message}"
+        raise PDF::Core::Errors::TemplateError, msg
       rescue PDF::Reader::UnsupportedFeatureError
         msg = "Template file contains unsupported PDF features"
-        raise Prawn::Errors::TemplateError, msg
+        raise PDF::Core::Errors::TemplateError, msg
       end
 
       private
 
+      # An index for page templates so that their loaded object graph
+      # can be reused without multiple loading
+      def template_index
+        @template_index ||= {}
+      end
+
+      # An index for the read object hash of a pdf template so that the
+      # object hash does not need to be parsed multiple times when using
+      # different pages of the pdf as page templates
+      def hash_index
+        @hash_index ||= {}
+      end
+
+      # returns the indexed object graph identifier for a template page if
+      # it exists
+      def indexed_template(input, page_number)
+        key = indexing_key(input)
+        template_index[key] && template_index[key][page_number]
+      end
+
+      # indexes the identifier for a page from a template
+      def index_template(input, page_number, id)
+        (template_index[indexing_key(input)] ||= {})[page_number] ||= id
+      end
+
+      # reads and indexes a new IO for a template
+      # if the IO has been indexed already then the parsed object hash
+      # is returned directly
+      def indexed_hash(input, io)
+        hash_index[indexing_key(input)] ||= PDF::Reader::ObjectHash.new(io)
+      end
+
+      # the index key for the input.
+      # uses object_id so that both a string filename or an IO stream can be
+      # indexed and reused provided the same object gets used in multiple page
+      # template calls.
+      def indexing_key(input)
+        input.object_id
+      end
+
       # returns a nested array of object IDs for all pages in this object store.
       #
       def get_page_objects(obj)
@@ -187,7 +243,7 @@ module Prawn
 
         if hash.trailer[:Encrypt]
           msg = "Template file is an encrypted PDF, it can't be used as a template"
-          raise Prawn::Errors::TemplateError, msg
+          raise PDF::Core::Errors::TemplateError, msg
         end
 
         if src_info
@@ -197,12 +253,12 @@ module Prawn
         if src_root
           @root = load_object_graph(hash, src_root).identifier
         end
-      rescue PDF::Reader::MalformedPDFError, PDF::Reader::InvalidObjectError
-        msg = "Error reading template file. If you are sure it's a valid PDF, it may be a bug."
-        raise Prawn::Errors::TemplateError, msg
+      rescue PDF::Reader::MalformedPDFError, PDF::Reader::InvalidObjectError => e
+        msg = "Error reading template file. If you are sure it's a valid PDF, it may be a bug.\n#{e.message}"
+        raise PDF::Core::Errors::TemplateError, msg
       rescue PDF::Reader::UnsupportedFeatureError
         msg = "Template file contains unsupported PDF features"
-        raise Prawn::Errors::TemplateError, msg
+        raise PDF::Core::Errors::TemplateError, msg
       end
 
       # recurse down an object graph from a source PDF, importing all the
@@ -223,10 +279,10 @@ module Prawn
           unless @loaded_objects.has_key?(object.id)
             @loaded_objects[object.id] = ref(nil)
             new_obj = load_object_graph(hash, hash[object])
-          if new_obj.kind_of?(PDF::Reader::Stream)
-            stream_dict = load_object_graph(hash, new_obj.hash)
-            @loaded_objects[object.id].data = stream_dict
-            @loaded_objects[object.id] << new_obj.data
+            if new_obj.kind_of?(PDF::Reader::Stream)
+              stream_dict = load_object_graph(hash, new_obj.hash)
+              @loaded_objects[object.id].data = stream_dict
+              @loaded_objects[object.id] << new_obj.data
             else
               @loaded_objects[object.id].data = new_obj
             end
@@ -237,7 +293,7 @@ module Prawn
           # being wrapped in a LiteralString
           object
         when String
-          is_utf8?(object) ? object : Prawn::Core::ByteString.new(object)
+          is_utf8?(object) ? object : PDF::Core::ByteString.new(object)
         else
           object
         end

data/lib/pdf/core/outline.rb

@@ -0,0 +1,315 @@
+module PDF
+  module Core
+    # The Outline class organizes the outline tree items for the document.
+    # Note that the prev and parent instance variables are adjusted while navigating
+    # through the nested blocks. These variables along with the presence or absense
+    # of blocks are the primary means by which the relations for the various
+    # OutlineItems and the OutlineRoot are set. Unfortunately, the best way to
+    # understand how this works is to follow the method calls through a real example.
+    #
+    # Some ideas for the organization of this class were gleaned from name_tree. In
+    # particular the way in which the OutlineItems are finally rendered into document
+    # objects in PdfObject through a hash.
+    #
+    class Outline
+
+      extend Forwardable
+      def_delegator :@document, :page_number
+
+      attr_accessor :parent
+      attr_accessor :prev
+      attr_accessor :document
+      attr_accessor :items
+
+      def initialize(document)
+        @document = document
+        @parent = root
+        @prev = nil
+        @items = {}
+      end
+
+      # Defines/Updates an outline for the document.
+      # The outline is an optional nested index that appears on the side of a PDF
+      # document usually with direct links to pages. The outline DSL is defined by nested
+      # blocks involving two methods: section and page; see the documentation on those methods
+      # for their arguments and options. Note that one can also use outline#update
+      # to add more sections to the end of the outline tree using the same syntax and scope.
+      #
+      # The syntax is best illustrated with an example:
+      #
+      # Prawn::Document.generate(outlined_document.pdf) do
+      #   text "Page 1. This is the first Chapter. "
+      #   start_new_page
+      #   text "Page 2. More in the first Chapter. "
+      #   start_new_page
+      #   outline.define do
+      #     section 'Chapter 1', :destination => 1, :closed => true do
+      #       page :destination => 1, :title => 'Page 1'
+      #       page :destination => 2, :title => 'Page 2'
+      #     end
+      #   end
+      #   start_new_page do
+      #   outline.update do
+      #     section 'Chapter 2', :destination =>  2, do
+      #       page :destination => 3, :title => 'Page 3'
+      #     end
+      #   end
+      # end
+      #
+      def define(&block)
+        instance_eval(&block)  if block
+      end
+
+      alias :update :define
+
+      # Inserts an outline section to the outline tree (see outline#define).
+      # Although you will probably choose to exclusively use outline#define so
+      # that your outline tree is contained and easy to manage, this method
+      # gives you the option to insert sections to the outline tree at any point
+      # during document generation. This method allows you to add a child subsection
+      # to any other item at any level in the outline tree.
+      # Currently the only way to locate the place of entry is with the title for the
+      # item. If your title names are not unique consider using define_outline.
+      # The method takes the following arguments:
+      #   title: a string that must match an outline title to add the subsection to
+      #   position: either :first or :last(the default) where the subsection will be placed relative
+      #      to other child elements. If you need to position your subsection in between
+      #      other elements then consider using #insert_section_after
+      #   block: uses the same DSL syntax as outline#define, for example:
+      #
+      # Consider using this method inside of outline.update if you want to have the outline object
+      # to be scoped as self (see #insert_section_after example).
+      #
+      #   go_to_page 2
+      #   start_new_page
+      #   text "Inserted Page"
+      #   outline.add_subsection_to :title => 'Page 2', :first do
+      #     outline.page :destination => page_number, :title => "Inserted Page"
+      #   end
+      #
+      def add_subsection_to(title, position = :last, &block)
+        @parent = items[title]
+        raise Prawn::Errors::UnknownOutlineTitle,
+          "\n No outline item with title: '#{title}' exists in the outline tree" unless @parent
+        @prev = position == :first ? nil : @parent.data.last
+        nxt = position == :first ? @parent.data.first : nil
+        insert_section(nxt, &block)
+      end
+
+      # Inserts an outline section to the outline tree (see outline#define).
+      # Although you will probably choose to exclusively use outline#define so
+      # that your outline tree is contained and easy to manage, this method
+      # gives you the option to insert sections to the outline tree at any point
+      # during document generation. Unlike outline.add_section, this method allows
+      # you to enter a section after any other item at any level in the outline tree.
+      # Currently the only way to locate the place of entry is with the title for the
+      # item. If your title names are not unique consider using define_outline.
+      # The method takes the following arguments:
+      #   title: the title of other section or page to insert new section after
+      #   block: uses the same DSL syntax as outline#define, for example:
+      #
+      #   go_to_page 2
+      #   start_new_page
+      #   text "Inserted Page"
+      #   update_outline do
+      #     insert_section_after :title => 'Page 2' do
+      #       page :destination => page_number, :title => "Inserted Page"
+      #     end
+      #   end
+      #
+      def insert_section_after(title, &block)
+        @prev = items[title]
+        raise Prawn::Errors::UnknownOutlineTitle,
+          "\n No outline item with title: '#{title}' exists in the outline tree" unless @prev
+        @parent = @prev.data.parent
+        nxt = @prev.data.next
+        insert_section(nxt, &block)
+      end
+
+      # See outline#define above for documentation on how this is used in that context
+      #
+      # Adds an outine section to the outline tree.
+      # Although you will probably choose to exclusively use outline#define so
+      # that your outline tree is contained and easy to manage, this method
+      # gives you the option to add sections to the outline tree at any point
+      # during document generation. When not being called from within another #section block
+      # the section will be added at the top level after the other root elements of the outline.
+      # For more flexible placement try using outline#insert_section_after and/or
+      # outline#add_subsection_to
+      # Takes the following arguments:
+      #   title: the outline text that appears for the section.
+      #   options: destination - optional integer defining the page number for a destination link
+      #                          to the top of the page (using a :FIT destination).
+      #                 - or an array with a custom destination (see the #dest_* methods of the
+      #                   PDF::Destination module)
+      #            closed - whether the section should show its nested outline elements.
+      #                   - defaults to false.
+      #            block: more nested subsections and/or page blocks
+      #
+      # example usage:
+      #
+      #   outline.section 'Added Section', :destination => 3 do
+      #     outline.page :destionation => 3, :title => 'Page 3'
+      #   end
+      def section(title, options = {}, &block)
+        add_outline_item(title, options, &block)
+      end
+
+      # See Outline#define above for more documentation on how it is used in that context
+      #
+      # Adds a page to the outline.
+      # Although you will probably choose to exclusively use outline#define so
+      # that your outline tree is contained and easy to manage, this method also
+      # gives you the option to add pages to the root of outline tree at any point
+      # during document generation. Note that the page will be added at the
+      # top level after the other root outline elements. For more flexible placement try
+      # using outline#insert_section_after and/or outline#add_subsection_to.
+      #
+      # Takes the following arguments:
+      #     options:
+      #            title - REQUIRED. The outline text that appears for the page.
+      #            destination - optional integer defining the page number for a destination link
+      #                          to the top of the page (using a :FIT destination).
+      #                 - or an array with a custom destination (see the #dest_* methods of the
+      #                   PDF::Destination module)
+      #            closed - whether the section should show its nested outline elements.
+      #                   - defaults to false.
+      # example usage:
+      #
+      #   outline.page :title => "Very Last Page"
+      # Note: this method is almost identical to section except that it does not accept a block
+      # thereby defining the outline item as a leaf on the outline tree structure.
+      def page(options = {})
+        if options[:title]
+          title = options[:title]
+        else
+          raise Prawn::Errors::RequiredOption,
+            "\nTitle is a required option for page"
+        end
+        add_outline_item(title, options)
+      end
+
+    private
+
+      # The Outline dictionary (12.3.3) for this document.  It is
+      # lazily initialized, so that documents that do not have an outline
+      # do not incur the additional overhead.
+      def root
+        document.state.store.root.data[:Outlines] ||= document.ref!(OutlineRoot.new)
+      end
+
+      def add_outline_item(title, options, &block)
+        outline_item = create_outline_item(title, options)
+        set_relations(outline_item)
+        increase_count
+        set_variables_for_block(outline_item, block)
+        block.call if block
+        reset_parent(outline_item)
+      end
+
+      def create_outline_item(title, options)
+        outline_item = OutlineItem.new(title, parent, options)
+
+        case options[:destination]
+        when Integer
+          page_index = options[:destination] - 1
+          outline_item.dest = [document.state.pages[page_index].dictionary, :Fit]
+        when Array
+          outline_item.dest = options[:destination]
+        end
+
+        outline_item.prev = prev if @prev
+        items[title] = document.ref!(outline_item)
+      end
+
+      def set_relations(outline_item)
+        prev.data.next = outline_item if prev
+        parent.data.first = outline_item unless prev
+        parent.data.last = outline_item
+      end
+
+      def increase_count
+        counting_parent = parent
+        while counting_parent
+          counting_parent.data.count += 1
+          if counting_parent == root
+            counting_parent = nil
+          else
+            counting_parent = counting_parent.data.parent
+          end
+        end
+      end
+
+      def set_variables_for_block(outline_item, block)
+        self.prev = block ? nil : outline_item
+        self.parent = outline_item if block
+      end
+
+      def reset_parent(outline_item)
+        if parent == outline_item
+          self.prev = outline_item
+          self.parent = outline_item.data.parent
+        end
+      end
+
+      def insert_section(nxt, &block)
+        last = @parent.data.last
+        if block
+          block.call
+        end
+        adjust_relations(nxt, last)
+        reset_root_positioning
+      end
+
+      def adjust_relations(nxt, last)
+        if nxt
+          nxt.data.prev = @prev
+          @prev.data.next = nxt
+          @parent.data.last = last
+        end
+      end
+
+      def reset_root_positioning
+        @parent = root
+        @prev = root.data.last
+      end
+
+    end
+
+    class OutlineRoot #:nodoc:
+      attr_accessor :count, :first, :last
+
+      def initialize
+        @count = 0
+      end
+
+      def to_hash
+        {:Type => :Outlines, :Count => count, :First => first, :Last => last}
+      end
+    end
+
+    class OutlineItem #:nodoc:
+      attr_accessor :count, :first, :last, :next, :prev, :parent, :title, :dest, :closed
+
+      def initialize(title, parent, options)
+        @closed = options[:closed]
+        @title = title
+        @parent = parent
+        @count = 0
+      end
+
+      def to_hash
+        hash = { :Title => title,
+                 :Parent => parent,
+                 :Count => closed ? -count : count }
+        [{:First => first}, {:Last => last}, {:Next => defined?(@next) && @next},
+         {:Prev => prev}, {:Dest => dest}].each do |h|
+          unless h.values.first.nil?
+            hash.merge!(h)
+          end
+        end
+        hash
+      end
+    end
+  end
+end