prawn 0.2.3 → 0.3.0

data/README

@@ -12,6 +12,11 @@ Website:
 
 http://prawn.majesticseacreature.com
 
+Examples:
+http://github.com/sandal/prawn/tree/master/examples
+
+(or gem unpack prawn, if you want to run them locally)
+
 Bug Tracker / Wiki:
 
 http://prawn.lighthouseapp.com/projects/9398-prawn/home
@@ -32,13 +37,4 @@ Find us in #prawn on irc.freenode.net
   
 NOTES TO DEVELOPERS: 
 
-You will need the pdf-reader and test-spec gems to run Prawn.  Be sure to run
-the specs on both Ruby 1.8.6 and the latest Ruby 1.9 snapshot, as both versions
-are supported.  1.8.7 is *not* officially supported.
-
-Prawn relies on PDF::Inspector, a collection of PDF::Reader backed classes
-for analyzing PDF output.  This is provided as a submodule in Prawn's git
-repository, so be sure to do the following before running the specs:
-
-  git submodule init
-  git submodule update    
+See HACKING file for details on getting set up with a local build.

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake/testtask'
 require "rake/rdoctask"
 require "rake/gempackagetask"  
 
-PRAWN_VERSION = "0.2.3" 
+PRAWN_VERSION = "0.3.0" 
 
 task :default => [:test]
        
@@ -26,7 +26,8 @@ desc "genrates documentation"
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_files.include( "README",
                            "COPYING",
-                           "LICENSE", "lib/" )
+                           "LICENSE", 
+                           "HACKING", "lib/" )
   rdoc.main     = "README"
   rdoc.rdoc_dir = "doc/html"
   rdoc.title    = "Prawn Documentation"
@@ -35,22 +36,12 @@ end
 desc "run all examples, and then diff them against reference PDFs"
 task :examples do 
   mkdir_p "output"
-  examples = Dir["examples/*.rb"]
+  examples = Dir["examples/**/*.rb"]
   t = Time.now
   puts "Running Examples"
   examples.each { |file| `ruby -Ilib #{file}` }  
   puts "Ran in #{Time.now - t} s"        
   `mv *.pdf output`                     
-                   
-  unless RUBY_VERSION < "1.9"    
-    puts "Checking for differences..."
-    output = Dir["output/*.pdf"]
-    ref    = Dir["reference_pdfs/*.pdf"]   
-    output.zip(ref).each do |o,r|
-      system "diff -q #{o} #{r}"
-    end                      
-  end
-
 end
 
 spec = Gem::Specification.new do |spec|

data/data/encodings/win_ansi.txt

@@ -0,0 +1,29 @@
+# A mapping of WinAnsi (win-1252) characters to unicode. Anything
+# not specified is left unchanged
+80;20AC
+82;201A
+83;0192
+84;201E
+85;2026
+86;2020
+87;2021
+88;02C6
+89;2030
+8A;0160
+8B;2039
+8C;0152
+8E;017D
+91;2018
+92;2019
+93;201C
+94;201D
+95;2022
+96;2013
+97;2014
+98;02DC
+99;2122
+9A;0161
+9B;203A
+9C;0152
+9E;017E
+9F;0178

data/examples/bounding_box/bounding_boxes.rb

