pdf-wrapper 0.1.3 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,30 @@
+v0.2.0 (15th September 2008)
+- API INCOMPATIBLE CHANGE: render() and render_file() are now deprecated.
+  - Use the output parameter of the constructor instead
+  - In versions before this, we automatically rendered to a StringIO object. This kept
+    things simple, but isn't great for scalability. Better to give the user the option
+    of bypassing memory and rendering direct to disk.
+  - Particuarly useful in rails apps to avoid the memory footprint of mongrels
+    blowing out
+- Added Wrapper#open()
+
+v0.1.5 (Unreleased)
+- Fix text wrapping that crosses page boundaries
+  - when a new page is started as a result of a text() call, the text
+    should continue at the top of the next page, not the y value the
+    text started at
+
+v0.1.4 (Unreleased)
+- Wrapper#font_size now accepts a block for temporary font size changes
+- Allow the page size to be changed when starting a new page
+- Added support for manually setting table column widths
+  - prevents the column widths from growing or shrinking automatically
+- Deprecated Table#table_options in favour of passing options to Table#new
+  - Thanks to Zubin Henner for the suggestion
+- Deprecated Table#header_options and Table#headers= in favour of a new method
+  that can be used to specify both the content and options of the header row.
+  - Thanks to Zubin Henner for the suggestion
+
 v0.1.3 (24th July 2008)
 - Require the gem version of cairo
   - >= 1.5. However I recommend >= 1.6.3 to avoid FATAL error under 1.8.7

data/Rakefile

@@ -6,7 +6,7 @@ require 'rake/testtask'
 require "rake/gempackagetask"
 require 'spec/rake/spectask'
 
-PKG_VERSION = "0.1.3"
+PKG_VERSION = "0.2.0"
 PKG_NAME = "pdf-wrapper"
 PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
 

data/TODO

@@ -1,2 +1,4 @@
-All TODO's are currently marked inline in the source code
+- Add a method that will start a new page if there isn't X space left on the current page.
+- Wrapper#required_space(50) {}
 
+There's plenty more TODO's marked inline in the source code

data/examples/cell.rb

@@ -5,6 +5,6 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("wrapper-cell.pdf", :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 => :black, :radius => 10})
-pdf.render_to_file("wrapper-cell.pdf")
+pdf.finish

data/examples/image.rb

@@ -5,12 +5,14 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("image.pdf", :paper => :A4)
 pdf.font("Sans Serif")
 pdf.color(:black)
 pdf.text("PDF::Wrapper Supports Images", :alignment => :center)
 pdf.image(File.dirname(__FILE__) + "/../specs/data/zits.gif")
+pdf.start_new_page
 pdf.image(File.dirname(__FILE__) + "/../specs/data/google.png", :left => 100, :top => 350)
+pdf.start_new_page
 pdf.image(File.dirname(__FILE__) + "/../specs/data/stef.jpg", :left => 200, :top => 500)
 pdf.start_new_page
 pdf.image(File.dirname(__FILE__) + "/../specs/data/orc.svg", :left => pdf.margin_left, :top => pdf.margin_top, :width => pdf.body_width, :height => pdf.body_height)
@@ -18,4 +20,4 @@ pdf.start_new_page
 pdf.image(File.dirname(__FILE__) + "/../specs/data/utf8-long.pdf", :left => pdf.margin_left, :top => pdf.margin_top, :width => pdf.body_width/2, :height => pdf.body_height/2)
 pdf.color(:red)
 
-pdf.render_to_file("image.pdf")
+pdf.finish

data/examples/markup.rb

@@ -5,8 +5,8 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("markup.pdf", :paper => :A4)
 pdf.font("Sans Serif")
 pdf.color(:black)
 pdf.text "<i>James Healy</i>", :font => "Monospace", :font_size => 16, :alignment => :center, :markup => :pango
-pdf.render_to_file("markup.pdf")
+pdf.finish

data/examples/repeating.rb

@@ -5,7 +5,7 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("repeating.pdf", :paper => :A4)
 
 pdf.repeating_element(:all) do
   pdf.text("Page #{pdf.page}!", :left => pdf.margin_left, :top => pdf.margin_top, :font_size => 18, :alignment => :center)
