prawn 0.12.0 → 0.13.0

data/lib/prawn/repeater.rb

@@ -29,10 +29,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 +49,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 +62,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 +108,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.rb

@@ -7,30 +7,31 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require 'digest/md5'
-require 'prawn/security/arcfour'
-require 'prawn/core/byte_string'
+require 'rc4'
+
+require_relative '../pdf/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
+
       # 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 +53,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 +67,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 +78,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 +105,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.
@@ -116,7 +117,7 @@ module Prawn
 
         # Compute the RC4 key from the extended key and perform the encryption
         rc4_key = Digest::MD5.digest(extended_key)[0, 10]
-        Arcfour.new(rc4_key).encrypt(str)
+        RC4.new(rc4_key).encrypt(str)
       end
 
       private
@@ -136,7 +137,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 +163,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]
@@ -186,20 +187,22 @@ module Prawn
       def owner_password_hash
         @owner_password_hash ||= begin
           key = Digest::MD5.digest(pad_password(@owner_password))[0, 5]
-          Arcfour.new(key).encrypt(pad_password(@user_password))
+          RC4.new(key).encrypt(pad_password(@user_password))
         end
       end
 
       # The U (user) value in the encryption dictionary. Algorithm 3.4.
       def user_password_hash
-        Arcfour.new(user_encryption_key).encrypt(PasswordPadding)
+        RC4.new(user_encryption_key).encrypt(PasswordPadding)
       end
 
     end
 
   end
+end
 
-  module Core #:nodoc:
+module PDF #:nodoc:
+  module Core
     module_function
 
     # Like PdfObject, but returns an encrypted result if required.
@@ -212,24 +215,22 @@ module Prawn
             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 +240,42 @@ 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
 
+
+    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
+
     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
-

data/lib/prawn/soft_mask.rb

@@ -0,0 +1,94 @@
+# encoding: utf-8
+#
+# soft_mask.rb : Implements soft-masking
+#
+# Copyright September 2012, Alexander Mankuta. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+
+module Prawn
+
+  # The Prawn::SoftMask module is used to create arbitrary transparency in
+  # document. Using a soft mask allows creaing more visually rich documents.
+  #
+  # You must group soft mask and graphics it's applied to under
+  # save_graphics_state because soft mask is a part of graphic state in PDF.
+  #
+  # Example:
+  #   pdf.save_graphics_state do
+  #     pdf.soft_mask do
+  #       pdf.fill_color "444444"
+  #       pdf.fill_polygon [0, 40], [60, 10], [120, 40], [60, 68]
+  #     end
+  #     pdf.fill_color '000000'
+  #     pdf.fill_rectangle [0, 50], 120, 68
+  #   end
+  #
+  module SoftMask
+    def soft_mask(&block)
+      min_version(1.4)
+
+      group_attrs = ref!({
+        :Type => :Group,
+        :S => :Transparency,
+        :CS => :DeviceRGB,
+        :I => false,
+        :K => false
+      })
+
+      group = ref!({
+        :Type => :XObject,
+        :Subtype => :Form,
+        :BBox => state.page.dimensions,
+        :Group => group_attrs,
+      })
+
+      state.page.stamp_stream(group, &block)
+
+      mask = ref!({
+        :Type => :Mask,
+        :S => :Luminosity,
+        :G => group
+      })
+
+      g_state = ref!({
+        :Type => :ExtGState,
+        :SMask => mask,
+
+        :AIS => false,
+        :BM => :Normal,
+        :OP => false,
+        :op => false,
+        :OPM => 1,
+        :SA => true,
+      })
+
+      registry_key = {
+        :bbox => state.page.dimensions,
+        :mask => [group.stream.filters.normalized, group.stream.filtered_stream],
+        :page => state.page_count,
+      }.hash
+
+      if soft_mask_registry[registry_key]
+        [g_state, mask, group, group_attrs].each { |ref| ref.live = false }
+
+        add_content "/#{soft_mask_registry[registry_key]} gs"
+      else
+        masks = page.resources[:ExtGState] ||= {}
+        id = masks.empty? ? 'GS1' : masks.keys.sort.last.succ
+        masks[id] = g_state
+
+        soft_mask_registry[registry_key] = id
+
+        add_content "/#{id} gs"
+      end
+    end
+
+    private
+
+    def soft_mask_registry
+      @soft_mask_registry ||= {}
+    end
+  end
+end

