prawn 0.8.4 → 0.11.1.pre

data/lib/prawn/security.rb

@@ -0,0 +1,262 @@
+# encoding: utf-8
+#
+# encryption.rb : Implements encrypted PDF and access permissions.
+#
+# Copyright August 2008, Brad Ediger. All Rights Reserved.
+#
+# 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'
+
+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
+      
+      # 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 
+      #                           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 
+      #                            the document or change or override its
+      #                            permissions. If this is set to
+      #                            <tt>:random</tt>, a random password will be
+      #                            used; this can be useful if you never want
+      #                            users to be able to override the document
+      #                            permissions.
+      #
+      # <tt>:permissions</tt>:: A hash mapping permission symbols (see below) to
+      #                         <tt>true</tt> or <tt>false</tt>. True means
+      #                         "permitted", and false means "not permitted".
+      #                         All permissions default to <tt>true</tt>.
+      #
+      # The following permissions can be specified:
+      #
+      # <tt>:print_document</tt>:: Print document.
+      #
+      # <tt>:modify_document</tt>:: Modify contents of document (other than text
+      #                             annotations and interactive form fields).
+      #
+      # <tt>:copy_contents</tt>:: Copy text and graphics from document.
+      #
+      # <tt>:modify_annotations</tt>:: Add or modify text annotations and 
+      #                                interactive form fields.
+      #
+      # == Examples
+      #
+      # Deny printing to everyone, but allow anyone to open without a password:
+      #
+      #   encrypt_document :permissions => { :print_document => false },
+      #                    :owner_password => :random
+      #
+      # Set a user and owner password on the document, with full permissions for
+      # 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 
+      # default in some readers, if no permissions are specified, is "deny"):
+      #
+      #   encrypt_document
+      #
+      # == Caveats
+      #
+      # * 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
+      #   PDF format.
+      #
+      def encrypt_document(options={})
+        Prawn.verify_options [:user_password, :owner_password, :permissions],
+          options
+        @user_password = options.delete(:user_password) || ""
+
+        @owner_password = options.delete(:owner_password) || @user_password
+        if @owner_password == :random
+          # Generate a completely ridiculous password
+          @owner_password = (1..32).map{ rand(256) }.pack("c*")
+        end
+
+        self.permissions = options.delete(:permissions) || {}
+
+        # Shove the necessary entries in the trailer and enable encryption.
+        state.trailer[:Encrypt] = encryption_dictionary
+        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.
+      def self.encrypt_string(str, key, id, gen)
+        # Convert ID and Gen number into little-endian truncated byte strings
+        id = [id].pack('V')[0,3]
+        gen = [gen].pack('V')[0,2]
+        extended_key = "#{key}#{id}#{gen}"
+
+        # 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)
+      end
+
+      private
+
+      # Provides the values for the trailer encryption dictionary.
+      def encryption_dictionary
+        { :Filter => :Standard, # default PDF security handler
+          :V      => 1,         # "Algorithm 3.1", PDF reference 1.3
+          :R      => 2,         # Revision 2 of the algorithm
+          :O      => ByteString.new(owner_password_hash),
+          :U      => ByteString.new(user_password_hash),
+          :P      => permissions_value }
+      end
+
+      # Flags in the permissions word, numbered as LSB = 1
+      PermissionsBits = { :print_document     => 3,
+                          :modify_contents    => 4,
+                          :copy_contents      => 5,
+                          :modify_annotations => 6 }
+      
+      FullPermissions = 0b1111_1111_1111_1111_1111_1111_1111_1111
+
+      def permissions=(perms={})
+        @permissions ||= FullPermissions
+        perms.each do |key, value|
+          # 0-based bit number, from LSB
+          bit_position = PermissionsBits[key] - 1
+
+          if value # set bit
+            @permissions |= (1 << bit_position)
+          else # clear bit
+            @permissions &= ~(1 << bit_position)
+          end
+        end
+      end
+
+      def permissions_value
+        @permissions || FullPermissions
+      end
+
+      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]
+        password + PasswordPadding[0, 32 - password.length]
+      end
+
+      def user_encryption_key
+        @user_encryption_key ||= begin
+          md5 = Digest::MD5.new
+          md5 << pad_password(@user_password)
+          md5 << owner_password_hash
+          md5 << [permissions_value].pack("V")
+          md5.digest[0, 5]
+        end
+      end
+
+      # The O (owner) value in the encryption dictionary. Algorithm 3.3.
+      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))
+        end
+      end
+
+      # The U (user) value in the encryption dictionary. Algorithm 3.4.
+      def user_password_hash
+        Arcfour.new(user_encryption_key).encrypt(PasswordPadding)
+      end
+
+    end
+
+  end
+
+  module Core #:nodoc:
+    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)
+      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})"
+      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})"
+      when String
+        PdfObject(
+          ByteString.new(
+            Document::Security.encrypt_string(obj, key, id, gen)),
+          in_content_stream)
+      when Hash
+        output = "<< "
+        obj.each do |k,v|
+          unless String === k || Symbol === k
+            raise Prawn::Errors::FailedObjectConversion,
+              "A PDF Dictionary must be keyed by names"
+          end
+          output << PdfObject(k.to_sym, in_content_stream) << " " <<
+                    EncryptedPdfObject(v, key, id, gen, in_content_stream) << "\n"
+        end
+        output << ">>"
+      when NameTree::Value
+        PdfObject(obj.name) + " " +
+          EncryptedPdfObject(obj.value, key, id, gen, in_content_stream)
+      else # delegate back to PdfObject
+        PdfObject(obj, in_content_stream)
+      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"
+        end
+        output << "endobj\n"
+      end
+
+    end
+  end
+
+end
+