@@ -35,4 +35,4 @@ pdf.start_new_page
 pdf.start_new_page
 pdf.start_new_page
 
-pdf.render_to_file("repeating.pdf")
+pdf.finish

data/examples/scaled_image.rb

@@ -5,10 +5,10 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("scaled_image.pdf", :paper => :A4)
 pdf.image(File.dirname(__FILE__) + "/../specs/data/zits.gif",     :top => 100, :height => 200, :width => 200, :proportional => true, :center => true)
 pdf.rectangle(pdf.margin_left, 100, 200, 200)
 pdf.image(File.dirname(__FILE__) + "/../specs/data/windmill.jpg", :top => 400, :height => 200, :width => 200, :proportional => true, :center => true)
 pdf.rectangle(pdf.margin_left, 400, 200, 200)
 
-pdf.render_to_file("scaled_image.pdf")
+pdf.finish

data/examples/shapes.rb

@@ -5,9 +5,9 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("shapes.pdf", :paper => :A4)
 pdf.rectangle(30,30,100,100, :fill_color => :red)
 pdf.circle(100,300,30)
 pdf.line(100, 350, 400, 150)
 pdf.rectangle(300,300, 200, 200, :fill_color => :green, :radius => 10)
-pdf.render_to_file("shapes.pdf")
+pdf.finish

data/examples/table.rb

@@ -5,7 +5,7 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("table.pdf", :paper => :A4)
 pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8.txt").strip, :alignment => :centre
 pdf.pad 5
 headers = %w{one two three four}
@@ -20,11 +20,9 @@ data << [[], "j", "a", "m"]
   data << %w{1 2 3 4}
 end
 
-table = PDF::Wrapper::Table.new do |t|
+table = PDF::Wrapper::Table.new(:font_size => 10) do |t|
   t.data = data
-  t.headers = headers
-  t.table_options :font_size => 10
-  t.header_options :color => :white, :fill_color => :black
+  t.headers headers, {:color => :white, :fill_color => :black}
   t.row_options 6, {:border => "t"}
   t.row_options :even, {:fill_color => :gray}
   t.col_options 0, {:border => "tb"}
@@ -36,4 +34,4 @@ table = PDF::Wrapper::Table.new do |t|
 end
 
 pdf.table(table)
-pdf.render_to_file("table.pdf")
+pdf.finish

data/examples/table_fixed_col_width.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+pdf = PDF::Wrapper.new("table-fixed.pdf", :paper => :A4)
+pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8.txt").strip, :alignment => :centre
+pdf.pad 5
+headers = %w{one two three four}
+
+data = []
+data << ["This is some longer text to ensure...",2,3,4]
+data << ["This is some longer text to ensure...",2,3,4]
+
+table = PDF::Wrapper::Table.new do |t|
+  t.data = data
+  t.headers = headers
+  t.table_options :font_size => 10
+  t.header_options :color => :white, :fill_color => :black
+  t.manual_col_width [1,2,3], 25
+end
+
+pdf.table(table)
+pdf.finish

data/examples/translate.rb

@@ -5,7 +5,7 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-@pdf = PDF::Wrapper.new(:paper => :A4)
+@pdf = PDF::Wrapper.new("translate.pdf", :paper => :A4)
 
 def captioned_image(filename, caption, x, y)
   @pdf.translate(x, y) do
