pdf-wrapper 0.0.7 → 0.1.0

data/lib/pdf/wrapper/graphics.rb

@@ -0,0 +1,116 @@
+module PDF
+  class Wrapper
+
+    # draw a circle with radius r and a centre point at (x,y).
+    # Parameters:
+    # <tt>:x</tt>::   The x co-ordinate of the circle centre.
+    # <tt>:y</tt>::   The y co-ordinate of the circle centre.
+    # <tt>:r</tt>::   The radius of the circle
+    #
+    # Options:
+    # <tt>:color</tt>::   The colour of the circle outline
+    # <tt>:line_width</tt>::   The width of outline. Defaults to 0.5
+    # <tt>:fill_color</tt>::   The colour to fill the circle with. Defaults to nil (no fill)
+    def circle(x, y, r, options = {})
+      options.assert_valid_keys(:color, :line_width, :fill_color)
+
+      save_coords_and_state do
+        move_to(x + r, y)
+
+        # if the circle should be filled in
+        if options[:fill_color]
+          @context.save do
+            color(options[:fill_color])
+            @context.circle(x, y, r).fill
+          end
+        end
+
+        color(options[:color])           if options[:color]
+        line_width(options[:line_width]) if options[:line_width]
+        @context.circle(x, y, r).stroke
+      end
+    end
+
+    # draw a line from x1,y1 to x2,y2
+    #
+    # Options:
+    # <tt>:color</tt>::   The colour of the line
+    # <tt>:line_width</tt>::   The width of line. Defaults its 0.5
+    def line(x0, y0, x1, y1, options = {})
+      options.assert_valid_keys(:color, :line_width)
+
+      save_coords_and_state do
+        color(options[:color])           if options[:color]
+        line_width(options[:line_width]) if options[:line_width]
+        move_to(x0,y0)
+        @context.line_to(x1,y1).stroke
+      end
+    end
+
+    # change the default line width used to draw stroke on the canvas
+    #
+    # Parameters:
+    # <tt>f</tt>:: float value of stroke width from 0.01 to 255
+    def line_width(f)
+      @line_width = f
+      @context.set_line_width @context.device_to_user_distance(f,f).max
+    end
+    alias line_width= line_width
+
+    # Adds a cubic Bezier spline to the path from the  (x0, y0) to position (x3, y3)
+    # in user-space coordinates, using (x1, y1) and (x2, y2) as the control points.
+    # Options:
+    # <tt>:color</tt>::   The colour of the line
+    # <tt>:line_width</tt>::   The width of line. Defaults to 0.5
+    def curve(x0, y0, x1, y1, x2, y2, x3, y3, options = {})
+      options.assert_valid_keys(:color, :line_width)
+
+      save_coords_and_state do
+        color(options[:color])           if options[:color]
+        line_width(options[:line_width]) if options[:line_width]
+        move_to(x0,y0)
+        @context.curve_to(x1, y1, x2, y2, x3, y3).stroke
+      end
+    end
+
+    # draw a rectangle starting at x,y with w,h dimensions.
+    # Parameters:
+    # <tt>:x</tt>::   The x co-ordinate of the top left of the rectangle.
+    # <tt>:y</tt>::   The y co-ordinate of the top left of the rectangle.
+    # <tt>:w</tt>::   The width of the rectangle
+    # <tt>:h</tt>::   The height of the rectangle
+    #
+    # Options:
+    # <tt>:color</tt>::   The colour of the rectangle outline
+    # <tt>:line_width</tt>::   The width of outline. Defaults to 0.5
+    # <tt>:fill_color</tt>::   The colour to fill the rectangle with. Defaults to nil (no fill)
+    # <tt>:radius</tt>::   If specified, the rectangle will have rounded corners with the specified radius
+    def rectangle(x, y, w, h, options = {})
+      options.assert_valid_keys(:color, :line_width, :fill_color, :radius)
+
+      save_coords_and_state do
+        # if the rectangle should be filled in
+        if options[:fill_color]
+          @context.save do
+            color(options[:fill_color])
+            if options[:radius]
+              @context.rounded_rectangle(x, y, w, h, options[:radius]).fill
+            else
+              @context.rectangle(x, y, w, h).fill
+            end
+          end
+        end
+
+        color(options[:color])           if options[:color]
+        line_width(options[:line_width]) if options[:line_width]
+
+        if options[:radius]
+          @context.rounded_rectangle(x, y, w, h, options[:radius]).stroke
+        else
+          @context.rectangle(x, y, w, h).stroke
+        end
+      end
+    end
+
+  end
+end