data/lib/prawn/security/arcfour.rb

@@ -0,0 +1,51 @@
+# Implementation of the "ARCFOUR" algorithm ("alleged RC4 (tm)"). Implemented
+# as described at:
+# http://www.mozilla.org/projects/security/pki/nss/draft-kaukonen-cipher-arcfour-03.txt
+#
+# "RC4" is a trademark of RSA Data Security, Inc.
+#
+# Copyright August 2009, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+class Arcfour
+  def initialize(key)
+    # Convert string key to Array of integers
+    key = key.unpack('c*') if key.is_a?(String)
+
+    # 1. Allocate an 256 element array of 8 bit bytes to be used as an S-box
+    # 2. Initialize the S-box.  Fill each entry first with it's index
+    @sbox = (0..255).to_a
+    
+    # 3. Fill another array of the same size (256) with the key, repeating
+    #    bytes as necessary.
+    s2 = []
+    while s2.length < 256
+      s2 += key
+    end
+    s2 = s2[0, 256]
+
+    # 4. Set j to zero and initialize the S-box
+    j = 0
+    (0..255).each do |i|
+      j = (j + @sbox[i] + s2[i]) % 256
+      @sbox[i], @sbox[j] = @sbox[j], @sbox[i]
+    end
+
+    @i = @j = 0
+  end
+
+  def encrypt(string)
+    string.unpack('c*').map{|byte| byte ^ key_byte}.pack('c*')
+  end
+  
+  private
+
+  # Produces the next byte of key material in the stream (3.2 Stream Generation)
+  def key_byte
+    @i = (@i + 1) % 256
+    @j = (@j + @sbox[@i]) % 256
+    @sbox[@i], @sbox[@j] = @sbox[@j], @sbox[@i]
+    @sbox[(@sbox[@i] + @sbox[@j]) % 256]
+  end
+end

data/lib/prawn/stamp.rb

