pdf-wrapper 0.0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+v0.0.1 (9th January 2008)
+- Initial, pre-alpha, eats small children for breakfast release

data/DESIGN

@@ -0,0 +1,29 @@
+*************************************
+* Overarching Design Principles
+*************************************
+- low level canvas drawing API
+  - add text
+  - add shapes / images
+
+- higher level "widget" API
+  - text boxes
+  - form helpers ( check boxes, etc)
+  - water mark
+  - repeating elements (page numbers, headers/footers, etc)
+  - image boxes
+  - lists
+  - tables (port simple table?)
+
+*************************************
+* Thoughts on the table API
+*************************************
+
+FPDF::Table 
+- .table(data = [], columns = [])
+- http://source.mihelac.org/2006/6/19/creating-pdf-documents-with-tables-in-ruby-rails#comments
+
+PDF::SimpleTable
+- .table(data = [{}], columns = []
+
+XHTML?
+- .table(data = String, opts = {})

data/README

@@ -0,0 +1,73 @@
+= Overview
+
+PDF::Wrapper is a PDF generation library that uses the cairo and pango
+libraries to do the heavy lifting. I've essentially just wrapped these general
+purpose graphics libraries with some sugar that makes them a little easier to
+use for making PDFs. The idea is to lever the low level tools in those libraries
+(drawing shapes, laying out text, importing raster images, etc) to build some
+higher level tools - tables, text boxes, borders, lists, repeating elements
+(headers/footers), etc.
+
+At this stage the API is *roughly* following that of PDF::Writer, but i've made 
+tweaks in some places and added some new methods. This is a work in progress so
+many features of PDF::Writer aren't available yet.
+
+A key motivation for writing this library is cairo's support for Unicode in PDFs.
+All text functions in this library support UTF8 input, although as a native 
+English speaker I've only tested this a little, so any feedback is welcome. 
+
+There also seems to be a lack of English documentation available for the ruby 
+bindings to cairo/pango, so I'm aiming to document the code as much as possible
+to provide worked examples for others. I'm learning as I go though, so if regular
+users of either library spot techniques that fail best practice, please let me know.
+
+It's early days, so the API is far from stable and I'm hesitant to write extensive 
+documentation just yet. It's the price you pay for being an early adopter. The
+examples/ dir should have a range of sample code, and I'll try to keep it up to
+date.
+
+I welcome all feedback, feature requests, patches and suggestions. In
+particular, what high level widgets would you like to see? What do you use when
+building reports and documents in GUI programs?
+
+= Installation
+
+The recommended installation method is via Rubygems.
+
+  gem install pdf-wrapper
+
+= Author
+
+James Healy <jimmy@deefa.com>
+
+= License
+
+* GPL version 2 or the Ruby License
+* Ruby: http://www.ruby-lang.org/en/LICENSE.txt
+ 
+= Dependencies
+
+* ruby/cairo
+* ruby/pango (optional, required to add text)
+* ruby/rsvg2 (optional, required for SVG support)
+
+These are all ruby bindings to C libraries. On Debian/Ubuntu based systems
+(which I develop on) you can get them by running:
+
+    aptitude install libcairo-ruby libpango1-ruby librsvg2-ruby
+
+For users of other systems, I'd love to receive info on how you set these bindings up.
+
+ruby/cairo is also available as a gem (cairo), which may be installable if you have a copy
+of the cairo source available on your system.
+
+= Compatibility
+
+JRuby users, you're probably out of luck. 
+
+Rubinius users, I have no idea.
+
+Ruby1.9 users, the current release of ruby/cairo (1.5.0) doesn't work with 1.9,
+but the version in SVN does. Hopefully it will be released soon. The version in
+Debian has been patched to work with 1.9 already. PDF::Wrapper itself is 1.9
+compatible.

data/Rakefile

@@ -0,0 +1,76 @@
+require "rubygems"
+require 'rake'
+require 'rake/clean'
+require 'rake/rdoctask'
+require 'rake/testtask'
+require "rake/gempackagetask"
+require 'spec/rake/spectask'
+
+PKG_VERSION = "0.0.1"
+PKG_NAME = "pdf-wrapper"
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+desc "Default Task"
+task :default => [ :spec ]
+
+# run all rspecs
+desc "Run all rspec files"
+Spec::Rake::SpecTask.new("spec") do |t|
+  t.spec_files = FileList['specs/**/*.rb']
+  t.rcov = true
+  t.rcov_dir = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + "/rcov"
+  t.rcov_opts = ["--exclude","spec.*\.rb","--exclude",".*cairo.*","--exclude",".*rcov.*","--exclude",".*rspec.*","--exclude",".*df-reader.*"]
+end
+
+# generate specdocs
+desc "Generate Specdocs"
+Spec::Rake::SpecTask.new("specdocs") do |t|
+  t.spec_files = FileList['specs/**/*.rb']
+  t.spec_opts = ["--format", "rdoc"]
+  t.out = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + '/specdoc.rd'
+end
+
+# generate failing spec report
+desc "Generate failing spec report"
+Spec::Rake::SpecTask.new("spec_report") do |t|
+  t.spec_files = FileList['specs/**/*.rb']
+  t.spec_opts = ["--format", "html", "--diff"]
+  t.out = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + '/spec_report.html'
+  t.fail_on_error = false
+end
+
+# Genereate the RDoc documentation
+desc "Create documentation"
+Rake::RDocTask.new("doc") do |rdoc|
+  rdoc.title = "pdf-wrapper"
+  rdoc.rdoc_dir = (ENV['CC_BUILD_ARTIFACTS'] || 'doc') + '/rdoc'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('CHANGELOG')
+  rdoc.rdoc_files.include('DESIGN')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.options << "--inline-source"
+end
+
+# a gemspec for packaging this library 
+spec = Gem::Specification.new do |spec|
+	spec.name = PKG_NAME
+	spec.version = PKG_VERSION
+	spec.platform = Gem::Platform::RUBY
+	spec.summary = "A PDF generating library built on top of cairo"
+	spec.files =  Dir.glob("{examples,lib}/**/**/*") + ["Rakefile"]
+  spec.require_path = "lib"
+	spec.has_rdoc = true
+	spec.extra_rdoc_files = %w{README DESIGN CHANGELOG}
+	spec.rdoc_options << '--title' << 'PDF::Wrapper Documentation' << '--main'  << 'README' << '-q'
+  spec.author = "James Healy"
+	spec.email = "jimmy@deefa.com"
+	spec.rubyforge_project = "pdf-wrapper"
+	spec.description = "A PDF writing library that uses the cairo and pango libraries to do the heavy lifting."
+end
+
+# package the library into a gem
+desc "Generate a gem for pdf-wrapper"
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_zip = true
+	pkg.need_tar = true
+end

data/examples/cell.rb

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.cell("Given an index within a layout, determines the positions that of the strong and weak cursors if the insertion point is at that index. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the layout are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the layout are inserted.", 100, 100, 100, 200, {:border => "", :color => :white, :bgcolor => :black})
+pdf.render_to_file("wrapper-cell.pdf")

data/examples/image.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.default_font("Sans Serif")
+pdf.default_color(:black)
+pdf.text("PDF::Wrapper Supports Images", :alignment => :center)
+pdf.image(File.dirname(__FILE__) + "/google.png", :left => 100, :top => 250)
+pdf.render_to_file("image.pdf")

data/examples/shapes.pdf

@@ -0,0 +1,66 @@
+%PDF-1.4
+%����
+2 0 obj
+<< /Length 3 0 R
+   /Filter /FlateDecode
+   /Type /XObject
+   /Subtype /Form
+   /BBox [ 0 0 595.28 841.89 ]
+>>
+stream
+x��R�N�0�W�?�(v�� !qX8"(�V��a��O�<�yQ��ӎ�c� ��G�G8~�/<����-p����;��%0�s�6��u�`S0g���>)+�^�Ey�1�(�S߽�
}GO���ɑ|��J�;z	w�A�`��8ܶ>�(Wق�i�ɱ�jhēd�Ӄ3�5d�)�wIs���X�q�Rr���~0��l��S�,��K�m��>A�mZ���pPb3�0VS`8�X%I���"�BR�ز��dj���^A*�%�H�Z���^���z�)��v�����3];�'a��q�hz����-b���͚‹C^��N
+endstream
+endobj
+3 0 obj
+   342
+endobj
+4 0 obj
+<< /Type /Page
+   /Parent 1 0 R
+   /MediaBox [ 0 0 595.28 841.89 ]
+   /Contents [ 2 0 R ]
+   /Group <<
+      /Type /Group
+      /S /Transparency
+      /CS /DeviceRGB
+   >>
+>>
+endobj
+1 0 obj
+<< /Type /Pages
+   /Kids [ 4 0 R ]
+   /Count 1
+   /Resources <<
+      /ExtGState <<
+         /a0 << /CA 1 /ca 1 >>
+      >>
+   >>
+>>
+endobj
+5 0 obj
+<< /Creator (cairo 1.4.12 (http://cairographics.org))
+   /Producer (cairo 1.4.12 (http://cairographics.org))
+>>
+endobj
+6 0 obj
+<< /Type /Catalog
+   /Pages 1 0 R
+>>
+endobj
+xref
+0 7
+0000000000 65535 f
+0000000739 00000 n
+0000000017 00000 n
+0000000512 00000 n
+0000000537 00000 n
+0000000898 00000 n
+0000001030 00000 n
+trailer
+<< /Size 7
+   /Root 6 0 R
+   /Info 5 0 R
+>>
+startxref
+1087
+%%EOF

data/examples/shapes.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.rectangle(30,30,100,100, :fill_color => :red)
+pdf.circle(100,300,30)
+pdf.line(100, 350, 400, 150)
+pdf.rounded_rectangle(300,300, 200, 200, 10, :fill_color => :green)
+pdf.render_to_file("shapes.pdf")

data/examples/table.rb

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.text "Chunky Bacon!!"
+data = [%w{one two three four}]
+
+data << ["This is some longer text to ensure that the cell wraps",2,3,4]
+
+(1..100).each do
+  data << %w{1 2 3 4}
+end
+pdf.table(data, :font_size => 10)
+pdf.render_to_file("table.pdf")

data/examples/utf8.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new(:paper => :A4)
+pdf.default_font("Sans Serif")
+pdf.default_color(:black)
+pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8.txt"), :font => "Monospace", :font_size => 8
+pdf.render_to_file("wrapper.pdf")

data/lib/pdf/core.rb

@@ -0,0 +1,8 @@
+class Hash
+  # raise an error if this hash has any keys that aren't in the supplied list
+  # - borrowed from activesupport
+  def assert_valid_keys(*valid_keys)
+    unknown_keys = keys - [valid_keys].flatten
+    raise(ArgumentError, "Unknown key(s): #{unknown_keys.join(", ")}") unless unknown_keys.empty?
+  end
+end

data/lib/pdf/wrapper.rb

@@ -0,0 +1,839 @@
+# -* coding: UTF-8 -*-
+
+require 'stringio'
+require 'pdf/core'
+
+# try to load cairo from the standard places, but don't worry if it fails, 
+# we'll try to find it via rubygems
+begin
+  require 'cairo'
+rescue LoadError
+    begin
+      require 'rubygems'
+      gem 'cairo', '>=1.5'
+      require 'cairo'
+    rescue Gem::LoadError
+      raise LoadError, "Could not find the ruby cairo bindings in the standard locations or via rubygems. Check to ensure they're installed correctly"
+    rescue LoadError
+      raise LoadError, "Could not load rubygems"
+    end
+end
+
+module PDF
+  # Create PDF files by using the cairo and pango libraries.
+  #
+  # Rendering to a file:
+  #   
+  #   require 'pdfwrapper'
+  #   pdf = PDF::Wrapper.new(:paper => :A4)
+  #   pdf.text "Hello World"
+  #   pdf.render_to_file("wrapper.pdf")
+  #
+  # Rendering to a string:
+  #
+  #   require 'pdfwrapper'
+  #   pdf = PDF::Wrapper.new(:paper => :A4)
+  #   pdf.text "Hello World", :font_size => 16
+  #   puts pdf.render
+  #
+  # Changing the default font:
+  #
+  #   require 'pdfwrapper'
+  #   pdf = PDF::Wrapper.new(:paper => :A4)
+  #   pdf.default_font("Monospace")
+  #   pdf.text "Hello World", :font => "Sans Serif", :font_size => 18
+  #   pdf.text "Pretend this is a code sample"
+  #   puts pdf.render
+  class Wrapper
+
+    attr_reader :margin_left, :margin_right, :margin_top, :margin_bottom
+    attr_reader :page_width, :page_height
+
+    # borrowed from PDF::Writer
+    PAGE_SIZES = { # :value {...}:
+      #:4A0   => [4767.87, 6740.79], :2A0    => [3370.39, 4767.87],
+      :A0    => [2383.94, 3370.39], :A1     => [1683.78, 2383.94],
+      :A2    => [1190.55, 1683.78], :A3     => [841.89, 1190.55],
+      :A4    => [595.28,  841.89],  :A5     => [419.53,  595.28],
+      :A6    => [297.64,  419.53],  :A7     => [209.76,  297.64],
+      :A8    => [147.40,  209.76],  :A9     => [104.88,  147.40],
+      :A10   => [73.70,  104.88],   :B0     => [2834.65, 4008.19],
+      :B1    => [2004.09, 2834.65], :B2     => [1417.32, 2004.09],
+      :B3    => [1000.63, 1417.32], :B4     => [708.66, 1000.63],
+      :B5    => [498.90,  708.66],  :B6     => [354.33,  498.90],
+      :B7    => [249.45,  354.33],  :B8     => [175.75,  249.45],
+      :B9    => [124.72,  175.75],  :B10    => [87.87,  124.72],
+      :C0    => [2599.37, 3676.54], :C1     => [1836.85, 2599.37],
+      :C2    => [1298.27, 1836.85], :C3     => [918.43, 1298.27],
+      :C4    => [649.13,  918.43],  :C5     => [459.21,  649.13],
+      :C6    => [323.15,  459.21],  :C7     => [229.61,  323.15],
+      :C8    => [161.57,  229.61],  :C9     => [113.39,  161.57],
+      :C10   => [79.37,  113.39],   :RA0    => [2437.80, 3458.27],
+      :RA1   => [1729.13, 2437.80], :RA2    => [1218.90, 1729.13],
+      :RA3   => [864.57, 1218.90],  :RA4    => [609.45,  864.57],
+      :SRA0  => [2551.18, 3628.35], :SRA1   => [1814.17, 2551.18],
+      :SRA2  => [1275.59, 1814.17], :SRA3   => [907.09, 1275.59],
+      :SRA4  => [637.80,  907.09],  :LETTER => [612.00,  792.00],
+      :LEGAL => [612.00, 1008.00],  :FOLIO  => [612.00,  936.00],
+      :EXECUTIVE => [521.86, 756.00]
+    }
+
+    # create a new PDF::Wrapper class to compose a PDF document
+    # Options:
+    # <tt>:paper</tt>::   The paper size to use (default :A4)
+    # <tt>:orientation</tt>::   :portrait (default) or :landscape
+    # <tt>:background_colour</tt>::   The background colour to use (default :white)
+    def initialize(opts={})
+      options = {:paper => :A4,
+                  :orientation => :portrait,
+                  :background_colour => :white
+                 }
+      options.merge!(opts)
+      
+      # test for invalid options
+      raise ArgumentError, "Invalid paper option" unless PAGE_SIZES.include?(options[:paper])
+      
+      # set page dimensions
+      if options[:orientation].eql?(:portrait)
+        @page_width = PAGE_SIZES[options[:paper]][0]
+        @page_height = PAGE_SIZES[options[:paper]][1]
+      elsif options[:orientation].eql?(:landscape)
+        @page_width = PAGE_SIZES[options[:paper]][1]
+        @page_height = PAGE_SIZES[options[:paper]][0]
+      else
+        raise ArgumentError, "Invalid orientation"
+      end
+
+      # set page margins and dimensions of usable canvas
+      # TODO: add options for customising the margins. ATM they're always 5% of the page dimensions
+      @margin_left = (@page_width * 0.05).ceil
+      @margin_right = (@page_width * 0.05).ceil
+      @margin_top = (@page_height * 0.05).ceil
+      @margin_bottom = (@page_height * 0.05).ceil
+
+      # initialize some cairo objects to draw on
+      @output = StringIO.new
+      @surface = Cairo::PDFSurface.new(@output, @page_width, @page_height)
+      @context = Cairo::Context.new(@surface)
+
+      # set the background colour
+      set_color(options[:background_colour])
+      @context.paint
+
+      # set a default drawing colour and font style
+      default_color(:black)
+      default_font("Sans Serif")
+      default_font_size(16)
+      
+      # move the cursor to the top left of the usable canvas
+      reset_cursor
+    end
+
+    #####################################################
+    # Functions relating to calculating various page dimensions
+    #####################################################
+    
+    # Returns the x value of the left margin
+    # The top left corner of the page is (0,0)
+    def absolute_left_margin
+      @margin_left
+    end
+    
+    # Returns the x value of the right margin
+    # The top left corner of the page is (0,0)
+    def absolute_right_margin
+      @page_width - @margin_right
+    end
+
+    # Returns the y value of the top margin
+    # The top left corner of the page is (0,0)
+    def absolute_top_margin
+      @margin_top
+    end
+
+    # Returns the y value of the bottom margin
+    # The top left corner of the page is (0,0)
+    def absolute_bottom_margin
+      @page_height - @margin_bottom
+    end
+
+    # Returns the x at the middle of the page
+    def absolute_x_middle
+      @page_width / 2
+    end
+
+    # Returns the y at the middle of the page
+    def absolute_y_middle
+      @page_height / 2
+    end
+
+    # Returns the width of the usable part of the page (between the side margins)
+    def body_width
+      @page_width - @margin_left - @margin_right
+    end
+
+    # Returns the height of the usable part of the page (between the top and bottom margins)
+    def body_height
+      @page_height - @margin_top - @margin_bottom
+    end
+
+    # Returns the x coordinate of the middle part of the usable space between the margins
+    def margin_x_middle
+      @margin_left + (body_width / 2)
+    end
+
+    # Returns the y coordinate of the middle part of the usable space between the margins
+    def margin_y_middle
+      @margin_top + (body_height / 2)
+    end
+
+    # return the current position of the cursor
+    # returns 2 values - x,y
+    def current_point
+      return @context.current_point
+    end
+
+    # return the number of points from  starty to the bottom border
+    def points_to_bottom_margin(starty)
+      absolute_bottom_margin - starty
+    end
+
+    # return the number of points from  startx to the right border
+    def points_to_right_margin(startx)
+      absolute_right_margin - startx
+    end
+
+    #####################################################
+    # Functions relating to working with text
+    #####################################################
+    
+    # change the default font size
+    def default_font_size(size)
+      #@context.set_font_size(size.to_i)
+      @default_font_size = size.to_i unless size.nil?
+    end
+    alias default_font_size= default_font_size
+    alias font_size default_font_size          # PDF::Writer compatibility
+
+    # change the default font to write with
+    def default_font(fontname, style = nil, weight = nil)
+      #@context.select_font_face(fontname, slant, bold)
+      @default_font = fontname
+      @default_font_style = style unless style.nil?
+      @default_font_weight = weight unless weight.nil?
+    end
+    alias default_font= default_font
+    alias select_font default_font   # PDF::Writer compatibility
+
+    # change the default colour used to draw on the canvas
+    #
+    # Parameters:
+    # <tt>c</tt>::  either a colour symbol recognised by rcairo (:red, :blue, :black, etc) or
+    #               an array with 3-4 integer elements. The first 3 numbers are red, green and 
+    #               blue (0-255). The optional 4th number is the alpha channel and should be
+    #               between 0 and 1. See the API docs at http://cairo.rubyforge.org/ for a list
+    #               of predefined colours
+    def default_color(c)
+      validate_color(c)
+      @default_color = c
+    end
+    alias default_color= default_color
+    alias stroke_color default_color    # PDF::Writer compatibility
+
+    # add text to the page, bounded by a box with dimensions HxW, with it's top left corner
+    # at x,y. Any text that doesn't fit it the box will be silently dropped.
+    #
+    # In addition to the standard text style options (see the documentation for text()), cell() supports
+    # the following options:
+    #
+    # <tt>:border</tt>::   Which sides of the cell should have a border? A string with any combination the letters tblr (top, bottom, left, right). Nil for no border, defaults to all sides.
+    # <tt>:border_width</tt>::  How wide should the border be? 
+    # <tt>:border_color</tt>::  What color should the border be?
+    # <tt>:bgcolor</tt>::  A background color for the cell. Defaults to none.
+    def cell(str, x, y, w, h, opts={})
+      # TODO: add support for pango markup (see http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup)
+      # TODO: add a wrap option so wrapping can be disabled
+      # TODO: raise an error if any unrecognised options were supplied 
+      # TODO: add padding between border and text
+      # TODO: how do we handle a single word that is too long for the width?
+
+      options = default_text_options
+      options.merge!({:border => "tblr", :border_width => 1, :border_color => :black, :bgcolor => nil})
+      options.merge!(opts)
+
+      options[:width]  = w
+      options[:border] = "" unless options[:border]
+      options[:border].downcase!
+
+      # TODO: raise an exception if the box coords or dimensions will place it off the canvas
+      rectangle(x,y,w,h, :color => options[:bgcolor], :fill_color => options[:bgcolor]) if options[:bgcolor]
+
+      layout = build_pango_layout(str.to_s, options)
+
+      set_color(options[:color])
+
+      # draw the context on our cairo layout
+      render_layout(layout, x, y, h, :auto_new_page => false)
+
+      # draw a border around the cell
+      # TODO: obey options[:border_width]
+      # TODO: obey options[:border_color]
+      line(x,y,x+w,y)     if options[:border].include?("t")
+      line(x,y+h,x+w,y+h) if options[:border].include?("b")
+      line(x,y,x,y+h)     if options[:border].include?("l")
+      line(x+w,y,x+w,y+h) if options[:border].include?("r")
+    end
+    
+    # draws a basic table onto the page
+    # data   - a 2d array with the data for the columns. The first row will be treated as the headings
+    #
+    # In addition to the standard text style options (see the documentation for text()), cell() supports
+    # the following options:
+    #
+    # <tt>:left</tt>::   The x co-ordinate of the left-hand side of the table. Defaults to the left margin
+    # <tt>:top</tt>::   The y co-ordinate of the top of the text. Defaults to the top margin
+    # <tt>:width</tt>::   The width of the table. Defaults to the width of the page body
+    def table(data, opts = {})
+      # TODO: instead of accepting the data, use a XHTML table string?
+      # TODO: handle overflowing to a new page
+      # TODO: add a way to display borders
+      # TODO: raise an error if any unrecognised options were supplied 
+
+      x, y = current_point
+      options = default_text_options.merge!({:left => x,
+                                             :top => y
+                                            })
+      options.merge!(opts)
+      options[:width] = body_width - options[:left] unless options[:width]
+
+      # move to the start of our table (the top left) 
+      x = options[:left]
+      y = options[:top]
+      move_to(x,y)
+
+      # all columns will have the same width at this stage
+      cell_width = options[:width] / data.first.size
+      
+      # draw the header cells
+      y = draw_table_row(data.shift, cell_width, options)
+      x = options[:left]
+      move_to(x,y)
+
+      # draw the data cells
+      data.each do |row|
+        y = draw_table_row(row, cell_width, options)
+        x = options[:left]
+        move_to(x,y)
+      end
+    end
+
+    # Write text to the page
+    #
+    # By default the text will be rendered using all the space within the margins and using
+    # the default font styling set by default_font(), default_font_size, etc
+    #
+    # There is no way to place a bottom bound (or height) onto the text. Text will wrap as
+    # necessary and take all the room it needs. For finer grained control of text boxes, see the 
+    # cell method.
+    #
+    # To override all these defaults, use the options hash
+    #
+    # Positioning Options:
+    #
+    # <tt>:left</tt>::   The x co-ordinate of the left-hand side of the text.
+    # <tt>:top</tt>::   The y co-ordinate of the top of the text.
+    # <tt>:width</tt>::   The width of the text to wrap at
+    #
+    # Text Style Options:
+    #
+    # <tt>:font</tt>::   The font family to use as a string
+    # <tt>:font_size</tt>::   The size of the font in points
+    # <tt>:alignment</tt>::   Align the text along the left, right or centre. Use :left, :right, :center
+    # <tt>:justify</tt>::   Justify the text so it exapnds to fill the entire width of each line. Note that this only works in pango >= 1.17
+    # <tt>:spacing</tt>::  Space between lines in PDF points
+    def text(str, opts={})
+      # TODO: add support for pango markup (see http://ruby-gnome2.sourceforge.jp/hiki.cgi?pango-markup)
+      # TODO: add a wrap option so wrapping can be disabled
+      # TODO: raise an error if any unrecognised options were supplied 
+      #
+      # the non pango way to add text to the cairo context, not particularly useful for
+      # PDF generation as it doesn't support wrapping text or other advanced layout features 
+      # and I really don't feel like re-implementing all that
+      # @context.show_text(str)
+
+      # the "pango way"
+      x, y = current_point
+      options = default_text_options.merge!({:left => x, :top => y})
+      options.merge!(opts)
+
+      # if the user hasn't specified a width, make the text wrap on the right margin
+      options[:width] = absolute_right_margin - options[:left] if options[:width].nil?
+
+      layout = build_pango_layout(str.to_s, options)
+      
+      set_color(options[:color])
+
+      # draw the context on our cairo layout
+      y = render_layout(layout, options[:left], options[:top], points_to_bottom_margin(options[:top]), :auto_new_page => true)
+
+      move_to(options[:left], y + 5)
+    end
+
+    # Returns the amount of vertical space needed to display the supplied text at the requested width
+    # opts is an options hash that specifies various attributes of the text. See the text function for more information.
+    # TODO: raise an error if any unrecognised options were supplied 
+    def text_height(str, width, opts = {})
+      options = default_text_options.merge!(opts)
+      options[:width] = width || body_width
+
+      layout = build_pango_layout(str.to_s, options)
+      width, height = layout.size
+
+      return height / Pango::SCALE
+    end
+
+    #####################################################
+    # Functions relating to working with graphics
+    #####################################################
+
+    # 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>:fill_color</tt>::   The colour to fill the circle with. Defaults to nil (no fill)
+    def circle(x, y, r, opts = {})
+      # TODO: raise an error if any unrecognised options were supplied 
+      options = {:color => @default_color,
+                 :fill_color => nil
+                 }
+      options.merge!(opts)
+
+      move_to(x + r, y)
+
+      # if the rectangle should be filled in
+      if options[:fill_color]
+        set_color(options[:fill_color])
+        @context.circle(x, y, r).fill
+      end
+      
+      set_color(options[:color])
+      @context.circle(x, y, r).stroke
+      move_to(x + r, y + r)
+    end
+
+    # draw a line from x1,y1 to x2,y2
+    #
+    # Options:
+    # <tt>:color</tt>::   The colour of the line
+    def line(x0, y0, x1, y1, opts = {})
+      # TODO: raise an error if any unrecognised options were supplied 
+      options = {:color => @default_color }
+      options.merge!(opts)
+
+      set_color(options[:color])
+
+      move_to(x0,y0)
+      @context.line_to(x1,y1).stroke
+      move_to(x1,y1)
+    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>:fill_color</tt>::   The colour to fill the rectangle with. Defaults to nil (no fill)
+    def rectangle(x, y, w, h, opts = {})
+      # TODO: raise an error if any unrecognised options were supplied 
+      options = {:color => @default_color,
+                 :fill_color => nil
+                 }
+      options.merge!(opts)
+      
+      # if the rectangle should be filled in
+      if options[:fill_color]
+        set_color(options[:fill_color])
+        @context.rectangle(x, y, w, h).fill 
+      end
+      
+      set_color(options[:color])
+      @context.rectangle(x, y, w, h).stroke
+      
+      move_to(x+w, y+h)
+    end
+
+    # draw a rounded 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
+    # <tt>:r</tt>::   The size of the rounded corners
+    #
+    # Options:
+    # <tt>:color</tt>::   The colour of the rectangle outline
+    # <tt>:fill_color</tt>::   The colour to fill the rectangle with. Defaults to nil (no fill)
+    def rounded_rectangle(x, y, w, h, r, opts = {})
+      # TODO: raise an error if any unrecognised options were supplied 
+      options = {:color => @default_color,
+                 :fill_color => nil
+                 }
+      options.merge!(opts)
+      
+      raise ArgumentError, "Argument r must be less than both w and h arguments" if r >= w || r >= h
+      
+      # if the rectangle should be filled in
+      if options[:fill_color]
+        set_color(options[:fill_color])
+        @context.rounded_rectangle(x, y, w, h, r).fill 
+      end
+      
+      set_color(options[:color])
+      @context.rounded_rectangle(x, y, w, h, r).stroke
+      
+      move_to(x+w, y+h)
+    end
+
+    #####################################################
+    # Functions relating to working with images
+    #####################################################
+
+    # add an image to the page
+    # at this stage the file must be a PNG or SVG
+    # 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
+    #
+    # left and top default to the current cursor location
+    # width and height default to the size of the imported image
+    def image(filename, opts = {})
+      # TODO: maybe split this up into separate functions for each image type
+      # TODO: add some options for things like justification, scaling and padding
+      # TODO: png images currently can't be resized
+      # TODO: raise an error if any unrecognised options were supplied 
+      raise ArgumentError, "file #{filename} not found" unless File.file?(filename)
+
+      filetype = detect_image_type(filename)
+
+      if filetype.eql?(:png)
+        img_surface = Cairo::ImageSurface.from_png(filename)
+        x, y = current_point
+        @context.set_source(img_surface, opts[:left] || x, opts[:top] || y)
+        @context.paint
+      elsif filetype.eql?(:svg)
+        # thanks to Nathan Stitt for help with this section
+        load_librsvg
+        @context.save
+
+        # import it
+        handle = RSVG::Handle.new_from_file(filename)
+
+        # size the SVG
+        if opts[:height] && opts[:width]
+          handle.set_size_callback do |h,w|
+            [ opts[:width], opts[:height] ]
+          end
+        end
+
+        # place the image on our main context
+        x, y = current_point
+        @context.translate( opts[:left] || x, opts[:top] || y )
+        @context.render_rsvg_handle(handle)
+        @context.restore
+      else
+        raise ArgumentError, "Unrecognised image format"
+      end
+    end
+
+    #####################################################
+    # Functions relating to generating the final document
+    #####################################################
+
+    # render the PDF and return it as a string
+    def render
+      # finalise the document, then convert the StringIO object it was rendered to
+      # into a string
+      @context.show_page
+      @context.target.finish
+      return @output.string
+    end
+
+    # save the rendered PDF to a file
+    def render_to_file(filename)
+      # finalise the document
+      @context.show_page
+      @context.target.finish
+
+      # write each line from the StringIO object it was rendered to into the 
+      # requested file
+      File.open(filename, "w") do |of| 
+        @output.rewind
+        @output.each_line { |line| of.write(line) }
+      end
+    end
+
+    #####################################################
+    # Misc Functions
+    #####################################################
+
+    # move the cursor to an arbitary position on the current page
+    def move_to(x,y)
+      raise ArgumentError, 'x cannot be larger than the width of the page' if x > page_width
+      raise ArgumentError, 'y cannot be larger than the height of the page' if y > page_height
+      @context.move_to(x,y)
+    end
+
+    # reset the cursor by moving it to the top left of the useable section of the page 
+    def reset_cursor
+      @context.move_to(margin_left,margin_top)
+    end
+
+    # move to the next page
+    def start_new_page
+      @context.show_page
+      reset_cursor
+    end
+
+    private
+
+    def build_pango_layout(str, opts = {})
+      options = {:left => @margin_left,
+                 :top => @margin_top,
+                 :font => @default_font,
+                 :font_size => @default_font_size,
+                 :color => @default_color,
+                 :alignment => :left,
+                 :justify => false,
+                 :spacing => 0
+                }
+      options.merge!(opts)
+
+      # if the user hasn't specified a width, make the text wrap on the right margin
+      options[:width] = absolute_right_margin - options[:left] if options[:width].nil?
+
+      # even though this is a private function, raise this error to force calling functions
+      # to decide how they want to handle converting non-strings into strings for rendering
+      raise ArgumentError, 'build_pango_layout must be passed a string' unless str.kind_of?(String)
+
+      # if we're running under a M17n aware VM, ensure the string provided is UTF-8
+      if RUBY_VERSION >= "1.9"
+        begin
+          str = str.encode("UTF-8")
+        rescue
+          raise ArgumentError, 'Strings must be supplied with a UTF-8 encoding, or an encoding that can be converted to UTF-8'
+        end 
+      end
+      
+      # The pango way:
+      load_libpango
+
+      # create a new Pango layout that our text will be added to
+      layout = @context.create_pango_layout
+      layout.text = str.to_s
+      layout.width = options[:width] * Pango::SCALE
+      layout.spacing = options[:spacing] * Pango::SCALE
+
+      # set the alignment of the text in the layout
+      if options[:alignment].eql?(:left)
+        layout.alignment = Pango::Layout::ALIGN_LEFT
+      elsif options[:alignment].eql?(:right)
+        layout.alignment = Pango::Layout::ALIGN_RIGHT
+      elsif options[:alignment].eql?(:center) || options[:alignment].eql?(:centre)
+        layout.alignment = Pango::Layout::ALIGN_CENTER
+      else
+        raise ArgumentError, "Invalid alignment requested"
+      end
+
+      # justify the text if need be - only works in pango >= 1.17
+      layout.justify = true if options[:justify]
+
+      # setup the font that will be used to render the text
+      fdesc = Pango::FontDescription.new(options[:font])
+      fdesc.set_size(options[:font_size] * Pango::SCALE)
+      layout.font_description = fdesc
+      @context.update_pango_layout(layout)
+      return layout
+    end
+
+    def default_text_options
+      { :font => @default_font,
+        :font_size => @default_font_size,
+        :color => @default_color,
+        :alignment => :left,
+        :justify => false,
+        :spacing => 0
+      }
+    end
+
+    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.include?("<svg")
+        return :svg
+      else
+        return nil
+      end
+    end
+
+    # adds a single table row to the canvas. Top left of the row will be at the current x,y
+    # co-ordinates, so make sure they're set correctly before calling this function
+    #
+    # strings - array of strings. Each element of the array is a cell
+    # column_widths - the width of each column. At this stage it should be an int. All columns are the same width
+    # options - any options relating to text style to use. font, font_size, alignment, etc. See text() for more info.
+    #
+    # Returns the y co-ordinates of the bottom edge of the row, ready for the next row
+    def draw_table_row(strings, column_widths, options)
+      row_height = 0
+      x, y = current_point
+
+      # we run all this code twice. The first time is a dry run to calculate the
+      # height of the largest cell, which determines the overall height of the row.
+      # The second run through we actually draw each cell onto the canvas
+      [:dry, :paint].each do |action|
+
+        strings.each do |head|
+          # TODO: provide a way for these to be overridden on a per cell basis
+          opts = {
+            :font      => options[:font],
+            :font_size => options[:font_size],
+            :color     => options[:color],
+            :alignment => options[:alignment],
+            :justify   => options[:justify],
+            :spacing   => options[:spacing]
+          }
+
+          if action == :dry
+            # calc the cell height, and set row_height if this cell is the biggest in the row
+            cell_height = text_height(head, column_widths, opts)
+            row_height = cell_height if cell_height > row_height
+          else
+            # start a new page if necesary
+            if row_height > (absolute_bottom_margin - y)
+              start_new_page 
+              y = margin_top
+            end
+
+            # add our cell, then advance x to the left edge of the next cell
+            self.cell(head, x, y, column_widths, row_height, opts)
+            x += column_widths 
+          end
+
+        end
+      end
+
+      return y + row_height
+    end
+
+    # 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 ::Object.const_defined?(:Pango)
+      rescue LoadError
+        raise LoadError, 'Ruby/Pango 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 ::Object.const_defined?(:RSVG)
+      rescue LoadError
+        raise LoadError, 'Ruby/RSVG library not found. Visit http://ruby-gnome2.sourceforge.jp/'
+      end
+    end
+
+    # renders a pango layout onto our main context
+    # based on a function of the same name found in the text2.rb sample file 
+    # distributed with rcairo - it's still black magic to me and has a few edge
+    # cases where it doesn't work too well. Needs to be improved.
+    def render_layout(layout, x, y, h, opts = {})
+      options = {:auto_new_page => true }
+      options.merge!(opts)
+
+      limit_y = y + h
+
+      iter = layout.iter
+      prev_baseline = iter.baseline / Pango::SCALE
+      begin
+        line = iter.line
+        ink_rect, logical_rect = iter.line_extents
+        y_begin, y_end = iter.line_yrange
+        if limit_y < (y + y_end / Pango::SCALE)
+          if options[:auto_new_page]
+            start_new_page
+            y = margin_top - prev_baseline
+          else
+            break
+          end
+        end
+        width, height = layout.size
+        baseline = iter.baseline / Pango::SCALE
+        move_to(x + logical_rect.x / Pango::SCALE, y + baseline)
+        @context.show_pango_layout_line(line)
+        prev_baseline = baseline
+      end while iter.next_line!
+      return y + baseline
+    end
+
+    # set the current drawing colour
+    #
+    # for info on what is valid, see the comments for default_color 
+    def set_color(c)
+      # catch and reraise an exception to keep stack traces readable and clear
+      validate_color(c)
+
+      if c.kind_of?(Array)
+        @context.set_source_color(*c)
+      else
+        @context.set_source_color(c)
+      end
+    end
+
+    # test to see if the specified colour is a a valid cairo color
+    #
+    # for info on what is valid, see the comments for default_color 
+    def validate_color(c)
+      @context.save
+      begin
+        if c.kind_of?(Array)
+          # if the colour is being specified manually, there must be 3 or 4 elements
+          raise ArgumentError if c.size != 3 && c.size != 4
+          @context.set_source_color(c)
+        else
+          @context.set_source_color(c)
+        end
+        @default_color = c
+      rescue ArgumentError
+        c.kind_of?(Array) ? str = "[#{c.join(",")}]" : str = c.to_s
+        raise ArgumentError, "#{str} is not a valid color definition"
+      ensure
+        @context.restore
+      end
+      return true
+    end
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: pdf-wrapper
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- James Healy
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-01-09 00:00:00 +11:00
+default_executable: 
+dependencies: []
+
+description: A PDF writing library that uses the cairo and pango libraries to do the heavy lifting.
+email: jimmy@deefa.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- DESIGN
+- CHANGELOG
+files: 
+- examples/google.png
+- examples/cell.rb
+- examples/image.rb
+- examples/table.rb
+- examples/shapes.rb
+- examples/shapes.pdf
+- examples/image.pdf
+- examples/utf8.rb
+- lib/pdf
+- lib/pdf/wrapper.rb
+- lib/pdf/core.rb
+- Rakefile
+- README
+- DESIGN
+- CHANGELOG
+has_rdoc: true
+homepage: 
+post_install_message: 
+rdoc_options: 
+- --title
+- PDF::Wrapper Documentation
+- --main
+- README
+- -q
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: pdf-wrapper
+rubygems_version: 1.0.1
+signing_key: 
+specification_version: 2
+summary: A PDF generating library built on top of cairo
+test_files: []
+