@@ -18,4 +18,4 @@ captioned_image(File.dirname(__FILE__) + "/../specs/data/orc.svg", "One", 100, 1
 captioned_image(File.dirname(__FILE__) + "/../specs/data/orc.svg", "Two", 250, 300)
 captioned_image(File.dirname(__FILE__) + "/../specs/data/orc.svg", "Three", 400, 500)
 
-@pdf.render_to_file("translate.pdf")
+@pdf.finish

data/examples/utf8-long.rb

@@ -5,7 +5,7 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("utf8-long.pdf", :paper => :A4)
 pdf.font("Sans Serif")
-pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8-long.txt"), :font => "Monospace", :font_size => 8
-pdf.render_to_file("utf8-long.pdf")
+pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8-long.txt"), :font => "Monospace", :font_size => 8, :top => 300
+pdf.finish

data/examples/utf8.rb

@@ -5,7 +5,7 @@ $:.unshift(File.dirname(__FILE__) + "/../lib")
 
 require 'pdf/wrapper'
 
-pdf = PDF::Wrapper.new(:paper => :A4)
+pdf = PDF::Wrapper.new("wrapper.pdf", :paper => :A4)
 pdf.font("Sans Serif")
 pdf.text File.read(File.dirname(__FILE__) + "/../specs/data/utf8.txt"), :font => "Monospace", :font_size => 8, :alignment => :center
-pdf.render_to_file("wrapper.pdf")
+pdf.finish

data/examples/varied_page_size.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+$:.unshift(File.dirname(__FILE__) + "/../lib")
+
+require 'pdf/wrapper'
+
+PDF::Wrapper.open("page_sizes.pdf", :paper => :A4) do |pdf|
+  pdf.rectangle(30,30,100,100, :fill_color => :red)
+  pdf.circle(100,300,30)
+
+  pdf.start_new_page(:orientation => :landscape)
+  pdf.line(100, 350, 400, 150)
+  pdf.rectangle(300,300, 200, 200, :fill_color => :green, :radius => 10)
+end

data/lib/pdf/wrapper.rb

@@ -3,6 +3,8 @@
 require 'stringio'
 require 'pdf/core'
 require 'pdf/errors'
+require 'tempfile'
+require 'fileutils'
 
 require File.dirname(__FILE__) + "/wrapper/graphics"
 require File.dirname(__FILE__) + "/wrapper/images"
@@ -18,28 +20,49 @@ require 'cairo'
 module PDF
   # Create PDF files by using the cairo and pango libraries.
   #
-  # Rendering to a file:
+  # == Rendering to a file
   #
   #   require 'pdf/wrapper'
-  #   pdf = PDF::Wrapper.new(:paper => :A4)
+  #   pdf = PDF::Wrapper.new("somefile.pdf", :paper => :A4)
   #   pdf.text "Hello World"
-  #   pdf.render_to_file("wrapper.pdf")
+  #   pdf.finish
   #
-  # Rendering to a string:
+  # == Rendering to a file (alternative)
   #
   #   require 'pdf/wrapper'
-  #   pdf = PDF::Wrapper.new(:paper => :A4)
+  #   File.open("somefile.pdf", "w") do |output|
+  #     pdf = PDF::Wrapper.new(output, :paper => :A4)
+  #     pdf.text "Hello World"
+  #     pdf.finish
+  #   end
+  #
+  # == Rendering to a string
+  #
+  #   require 'pdf/wrapper'
+  #   output = StringIO.new
+  #   pdf = PDF::Wrapper.new(output, :paper => :A4)
   #   pdf.text "Hello World", :font_size => 16
-  #   puts pdf.render
+  #   pdf.finish
+  #   puts output.string
+  #
+  # == Block format
   #
-  # Changing the default font:
+  # Avoid the need to call finish()
   #
   #   require 'pdf/wrapper'
-  #   pdf = PDF::Wrapper.new(:paper => :A4)
+  #   PDF::Wrapper.open("somefile.pdf", :paper => :A4)
+  #     pdf.text "Hello World", :font_size => 16
+  #   end
+  #
+  # == Changing the default font
+  #
+  #   require 'pdf/wrapper'
+  #   pdf = PDF::Wrapper.new("file.pdf", :paper => :A4)
   #   pdf.font("Monospace")
   #   pdf.text "Hello World", :font => "Sans Serif", :font_size => 18
   #   pdf.text "Pretend this is a code sample"
-  #   puts pdf.render
+  #   pdf.finish
+  #
   class Wrapper
 
     attr_reader :page
@@ -74,6 +97,9 @@ module PDF
     }
 
     # create a new PDF::Wrapper class to compose a PDF document
+    # Params:
+    # <tt>output</tt>:: Where to render the PDF to. Can be a string containing a filename,
+    #                   or an IO object (File, StringIO, etc)
     # Options:
     # <tt>:paper</tt>::   The paper size to use (default :A4)
     # <tt>:orientation</tt>::   :portrait (default) or :landscape