@@ -0,0 +1,126 @@
+# encoding: utf-8
+#
+# stamp.rb : Implements a repeatable stamp
+#
+# Copyright October 2009, Daniel Nelson. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+
+module Prawn
+
+  # The Prawn::Stamp module is used to create content that will be
+  # included multiple times in a document. Using a stamp has three
+  # advantages over creating content anew each time it is placed on
+  # the page:
+  #   i.   faster document creation
+  #   ii.  smaller final document
+  #   iii. faster display on subsequent displays of the repeated
+  #   element because the viewer application can cache the rendered
+  #   results
+  #
+  # Example:
+  #   pdf.create_stamp("my_stamp") {
+  #     pdf.fill_circle_at([10, 15], :radius => 5)
+  #     pdf.draw_text("hello world", :at => [20, 10])
+  #   }
+  #   pdf.stamp("my_stamp")
+  #
+  module Stamp
+
+    # Renders the stamp named <tt>name</tt> to the page
+    # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
+    # raises <tt>Prawn::Errors::UndefinedObjectName</tt> if no stamp
+    # has been created with this name
+    #
+    # Example:
+    #   pdf.create_stamp("my_stamp") {
+    #     pdf.fill_circle_at([10, 15], :radius => 5)
+    #     pdf.text("hello world", :at => [20, 10])
+    #   }
+    #   pdf.stamp("my_stamp")
+    #
+    def stamp(name)
+      dictionary_name, dictionary = stamp_dictionary(name)
+      add_content "/#{dictionary_name} Do"
+      state.page.xobjects.merge!(dictionary_name => dictionary)
+    end
+
+    # Renders the stamp named <tt>name</tt> at a position offset from
+    # the initial coords at which the elements of the stamp was
+    # created
+    #
+    # Example:
+    #   pdf.create_stamp("circle") do
+    #     pdf.fill_circle_at([0, 0], :radius => 25)
+    #   end
+    #   # draws a circle at 100, 100
+    #   pdf.stamp_at("circle", [100, 100])
+    #
+    # See stamp() for exceptions that might be raised
+    #
+    def stamp_at(name, point)
+      translate(point[0], point[1]) { stamp(name) }
+    end
+
+    # Creates a re-usable stamp named <tt>name</tt>
+    #
+    # raises <tt>Prawn::Errors::NameTaken</tt> if a stamp already
+    # exists in this document with this name
+    # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
+    #
+    # Example:
+    #   pdf.create_stamp("my_stamp") {
+    #     pdf.fill_circle_at([10, 15], :radius => 5)
+    #     pdf.draw_text("hello world", :at => [20, 10])
+    #   }
+    #
+    def create_stamp(name, &block)
+      dictionary = create_stamp_dictionary(name)
+
+      state.page.stamp_stream(dictionary, &block)
+    end
+    
+    private
+
+    def stamp_dictionary_registry
+      @stamp_dictionary_registry ||= {}
+    end
+
+    def next_stamp_dictionary_id
+      stamp_dictionary_registry.length + 1
+    end
+
+    def stamp_dictionary(name)
+      raise Prawn::Errors::InvalidName if name.empty?
+      if stamp_dictionary_registry[name].nil?
+        raise Prawn::Errors::UndefinedObjectName
+      end
+
+      dict = stamp_dictionary_registry[name]
+
+      dictionary_name = dict[:stamp_dictionary_name]
+      dictionary = dict[:stamp_dictionary]
+      [dictionary_name, dictionary]
+    end
+
+    def create_stamp_dictionary(name)
+      raise Prawn::Errors::InvalidName if name.empty?
+      raise Prawn::Errors::NameTaken unless stamp_dictionary_registry[name].nil?
+      # BBox origin is the lower left margin of the page, so we need
+      # it to be the full dimension of the page, or else things that
+      # should appear near the top or right margin are invisible
+      dictionary = ref!(:Type    => :XObject,
+                        :Subtype => :Form,
+                        :BBox    => [0, 0,
+                                     state.page.dimensions[2], state.page.dimensions[3]])
+
+      dictionary_name = "Stamp#{next_stamp_dictionary_id}"
+
+      stamp_dictionary_registry[name] = { :stamp_dictionary_name => dictionary_name,
+                                          :stamp_dictionary      => dictionary }
+      dictionary
+    end
+
+  end
+end

data/lib/prawn/table.rb

