prawn-core 0.6.3 → 0.7.1

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/testtask'
 require "rake/rdoctask"
 require "rake/gempackagetask"  
 
-PRAWN_VERSION = "0.6.3" 
+PRAWN_VERSION = "0.7.1" 
 
 task :default => [:test]
        

data/examples/general/context_sensitive_headers.rb

@@ -0,0 +1,37 @@
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+# Ex. Generate a roster of meeting attendees given a set of meetings.
+# Attendees for a meeting may overflow to accross page boundaries but 
+# each meeting starts on a separate page. Each page for any given
+# meeting will have the heading for that meeting. 
+
+#dummying up some meetings
+meetings = []
+5.times do |i|
+  meetings << "Meeting number #{i}"
+end
+
+Prawn::Document.generate('context_sensitive_headers.pdf', :margin => [100, 100], :skip_page_creation => true) do
+  meetings.each_with_index do |meeting,i|
+    
+    create_stamp(meeting.to_s) do
+      canvas do
+        text_box("header for #{meeting}",
+          :at => [bounds.left + 50, bounds.top - 20],
+          :height => 50,
+          :width => margin_box.width)
+      end
+    end
+    on_page_create { stamp(meeting.to_s) }
+
+    start_new_page
+
+    #simulate some meetings with content over multiple pages
+    (15 + 20*i).times do |i|
+      text "#{meeting} attendee #{i}"
+    end
+    
+  end
+
+end
+

data/examples/general/float.rb

@@ -0,0 +1,11 @@
+require "#{File.dirname(__FILE__)}/../example_helper"
+
+Prawn::Document.generate('float.pdf') do
+  float do
+    bounding_box [bounds.width / 2.0, bounds.top], :width => 100 do
+      text "Hello world. " * 50
+    end
+  end
+
+  text "Hello world again"
+end

data/examples/general/repeaters.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+#
+# This example demonstrates how to make use of Prawn's repeating element
+# support.  Note that all repeated elements are generated using XObjects, so
+# they should be pretty efficient.
+#
+#
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("repeat.pdf", :skip_page_creation => true) do
+
+  repeat :all do
+    text "ALLLLLL", :at => bounds.top_left
+  end
+
+  repeat :odd do
+    text "ODD", :at => [0,0]
+  end
+
+  repeat :even do
+    text "EVEN", :at => [0,0]
+  end
+
+  repeat [1,2] do 
+    text "[1,2]", :at => [100,0]
+  end
+
+  repeat 2..4 do
+    text "2..4", :at => [200,0]
+  end
+
+  repeat(lambda { |pg| pg % 3 == 0 }) do
+    text "Every third", :at => [250, 20]
+  end
+
+  10.times do 
+    start_new_page
+    text "A wonderful page", :at => [400,400]
+  end
+
+end
+
+

data/examples/m17n/chinese_text_wrapping.rb

@@ -1,7 +1,5 @@
 # encoding: utf-8
 #
-# Some text is not usefully wrapped by our naive_wrap which depends on 
-# spaces.  This example shows how to wrap by character instead.
 #
 require "#{File.dirname(__FILE__)}/../example_helper.rb"
 
@@ -11,7 +9,7 @@ Prawn::Document.generate("chinese_flow.pdf") do
   font_size 16
 
   long_text = "更可怕的是，同质化竞争对手可以按照URL中后面这个ID来遍历您的DB中的内容，写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事，这样的话，你就非常被动了。写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事写个小爬虫把你的页面上的关键信息顺次爬下来也不是什么难事"                                                       
-  text long_text, :wrap => :character
+  text long_text
   
   # be sure to restore space based wrapping when dealing with latin scripts
   long_text = "Text with some spaces " * 25

data/examples/text/font_calculations.rb

@@ -64,17 +64,17 @@ Prawn::Document.generate('font_calculations.pdf') do
     stroke_line [0, bl + font.ascender], [bounds.width, bl + font.ascender]
 
     stroke_color colors[:descender]