data/lib/prawn/stamp.rb

@@ -80,7 +80,7 @@ module Prawn
 
       state.page.stamp_stream(dictionary, &block)
     end
-    
+
     private
 
     def stamp_dictionary_registry
@@ -121,12 +121,12 @@ module Prawn
                                           :stamp_dictionary      => dictionary }
       dictionary
     end
-    
+
     def freeze_stamp_graphics
       update_colors
       write_line_width
       write_stroke_cap_style
-      write_stroke_join_style     
+      write_stroke_join_style
       write_stroke_dash
     end
 

data/lib/prawn/table.rb

@@ -11,11 +11,13 @@ require 'prawn/table/cell'
 require 'prawn/table/cell/in_table'
 require 'prawn/table/cell/text'
 require 'prawn/table/cell/subtable'
+require 'prawn/table/cell/image'
+require 'prawn/table/cell/span_dummy'
 
 module Prawn
 
   class Document
-    
+
     # Set up and draw a table on this document. A block can be given, which will
     # be run after cell setup but before layout and drawing.
     #
@@ -49,7 +51,7 @@ module Prawn
   #   Produces a text cell. This is the most common usage.
   # Prawn::Table::Cell::
   #   If you have already built a Cell or have a custom subclass of Cell you
-  #   want to use in a table, you can pass through Cell objects. 
+  #   want to use in a table, you can pass through Cell objects.
   # Prawn::Table::
   #   Creates a subtable (a table within a cell). You can use
   #   Prawn::Document#make_table to create a table for use as a subtable
@@ -71,17 +73,21 @@ module Prawn
   #   A hash of style options to style all cells. See the documentation on
   #   Prawn::Table::Cell for all cell style options.
   # +header+::
-  #   If set to +true+, the first row will be repeated on every page. The
-  #   header must be included as the first row of your data. Row numbering
-  #   (for styling and other row-specific options) always indexes based on
-  #   your data array. Whether or not you have a header, row(n) always refers
-  #   to the nth element (starting from 0) of the +data+ array.
-  # +column_widths+:: 
+  #   If set to +true+, the first row will be repeated on every page. If set
+  #   to an Integer, the first +x+ rows will be repeated on every page. Row
+  #   numbering (for styling and other row-specific options) always indexes
+  #   based on your data array. Whether or not you have a header, row(n) always
+  #   refers to the nth element (starting from 0) of the +data+ array.
+  # +column_widths+::
   #   Sets widths for individual columns. Manually setting widths can give
   #   better results than letting Prawn guess at them, as Prawn's algorithm
   #   for defaulting widths is currently pretty boneheaded. If you experience
   #   problems like weird column widths or CannotFit errors, try manually
   #   setting widths on more columns.
+  # +position+::
+  #   Either :left (the default), :center, :right, or a number. Specifies the
+  #   horizontal position of the table within its bounding box. If a number is
+  #   provided, it specifies the distance in points from the left edge.
   #
   # = Initializer Block
   #
@@ -95,7 +101,7 @@ module Prawn
   #   pdf.table(data) do |table|
   #     table.rows(1..3).width = 72
   #   end
-  # 
+  #
   # As with Prawn::Document#initialize, if the block has no arguments, it will
   # be evaluated in the context of the object itself. The above code could be
   # rewritten as:
@@ -104,7 +110,7 @@ module Prawn
   #     rows(1..3).width = 72
   #   end
   #
-  class Table  
+  class Table
 
     # Set up a table on the given document. Arguments:
     #
@@ -131,7 +137,7 @@ module Prawn
       set_column_widths
       set_row_heights
       position_cells
-    end                                        
+    end
 
     # Number of rows in the table.
     #
@@ -145,6 +151,25 @@ module Prawn
     #
     attr_writer :width
 
