prawn-core 0.5.1 → 0.6.1

data/lib/prawn/document/destinations.rb

@@ -11,6 +11,7 @@ require 'prawn/name_tree'
 module Prawn
   class Document
     module Destinations
+      
       # The maximum number of children to fit into a single node in the Dests tree.
       NAME_TREE_CHILDREN_LIMIT = 20 #:nodoc:
       
@@ -19,7 +20,7 @@ module Prawn
       # (For more on name trees, see section 3.8.4 in the PDF spec.)
       #
       def dests
-        names.data[:Dests] ||= ref(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
+        names.data[:Dests] ||= ref!(Prawn::NameTree::Node.new(self, NAME_TREE_CHILDREN_LIMIT))
       end
 
       # Adds a new destination to the dests name tree (see #dests). The
@@ -27,63 +28,63 @@ module Prawn
       # it is not already one.
       #
       def add_dest(name, reference)
-        reference = ref(reference) unless reference.is_a?(Prawn::Reference)
+        reference = ref!(reference) unless reference.is_a?(Prawn::Reference)
         dests.data.add(name, reference)
       end
 
       # Return a Dest specification for a specific location (and optional zoom
       # level).
       #
-      def dest_xyz(left, top, zoom=nil, page=@current_page)
+      def dest_xyz(left, top, zoom=nil, page=current_page)
         [page, :XYZ, left, top, zoom]
       end
 
       # Return a Dest specification that will fit the given page into the
       # viewport.
       #
-      def dest_fit(page=@current_page)
+      def dest_fit(page=current_page)
         [page, :Fit]
       end
 
       # Return a Dest specification that will fit the given page horizontally
       # into the viewport, aligned vertically at the given top coordinate.
       #
-      def dest_fit_horizontally(top, page=@current_page)
+      def dest_fit_horizontally(top, page=current_page)
         [page, :FitH, top]
       end
 
       # Return a Dest specification that will fit the given page vertically
       # into the viewport, aligned horizontally at the given left coordinate.
       #
-      def dest_fit_vertically(left, page=@current_page)
+      def dest_fit_vertically(left, page=current_page)
         [page, :FitV, left]
       end
 
       # Return a Dest specification that will fit the given rectangle into the
       # viewport, for the given page.
       #
-      def dest_fit_rect(left, bottom, right, top, page=@current_page)
+      def dest_fit_rect(left, bottom, right, top, page=current_page)
         [page, :FitR, left, bottom, right, top]
       end
 
       # Return a Dest specfication that will fit the given page's bounding box
       # into the viewport.
       #
-      def dest_fit_bounds(page=@current_page)
+      def dest_fit_bounds(page=current_page)
         [page, :FitB]
       end
 
       # Same as #dest_fit_horizontally, but works on the page's bounding box
       # instead of the entire page.
       #
-      def dest_fit_bounds_horizontally(top, page=@current_page)
+      def dest_fit_bounds_horizontally(top, page=current_page)
         [page, :FitBH, top]
       end
 
       # Same as #dest_fit_vertically, but works on the page's bounding box
       # instead of the entire page.
       #
-      def dest_fit_bounds_vertically(left, page=@current_page)
+      def dest_fit_bounds_vertically(left, page=current_page)
         [page, :FitBV, left]
       end
     end

data/lib/prawn/document/internals.rb

@@ -17,7 +17,9 @@ module Prawn
     module Internals    
       
       # Creates a new Prawn::Reference and adds it to the Document's object
-      # list.  The +data+ argument is anything that Prawn::PdfObject() can convert.    
+      # list.  The +data+ argument is anything that Prawn::PdfObject() can convert. 
+      #
+      # Returns the identifier which points to the reference in the ObjectStore   
       # 
       # If a block is given, it will be invoked just before the object is written
       # out to the PDF document stream. This allows you to do deferred processing
@@ -25,8 +27,40 @@ module Prawn
       # about until the last page of the document is finished).
       #
       def ref(data, &block)
-        @objects.push(Prawn::Reference.new(@objects.size + 1, data, &block)).last
+        ref!(data, &block).identifier
       end                                               
+
+      # Like ref, but returns the actual reference instead of its identifier.
+      # 
+      # While you can use this to build up nested references within the object
+      # tree, it is recommended to persist only identifiers, and them provide
+      # helper methods to look up the actual references in the ObjectStore
+      # if needed.  If you take this approach, Prawn::Document::Snapshot
+      # will probably work with your extension
+      #
+      def ref!(data, &block)
+        @store.ref(data, &block)
+      end
+
+      def page_content
+        @store[@page_content]
+      end
+
+      def current_page
+        @store[@current_page]
+      end
+
+      # Grabs the reference for the current page content
+      #
+      def page_content
+        @active_stamp_stream || @store[@page_content]
+      end
+
+      # Grabs the reference for the current page
+      #
+      def current_page
+        @active_stamp_dictionary || @store[@current_page]
+      end
       
       # Appends a raw string to the current page content.
       #                               
@@ -37,20 +71,20 @@ module Prawn
       #  pdf.add_content("S") # stroke                    
       #
       def add_content(str)
-       @page_content << str << "\n"
+        page_content << str << "\n"
       end  
 
       # Add a new type to the current pages ProcSet 
       #
       def proc_set(*types)
-        @current_page.data[:ProcSet] ||= ref([])
-        @current_page.data[:ProcSet].data |= types
+        current_page.data[:ProcSet] ||= ref!([])
+        current_page.data[:ProcSet].data |= types
       end
              
       # The Resources dictionary for the current page
       #
       def page_resources
-        @current_page.data[:Resources] ||= {}
+        current_page.data[:Resources] ||= {}
       end
       
       # The Font dictionary for the current page
@@ -63,24 +97,28 @@ module Prawn
       #
       def page_xobjects
         page_resources[:XObject] ||= {}
-      end  
+      end
+
+      def page_ext_gstates
+        page_resources[:ExtGState] ||= {}
+      end
       
       # The Name dictionary (PDF spec 3.6.3) for this document. It is
       # lazily initialized, so that documents that do not need a name
       # dictionary do not incur the additional overhead.
       #
       def names
-        @root.data[:Names] ||= ref(:Type => :Names)
+        @store.root.data[:Names] ||= ref!(:Type => :Names)
       end
 
       private      
       
       def finish_page_content     
-        @header.draw if @header      
-        @footer.draw if @footer
+        @header.draw if defined?(@header) and @header
+        @footer.draw if defined?(@footer) and @footer
         add_content "Q"
-        @page_content.compress_stream if compression_enabled?
-        @page_content.data[:Length] = @page_content.stream.size
+        page_content.compress_stream if compression_enabled?
+        page_content.data[:Length] = page_content.stream.size
       end
 
       # raise the PDF version of the file we're going to generate.
@@ -91,39 +129,44 @@ module Prawn
       end
 
       # Write out the PDF Header, as per spec 3.4.1
+      #
       def render_header(output)
         # pdf version
         output << "%PDF-#{@version}\n"
 
         # 4 binary chars, as recommended by the spec
-        output << "\xFF\xFF\xFF\xFF\n"
+        output << "%\xFF\xFF\xFF\xFF\n"
       end
 
       # Write out the PDF Body, as per spec 3.4.2
+      #
       def render_body(output)
-        @objects.each do |ref|
+        @store.each do |ref|
           ref.offset = output.size
           output << ref.object
         end
       end
 
       # Write out the PDF Cross Reference Table, as per spec 3.4.3
+      #
       def render_xref(output)
         @xref_offset = output.size
         output << "xref\n"
-        output << "0 #{@objects.size + 1}\n"
+        output << "0 #{@store.size + 1}\n"
         output << "0000000000 65535 f \n"
-        @objects.each do |ref|
+        @store.each do |ref|
           output.printf("%010d", ref.offset)
           output << " 00000 n \n"
         end
       end
 
       # Write out the PDF Trailer, as per spec 3.4.4
+      #
       def render_trailer(output)
-        trailer_hash = {:Size => @objects.size + 1, 
-                        :Root => @root,
-                        :Info => @info}
+        trailer_hash = {:Size => @store.size + 1, 
+                        :Root => @store.root,
+                        :Info => @store.info}
+        trailer_hash.merge!(@trailer) if @trailer
 
         output << "trailer\n"
         output << Prawn::PdfObject(trailer_hash) << "\n"

data/lib/prawn/document/snapshot.rb

@@ -0,0 +1,71 @@
+# encoding: utf-8
+
+# snapshot.rb : Implements transactional rendering for Prawn
+#
+# Copyright August 2008, Brad Ediger.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+require 'delegate'
+
+module Prawn
+  class Document
+    module Snapshot
+
+      RollbackTransaction = Class.new(StandardError)
+
+      # Call this within a +transaction+ block to roll back the transaction and
+      # prevent any of its data from being rendered. You must reset the
+      # y-position yourself if you have performed any drawing operations that
+      # modify it.
+      def rollback
+        raise RollbackTransaction
+      end
+
+      # Run a block of drawing operations, to be completed atomically. If
+      # +rollback+ is called or a RollbackTransaction exception is raised
+      # inside the block, all actions taken inside the block will be rolled
+      # back (with the exception of y-position, which you must restore
+      # yourself). 
+      #
+      # Returns true on success, or false if the transaction was rolled back.
+      def transaction
+        snap = take_snapshot
+        yield
+        true
+      rescue RollbackTransaction
+        restore_snapshot(snap)
+        false
+      end
+
+      private
+      
+      # Takes a current snapshot of the document's state, sufficient to
+      # reconstruct it after it was amended.
+      def take_snapshot
+        {:page_content    => Marshal.load(Marshal.dump(page_content)),
+         :current_page    => Marshal.load(Marshal.dump(current_page)),
+         :page_kids       => @store.pages.data[:Kids].map{|kid| kid.identifier},
+         :dests           => Marshal.load(Marshal.dump(names.data[:Dests]))}
+      end
+
+      # Rolls the page state back to the state of the given snapshot.
+      def restore_snapshot(shot)
+        # Because these objects are referenced by identifier from the Pages
+        # dictionary, we can't just restore them over the current refs in
+        # page_content and current_page. We have to restore them over the old
+        # ones.
+        @page_content = shot[:page_content].identifier
+        page_content.replace shot[:page_content]
+
+        @current_page = shot[:current_page].identifier
+        current_page.replace shot[:current_page]
+
+        @store.pages.data[:Kids] = shot[:page_kids].map{|id| @store[id]}
+        @store.pages.data[:Count] = shot[:page_kids].size
+
+        names.data[:Dests] = shot[:dests]
+      end
+
+    end
+  end
+end

data/lib/prawn/document/text/box.rb

@@ -23,6 +23,8 @@ module Prawn
     end
     
     module Text 
+      # FIXME: requires documentation
+      #
       class Box #:nodoc:
         def initialize(text,options={})
           @document  = options[:for]
@@ -54,6 +56,8 @@ module Prawn
           unless @overflow == :expand
             @document.y = y + @document.bounds.absolute_bottom - @height  
           end        
+
+          @excess_text
         end
         
         private        
@@ -71,6 +75,9 @@ module Prawn
             when :ellipses
               @text[-3..-1] = "..." if @text.size > 3
             end
+            @excess_text = @document.naive_unwrap(lines[max_lines..-1].join)
+          else
+            @excess_text = ""
           end 
         end
         

data/lib/prawn/document/text/wrapping.rb

@@ -53,6 +53,9 @@ module Prawn
           output
         end
         
+        def naive_unwrap(string)
+          string.gsub(/(\S)\n/, '\1 ')
+        end
       end  
     end
   end

data/lib/prawn/document/text.rb

@@ -43,8 +43,10 @@ module Prawn
       #
       # === Text Positioning Details:
       #
-      # When using the :at parameter, Prawn will position your text by its
-      # baseline, and flow along a single line.
+      # When using the :at parameter, Prawn will position your text by the
+      # left-most edge of its baseline, and flow along a single line.  (This
+      # means that :align will not work)
+      # 
       #
       # Otherwise, the text is positioned at font.ascender below the baseline,
       # making it easy to use this method within bounding boxes and spans.
@@ -79,6 +81,11 @@ module Prawn
           font.normalize_encoding!(text) unless @skip_encoding        
 
           if options[:at]                
+
+            if options[:align]
+              raise ArgumentError, "The :align option does not work with :at" 
+            end
+
             x,y = translate(options[:at])            
             font_size(options[:size]) { add_text_content(text,x,y,options) }
           else

data/lib/prawn/document.rb

@@ -15,6 +15,7 @@ require "prawn/document/span"
 require "prawn/document/text"
 require "prawn/document/annotations"
 require "prawn/document/destinations"
+require "prawn/document/snapshot"
 
 module Prawn
   
@@ -58,13 +59,20 @@ module Prawn
     include Internals
     include Annotations
     include Destinations
+    include Snapshot
     include Prawn::Graphics
     include Prawn::Images
+    include Prawn::Stamp
 
-    attr_accessor :y, :margin_box
-    attr_reader   :margins, :page_size, :page_layout
+    attr_accessor :margin_box
+    attr_reader   :margins, :page_size, :page_layout, :y
     attr_writer   :font_size
 
+
+    def self.extensions
+      @extensions ||= []
+    end
+
     # Creates and renders a PDF document.
     #
     # When using the implicit block form, Prawn will evaluate the block
@@ -102,6 +110,7 @@ module Prawn
     #
     # <tt>:page_size</tt>:: One of the Document::PageGeometry sizes [LETTER]
     # <tt>:page_layout</tt>:: Either <tt>:portrait</tt> or <tt>:landscape</tt>
+    # <tt>:margin</tt>:: Sets the margin on all sides in points [0.5 inch]
     # <tt>:left_margin</tt>:: Sets the left margin in points [0.5 inch]
     # <tt>:right_margin</tt>:: Sets the right margin in points [0.5 inch]
     # <tt>:top_margin</tt>:: Sets the top margin in points [0.5 inch]
@@ -111,7 +120,19 @@ module Prawn
     # <tt>:background</tt>:: An image path to be used as background on all pages [nil]
     # <tt>:info</tt>:: Generic hash allowing for custom metadata properties [nil]
     # <tt>:text_options</tt>:: A set of default options to be handed to text(). Be careful with this.
-
+    #
+    # Setting e.g. the :margin to 100 points and the :left_margin to 50 will result in margins
+    # of 100 points on every side except for the left, where it will be 50.
+    #
+    # The :margin can also be an array much like CSS shorthand:
+    #
+    #   # Top and bottom are 20, left and right are 100.
+    #   :margin => [20, 100]
+    #   # Top is 50, left and right are 100, bottom is 20.
+    #   :margin => [50, 100, 20]
+    #   # Top is 10, right is 20, bottom is 30, left is 40.
+    #   :margin => [10, 20, 30, 40]
+    #
     # Additionally, :page_size can be specified as a simple two value array giving
     # the width and height of the document you need in PDF Points.
     # 
@@ -130,9 +151,11 @@ module Prawn
     #   pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")
     #
     def initialize(options={},&block)   
-       Prawn.verify_options [:page_size, :page_layout, :left_margin, 
+       Prawn.verify_options [:page_size, :page_layout, :margin, :left_margin, 
          :right_margin, :top_margin, :bottom_margin, :skip_page_creation, 
          :compress, :skip_encoding, :text_options, :background, :info], options
+
+       self.class.extensions.reverse_each { |e| extend e }
       
        options[:info] ||= {}
        options[:info][:Creator] ||= "Prawn"
@@ -145,23 +168,28 @@ module Prawn
        end
           
        @version = 1.3
-       @objects = []
-       @info    = ref(options[:info])
-       @pages   = ref(:Type => :Pages, :Count => 0, :Kids => [])
-       @root    = ref(:Type => :Catalog, :Pages => @pages)
-       @page_size       = options[:page_size]   || "LETTER"
-       @page_layout     = options[:page_layout] || :portrait
-       @compress        = options[:compress] || false
-       @skip_encoding   = options[:skip_encoding]
-       @background      = options[:background]
-       @font_size       = 12
+       @store = ObjectStore.new(options[:info])
+       @trailer = {}
+
+       @page_size     = options[:page_size]   || "LETTER"
+       @page_layout   = options[:page_layout] || :portrait
+       @compress      = options[:compress] || false
+       @skip_encoding = options[:skip_encoding]
+       @background    = options[:background]
+       @font_size     = 12
+       @page_content  = nil
+       @bounding_box  = nil
+       @margin_box    = nil
 
        @text_options = options[:text_options] || {}
+       
+       apply_margin_option(options) if options[:margin]
 
-       @margins = { :left   => options[:left_margin]   || 36,
-                    :right  => options[:right_margin]  || 36,
-                    :top    => options[:top_margin]    || 36,
-                    :bottom => options[:bottom_margin] || 36  }
+       default_margin = 36  # 0.5 inch
+       @margins = { :left   => options[:left_margin]   || default_margin,
+                    :right  => options[:right_margin]  || default_margin,
+                    :top    => options[:top_margin]    || default_margin,
+                    :bottom => options[:bottom_margin] || default_margin  }
 
        generate_margin_box
 
@@ -182,22 +210,25 @@ module Prawn
      #   pdf.start_new_page #=> Starts new page keeping current values
      #   pdf.start_new_page(:size => "LEGAL", :layout => :landscape)
      #   pdf.start_new_page(:left_margin => 50, :right_margin => 50)
+     #   pdf.start_new_page(:margin => 100)
      #
      def start_new_page(options = {})
        @page_size   = options[:size] if options[:size]
        @page_layout = options[:layout] if options[:layout]
+       
+       apply_margin_option(options) if options[:margin]
 
        [:left,:right,:top,:bottom].each do |side|
-         if options[:"#{side}_margin"]
-           @margins[side] = options[:"#{side}_margin"]
+         if margin = options[:"#{side}_margin"]
+           @margins[side] = margin
          end
        end
 
        finish_page_content if @page_content
        build_new_page_content
 
-       @pages.data[:Kids] << @current_page
-       @pages.data[:Count] += 1
+       @store.pages.data[:Kids] << current_page
+       @store.pages.data[:Count] += 1
 
        add_content "q"
 
@@ -214,7 +245,12 @@ module Prawn
     #   pdf.page_count #=> 4
     #
     def page_count
-      @pages.data[:Count]
+      @store.pages.data[:Count]
+    end
+
+    def y=(new_y)
+      @y = new_y
+      bounds.update_height
     end
 
     # The current y drawing position relative to the innermost bounding box,
@@ -224,6 +260,13 @@ module Prawn
       y - bounds.absolute_bottom
     end
 
+
+    # Moves to the specified y position in relative terms to the bottom margin.
+    # 
+    def move_cursor_to(new_y)
+      self.y = new_y + bounds.absolute_bottom
+    end
+
     # Renders the PDF document to string, useful for example in a Rails 
     # application where you want to stream out the PDF to a web browser:
     # 
@@ -376,6 +419,67 @@ module Prawn
       fields.each { |f| send("#{f}=", stored[f]) }
     end
 
+    # Raised if group() is called with a block that is too big to be
+    # rendered in the current context.
+    #
+    CannotGroup = Class.new(StandardError)
+
+    # Attempts to group the given block vertically within the current context.
+    # First attempts to render it in the current position on the current page.
+    # If that attempt overflows, it is tried anew after starting a new context
+    # (page or column).
+    #
+    # Raises CannotGroup if the provided content is too large to fit alone in
+    # the current page or column.
+    #
+    def group(second_attempt=false)
+      old_bounding_box = @bounding_box
+      @bounding_box = SimpleDelegator.new(@bounding_box)
+
+      def @bounding_box.move_past_bottom
+        raise RollbackTransaction
+      end
+
+      success = transaction { yield }
+
+      unless success
+        raise CannotGroup if second_attempt
+        old_bounding_box.move_past_bottom
+        group(second_attempt=true) { yield }
+      end 
+
+      @bounding_box = old_bounding_box
+    end
+
+    # Specify a template for page numbering.  This should be called
+    # towards the end of document creation, after all your content is already in
+    # place.  In your template string, <page> refers to the current page, and
+    # <total> refers to the total amount of pages in the doucment.
+    #
+    # Example:
+    #
+    #   Prawn::Document.generate("page_with_numbering.pdf") do
+    #     text "Hai"
+    #     start_new_page
+    #     text "bai"
+    #     start_new_page
+    #     text "-- Hai again"
+    #     number_pages "<page> in a total of <total>", [bounds.right - 50, 0]  
+    #   end
+    def number_pages(string, position)
+      page_count.times do |i|
+        go_to_page(i)
+        str = string.gsub("<page>","#{i+1}").gsub("<total>","#{page_count}")
+        text str, :at => position
+      end
+    end
+
+    def go_to_page(k) # :nodoc:
+      jump_to = @store.pages.data[:Kids][k]
+      @current_page = jump_to.identifier
+      @page_content = jump_to.data[:Contents].identifier
+    end
+
     # Returns true if content streams will be compressed before rendering,
     # false otherwise
     #
@@ -392,10 +496,11 @@ module Prawn
       @page_content = ref(:Length => 0)
 
       @current_page = ref(:Type      => :Page,
-                          :Parent    => @pages,
+                          :Parent    => @store.pages,
                           :MediaBox  => page_dimensions,
-                          :Contents  => @page_content)
+                          :Contents  => page_content)
       update_colors
+      undash if dashed?
     end
 
     def generate_margin_box
@@ -413,6 +518,17 @@ module Prawn
       # when the bounding box exits.
       @bounding_box = @margin_box if old_margin_box == @bounding_box
     end
+    
+    def apply_margin_option(options)
+      # Treat :margin as CSS shorthand with 1-4 values.
+      margin = Array(options[:margin])
+      positions = { 4 => [0,1,2,3], 3 => [0,1,2,1],
+                    2 => [0,1,0,1], 1 => [0,0,0,0] }[margin.length]
+
+      [:top, :right, :bottom, :left].zip(positions).each do |p,i|
+        options[:"#{p}_margin"] ||= margin[i]
+      end
+    end
 
   end
 end

data/lib/prawn/errors.rb

@@ -45,5 +45,17 @@ module Prawn
      # type. This can either a completely unsupported format, or a dialect of a
      # supported format (ie. some types of PNG)
      UnsupportedImageType = Class.new(StandardError)
+
+    # This error is raised when a named element has alredy been
+    # created. For example, in the stamp module, stamps must have
+    # unique names within a document
+    NameTaken = Class.new(StandardError)
+
+    # This error is raised when a name is not a valid format
+    InvalidName = Class.new(StandardError)
+
+    # This error is raised when an object is attempted to be
+    # referenced by name, but no such name is associated with an object
+    UndefinedObjectName = Class.new(StandardError)
   end
 end   

data/lib/prawn/font/afm.rb

@@ -95,7 +95,7 @@ module Prawn
       private
 
       def register(subset)
-        @document.ref(:Type     => :Font,
+        @document.ref!(:Type     => :Font,
                       :Subtype  => :Type1,
                       :BaseFont => name.to_sym,
                       :Encoding => :WinAnsiEncoding)