-    stroke_line [0,bl], [0, bl + font.descender]
-    stroke_line [0, bl + font.descender], [bounds.width, bl + font.descender]
+    stroke_line [0,bl], [0, bl - font.descender]
+    stroke_line [0, bl - font.descender], [bounds.width, bl - font.descender]
 
     stroke_color colors[:line_gap]
-    stroke_line [0, bl + font.descender], [0,bl + font.descender - font.line_gap]
-    stroke_line [0, bl + font.descender - font.line_gap], 
-                [bounds.width,bl + font.descender - font.line_gap]
+    stroke_line [0, bl - font.descender], [0,bl - font.descender - font.line_gap]
+    stroke_line [0, bl - font.descender - font.line_gap], 
+                [bounds.width,bl - font.descender - font.line_gap]
 
     stroke_color colors[:font_height]
     stroke_line [bounds.width, bl + font.ascender],
-                [bounds.width, bl + font.descender - font.line_gap]
+                [bounds.width, bl - font.descender - font.line_gap]
                 
     stroke_color "000000"
     fill_color "000000"

data/examples/text/text_box.rb

@@ -1,25 +1,88 @@
 # encoding: utf-8
 #
-# A text box is positioned by a top-left corner, width, and height and is
-# essentially an invisible rectangle that the text will flow within.  If the
-# text exceeds the boundaries, it is either truncated, replaced with some
-# ellipses, or set to expand beyond the bottom boundary.
-#
-require "#{File.dirname(__FILE__)}/../example_helper.rb"
 
-Prawn::Document.generate("text_box.pdf") do
+require 'examples/example_helper'
 
-  text_box "Oh hai text box. " * 200, 
-    :width    => 300, :height => font.height * 5,
-    :overflow => :ellipses, 
-    :at       => [100,bounds.top]
+Prawn::Document.generate("text_box.pdf") do
+  def get_string(i, j)      
+    case i
+    when 0
+      text = "this is left text " * 30
+      text.insert(48, "\n\n")
+    when 1
+      text = "this is center text " * 30
+      text.insert(54, "\n\n")
+    when 2
+      text = "this is right text " * 30
+      text.insert(51, "\n\n")
+    end
+    
+    case j
+    when 0
+      text.split(" ").slice(0..47).join(" ")
+    when 3
+      text.delete(" ")
+    else
+      text
+    end
+  end
 
-  text_box "Oh hai text box. " * 200,
-    :width    => 250, :height => font.height * 10,
-    :overflow => :truncate,
-    :at       => [50, 300]
+  def get_options(i, j)
+    options = {
+      :width    => bounds.width * 0.3,
+      :height   => bounds.width * 0.3,
+      :overflow => :ellipses,
+      :at       => [0, 0],
+      :align    => :left,
+      :document => self
+    }
+    
+    case i
+    when 0
+      options[:valign] = :top if j == 0
+    when 1
+      options[:align] = :center
+      options[:valign] = :center if j == 0
+    when 2
+      options[:align] = :right
+      options[:valign] = :bottom if j == 0
+    end
+    
+    case j
+    when 1
+      options[:overflow] = :shrink_to_fit
+    when 2
+      options[:leading] = font.height * 0.5
+      options[:overflow] = :truncate
+    end
+    options
+  end
 
-  move_down 20
+  stroke_color("555555")
+  3.times do |i|
+    4.times do |j|
+      options = get_options(i, j)
+      options[:at][0] = (bounds.width  - options[:width]) * 0.5 * i
+      options[:at][1] = bounds.top - (bounds.height - options[:height]) * 0.33 * j
+      box = Prawn::Text::Box.new(get_string(i, j), options)
 