@@ -0,0 +1,44 @@
+# encoding: utf-8
+#
+# This example demonstrates the basic functionality of Prawn's bounding boxes.
+# Note that top level bounding boxes are positioned relative to the margin_box.
+# 
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require 'prawn'
+
+Prawn::Document.generate("bounding_boxes.pdf") do
+
+  # Generates a box with a top-left of [100,600] and a top-right of [300,600]
+  # The box automatically expands as the cursor moves down the page.  Notice
+  # that the final coordinates are outlined by a top and bottom line drawn
+  # relatively using calculations from +bounds+.
+  #
+  bounding_box [100,600], :width => 200 do
+    move_down 10
+    text "The rain in spain falls mainly on the plains " * 5
+    move_down 20
+    stroke do
+      line bounds.top_left,    bounds.top_right
+      line bounds.bottom_left, bounds.bottom_right
+    end
+  end
+
+  # Generates a bounding box from [100, cursor], [300, cursor - 200],
+  # where cursor is the current y position.
+  #
+  bounding_box [100,cursor], :width => 200, :height => 200 do
+    stroke do
+      circle_at [100,100], :radius => 100
+      line bounds.top_left, bounds.bottom_right
+      line bounds.top_right, bounds.bottom_left
+    end
+    
+    # Generates a nested bonding box and strokes its boundaries.  Note that
+    # this box is anchored relative to its parent bounding box, not the
+    # margin_box 
+    bounding_box [50,150], :width => 100, :height => 100 do
+      stroke_bounds
+    end
+  end
+
+end                 

data/examples/bounding_box/lazy_bounding_boxes.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# This example demonstrates Document#lazy_bounding_box, which is used for
+# storing a set of drawing instructions to be executed later.  This is used
+# for header and footer support in Prawn, and can be used for repeating page
+# elements in general.
+#
+# Note that once a lazy bounding box is positioned, it calculates its anchor
+# relative to its parent bounding box.  It will be positioned at this exact
+# location each time it is redrawn, regardless of the bounds 
+# LazyBoundingBox#draw is in.
+# 
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+file = "lazy_bounding_boxes.pdf"
+Prawn::Document.generate(file, :skip_page_creation => true) do
+  point = [bounds.right-50, bounds.bottom + 25]
+  page_counter = lazy_bounding_box(point, :width => 50) do
+    text "Page: #{page_count}"
+  end 
+  
+  10.times do
+    start_new_page
+    text "Some filler text for the page"  
+    page_counter.draw
+  end
+end

data/examples/bounding_box/padded_box.rb

@@ -0,0 +1,24 @@
+# encoding: utf-8
+#
+# Padded box is a kind of bounding box which places padding on all sides of
+# the current bounds.  This is easier to see than explain, so please run the
+# example.
+#
+# Feature borrowed from Josh Knowle's pt at:
+# http://github.com/joshknowles/pt/tree/master
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require 'prawn'
+
+Prawn::Document.generate('padded_box.pdf') do
+  stroke_bounds
+  text "Margin box"
+  padded_box(25) do
+    stroke_bounds
+    text "Bounding box padded by 25 on all sides from the margins"
+    padded_box(50) do
+      stroke_bounds
+      text "Bounding box padded by 50 on all sides from the parent bounds"
+    end
+  end
+end

data/examples/{russian_boxes.rb → bounding_box/russian_boxes.rb}

@@ -1,4 +1,10 @@
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+# encoding: utf-8
+#
+# This example is mostly just for fun, and shows how nested bounding boxes
+# can simplify calculations.  See the other files in examples/bounding_box
+# for more basic uses.
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require 'prawn'
 
 class Array
@@ -20,15 +26,12 @@ def recurse_bounding_box(pdf, max_depth=5, depth=1)
   left_top_corners = [5, box.right-width-5].combine [box.top-5, height+5]
   left_top_corners.each do |lt|
     pdf.bounding_box(lt, :width=>width, :height=>height) do
-      pdf.stroke_rectangle [0,height], width, height
+      pdf.stroke_bounds
       recurse_bounding_box(pdf, max_depth, depth+1) if depth<max_depth
     end
   end
 end
 
-
 Prawn::Document.generate("russian_boxes.pdf") do |pdf|
   recurse_bounding_box(pdf)
-end
-
-
+end

data/examples/general/background.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+#
+# This example demonstrates the use of the new :background option when
+# generating a new Document.  Image is assumed to be pre-fit for your page
+# size, and will not be rescaled.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+img = "#{Prawn::BASEDIR}/data/images/letterhead.jpg"
+
+Prawn::Document.generate("background.pdf", :background => img) do
+  text_options.update(:size => 18, :align => :right)
+  text "My report caption"
+  text_options.update(:size => 12, :align => :left, :spacing => 2)
+  move_down font.height * 2
+  text "Here is my text explaning this report. " * 20
+  move_down font.height
+  text "I'm using a soft background. " * 40
+end