@@ -85,14 +111,14 @@ module PDF
     # <tt>:template</tt>::  The path to an image file. If specified, the first page of the document will use the specified image as a template.
     #                       The page will be sized to match the template size. The use templates on subsequent pages, see the options for
     #                       start_new_page.
-    def initialize(opts={})
+    def initialize(*args)
       # TODO: Investigate ways of using the cairo transform/translate/scale functionality to
       #       reduce the amount of irritating co-ordinate maths the user of PDF::Wrapper (ie. me!)
       #       is required to do.
       #       - translate the pdf body width so that it's 1.0 wide and 1.0 high?
       # TODO: find a way to add metadata (title, author, subject, etc) to the output file
       #       currently no way to specify this in cairo.
-      #       tentatively scheduled for cairo 1.8 - see:
+      #       tentatively scheduled for cairo 1.10 - see:
       #       - http://cairographics.org/roadmap/
       #       - http://lists.cairographics.org/archives/cairo/2007-September/011441.html
       #       - http://lists.freedesktop.org/archives/cairo/2006-April/006809.html
@@ -100,6 +126,25 @@ module PDF
       # ensure we have recentish cairo bindings
       raise "Ruby Cairo bindings version #{Cairo::BINDINGS_VERSION.join(".")} is too low. At least 1.5 is required" if Cairo::BINDINGS_VERSION.to_s < "150"
 
+      if args.size == 0
+        opts = {}
+        output = StringIO.new
+        warn "WARNING: deprecated call to PDF::Wrapper constructor. Check API documentation on new compulsory parameter"
+      elsif args.size == 1
+        if args.first.kind_of?(Hash)
+          opts = *args
+          output = StringIO.new
+          warn "WARNING: deprecated call to PDF::Wrapper constructor. Check API documentation on new compulsory parameter"
+        else
+          output = args.first
+          opts = {}
+        end
+      elsif args.size == 2
+        output, opts = *args
+      else
+        raise ArgumentError, 'Invalid parameters passed to constructor'
+      end
+
       options = {:paper => :A4,
                   :orientation => :portrait,
                   :background_color => :white
@@ -107,20 +152,10 @@ module PDF
       options.merge!(opts)
 
       # test for invalid options
-      options.assert_valid_keys(:paper, :orientation, :background_color, :margin_left, :margin_right, :margin_top, :margin_bottom, :template)
-      options[:paper] = options[:paper].to_sym
-      raise ArgumentError, "Invalid paper option" unless PAGE_SIZES.include?(options[:paper])
+      options.assert_valid_keys(:paper, :orientation, :background_color, :margin_left, :margin_right, 
+                                :margin_top, :margin_bottom, :io, :template)
 
-      # 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_dimensions(options[:orientation], options[:paper])
 
       # set page margins and dimensions of usable canvas
       @margin_left = options[:margin_left] || (@page_width * 0.05).ceil
@@ -129,7 +164,7 @@ module PDF
       @margin_bottom = options[:margin_bottom] || (@page_height * 0.05).ceil
 
       # initialize some cairo objects to draw on
-      @output = StringIO.new
+      @output = output
       @surface = Cairo::PDFSurface.new(@output, @page_width, @page_height)
       @context = Cairo::Context.new(@surface)
 
@@ -158,6 +193,21 @@ module PDF
       reset_cursor
     end
 
+    # convenience method, takes the same arguments as the constructor along with a block,
+    # and automatically finishes the PDF for you.
+    #
+    #= Usage
+    #
+    #   PDF::Wrapper.open("somefile.pdf") do |pdf|
+    #     pdf.text "hi!"
+    #   end
+    #
+    def self.open(output, options = {}, &block)
+      pdf = PDF::Wrapper.new(output, options)
+      yield pdf
+      pdf.finish
+    end
+
     #####################################################
     # Functions relating to calculating various page dimensions
     #####################################################
@@ -231,6 +281,14 @@ module PDF
       @context.current_point
     end
 
+    def x
+      @context.current_point.first
+    end
+
+    def y
+      @context.current_point.last
+    end
+
     def margin_bottom
       device_y_to_user_y(@margin_bottom).to_i
     end
@@ -305,27 +363,30 @@ module PDF
 
     # 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
+      # TODO: remove this method at some point. Deprecation started on 15th September 2008
+      warn "WARNING: render() is deprecated. See documentation for PDF::Wrapper#initialize for more information"
       finish
-      return @output.string
-    end
-
-    def render_to_file(filename) #nodoc
-      # TODO: remove this at some point
-      warn "WARNING: render_to_file() is deprecated, please use render_file()"
-      render_file filename
+      case @output
+      when StringIO then return @output.string
+      when File     then return File.read(@output.path)
+      else
+        return File.read(@output)
+      end
     end
 
     # save the rendered PDF to a file
     def render_file(filename)
+      # TODO: remove this method at some point. Deprecation started on 15th September 2008
+      warn "WARNING: render_file() is deprecated. See documentation for PDF::Wrapper#initialize for more information"
       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) }