-  text_box "Oh hai text box. " * 100, :overflow => :expand
+      fill_color("ffeeee")
+      if i == 1
+        # bound with a box of a particular size, regardless of how
+        # much text it contains
+        fill_and_stroke_rectangle(options[:at],
+                                  options[:width],
+                                  options[:height])
+      else
+        # bound with a box that exactly fits the printed text using
+        # dry_run look-ahead
+        box.render(:dry_run => true)
+        fill_and_stroke_rectangle(options[:at],
+                                  options[:width],
+                                  box.height)
+      end
+      fill_color("000000")
+      box.render
+    end
+  end
 end

data/lib/prawn/core.rb

@@ -25,7 +25,7 @@ module Prawn
   # The base source directory for Prawn as installed on the system
   BASEDIR = File.expand_path(File.join(dir, '..', '..'))
   
-  VERSION = "0.6.3"
+  VERSION = "0.7.1"
   
   extend self
 
@@ -73,6 +73,7 @@ require "prawn/compatibility"
 require "prawn/errors"
 require "prawn/pdf_object"
 require "prawn/object_store"
+require "prawn/text"
 require "prawn/graphics"
 require "prawn/images"
 require "prawn/images/jpg"
@@ -83,3 +84,4 @@ require "prawn/reference"
 require "prawn/font"
 require "prawn/encoding"
 require "prawn/measurements"
+require "prawn/repeater"

data/lib/prawn/document/bounding_box.rb

@@ -223,6 +223,15 @@ module Prawn
       
       # Temporarily adjust the @x coordinate to allow for left_padding
       #
+      # Example:
+      #
+      #  indent 20 do
+      #     text "20 points in"
+      #     indent 30 do
+      #       text "50 points in"
+      #     end
+      #   end
+      #
       def indent(left_padding, &block)
         @x += left_padding
         @width -= left_padding

data/lib/prawn/document/column_box.rb

@@ -43,22 +43,29 @@ module Prawn
     
     # Template methods to support ColumnBox extensions
     class BoundingBox
+      
+      # an alias for absolute_left
       def left_side
          absolute_left
       end
 
+      # an alias for absolute_right
       def right_side
          absolute_right
       end
 
+      # starts a new page
       def move_past_bottom
          @parent.start_new_page
       end
     end
 
+    # Implements the necessary functionality to allow Document#column_box to
+    # work.
+    #
     class ColumnBox < BoundingBox
 
-      def initialize(parent, point, options={})
+      def initialize(parent, point, options={}) #:nodoc:
         super
         @columns = options[:columns] || 3
         @spacer  = options[:spacer]  || @parent.font_size
@@ -72,6 +79,8 @@ module Prawn
         super / @columns - @spacer
       end
 
+      # Column width including the spacer.
+      #
       def width_of_column
         width + @spacer
       end
@@ -89,7 +98,9 @@ module Prawn
         absolute_right - (width_of_column * columns_from_right)
       end
 
-      def move_past_bottom #:nodoc:
+      # Moves to the next column or starts a new page if currently positioned at
+      # the rightmost column.
+      def move_past_bottom 
         @current_column = (@current_column + 1) % @columns
         @parent.y = @y
         if 0 == @current_column

data/lib/prawn/document/internals.rb

@@ -79,6 +79,8 @@ module Prawn
         page_resources[:XObject] ||= {}
       end
 
+      # The ExtGState dictionary for the current page
+      #
       def page_ext_gstates
         page_resources[:ExtGState] ||= {}
       end
@@ -91,6 +93,12 @@ module Prawn
         @store.root.data[:Names] ||= ref!(:Type => :Names)
       end
 
+      # Returns true if the Names dictionary is in use for this document.
+      # 
+      def names?
+        @store.root.data[:Names]
+      end
+
       # Defines a block to be called just before the document is rendered.
       #
       def before_render(&block)
@@ -103,13 +111,22 @@ module Prawn
         @page_content = jump_to.data[:Contents].identifier
       end
 
+      # Defines a block to be called just before a new page is started.
+      #
+      def on_page_create(&block)
+         if block_given?
+            @on_page_create_callback = block
+         else
+            @on_page_create_callback = nil
+         end
+      end
+      
       private      
 
       def finalize_all_page_contents