data/lib/pdf/wrapper/images.rb

@@ -0,0 +1,206 @@
+module PDF
+  class Wrapper
+    # add an image to the page - a wide range of image formats are supported,
+    # including svg, jpg, png and gif. PDF images are also supported - an attempt
+    # to add a multipage PDF will result in only the first page appearing in the
+    # new document.
+    #
+    # supported options:
+    # <tt>:left</tt>::     The x co-ordinate of the left-hand side of the image.
+    # <tt>:top</tt>::      The y co-ordinate of the top of the image.
+    # <tt>:height</tt>::   The height of the image
+    # <tt>:width</tt>::    The width of the image
+    # <tt>:proportional</tt>::   Boolean. Maintain image proportions when scaling. Defaults to false.
+    # <tt>:padding</tt>::    Add some padding between the image and the specified box.
+    # <tt>:center</tt>::    If the image is scaled, it will be centered horizontally and vertically
+    #
+    # left and top default to the current cursor location
+    # width and height default to the size of the imported image
+    # padding defaults to 0
+    def image(filename, opts = {})
+      # TODO: add some options for justification and padding
+      raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
+      opts.assert_valid_keys(default_positioning_options.keys + [:padding, :proportional, :center])
+
+      if opts[:padding]
+        opts[:left]   += opts[:padding].to_i if opts[:left]
+        opts[:top]    += opts[:padding].to_i if opts[:top]
+        opts[:width]  -= opts[:padding].to_i * 2 if opts[:width]
+        opts[:height] -= opts[:padding].to_i * 2 if opts[:height]
+      end
+
+      case detect_image_type(filename)
+      when :pdf   then draw_pdf filename, opts
+      when :png   then draw_png filename, opts
+      when :svg   then draw_svg filename, opts
+      else
+        draw_pixbuf filename, opts
+      end
+    end
+
+    private
+
+    def detect_image_type(filename)
+      # read the first Kb from the file to attempt file type detection
+      f = File.new(filename)
+      bytes = f.read(1024)
+
+      # if the file is a PNG
+      if bytes[1,3].eql?("PNG")
+        return :png
+      elsif bytes[0,3].eql?("GIF")
+        return :gif
+      elsif bytes[0,4].eql?("%PDF")
+        return :pdf
+      elsif bytes.include?("<svg")
+        return :svg
+      elsif bytes.include?("Exif") || bytes.include?("JFIF")
+        return :jpg
+      else
+        return nil
+      end
+    end
+
+    # if need be, translate the x,y co-ords for an image to something different
+    #
+    # arguments:
+    # <tt>x</tt>::    The current x co-ord of the image
+    # <tt>y</tt>::    The current x co-ord of the image
+    # <tt>desired_w</tt>::    The image width requested by the user
+    # <tt>desired_h</tt>::    The image height requested by the user
+    # <tt>actual_w</tt>::    The width of the image we're going to draw
+    # <tt>actual_h</tt>::    The height of the image we're going to draw
+    # <tt>centre</tt>::    True if the image should be shifted to the center of it's box
+    def calc_image_coords(x, y, desired_w, desired_h, actual_w, actual_h, centre = false)
+
+      # if the width of the image is less than the requested box, calculate
+      # the white space buffer
+      if actual_w < desired_w && centre
+        white_space = desired_w - actual_w
+        x = x + (white_space / 2)
+      end
+
+      # if the height of the image is less than the requested box, calculate
+      # the white space buffer
+      if actual_h < desired_h && centre
+        white_space = desired_h - actual_h
+        y = y + (white_space / 2)
+      end
+
+      return x, y
+    end
+
+    # given a list of desired and actual image dimensions, calculate the
+    # size the image should actually be rendered at
+    def calc_image_dimensions(desired_w, desired_h, actual_w, actual_h, scale = false)
+      if scale
+        wp = desired_w / actual_w.to_f
+        hp = desired_h / actual_h.to_f
+
+        if wp < hp
+          width = actual_w * wp
+          height = actual_h * wp
+        else
+          width = actual_w * hp
+          height = actual_h * hp
+        end
+      else
+        width = desired_w || actual_w
+        height = desired_h || actual_h
+      end
+      return width.to_f, height.to_f
+    end
+
+    def draw_pdf(filename, opts = {})
+      # based on a similar function in rabbit. Thanks Kou.
+      load_libpoppler
+      x, y = current_point
+      page = Poppler::Document.new(filename).get_page(1)
+      w, h = page.size
+      width, height = calc_image_dimensions(opts[:width], opts[:height], w, h, opts[:proportional])
+      x, y = calc_image_coords(opts[:left] || x, opts[:top] || y, opts[:width] || w, opts[:height] || h, width, height,  opts[:center])
+      @context.save do
+        @context.translate(x, y)
+        @context.scale(width / w, height / h)
+        @context.render_poppler_page(page)
+      end
+      move_to(opts[:left] || x, (opts[:top] || y) + height)
+    end
+
+    def draw_pixbuf(filename, opts = {})
+      # based on a similar function in rabbit. Thanks Kou.
+      load_libpixbuf
+      x, y = current_point
+      pixbuf = Gdk::Pixbuf.new(filename)
+      width, height = calc_image_dimensions(opts[:width], opts[:height], pixbuf.width, pixbuf.height, opts[:proportional])
+      x, y = calc_image_coords(opts[:left] || x, opts[:top] || y, opts[:width] || pixbuf.width, opts[:height] || pixbuf.height, width, height,  opts[:center])
+      @context.save do
+        @context.translate(x, y)
+        @context.scale(width / pixbuf.width, height / pixbuf.height)
+        @context.set_source_pixbuf(pixbuf, 0, 0)
+        @context.paint
+      end
+      move_to(opts[:left] || x, (opts[:top] || y) + height)
+    rescue Gdk::PixbufError
+      raise ArgumentError, "Unrecognised image format (#{filename})"
+    end
+
+    def draw_png(filename, opts = {})
+      # based on a similar function in rabbit. Thanks Kou.
+      x, y = current_point
+      img_surface = Cairo::ImageSurface.from_png(filename)
+      width, height = calc_image_dimensions(opts[:width], opts[:height], img_surface.width, img_surface.height, opts[:proportional])
+      x, y = calc_image_coords(opts[:left] || x, opts[:top] || y, opts[:width] || img_surface.width, opts[:height] || img_surface.height, width, height,  opts[:center])
+      @context.save do
+        @context.translate(x, y)
+        @context.scale(width / img_surface.width, height / img_surface.height)
+        @context.set_source(img_surface, 0, 0)
+        @context.paint
+      end
+      move_to(opts[:left] || x, (opts[:top] || y) + height)
+    end
+
+    def draw_svg(filename, opts = {})
+      # based on a similar function in rabbit. Thanks Kou.
+      load_librsvg
+      x, y = current_point
+      handle = RSVG::Handle.new_from_file(filename)
+      width, height = calc_image_dimensions(opts[:width], opts[:height], handle.width, handle.height, opts[:proportional])
+      x, y = calc_image_coords(opts[:left] || x, opts[:top] || y, opts[:width] || handle.width, opts[:height] || handle.height, width, height,  opts[:center])
+      @context.save do
+        @context.translate(x, y)
+        @context.scale(width / handle.width, height / handle.height)
+        @context.render_rsvg_handle(handle)
+        #@context.paint
+      end
+      move_to(opts[:left] || x, (opts[:top] || y) + height)
+    end
+
+    def image_dimensions(filename)
+      raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
+
+      case detect_image_type(filename)
+      when :pdf   then
+        load_libpoppler
+        page = Poppler::Document.new(filename).get_page(1)
+        return page.size
+      when :png   then
+        img_surface = Cairo::ImageSurface.from_png(filename)
+        return img_surface.width, img_surface.height
+      when :svg   then
+        load_librsvg
+        handle = RSVG::Handle.new_from_file(filename)
+        return handle.width, handle.height
+      else
+        load_libpixbuf
+        begin
+          pixbuf = Gdk::Pixbuf.new(filename)
+          return pixbuf.width, pixbuf.height
+        rescue Gdk::PixbufError
+          raise ArgumentError, "Unrecognised image format (#{filename})"
+        end
+      end
+    end
+
+  end
+end