data/examples/{canvas.rb → general/canvas.rb}

@@ -1,11 +1,15 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+#
+# Demonstrates how to enable absolute positioning in Prawn by temporarily
+# removing the margin_box via Document#canvas()
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 Prawn::Document.generate("canvas.pdf") do
   canvas do
     text "This text should appear at the absolute top left"
+
     # stroke a line to show that the relative coordinates are the same as absolute
     stroke_line [bounds.left,bounds.bottom], [bounds.right,bounds.top]
   end

data/examples/general/measurement_units.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+#
+# Generates a ruler and also demonstrates prawn/measurement_extensions.
+# It's better to run this example and examine its output than to worry about
+# its particular implementation, though some might find that interesting as
+# well.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+require "prawn/measurement_extensions"
+
+# this makes the following units available (Millimeters, Centimeters, Decimeters, Meters, Inches, Foot, Yards, Points)
+# Methodname is the common abbravation for the unit (mm, cm, dm, m, in, ft, yd, pt)
+# Usage: '10.mm'. 
+# This converts 10mm to PDF points, which Prawn uses internally.
+
+pdf = Prawn::Document.new(
+:page_size => "A4", 
+:left_margin => 10.mm,    # different
+:right_margin => 1.cm,    # units
+:top_margin => 0.1.dm,    # work
+:bottom_margin => 0.01.m) # well
+
+pdf.font.size = 6
+pdf.line_width = 0.05
+
+units_long = %w[Millimeters Centimeters Decimeters Inches Foot Points]
+units = %w[mm cm dm in ft pt]
+offset_multiplier = 2.cm
+temp = "Units\n"
+
+units.each_with_index do |unit, unit_index| #iterate through all units that make sense to display on a sheet of paper
+  one_unit_in_pt = eval "1.#{unit}" # calc the width of one unit
+  temp << "1#{unit} => #{one_unit_in_pt}pt\n" #puts converted unit in points
+  
+  offset = offset_multiplier * unit_index
+  pdf.text units[unit_index], :at => [offset + 0.5.mm, pdf.bounds.top - 2.mm]
+  
+  pdf.stroke_line(offset, pdf.bounds.top, offset, pdf.bounds.bottom)
+  
+  0.upto(((pdf.bounds.height - 5.mm) / one_unit_in_pt).to_i) do |i| # checks, how many strokes can be drawn
+    pdf.stroke_line(offset, i * one_unit_in_pt, (i % 5 == 0 ? 6.mm : 3.mm) + offset, i * one_unit_in_pt) # every fifth stroke is twice as large like on a real ruler
+    pdf.text "#{i}#{unit}", :at => [7.mm + offset, i * one_unit_in_pt] unless unit == "mm" && i % 5 != 0 || unit == "pt" && i % 10 != 0 # avoid text too close to each other
+  end    
+end
+
+pdf.text_box temp,
+  :width    => 5.cm, :height => pdf.font.height * units_long.length,
+  :at       => [offset_multiplier * units_long.length, pdf.bounds.top]
+
+pdf.render_file "measurement_units.pdf"

data/examples/{multi_page_layout.rb → general/multi_page_layout.rb}

@@ -1,6 +1,9 @@
-# coding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+# encoding: utf-8
+#
+# This demonstrates that Prawn can modify page size, margins and layout for 
+# each individual page, via Document#start_new_page()
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 Prawn::Document.generate("multi-layout.pdf", :page_layout => :landscape) do |pdf|

data/examples/{page_geometry.rb → general/page_geometry.rb}

@@ -1,6 +1,10 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+#
+# This demonstrates basic page layout and landscape options for Prawn
+# documents.  The style used here is a bit out of date, see 
+# multi_page_layout.rb for a more modern example.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 def pdf(*options)  