-        page_count.times do |i|
+        (1..page_count).each do |i|
           go_to_page i
-          @header.draw if defined?(@header) and @header
-          @footer.draw if defined?(@footer) and @footer
+          repeaters.each { |r| r.run(i) }
           add_content "Q"
           page_content.compress_stream if compression_enabled?
           page_content.data[:Length] = page_content.stream.size
@@ -138,6 +155,7 @@ module Prawn
       # Write out the PDF Body, as per spec 3.4.2
       #
       def render_body(output)
+        @store.compact if @optimize_objects
         @store.each do |ref|
           ref.offset = output.size
           output << ref.object

data/lib/prawn/document/snapshot.rb

@@ -17,6 +17,7 @@ module Prawn
       # 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
@@ -28,6 +29,7 @@ module Prawn
       # yourself). 
       #
       # Returns true on success, or false if the transaction was rolled back.
+      #
       def transaction
         snap = take_snapshot
         yield
@@ -45,7 +47,8 @@ module Prawn
         {: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]))}
+         :dests           => names? && 
+                             Marshal.load(Marshal.dump(names.data[:Dests]))}
       end
 
       # Rolls the page state back to the state of the given snapshot.
@@ -64,7 +67,9 @@ module Prawn
         @store.pages.data[:Kids] = shot[:page_kids].map{|id| @store[id]}
         @store.pages.data[:Count] = shot[:page_kids].size
 
-        names.data[:Dests] = shot[:dests]
+        if shot[:dests]
+          names.data[:Dests] = shot[:dests] 
+        end
       end
 
     end

data/lib/prawn/document/span.rb

@@ -27,8 +27,8 @@ module Prawn
     def span(width, options={})
       Prawn.verify_options [:position], options
       original_position = self.y      
-      
-      # FIXME: How many effing times do I want to write this same code?
+     
+      # FIXME: Any way to move this upstream?
       left_boundary = case(options[:position] || :left)
       when :left
         margin_box.absolute_left
@@ -52,4 +52,4 @@ module Prawn
       end          
     end
   end
-end
+end

data/lib/prawn/document.rb

@@ -12,7 +12,6 @@ require "prawn/document/bounding_box"
 require "prawn/document/column_box"
 require "prawn/document/internals"
 require "prawn/document/span"
-require "prawn/document/text"
 require "prawn/document/annotations"
 require "prawn/document/destinations"
 require "prawn/document/snapshot"
@@ -60,6 +59,7 @@ module Prawn
     include Annotations
     include Destinations
     include Snapshot
+    include Prawn::Text
     include Prawn::Graphics
     include Prawn::Images
     include Prawn::Stamp
@@ -69,11 +69,31 @@ module Prawn
     attr_writer   :font_size
 
 
+    # Any module added to this array will be included into instances of
+    # Prawn::Document at the per-object level.  These will also be inherited by
+    # any subclasses.
+    #
+    # Example:
+    #
+    #   module MyFancyModule
+    #    
+    #     def party!
+    #       text "It's a big party!"
+    #     end
+    #   
+    #   end
+    #
+    #   Prawn::Document.extensions << MyFancyModule
+    #
+    #   Prawn::Document.generate("foo.pdf") do
+    #     party!
+    #   end
+    #
     def self.extensions
       @extensions ||= []
     end
 
-    def self.inherited(base)
+    def self.inherited(base) #:nodoc:
       extensions.each { |e| base.extensions << e }
     end
 
@@ -121,6 +141,7 @@ module Prawn
     # <tt>:bottom_margin</tt>:: Sets the bottom margin in points [0.5 inch]
     # <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
     # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
+    # <tt>:optimize_objects</tt>:: Reduce number of PDF objects in output, at expense of render time [false]
     # <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.
@@ -157,7 +178,8 @@ module Prawn
     def initialize(options={},&block)   
        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