data/lib/pdf/wrapper/loading.rb

@@ -0,0 +1,52 @@
+module PDF
+  class Wrapper
+    # load libpango if it isn't already loaded.
+    # This will add some methods to the cairo Context class in addition to providing
+    # its own classes and constants. A small amount of documentation is available at
+    # http://ruby-gnome2.sourceforge.jp/fr/hiki.cgi?Cairo%3A%3AContext#Pango+related+APIs
+    def load_libpango
+      begin
+        require 'pango' unless @context.respond_to? :create_pango_layout
+      rescue LoadError
+        raise LoadError, 'Ruby/Pango library not found. Visit http://ruby-gnome2.sourceforge.jp/'
+      end
+    end
+
+    # load lib gdkpixbuf if it isn't already loaded.
+    # This will add some methods to the cairo Context class in addition to providing
+    # its own classes and constants.
+    def load_libpixbuf
+      begin
+        require 'gdk_pixbuf2' unless @context.respond_to? :set_source_pixbuf
+      rescue LoadError
+        raise LoadError, 'Ruby/GdkPixbuf library not found. Visit http://ruby-gnome2.sourceforge.jp/'
+      end
+    end
+
+    # load lib poppler if it isn't already loaded.
+    # This will add some methods to the cairo Context class in addition to providing
+    # its own classes and constants.
+    def load_libpoppler
+      begin
+        require 'poppler' unless @context.respond_to? :render_poppler_page
+      rescue LoadError
+        raise LoadError, 'Ruby/Poppler library not found. Visit http://ruby-gnome2.sourceforge.jp/'
+      end
+    end
+
+    # load librsvg if it isn't already loaded
+    # This will add an additional method to the Cairo::Context class
+    # that allows an existing SVG to be drawn directly onto it
+    # There's a *little* bit of documentation at:
+    # http://ruby-gnome2.sourceforge.jp/fr/hiki.cgi?Cairo%3A%3AContext#render_rsvg_handle
+    def load_librsvg
+      begin
+        require 'rsvg2' unless @context.respond_to? :render_svg_handle
+      rescue LoadError
+        raise LoadError, 'Ruby/RSVG library not found. Visit http://ruby-gnome2.sourceforge.jp/'
+      end
+    end
+
+
+  end
+end