+    # Position (:left, :right, :center, or a number indicating distance in
+    # points from the left edge) of the table within its parent bounds.
+    #
+    attr_writer :position
+
+    # Returns a Prawn::Table::Cells object representing all of the cells in
+    # this table.
+    #
+    attr_reader :cells
+
+    # Specify a callback to be called before each page of cells is rendered.
+    # The block is passed a Cells object containing all cells to be rendered on
+    # that page. You can change styling of the cells in this block, but keep in
+    # mind that the cells have already been positioned and sized.
+    #
+    def before_rendering_page(&block)
+      @before_rendering_page = block
+    end
+
     # Returns the width of the table in PDF points.
     #
     def width
@@ -154,9 +179,9 @@ module Prawn
     # Sets column widths for the table. The argument can be one of the following
     # types:
     #
-    # +Array+:: 
+    # +Array+::
     #   <tt>[w0, w1, w2, ...]</tt> (specify a width for each column)
-    # +Hash+:: 
+    # +Hash+::
     #   <tt>{0 => w0, 1 => w1, ...}</tt> (keys are column names, values are
     #   widths)
     # +Numeric+::
@@ -182,8 +207,9 @@ module Prawn
     end
 
     # If +true+, designates the first row as a header row to be repeated on
-    # every page. Does not change row numbering -- row numbers always index into
-    # the data array provided, with no modification.
+    # every page. If an integer, designates the number of rows to be treated
+    # as a header Does not change row numbering -- row numbers always index
+    # into the data array provided, with no modification.
     #
     attr_writer :header
 
@@ -221,86 +247,139 @@ module Prawn
     # Draws the table onto the document at the document's current y-position.
     #
     def draw
-      # The cell y-positions are based on an infinitely long canvas. The offset
-      # keeps track of how much we have to add to the original, theoretical
-      # y-position to get to the actual position on the current page.
-      offset = @pdf.y
-
-      # Reference bounds are the non-stretchy bounds used to decide when to
-      # flow to a new column / page.
-      ref_bounds = @pdf.reference_bounds
-
-      last_y = @pdf.y
-
-      # Determine whether we're at the top of the current bounds (margin box or
-      # bounding box). If we're at the top, we couldn't gain any more room by
-      # breaking to the next page -- this means, in particular, that if the
-      # first row is taller than the margin box, we will only move to the next
-      # page if we're below the top. Some floating-point tolerance is added to
-      # the calculation.
-      #
-      # Note that we use the actual bounds, not the reference bounds. This is
-      # because even if we are in a stretchy bounding box, flowing to the next
-      # page will not buy us any space if we are at the top.
-      if @pdf.y > @pdf.bounds.height + @pdf.bounds.absolute_bottom - 0.001
-        # we're at the top of our bounds
-        started_new_page_at_row = 0
-      else
-        started_new_page_at_row = -1
-
-        # If there isn't enough room left on the page to fit the first data row
-        # (excluding the header), start the table on the next page.
-        needed_height = row(0).height
-        needed_height += row(1).height if @header
-        if needed_height > @pdf.y - ref_bounds.absolute_bottom
-          @pdf.bounds.move_past_bottom
-          offset = @pdf.y
+      with_position do
+        # The cell y-positions are based on an infinitely long canvas. The offset
+        # keeps track of how much we have to add to the original, theoretical
+        # y-position to get to the actual position on the current page.
+        offset = @pdf.y
+
+        # Reference bounds are the non-stretchy bounds used to decide when to
+        # flow to a new column / page.
+        ref_bounds = @pdf.reference_bounds
+
+        last_y = @pdf.y
+
+        # Determine whether we're at the top of the current bounds (margin box or
+        # bounding box). If we're at the top, we couldn't gain any more room by
+        # breaking to the next page -- this means, in particular, that if the
+        # first row is taller than the margin box, we will only move to the next
+        # page if we're below the top. Some floating-point tolerance is added to
+        # the calculation.
+        #
+        # Note that we use the actual bounds, not the reference bounds. This is
+        # because even if we are in a stretchy bounding box, flowing to the next
+        # page will not buy us any space if we are at the top.
+        if @pdf.y > @pdf.bounds.height + @pdf.bounds.absolute_bottom - 0.001
+          # we're at the top of our bounds
           started_new_page_at_row = 0
+        else
+          started_new_page_at_row = -1
+
+          # If there isn't enough room left on the page to fit the first data row
+          # (excluding the header), start the table on the next page.
+          needed_height = row(0).height
+          if @header
+            if @header.is_a? Integer
+              needed_height += row(1..@header).height
+            else
+              needed_height += row(1).height
+            end
+          end
+          if needed_height > @pdf.y - ref_bounds.absolute_bottom
+            @pdf.bounds.move_past_bottom
+            offset = @pdf.y
+            started_new_page_at_row = 0
+          end
         end