data/examples/{image.rb → graphics/basic_images.rb}

@@ -1,9 +1,13 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+#
+# Demonstrates basic image embedding and positioning functionality.
+# For positioning images alongside flowing text, see the image_flow.rb
+# example.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
    
-Prawn::Document.generate("image.pdf", :page_layout => :landscape) do     
+Prawn::Document.generate("basic_images.pdf", :page_layout => :landscape) do     
   pigs = "#{Prawn::BASEDIR}/data/images/pigs.jpg" 
   image pigs, :at => [50,450], :scale => 0.5                                       
   
@@ -20,4 +24,4 @@ Prawn::Document.generate("image.pdf", :page_layout => :landscape) do
 
   ruport = "#{Prawn::BASEDIR}/data/images/ruport_transparent.png"  
   image ruport, :at => [50,525] 
-end
+end

data/examples/graphics/cmyk.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+#
+# Demonstrates Prawn's support for CMYK images and colors.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+Prawn::Document.generate("cmyk.pdf", :page_layout => :landscape) do
+  fill_color 50, 100, 0, 0
+  text "Prawn is CYMK Friendly"
+  fractal = "#{Prawn::BASEDIR}/data/images/fractal.jpg"
+  image fractal, :at => [50,450]
+end

data/examples/graphics/curves.rb

@@ -0,0 +1,12 @@
+# encoding: utf-8
+#
+# Demonstrates simple curve and circle usage
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+
+pdf = Prawn::Document.new
+pdf.move_to [100,100]
+pdf.stroke_curve_to [50,50], :bounds => [[20,90], [90,90]]  
+pdf.fill_circle_at [200,200], :radius => 10
+pdf.render_file "curves.pdf"

data/examples/{hexagon.rb → graphics/hexagon.rb}

@@ -1,6 +1,8 @@
 # encoding: utf-8
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', 'lib')
+#
+# Draws and fills a Hexagon using Document#polygon
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
 require "prawn"
 
 pdf = Prawn::Document.new
@@ -8,7 +10,5 @@ pdf = Prawn::Document.new
 pdf.fill_color "ff0000"
 pdf.fill_polygon [100, 250], [200, 300], [300, 250],
                  [300, 150], [200, 100], [100, 150]            
-                  
-pdf.render_file "hexagon.pdf"
-              
 
+pdf.render_file "hexagon.pdf"

data/examples/graphics/image_fit.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+#
+# Demonstrates fitting an image within a rectangular width and height.
+# The image will be scaled down to fit within the box, while preserving
+# the aspect ratio.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+   
+Prawn::Document.generate("image_fit.pdf", :page_layout => :landscape) do
+
+  pigs = "#{Prawn::BASEDIR}/data/images/pigs.jpg" 
+  stroke_rectangle [50,450], 200, 200
+  image pigs, :at => [50,450], :fit => [200,200]
+
+end

data/examples/graphics/image_flow.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+#
+# Demonstrates automated flowing and positioning of images, as well as
+# aligining images along the x-axis via the :position argument.  This is
+# useful when used in combination with flowing text, where the exact final
+# position of the image is not known ahead of time.
+#
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+require "prawn"
+   
+Prawn::Document.generate("image-flow.pdf", :page_layout => :landscape) do  
+  font.size = 8                           
+  stef = "#{Prawn::BASEDIR}/data/images/stef.jpg"  
+  
+  text "Image at default position with no arguments"
+  
+  move_down 10
+  
+  image stef 
+  
+  text "Centered image flowing" 
+  
+  image stef, :position => :center   
+  
+  text "Right aligned image flowing"
+                 
+  image stef, :position => :right  
+  
+  text "Explicitly left aligned image flowing"
+                 
+  move_down 10                 
+                 
+  image stef, :position => :left     
+  
+  text "Flowing image at x=50"     
+  
+  image stef, :position => 50
+end