data/lib/pdf/wrapper/table.rb

@@ -0,0 +1,473 @@
+module PDF
+  class Wrapper
+
+    # Draws a basic table of text on the page. See the documentation for a detailed description of
+    # how to control the table and its appearance.
+    #
+    # <tt>data</tt>:: a 2d array with the data for the columns, or a PDF::Wrapper::Table object
+    #
+    # == Options
+    #
+    # The only options available when rendering a table are those relating to its size and location.
+    # All other options that relate to the content of the table and how it looks should be configured
+    # on the PDF::Wrapper::Table object that is passed into this function.
+    #
+    # <tt>:left</tt>::   The x co-ordinate of the left-hand side of the table. Defaults to the current cursor location
+    # <tt>:top</tt>::   The y co-ordinate of the top of the text. Defaults to the current cursor location
+    # <tt>:width</tt>::   The width of the table. Defaults to the distance from the left of the table to the right margin
+    def table(data, opts = {})
+
+      x, y = current_point
+      options = {:left => x, :top => y }
+      options.merge!(opts)
+      options.assert_valid_keys(default_positioning_options.keys)
+
+      if data.kind_of?(::PDF::Wrapper::Table)
+        t = data
+      else
+        t = ::PDF::Wrapper::Table.new do |table|
+          table.data = data
+        end
+      end
+
+      t.width = options[:width] || points_to_right_margin(options[:left])
+      calc_table_dimensions t
+
+      # move to the start of our table (the top left)
+      move_to(options[:left], options[:top])
+
+      # draw the header cells
+      draw_table_headers(t) if t.headers && (t.show_headers == :page || t.show_headers == :once)
+
+      x, y = current_point
+
+      # loop over each row in the table
+      t.cells.each_with_index do |row, row_idx|
+
+        # calc the height of the current row
+        h = t.row_height(row_idx)
+
+        if y + h > absolute_bottom_margin
+          start_new_page
+          y = margin_top
+
+          # draw the header cells
+          draw_table_headers(t) if t.headers && (t.show_headers == :page)
+          x, y = current_point
+        end
+
+        # loop over each column in the current row
+        row.each_with_index do |cell, col_idx|
+
+          # calc the options and widths for this particular cell
+          opts = t.options_for(col_idx, row_idx)
+          w = t.col_width(col_idx)
+
+          # paint it
+          self.cell(cell.data, x, y, w, h, opts)
+          x += w
+          move_to(x, y)
+        end
+
+        # move to the start of the next row
+        y += h
+        x = options[:left]
+        move_to(x, y)
+      end
+    end
+    
+    def calc_table_dimensions(t)
+      # TODO: when calculating the min cell width, we basically want the width of the widest character. At the
+      #       moment I'm stripping all pango markup tags from the string, which means if any character is made
+      #       intentioanlly large, we'll miss it and it might not fit into our table cell.
+      t.cells.each_with_index do |row, row_idx|
+        row.each_with_index do |cell, col_idx|
+          opts = t.options_for(col_idx, row_idx).only(default_text_options.keys)
+          padding = opts[:padding] || 3
+          cell.min_width  = text_width(cell.data.to_s.dup.gsub(/<.+?>/,"").gsub(/\b|\B/,"\n"), opts) + (padding * 4)
+          cell.max_width  = text_width(cell.data, opts) + (padding * 4)
+        end
+      end
+      if t.headers
+        t.headers.each_with_index do |cell, col_idx|
+          opts = t.options_for(col_idx, :headers).only(default_text_options.keys)
+          padding = opts[:padding] || 3
+          cell.min_width  = text_width(cell.data.to_s.dup.gsub(/<.+?>/,"").gsub(/\b|\B/,"\n"), opts) + (padding * 4)
+          cell.max_width  = text_width(cell.data, opts) + (padding * 4)
+        end
+      end
+      t.calc_col_widths!
+      t.cells.each_with_index do |row, row_idx|
+        row.each_with_index do |cell, col_idx|
+          opts = t.options_for(col_idx, row_idx).only(default_text_options.keys)
+          padding = opts[:padding] || 3
+          cell.height = text_height(cell.data, t.col_width(col_idx) - (padding * 2), opts) + (padding * 2)
+        end
+      end
+      t.calc_row_heights!
+      if t.headers
+        t.headers.each_with_index do |cell, col_idx|
+          opts = t.options_for(col_idx, :headers).only(default_text_options.keys)
+          padding = opts[:padding] || 3
+          cell.height = text_height(cell.data, t.col_width(col_idx) - (padding * 2), opts) + (padding * 2)
+        end
+        t.calc_headers_height!
+      end
+    end
+    private :calc_table_dimensions
+
+    def draw_table_headers(t)
+      x, y = current_point
+      origx = x
+      h = t.headers_height
+      t.headers.each_with_index do |cell, col_idx|
+        # calc the options and widths for this particular header cell
+        opts = t.options_for(col_idx, :headers)
+        w = t.col_width(col_idx)
+
+        # paint it
+        self.cell(cell.data, x, y, w, h, opts)
+        x += w
+        move_to(x, y)
+      end
+      move_to(origx, y + h)
+    end
+    private :draw_table_headers
+
+    # This class is used to hold all the data and options for a table that will
+    # be added to a PDF::Wrapper document. Tables are a collection of cells, each
+    # one rendered to the document using the Wrapper#cell function.
+    #
+    # To begin working with a table, pass in a 2d array of data to display, along
+    # with optional headings, then pass the object to Wrapper#table
+    #
+    #    table = Table.new do |t|
+    #      t.headings = ["Words", "Numbers"]
+    #      t.data = [['one',  1],
+    #                ['two',  2],
+    #                ['three',3]]
+    #    end
+    #    pdf.table(table)
+    #
+    # For all but the most basic tables, you will probably want to tweak at least 
+    # some of the options for some of the cells. The options available are the same
+    # as those that are valid for the Wrapper#cell method, including things like font,
+    # font size, color and alignment.
+    #
+    # Options can be specified at the table, column, row and cell level. When it comes time
+    # to render each cell, the options are merged together so that cell options override row 
+    # ones, row ones override column ones and column ones override table wide ones.
+    #
+    # By default, no options are defined at all, and the document defaults will be used.
+    #
+    # For example:
+    #
+    #    table = Table.new do |t|
+    #      t.headings = ["Words", "Numbers"]
+    #      t.data = [['one',  1],
+    #                ['two',  2],
+    #                ['three',3]]
+    #      t.table_options :font_size => 10
+    #      t.row_options 0, :color => :green
+    #      t.row_options 2, :color => :red
+    #      t.col_options 0, :color => :blue
+    #      t.cell_options 2, 2, :font_size => 18
+    #    end
+    #    pdf.table(table)
+    #
+    # == Displaying Headings
+    #
+    # By default, the column headings will be displayed at the top of the table, and at
+    # the start of each new page the table wraps on to. Use the show_headers= option
+    # to change this behaviour. Valid values are nil for never, :once for just the at the
+    # top of the table, and :page for the default.
+    #
+    class Table
+      attr_reader :cells, :headers
+      attr_accessor :width, :show_headers
+
+      # Create a new table object.
+      #
+      # data should be a 2d array
+      #
+      #   [[ "one", "two"],
+      #    [ "one", "two"]]
+      #
+      # headers should be a single array
+      #  
+      #   ["first", "second"]
+      def initialize
+
+        # default table options
+        @table_options  = {}
+        @col_options    = Hash.new({})
+        @row_options    = Hash.new({})
+        @header_options = {}
+        @show_headers  = :page
+
+        yield self if block_given?
+        self
+      end
+
+      def data=(d)
+        # TODO: ensure d is array-like
+        @cells = d.collect do |row|
+          row.collect do |str|
+            Wrapper::Cell.new(str)
+          end
+        end
+      end
+
+      def headers=(h)
+        # TODO: ensure h is array-like
+        @headers = h.collect do |str|
+          Wrapper::Cell.new(str)
+        end
+      end
+
+      # access a particular cell
+      def cell(col_idx, row_idx)
+        @cells[row_idx, col_idx]
+      end
+
+      # Set or retrieve options that apply to every cell in the table.
+      # For a list of valid options, see Wrapper#cell.
+      def table_options(opts = nil)
+        @table_options = @table_options.merge(opts) if opts
+        @table_options
+      end
+
+      # set or retrieve options that apply to header cells
+      # For a list of valid options, see Wrapper#cell.
+      def header_options(opts = nil)
+        @header_options = @header_options.merge(opts) if opts
+        @header_options
+      end
+
+      # set or retrieve options that apply to a single cell
+      # For a list of valid options, see Wrapper#cell.
+      def cell_options(col_idx, row_idx, opts = nil)
+        raise ArgumentError, "#{col_idx},#{row_idx} is not a valid cell reference" unless @cells[row_idx] && @cells[row_idx][col_idx]
+        @cells[row_idx][col_idx].options = @cells[row_idx][col_idx].options.merge(opts) if opts
+        @cells[row_idx][col_idx].options
+      end
+
+      # set options that apply to 1 or more columns
+      # For a list of valid options, see Wrapper#cell.
+      # <tt>spec</tt>::     Which columns to add the options to. :odd, :even, a range, an Array of numbers or a number
+      def col_options(spec, opts)
+        each_column do |col_idx|
+          if (spec == :even && (col_idx % 2) == 0) ||
+             (spec == :odd  && (col_idx % 2) == 1) ||
+             (spec.class == Range && spec.include?(col_idx)) ||
+             (spec.class == Array && spec.include?(col_idx)) ||
+             (spec.respond_to?(:to_i) && spec.to_i == col_idx)
+            
+            @col_options[col_idx] = @col_options[col_idx].merge(opts)
+          end
+        end
+        self
+      end
+
+      # set options that apply to 1 or more rows
+      # For a list of valid options, see Wrapper#cell.
+      # <tt>spec</tt>::     Which columns to add the options to. :odd, :even, a range, an Array of numbers or a number
+      def row_options(spec, opts)
+        each_row do |row_idx|
+          if (spec == :even && (row_idx % 2) == 0) ||
+             (spec == :odd  && (row_idx % 2) == 1) ||
+             (spec.class == Range && spec.include?(row_idx)) ||
+             (spec.class == Array && spec.include?(row_idx)) ||
+             (spec.respond_to?(:to_i) && spec.to_i == row_idx)
+            
+            @row_options[row_idx] = @col_options[row_idx].merge(opts)
+          end
+        end
+        self
+      end
+
+      # calculate the combined options for a particular cell
+      #
+      # To get the options for a regular cell, use numbers to refernce the exact cell:
+      #
+      #    options_for(3, 3)
+      #
+      # To get options for a header cell, use :headers for the row:
+      #
+      #    options_for(3, :headers)
+      #
+      def options_for(col_idx, row_idx = nil)
+        opts = @table_options.dup
+        opts.merge! @col_options[col_idx]
+        if row_idx == :headers
+          opts.merge! @header_options
+        else
+          opts.merge! @row_options[row_idx]
+          opts.merge! @cells[row_idx][col_idx].options
+        end
+        opts
+      end
+
+      # Returns the required height for the headers row.
+      # Essentially just the height of the tallest cell in the row.
+      def headers_height
+        raise "You must call calc_headers_height! before calling headers_height" if @headers_height.nil?
+        @headers_height
+      end
+
+      # Returns the required height for a particular row.
+      # Essentially just the height of the tallest cell in the row.
+      def row_height(idx)
+        raise "You must call calc_row_heights! before calling row_heights" if @row_heights.nil?
+        @row_heights[idx]
+      end
+
+      # Returns the number of columns in the table
+      def col_count
+        @cells.first.size.to_f
+      end
+
+      # Returns the width of the specified column
+      def col_width(idx)
+        raise "You must call calc_col_widths! before calling col_width" if @col_widths.nil?
+        @col_widths[idx]
+      end
+
+      # process the individual cell widths and decide on the resulting
+      # width of each column in the table
+      def calc_col_widths!
+        @col_widths = calc_column_widths
+      end
+
+      # process the individual cell heights in the header and decide on the 
+      # resulting height of each row in the table
+      def calc_headers_height!
+        @headers_height = @headers.collect { |cell| cell.height }.compact.max
+      end
+
+      # process the individual cell heights and decide on the resulting
+      # height of each row in the table
+      def calc_row_heights!
+        @row_heights = @cells.collect do |row|
+          row.collect { |cell| cell.height }.compact.max
+        end
+      end
+
+      # forget row and column dimensions
+      def reset!
+        @col_widths = nil
+        @row_heights = nil
+      end
+
+      private
+
+      # the main smarts behind deciding on the width of each column. If possible, 
+      # each cell will get the maximum amount of space it wants. If not, some
+      # negotiation happens to find the best possible set of widths.
+      def calc_column_widths
+        raise "Can't calculate column widths without knowing the overall table width" if self.width.nil?
+        check_cell_widths
+
+        max_col_widths = {}
+        min_col_widths = {}
+        each_column do |col|
+          min_col_widths[col] = cells_in_col(col).collect { |c| c.min_width}.max.to_f
+          max_col_widths[col] = cells_in_col(col).collect { |c| c.max_width}.max.to_f
+        end
+        # add header cells to the mix
+        if @headers
+          @headers.each_with_index do |cell, idx|
+            min_col_widths[idx] = [cell.min_width.to_f, min_col_widths[idx]].max
+            max_col_widths[idx] = [cell.max_width.to_f, max_col_widths[idx]].max
+          end
+        end
+
+        if min_col_widths.values.sum > self.width
+          raise RuntimeError, "table content cannot fit into a table width of #{self.width}"
+        end
+        
+        if max_col_widths.values.sum == self.width
+          # every col gets the space it wants
+          col_widths = max_col_widths.dup
+        elsif max_col_widths.values.sum < self.width
+          # every col gets the space it wants, and there's
+          # still more room left. Distribute the extra room evenly
+          col_widths = grow_col_widths(max_col_widths.dup, max_col_widths, true)
+        else
+          # there's not enough room for every col to get as much space
+          # as it wants, so work our way down until it fits
+          col_widths = grow_col_widths(min_col_widths.dup, max_col_widths, false)
+        end
+        col_widths
+      end
+
+      # ceck to ensure every cell has a minimum and maximum cell width defined
+      def check_cell_widths
+        @cells.each do |row|
+          row.each do |cell|
+            raise "Every cell must have a min_width defined before being rendered to a document" if cell.min_width.nil?
+            raise "Every cell must have a max_width defined before being rendered to a document" if cell.max_width.nil?
+          end
+        end
+        if @headers
+          @headers.each do |cell|
+            raise "Every header cell must have a min_width defined before being rendered to a document" if cell.min_width.nil?
+            raise "Every header cell must have a max_width defined before being rendered to a document" if cell.max_width.nil?
+          end
+        end
+      end
+
+      # iterate over each column in the table
+      def each_column(&block)
+        (0..(col_count-1)).each do |col|
+          yield col
+        end
+      end
+
+      # iterate over each row in the table
+      def each_row(&block)
+        (0..(@cells.size-1)).each do |row|
+          yield row
+        end
+      end
+
+      # an array of all the cells in the specified column
+      def cells_in_col(idx)
+        @cells.collect {|row| row[idx]}
+      end
+
+      # an array of all the cells in the specified row
+      def cells_in_row(idx)
+        @cells[idx]
+      end
+
+      # if the widths of every column are less than the total width
+      # of the table, grow them to make use of it.
+      #
+      # col_widths - the cuurect hash of widths for each column index
+      # max_col_widths - the maximum width each column desires
+      # pas_max - can the width of a colum grow beyond its maximum desired
+      def grow_col_widths(col_widths, max_col_widths, past_max = false)
+        loop do
+          each_column do |idx|
+            col_widths[idx] += 0.3 unless col_widths[idx].frozen?
+            col_widths[idx].freeze if col_widths[idx] >= max_col_widths[idx] && past_max == false
+            break if col_widths.values.sum >= self.width
+          end
+          break if col_widths.values.sum >= self.width
+        end
+        col_widths
+      end
+    end
+
+    # A basic container to hold the required information for each cell
+    class Cell
+      attr_accessor :data, :options, :height, :min_width, :max_width
+
+      def initialize(str)
+        @data = str
+        @options = {}
+      end
+    end
+  end
+end