+      case @output
+      when StringIO then
+        File.open(filename, "w") do |of|
+          of.write(@output.string)
+        end 
+      when File     then return FileUtils.cp(@output.path, filename)
+      else
+        return FileUtils.cp(@output, filename)
       end
     end
 
@@ -449,13 +510,30 @@ module PDF
       @context.move_to(margin_left,margin_top)
     end
 
+    def finish
+      # finalise the document
+      @context.show_page
+      @context.target.finish
+      #@output.close if io_output?
+      @surface.finish
+      #@surface.destroy
+      #@context.destroy
+      self
+    rescue Cairo::SurfaceFinishedError
+      # do nothing, we're happy that the surfaced has been finished
+    end
+
     # returns true if the PDF has already been rendered, false if it hasn't.
     # Due to limitations of the underlying libraries, content cannot be
     # added to a PDF once it has been rendered.
     #
     def finished?
-      @output.seek(@output.size - 6)
-      bytes = @output.read(6)
+      if io_output?
+        @output.seek(@output.size - 6)
+        bytes = @output.read(6)
+      else
+        bytes = @output[-6,6]
+      end
       bytes == "%%EOF\n" ? true : false
     end
 
@@ -488,11 +566,15 @@ module PDF
     # move to the next page
     #
     # options:
+    # <tt>:paper</tt>::   The paper size to use (default: same as the previous page)
+    # <tt>:orientation</tt>::   :portrait or :landscape (default: same as the previous page)
     # <tt>:pageno</tt>::    If specified, the current page number will be set to that. By default, the page number will just increment.
     # <tt>:template</tt>::  The path to an image file. If specified, the new page will use the specified image as a template. The page will be sized to match the template size
     #
     def start_new_page(opts = {})
-      opts.assert_valid_keys(:pageno, :template)
+      opts.assert_valid_keys(:paper, :orientation, :pageno, :template)
+
+      set_dimensions(opts[:orientation], opts[:paper])
 
       @context.show_page
 
@@ -522,12 +604,31 @@ module PDF
 
     private
 
-    def finish
-      # finalise the document
-      @context.show_page
-      @context.target.finish
-    rescue Cairo::SurfaceFinishedError
-      # do nothing, we're happy that the surfaced has been finished
+    def set_dimensions(orientation, paper)
+      # use the defaults if none were provided
+      orientation ||= @orientation
+      paper       ||= @paper
+
+      # safety check
+      orientation = orientation.to_sym
+      paper = paper.to_sym
+
+      raise ArgumentError, "Unrecognised paper size (#{paper})" if PAGE_SIZES[paper].nil?
+
+      # set page dimensions
+      if orientation.eql?(:portrait)
+        @page_width = PAGE_SIZES[paper][0]
+        @page_height = PAGE_SIZES[paper][1]
+      elsif orientation.eql?(:landscape)
+        @page_width = PAGE_SIZES[paper][1]
+        @page_height = PAGE_SIZES[paper][0]
+      else
+        raise ArgumentError, "Invalid orientation"
+      end
+
+      # make the new values the defaults
+      @orientation = orientation
+      @paper = paper
     end
 
     # runs the code in block, passing it a hash of options that might be
@@ -557,6 +658,14 @@ module PDF
       }
     end
 
+    def io_output?
+      if @output.respond_to?(:write) && @output.respond_to?(:read)
+        true
+      else
+        false
+      end
+    end
+
     # save and restore the cursor position around a block
     def save_coords(&block)
       origx, origy = current_point