-      end
 
-      # Track cells to be drawn on this page. They will all be drawn when this
-      # page is finished.
-      cells_this_page = []
-
-      @cells.each do |cell|
-        if cell.height > (cell.y + offset) - ref_bounds.absolute_bottom &&
-           cell.row > started_new_page_at_row
-          # Ink all cells on the current page
-          Cell.draw_cells(cells_this_page)
-          cells_this_page = []
-
-          # start a new page or column
-          @pdf.bounds.move_past_bottom
-          draw_header unless cell.row == 0
-          offset = @pdf.y - cell.y
-          started_new_page_at_row = cell.row
+        # Duplicate each cell of the header row into @header_row so it can be
+        # modified in before_rendering_page callbacks.
+        if @header
+          @header_row = Cells.new
+          if @header.is_a? Integer
+            @header.times do |r|
+              row(r).each { |cell| @header_row[cell.row, cell.column] = cell.dup }
+            end
+          else
+            row(0).each { |cell| @header_row[cell.row, cell.column] = cell.dup }
+          end
         end
- 
-        # Don't modify cell.x / cell.y here, as we want to reuse the original
-        # values when re-inking the table. #draw should be able to be called
-        # multiple times.
-        x, y = cell.x, cell.y
-        y += offset 
-
-        # Translate coordinates to the bounds we are in, since drawing is 
-        # relative to the cursor, not ref_bounds.
-        x += @pdf.bounds.left_side - @pdf.bounds.absolute_left
-        y -= @pdf.bounds.absolute_bottom
-
-        # Set background color, if any.
-        if @row_colors && (!@header || cell.row > 0)
-          index = @header ? (cell.row - 1) : cell.row
-          cell.background_color = @row_colors[index % @row_colors.length]
+
+        # Track cells to be drawn on this page. They will all be drawn when this
+        # page is finished.
+        cells_this_page = []
+
+        @cells.each do |cell|
+          if cell.height > (cell.y + offset) - ref_bounds.absolute_bottom &&
+             cell.row > started_new_page_at_row
+            # Ink all cells on the current page
+            if defined?(@before_rendering_page) && @before_rendering_page
+              c = Cells.new(cells_this_page.map { |ci, _| ci })
+              @before_rendering_page.call(c)
+            end
+            Cell.draw_cells(cells_this_page)
+            cells_this_page = []
+
+            # start a new page or column
+            @pdf.bounds.move_past_bottom
+            x_offset = @pdf.bounds.left_side - @pdf.bounds.absolute_left
+            if cell.row > 0 && @header
+              if @header.is_a? Integer
+                header_height = 0
+                y_coord = @pdf.cursor
+                @header.times do |h|
+                  additional_header_height = add_header(cells_this_page, x_offset, y_coord-header_height, cell.row-1, h)
+                  header_height += additional_header_height
+                end
+              else
+                header_height = add_header(cells_this_page, x_offset, @pdf.cursor, cell.row-1)
+              end
+            else
+              header_height = 0
+            end
+            offset = @pdf.y - cell.y - header_height
+            started_new_page_at_row = cell.row
+          end
+
+          # Don't modify cell.x / cell.y here, as we want to reuse the original
+          # values when re-inking the table. #draw should be able to be called
+          # multiple times.
+          x, y = cell.x, cell.y
+          y += offset
+
+          # Translate coordinates to the bounds we are in, since drawing is
+          # relative to the cursor, not ref_bounds.
+          x += @pdf.bounds.left_side - @pdf.bounds.absolute_left
+          y -= @pdf.bounds.absolute_bottom
+
+          # Set background color, if any.
+          if defined?(@row_colors) && @row_colors && (!@header || cell.row > 0)
+            # Ensure coloring restarts on every page (to make sure the header
+            # and first row of a page are not colored the same way).
+            if @header.is_a? Integer
+              rows = @header
+            elsif @header
+              rows = 1
+            else
+              rows = 0
+            end
+            index = cell.row - [started_new_page_at_row, rows].max
+
+            cell.background_color ||= @row_colors[index % @row_colors.length]
+          end
+
+          cells_this_page << [cell, [x, y]]
+          last_y = y
+        end
+        # Draw the last page of cells
+        if defined?(@before_rendering_page) && @before_rendering_page
+          c = Cells.new(cells_this_page.map { |ci, _| ci })
+          @before_rendering_page.call(c)
         end