+         :compress, :skip_encoding, :text_options, :background, :info,
+         :optimize_objects], options
 
        self.class.extensions.reverse_each { |e| extend e }
       
@@ -175,10 +197,12 @@ module Prawn
        @store = ObjectStore.new(options[:info])
        @trailer = {}
        @before_render_callbacks = []
+       @on_page_create_callback = nil
 
        @page_size     = options[:page_size]   || "LETTER"
        @page_layout   = options[:page_layout] || :portrait
        @compress      = options[:compress] || false
+       @optimize_objects = options.fetch(:optimize_objects, false)
        @skip_encoding = options[:skip_encoding]
        @background    = options[:background]
        @font_size     = 12
@@ -199,6 +223,7 @@ module Prawn
        generate_margin_box
 
        @bounding_box = @margin_box
+       @page_number = 0
 
        start_new_page unless options[:skip_page_creation]
 
@@ -218,6 +243,7 @@ module Prawn
      #   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]
        
@@ -230,15 +256,20 @@ module Prawn
        end
 
        build_new_page_content
-
-       @store.pages.data[:Kids] << current_page
+       
+       @store.pages.data[:Kids].insert(@page_number, current_page)
        @store.pages.data[:Count] += 1
-
+       @page_number += 1
+        
        add_content "q"
-
+       
        @y = @bounding_box.absolute_top
 
        image(@background, :at => [0,@y]) if @background
+       
+       float do
+         @on_page_create_callback.call(self) if @on_page_create_callback 
+       end
     end
 
     # Returns the number of pages in the document
@@ -252,6 +283,26 @@ module Prawn
       @store.pages.data[:Count]
     end
 
+    # Returns the 1-based page number of the current page. Returns 0 if the
+    # document has no pages.
+    #
+    def page_number
+      @page_number
+    end
+
+    # Re-opens the page with the given (1-based) page number so that you can
+    # draw on it. Does not restore page state such as margins, page orientation,
+    # or paper size, so you'll have to handle that yourself.
+    #
+    # See Prawn::Document#number_pages for a sample usage of this capability.
+    #
+    def go_to_page(k)
+      @page_number = k
+      jump_to = @store.pages.data[:Kids][k-1]
+      @current_page = jump_to.identifier
+      @page_content = jump_to.data[:Contents].identifier
+    end
+
     def y=(new_y)
       @y = new_y
       bounds.update_height
@@ -271,15 +322,22 @@ module Prawn
       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:
-    # 
-    #  def show
-    #    pdf = Prawn::Document.new do
-    #      text "Putting PDF generation code in a controller is _BAD_"
-    #    end
-    #    send(pdf.render, :filename => 'silly.pdf', :type => 'application/pdf', :disposition => 'inline)
-    #  end
+    # Executes a block and then restores the original y position
+    #
+    #   pdf.text "A"
+    #
+    #   pdf.float do
+    #     pdf.move_down 100
+    #     pdf.text "C"
+    #   end
+    #
+    #   pdf.text "B" 
+    #   
+    def float 
+      mask(:y) { yield }
+    end
+
+    # Renders the PDF document to string
     #
     def render
       output = StringIO.new
@@ -426,7 +484,7 @@ module Prawn
     # Raised if group() is called with a block that is too big to be
     # rendered in the current context.
     #
-    CannotGroup = Class.new(StandardError)
+    CannotGroup = Class.new(StandardError) #FIXME: should be in prawn/errors.rb
 
     # Attempts to group the given block vertically within the current context.
     # First attempts to render it in the current position on the current page.
@@ -470,9 +528,10 @@ module Prawn
     #     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)
+        go_to_page(i+1)
         str = string.gsub("<page>","#{i+1}").gsub("<total>","#{page_count}")
         text str, :at => position
       end
@@ -488,7 +547,7 @@ module Prawn
     private
 
     # See Prawn::Document::Internals for low-level PDF functions
-
+    #
     def build_new_page_content
       generate_margin_box
       @page_content = ref(:Length => 0)