prawn 0.11.1 → 0.15.0

data/lib/prawn/outline.rb

@@ -5,322 +5,20 @@
 # Author Jonathan Greenberg
 
 require 'forwardable'
+require "pdf/core/outline"
 
 module Prawn
-  
+
   class Document
 
+    # @group Experimental API
+
     # Lazily instantiates an Outline object for document. This is used as point of entry
     # to methods to build the outline tree.
     def outline
-      @outline ||= Outline.new(self)
-    end 
-
-  end
-  
-  # 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)   
+      @outline ||= PDF::Core::Outline.new(self)
     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.
-    #                 - currently only :FIT destination supported with link to top of page.
-    #            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 - integer defining the page number for the destination link.
-    #              currently only :FIT destination supported with link to top of page.
-    #            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)
 
-      if options[:destination]
-        page_index = options[:destination] - 1
-        outline_item.dest = [document.state.pages[page_index].dictionary, :Fit] 
-      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 => @next}, 
-       {:Prev => prev}, {:Dest => dest}].each do |h|
-        unless h.values.first.nil?
-          hash.merge!(h)
-        end
-      end
-      hash 
-    end
-  end    
+
 end
-     

data/lib/prawn/repeater.rb

@@ -11,14 +11,16 @@
 module Prawn
 
   class Document
-
     # A list of all repeaters in the document.
     # See Document#repeat for details
     #
+    # @private
     def repeaters
       @repeaters ||= []
     end
 
+    # @group Experimental API
+
     # Provides a way to execute a block of code repeatedly based on a
     # page_filter.  Since Stamp is used under the hood, this method is very space
     # efficient.
@@ -29,10 +31,10 @@ module Prawn
     #   :even       -- repeats on even pages
     #   some_array  -- repeats on every page listed in the array
     #   some_range  -- repeats on every page included in the range
-    #   some_lambda -- yields page number and repeats for true return values 
+    #   some_lambda -- yields page number and repeats for true return values
     #
-    # Also accepts an optional second argument for dynamic content which executes the code 
-    # in the context of the filtered pages without using a Stamp. 
+    # Also accepts an optional second argument for dynamic content which executes the code
+    # in the context of the filtered pages without using a Stamp.
     #
     # Example:
     #
@@ -49,8 +51,8 @@ module Prawn
     #     repeat :even do
     #       draw_text "EVEN", :at => [0,0]
     #     end
-    # 
-    #     repeat [1,2] do 
+    #
+    #     repeat [1,2] do
     #       draw_text "[1,2]", :at => [100,0]
     #     end
     #
@@ -62,11 +64,11 @@ module Prawn
     #       draw_text "Every third", :at => [250, 20]
     #     end
     #
-    #     10.times do 
+    #     10.times do
     #       start_new_page
     #       draw_text "A wonderful page", :at => [400,400]
     #     end
-    #     
+    #
     #     repeat(:all, :dynamic => true) do
     #       text page_number, :at => [500, 0]
     #     end
@@ -108,7 +110,7 @@ module Prawn
     def run(page_number)
       if !@dynamic
         @document.stamp(@stamp_name) if match?(page_number)
-      elsif @block
+      elsif @block && match?(page_number)
         @document.save_graphics_state(@graphic_state) do
           @document.send(:freeze_stamp_graphics)
           @block.call

data/lib/prawn/security/arcfour.rb

@@ -8,6 +8,7 @@
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
 
+# @private
 class Arcfour
   def initialize(key)
     # Convert string key to Array of integers

data/lib/prawn/security.rb

@@ -7,30 +7,34 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require 'digest/md5'
+
+require 'pdf/core/byte_string'
+
 require 'prawn/security/arcfour'
-require 'prawn/core/byte_string'
 
 module Prawn
   class Document
-    
+
     # Implements PDF encryption (password protection and permissions) as
     # specified in the PDF Reference, version 1.3, section 3.5 "Encryption".
     module Security
-      include Prawn::Core
-      
+      include PDF::Core
+
+      # @group Experimental API
+
       # Encrypts the document, to protect confidential data or control
       # modifications to the document. The encryption algorithm used is
       # detailed in the PDF Reference 1.3, section 3.5 "Encryption", and it is
       # implemented by all major PDF readers.
       #
       # +options+ can contain the following:
-      # 
-      # <tt>:user_password</tt>:: Password required to open the document. If 
+      #
+      # <tt>:user_password</tt>:: Password required to open the document. If
       #                           this is omitted or empty, no password will be
       #                           required. The document will still be
       #                           encrypted, but anyone can read it.
       #
-      # <tt>:owner_password</tt>:: Password required to make modifications to 
+      # <tt>:owner_password</tt>:: Password required to make modifications to
       #                            the document or change or override its
       #                            permissions. If this is set to
       #                            <tt>:random</tt>, a random password will be
@@ -52,7 +56,7 @@ module Prawn
       #
       # <tt>:copy_contents</tt>:: Copy text and graphics from document.
       #
-      # <tt>:modify_annotations</tt>:: Add or modify text annotations and 
+      # <tt>:modify_annotations</tt>:: Add or modify text annotations and
       #                                interactive form fields.
       #
       # == Examples
@@ -66,8 +70,8 @@ module Prawn
       # both the user and the owner:
       #
       #   encrypt_document :user_password => 'foo', :owner_password => 'bar'