+        Cell.draw_cells(cells_this_page)
 
-        cells_this_page << [cell, [x, y]]
-        last_y = y
+        @pdf.move_cursor_to(last_y - @cells.last.height)
       end
-      # Draw the last page of cells
-      Cell.draw_cells(cells_this_page)
-
-      @pdf.move_cursor_to(last_y - @cells.last.height)
     end
 
     # Calculate and return the constrained column widths, taking into account
@@ -331,7 +410,7 @@ module Prawn
           f = (width - cells.min_width).to_f / (natural_width - cells.min_width)
 
           (0...column_length).map do |c|
-            min, nat = column(c).min_width, column(c).width
+            min, nat = column(c).min_width, natural_column_widths[c]
             (f * (nat - min)) + min
           end
         elsif width - natural_width > epsilon
@@ -339,7 +418,7 @@ module Prawn
           f = (width - cells.width).to_f / (cells.max_width - cells.width)
 
           (0...column_length).map do |c|
-            nat, max = column(c).width, column(c).max_width
+            nat, max = natural_column_widths[c], column(c).max_width
             (f * (max - nat)) + nat
           end
         else
@@ -351,7 +430,21 @@ module Prawn
     # Returns an array with the height of each row.
     #
     def row_heights
-      @natural_row_heights ||= (0...row_length).map{ |r| row(r).height }
+      @natural_row_heights ||=
+        begin
+          heights_by_row = Hash.new(0)
+          cells.each do |cell|
+            next if cell.is_a?(Cell::SpanDummy)
+
+            # Split the height of row-spanned cells evenly by rows
+            height_per_row = cell.height.to_f / cell.rowspan
+            cell.rowspan.times do |i|
+              heights_by_row[cell.row + i] =
+                [heights_by_row[cell.row + i], height_per_row].max
+            end
+          end
+          heights_by_row.sort_by { |row, _| row }.map { |_, h| h }
+        end
     end
 
     protected
@@ -363,23 +456,80 @@ module Prawn
     def make_cells(data)
       assert_proper_table_data(data)
 
-      cells = []
-      
-      @row_length = data.length
-      @column_length = data.map{ |r| r.length }.max
+      cells = Cells.new
+
+      row_number = 0
+      data.each do |row_cells|
+        column_number = 0
+        row_cells.each do |cell_data|
+          # If we landed on a spanned cell (from a rowspan above), continue
+          # until we find an empty spot.
+          column_number += 1 until cells[row_number, column_number].nil?
 
-      data.each_with_index do |row_cells, row_number|
-        row_cells.each_with_index do |cell_data, column_number|
+          # Build the cell and store it in the Cells collection.
           cell = Cell.make(@pdf, cell_data)
-          cell.extend(Cell::InTable)
-          cell.row = row_number
-          cell.column = column_number
-          cells << cell
+          cells[row_number, column_number] = cell
+
+          # Add dummy cells for the rest of the cells in the span group. This
+          # allows Prawn to keep track of the horizontal and vertical space
+          # occupied in each column and row spanned by this cell, while still
+          # leaving the master (top left) cell in the group responsible for
+          # drawing. Dummy cells do not put ink on the page.
+          cell.rowspan.times do |i|
+            cell.colspan.times do |j|
+              next if i == 0 && j == 0
+
+              # It is an error to specify spans that overlap; catch this here
+              if cells[row_number + i, column_number + j]
+                raise Prawn::Errors::InvalidTableSpan,
+                  "Spans overlap at row #{row_number + i}, " +
+                  "column #{column_number + j}."
+              end
+
+              dummy = Cell::SpanDummy.new(@pdf, cell)
+              cells[row_number + i, column_number + j] = dummy
+              cell.dummy_cells << dummy
+            end
+          end
+
+          column_number += cell.colspan
         end
+
+        row_number += 1
       end