@@ -0,0 +1,421 @@
+# encoding: utf-8
+#
+# table.rb: Table drawing functionality.
+#
+# Copyright December 2009, Brad Ediger. All rights reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require 'prawn/table/cells'
+require 'prawn/table/cell'
+require 'prawn/table/cell/in_table'
+require 'prawn/table/cell/text'
+require 'prawn/table/cell/subtable'
+
+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.
+    #
+    # See the documentation on Prawn::Table for details on the arguments.
+    #
+    def table(data, options={}, &block)
+      t = Table.new(data, self, options, &block)
+      t.draw
+      t
+    end
+
+    # Set up, but do not draw, a table. Useful for creating subtables to be
+    # inserted into another Table. Call +draw+ on the resulting Table to ink it.
+    #
+    # See the documentation on Prawn::Table for details on the arguments.
+    #
+    def make_table(data, options={}, &block)
+      Table.new(data, self, options, &block)
+    end
+
+  end
+
+  # Next-generation table drawing for Prawn.
+  #
+  # = Data
+  #
+  # Data, for a Prawn table, is a two-dimensional array of objects that can be
+  # converted to cells ("cellable" objects). Cellable objects can be:
+  #
+  # String::
+  #   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. 
+  # 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
+  #   without immediately drawing it. See examples/table/bill.rb for a
+  #   somewhat complex use of subtables.
+  # Array::
+  #   Creates a simple subtable. Create a Table object using make_table (see
+  #   above) if you need more control over the subtable's styling.
+  #
+  # = Options
+  #
+  # Prawn/Layout provides many options to control style and layout of your
+  # table. These options are implemented with a uniform interface: the +:foo+
+  # option always sets the +foo=+ accessor. See the accessor and method
+  # documentation for full details on the options you can pass. Some
+  # highlights:
+  #
+  # +cell_style+::
+  #   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+:: 
+  #   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.
+  #
+  # = Initializer Block
+  #
+  # If a block is passed to methods that initialize a table
+  # (Prawn::Table.new, Prawn::Document#table, Prawn::Document#make_table), it
+  # will be called after cell setup but before layout. This is a very flexible
+  # way to specify styling and layout constraints. This code sets up a table
+  # where the second through the fourth rows (1-3, indexed from 0) are each one
+  # inch (72 pt) wide:
+  #
+  #   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:
+  #
+  #   pdf.table(data) do
+  #     rows(1..3).width = 72
+  #   end
+  #
+  class Table  
+
+    # Set up a table on the given document. Arguments:
+    #
+    # +data+::
+    #   A two-dimensional array of cell-like objects. See the "Data" section
+    #   above for the types of objects that can be put in a table.
+    # +document+::
+    #   The Prawn::Document instance on which to draw the table.
+    # +options+::
+    #   A hash of attributes and values for the table. See the "Options" block
+    #   above for details on available options.
+    #
+    def initialize(data, document, options={}, &block)
+      @pdf = document
+      @cells = make_cells(data)
+      @header = false
+      options.each { |k, v| send("#{k}=", v) }
+
+      if block
+        block.arity < 1 ? instance_eval(&block) : block[self]
+      end
+
+      set_column_widths
+      set_row_heights
+      position_cells
+    end                                        
+
+    # Number of rows in the table.
+    #
+    attr_reader :row_length
+
+    # Number of columns in the table.
+    #
+    attr_reader :column_length
+
+    # Manually set the width of the table.
+    #
+    attr_writer :width
+
+    # Returns the width of the table in PDF points.
+    #
+    def width
+      @width ||= [natural_width, @pdf.bounds.width].min
+    end
+
+    # Sets column widths for the table. The argument can be one of the following
+    # types:
+    #
+    # +Array+:: 
+    #   <tt>[w0, w1, w2, ...]</tt> (specify a width for each column)
+    # +Hash+:: 
+    #   <tt>{0 => w0, 1 => w1, ...}</tt> (keys are column names, values are
+    #   widths)
+    # +Numeric+::
+    #   +72+ (sets width for all columns)
+    #
+    def column_widths=(widths)
+      case widths
+      when Array
+        widths.each_with_index { |w, i| column(i).width = w }
+      when Hash
+        widths.each { |i, w| column(i).width = w }
+      when Numeric
+        columns.width = widths
+      else
+        raise ArgumentError, "cannot interpret column widths"
+      end
+    end
+
+    # Returns the height of the table in PDF points.
+    #
+    def height
+      cells.height
+    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.
+    #
+    attr_writer :header
+
+    # Accepts an Array of alternating row colors to stripe the table.
+    #
+    attr_writer :row_colors
+
+    # Sets styles for all cells.
+    #
+    #   pdf.table(data, :cell_style => { :borders => [:left, :right] })
+    #
+    def cell_style=(style_hash)
+      cells.style(style_hash)
+    end
+
+    # Allows generic stylable content. This is an alternate syntax that some
+    # prefer to the attribute-based syntax. This code using style:
+    #
+    #   pdf.table(data) do
+    #     style(row(0), :background_color => 'ff00ff')
+    #     style(column(0)) { |c| c.border_width += 1 }
+    #   end
+    #
+    # is equivalent to:
+    #
+    #   pdf.table(data) do
+    #     row(0).style :background_color => 'ff00ff'
+    #     column(0).style { |c| c.border_width += 1 }
+    #   end
+    #
+    def style(stylable, style_hash={}, &block)
+      stylable.style(style_hash, &block)
+    end
+
+    # 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.bounds.stretchy? ? @pdf.margin_box : @pdf.bounds
+
+      last_y = @pdf.y
+      @cells.each do |cell|
+        if cell.height > (cell.y + offset) - ref_bounds.absolute_bottom
+          # start a new page or column
+          @pdf.bounds.move_past_bottom
+          draw_header
+          offset = @pdf.y - cell.y
+        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]
+        end
+
+        cell.draw([x, y])
+        last_y = y
+      end
+
+      @pdf.move_cursor_to(last_y - @cells.last.height)
+    end
+
+    # Calculate and return the constrained column widths, taking into account
+    # each cell's min_width, max_width, and any user-specified constraints on
+    # the table or column size.
+    #
+    # Because the natural widths can be silly, this does not always work so well
+    # at guessing a good size for columns that have vastly different content. If
+    # you see weird problems like CannotFit errors or shockingly bad column
+    # sizes, you should specify more column widths manually.
+    #
+    def column_widths
+      @column_widths ||= begin
+        if width < cells.min_width
+          raise Errors::CannotFit,
+            "Table's width was set too small to contain its contents"
+        end
+
+        if width > cells.max_width
+          raise Errors::CannotFit,
+            "Table's width was set larger than its contents' maximum width"
+        end
+
+        if width < natural_width
+          # Shrink the table to fit the requested width.
+          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
+            (f * (nat - min)) + min
+          end
+        elsif width > natural_width
+          # Expand the table to fit the requested width.
+          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
+            (f * (max - nat)) + nat
+          end
+        else
+          natural_column_widths
+        end
+      end
+    end
+
+    # Returns an array with the height of each row.
+    #
+    def row_heights
+      @natural_row_heights ||= (0...row_length).map{ |r| row(r).height }
+    end
+
+    protected
+
+    # Converts the array of cellable objects given into instances of
+    # Prawn::Table::Cell, and sets up their in-table properties so that they
+    # know their own position in the table.
+    #
+    def make_cells(data)
+      assert_proper_table_data(data)
+
+      cells = []
+      
+      @row_length = data.length
+      @column_length = data.map{ |r| r.length }.max
+
+      data.each_with_index do |row_cells, row_number|
+        row_cells.each_with_index do |cell_data, column_number|
+          cell = Cell.make(@pdf, cell_data)
+          cell.extend(Cell::InTable)
+          cell.row = row_number
+          cell.column = column_number
+          cells << cell
+        end
+      end
+      cells
+    end
+
+    # Raises an error if the data provided cannot be converted into a valid
+    # table.
+    #
+    def assert_proper_table_data(data)
+      if data.nil? || data.empty?
+        raise Prawn::Errors::EmptyTable,
+          "data must be a non-empty, non-nil, two dimensional array " +
+          "of cell-convertible objects"
+      end
+
+      unless data.all? { |e| Array === e }
+        raise Prawn::Errors::InvalidTableData,
+          "data must be a two dimensional array of cellable objects"
+      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 }
+    end
+
+    # Returns the "natural" (unconstrained) width of the table. This may be
+    # extremely silly; for example, the unconstrained width of a paragraph of
+    # text is the width it would assume if it were not wrapped at all. Could be
+    # a mile long.
+    #
+    def natural_width
+      @natural_width ||= natural_column_widths.inject(0) { |sum, w| sum + w }
+    end
+
+    # Assigns the calculated column widths to each cell. This ensures that each
+    # cell in a column is the same width. After this method is called,
+    # subsequent calls to column_widths and width should return the finalized
+    # values that will be used to ink the table.
+    #
+    def set_column_widths
+      column_widths.each_with_index do |w, col_num| 
+        column(col_num).width = w
+      end
+    end
+
+    # Assigns the row heights to each cell. This ensures that every cell in a
+    # row is the same height.
+    #
+    def set_row_heights
+      row_heights.each_with_index { |h, row_num| row(row_num).height = h }
+    end
+
+    # Set each cell's position based on the widths and heights of cells
+    # preceding it.
+    #
+    def position_cells
+      # Calculate x- and y-positions as running sums of widths / heights.
+      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 }
+
+      # y-positions assume an infinitely long canvas starting at zero -- this
+      # is corrected for in Table#draw, and page breaks are properly inserted.
+      y_positions = row_heights.inject([0]) { |ary, y|
+        ary << (ary.last - y); ary}[0..-2]
+      y_positions.each_with_index { |y, i| row(i).y = y }
+    end
+
+  end
+
+
+end