-      # 
-      # Set no passwords, grant all permissions (This is useful because the 
+      #
+      # Set no passwords, grant all permissions (This is useful because the
       # default in some readers, if no permissions are specified, is "deny"):
       #
       #   encrypt_document
@@ -77,10 +81,10 @@ module Prawn
       # * The encryption used is weak; the key is password-derived and is
       #   limited to 40 bits, due to US export controls in effect at the time
       #   the PDF standard was written.
-      # 
+      #
       # * There is nothing technologically requiring PDF readers to respect the
       #   permissions embedded in a document. Many PDF readers do not.
-      # 
+      #
       # * In short, you have <b>no security at all</b> against a moderately
       #   motivated person. Don't use this for anything super-serious. This is
       #   not a limitation of Prawn, but is rather a built-in limitation of the
@@ -104,7 +108,7 @@ module Prawn
         state.encrypt = true
         state.encryption_key = user_encryption_key
       end
-      
+
       # Encrypts the given string under the given key, also requiring the
       # object ID and generation number of the reference.
       # See Algorithm 3.1.
@@ -136,7 +140,7 @@ module Prawn
                           :modify_contents    => 4,
                           :copy_contents      => 5,
                           :modify_annotations => 6 }
-      
+
       FullPermissions = 0b1111_1111_1111_1111_1111_1111_1111_1111
 
       def permissions=(perms={})
@@ -162,10 +166,10 @@ module Prawn
         @permissions || FullPermissions
       end
 
-      PasswordPadding = 
+      PasswordPadding =
         "28BF4E5E4E758A4164004E56FFFA01082E2E00B6D0683E802F0CA9FE6453697A".
         scan(/../).map{|x| x.to_i(16)}.pack("c*")
-      
+
       # Pads or truncates a password to 32 bytes as per Alg 3.2.
       def pad_password(password)
         password = password[0, 32]
@@ -198,38 +202,41 @@ module Prawn
     end
 
   end
+end
 
-  module Core #:nodoc:
+# @private
+module PDF
+  module Core
     module_function
 
     # Like PdfObject, but returns an encrypted result if required.
     # For direct objects, requires the object identifier and generation number
     # from the indirect object referencing obj.
-    def EncryptedPdfObject(obj, key, id, gen, in_content_stream=false)
+    #
+    # @private
+    def EncryptedPdfObject(obj, key, id, gen, in_content_stream=false) 
       case obj
       when Array
         "[" << obj.map { |e|
             EncryptedPdfObject(e, key, id, gen, in_content_stream)
         }.join(' ') << "]"
       when LiteralString
-        # FIXME: encrypted?
-        obj = obj.gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
+        obj = ByteString.new(Prawn::Document::Security.encrypt_string(obj, key, id, gen)).gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
         "(#{obj})"
       when Time
-        # FIXME: encrypted?
         obj = obj.strftime("D:%Y%m%d%H%M%S%z").chop.chop + "'00'"
-        obj = obj.gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
+        obj = ByteString.new(Prawn::Document::Security.encrypt_string(obj, key, id, gen)).gsub(/[\\\n\(\)]/) { |m| "\\#{m}" }
         "(#{obj})"
       when String
         PdfObject(
           ByteString.new(
-            Document::Security.encrypt_string(obj, key, id, gen)),
+            Prawn::Document::Security.encrypt_string(obj, key, id, gen)),
           in_content_stream)
-      when Hash
+      when ::Hash
         output = "<< "
         obj.each do |k,v|
           unless String === k || Symbol === k
-            raise Prawn::Errors::FailedObjectConversion,
+            raise PDF::Core::Errors::FailedObjectConversion,
               "A PDF Dictionary must be keyed by names"
           end
           output << PdfObject(k.to_sym, in_content_stream) << " " <<
@@ -239,29 +246,44 @@ module Prawn
       when NameTree::Value
         PdfObject(obj.name) + " " +
           EncryptedPdfObject(obj.value, key, id, gen, in_content_stream)
+      when PDF::Core::OutlineRoot, PDF::Core::OutlineItem
+        EncryptedPdfObject(obj.to_hash, key, id, gen, in_content_stream)
       else # delegate back to PdfObject
         PdfObject(obj, in_content_stream)
       end
     end
 
+
+    # @private
+    class Stream
+      def encrypted_object(key, id, gen)
+        if filtered_stream
+          "stream\n#{Prawn::Document::Security.encrypt_string filtered_stream, key, id, gen}\nendstream\n"
+        else
+          ''
+        end
+      end
+    end
+
+    # @private
     class Reference
 
       # Returns the object definition for the object this references, keyed from
       # +key+.
       def encrypted_object(key)
         @on_encode.call(self) if @on_encode
-        output = "#{@identifier} #{gen} obj\n" <<
-          Prawn::Core::EncryptedPdfObject(data, key, @identifier, gen) << "\n"
-        if @stream
-          output << "stream\n" <<
-            Document::Security.encrypt_string(@stream, key, @identifier, gen) <<
-            "\nendstream\n"
+
+        output = "#{@identifier} #{gen} obj\n"
+        unless @stream.empty?
+          output << PDF::Core::EncryptedPdfObject(data.merge(@stream.data), key, @identifier, gen) << "\n" <<
+            @stream.encrypted_object(key, @identifier, gen)
+        else
+          output << PDF::Core::EncryptedPdfObject(data, key, @identifier, gen) << "\n"
         end
+
         output << "endobj\n"
       end
 
     end
   end
-
 end
-