+
+      # Calculate the number of rows and columns in the table, taking into
+      # account that some cells may span past the end of the physical cells we
+      # have.
+      @row_length = cells.map do |cell|
+        cell.row + cell.rowspan
+      end.max
+
+      @column_length = cells.map do |cell|
+        cell.column + cell.colspan
+      end.max
+
       cells
     end
 
+    # Add the header row(s) to the given array of cells at the given y-position.
+    # Number the row with the given +row+ index, so that the header appears (in
+    # any Cells built for this page) immediately prior to the first data row on
+    # this page.
+    #
+    # Return the height of the header.
+    #
+    def add_header(page_of_cells, x_offset, y, row, row_of_header=nil)
+      rows_to_operate_on = @header_row
+      rows_to_operate_on = @header_row.rows(row_of_header) if row_of_header
+      rows_to_operate_on.each do |cell|
+        cell.row = row
+        cell.dummy_cells.each {|c| c.row = row }
+        page_of_cells << [cell, [cell.x + x_offset, y]]
+      end
+      rows_to_operate_on.height
+    end
+
     # Raises an error if the data provided cannot be converted into a valid
     # table.
     #
@@ -396,23 +546,24 @@ module Prawn
       end
     end
 
-    # If the table has a header, draw it at the current position.
-    #
-    def draw_header
-      if @header
-        y = @pdf.cursor
-        row(0).each do |cell|
-          cell.y = y
-          cell.draw
-        end
-        @pdf.move_cursor_to(y - row(0).height)
-      end
-    end
-
     # Returns an array of each column's natural (unconstrained) width.
     #
     def natural_column_widths
-      @natural_column_widths ||= (0...column_length).map { |c| column(c).width }
+      @natural_column_widths ||=
+        begin
+          widths_by_column = Hash.new(0)
+          cells.each do |cell|
+            next if cell.is_a?(Cell::SpanDummy)
+
+            # Split the width of colspanned cells evenly by columns
+            width_per_column = cell.width.to_f / cell.colspan
+            cell.colspan.times do |i|
+              widths_by_column[cell.column + i] =
+                [widths_by_column[cell.column + i], width_per_column].max
+            end
+          end
+          widths_by_column.sort_by { |col, _| col }.map { |_, w| w }
+        end
     end
 
     # Returns the "natural" (unconstrained) width of the table. This may be
@@ -421,7 +572,7 @@ module Prawn
     # a mile long.
     #
     def natural_width
-      @natural_width ||= natural_column_widths.inject(0) { |sum, w| sum + w }
+      @natural_width ||= natural_column_widths.inject(0, &:+)
     end
 
     # Assigns the calculated column widths to each cell. This ensures that each
@@ -430,7 +581,7 @@ module Prawn
     # values that will be used to ink the table.
     #
     def set_column_widths
-      column_widths.each_with_index do |w, col_num| 
+      column_widths.each_with_index do |w, col_num|
         column(col_num).width = w
       end
     end
@@ -447,7 +598,7 @@ module Prawn
     #
     def position_cells
       # Calculate x- and y-positions as running sums of widths / heights.
-      x_positions = column_widths.inject([0]) { |ary, x| 
+      x_positions = column_widths.inject([0]) { |ary, x|
         ary << (ary.last + x); ary }[0..-2]
       x_positions.each_with_index { |x, i| column(i).x = x }
 
@@ -458,6 +609,29 @@ module Prawn
       y_positions.each_with_index { |y, i| row(i).y = y }
     end
 
+    # Sets up a bounding box to position the table according to the specified
+    # :position option, and yields.
+    #
+    def with_position
+      x = case defined?(@position) && @position || :left
+          when :left   then return yield
+          when :center then (@pdf.bounds.width - width) / 2.0
+          when :right  then  @pdf.bounds.width - width
+          when Numeric then  @position
+          else raise ArgumentError, "unknown position #{@position.inspect}"
+          end
+      dy = @pdf.bounds.absolute_top - @pdf.y
+      final_y = nil
+
+      @pdf.bounding_box([x, @pdf.bounds.top], :width => width) do
+        @pdf.move_down dy
+        yield
+        final_y = @pdf.y
+      end
+
+      @pdf.y = final_y
+    end
+
     private
 
     def epsilon