prawn-core 0.5.1 → 0.6.1

data/HACKING

@@ -0,0 +1,46 @@
+= Hacking on Prawn
+
+A stub file that'll eventually get bigger
+
+== NOTES 
+
+Install test-spec, pdf-reader, and mocha from RubyGems
+
+Be sure to load in the necessary git submodules as well:
+
+  git submodule init
+  git submodule update
+
+If you are running on Ruby 1.9.1, you will need Test::Unit 1.2.3
+
+  gem install test-unit -v 1.2.3
+  
+== Patch process 
+
+  1. File a ticket in the tracker that contains the code your issue is
+     related to:
+
+   http://github.com/sandal/prawn/issues
+   http://github.com/sandal/prawn-layout/issues
+   http://github.com/sandal/prawn-format/issues
+
+  2. Fork any necessary repositories on Github, make your changes
+  3. Submit pull request so Gregory is notified
+  4. Include your ticket number in commit messages       
+  
+  If you are working on a ticket that has already been created, skip step 1.
+  
+  All feature enhancements should come with an example in the examples/ dir,
+  and preferably, some specs.
+  
+  All bug reports should have a reproducible example in bugs/ and preferably,
+  some specs.
+  
+== Support
+
+  Find us in #prawn on irc.freenode.net
+  <sandal> - Gregory Brown
+  <yob>    - James Healy
+  
+  Otherwise, use the mailing list:
+  http://groups.google.com/group/prawn-ruby

data/README

@@ -27,8 +27,8 @@ But prawn can do a lot more:
 
 ...gives you an _really_ big page.
 
- Prawn::Document.new(:size => [11.32, 8.49],
-                     :page_orientation => :portrait)
+ Prawn::Document.new(:page_size   => [11.32, 8.49],
+                     :page_layout => :portrait)
 
 ...giving you a postage stamp.
 
@@ -107,19 +107,25 @@ For inline styling and advanced formatting:
 
 http://github.com/sandal/prawn-format/tree/stable/examples
 
-(or gem unpack prawn-core, prawn-format, and prawn-layout if you want to run them locally)
+For encryption, password protection, and permissions:
+
+http://github.com/madriska/prawn-security/tree/stable/examples
+
+(or gem unpack prawn-core, prawn-format, prawn-security and prawn-layout if you want to run them locally)
 
 === Bug Tracker / Wiki:
 
 http://github.com/sandal/prawn/issues
 http://github.com/sandal/prawn-layout/issues
 http://github.com/sandal/prawn-format/issues
+http://github.com/madriska/prawn-security/issues
 
 === Source Code:
 
 http://github.com/sandal/prawn
 http://github.com/sandal/prawn-layout
 http://github.com/sandal/prawn-format
+http://github.com/madriska/prawn-security
 
 === Mailing List:
 

data/Rakefile

@@ -4,15 +4,16 @@ require 'rake/testtask'
 require "rake/rdoctask"
 require "rake/gempackagetask"  
 
-PRAWN_VERSION = "0.5.1" 
+PRAWN_VERSION = "0.6.1" 
 
 task :default => [:test]
        
-desc "Run all tests, test-spec and mocha required"
+desc "Run all tests, test-spec, mocha, and pdf-reader required"
 Rake::TestTask.new do |test|
-  test.libs << "spec"
-  test.test_files = Dir[ "spec/*_spec.rb" ]
-  test.verbose = true
+  # test.ruby_opts  << "-w"  # .should == true triggers a lot of warnings
+  test.libs       << "spec"
+  test.test_files =  Dir[ "spec/*_spec.rb" ]
+  test.verbose    =  true
 end
 
 desc "Show library's code statistics"
@@ -56,7 +57,7 @@ spec = Gem::Specification.new do |spec|
 
   spec.test_files = Dir[ "test/*_test.rb" ]
   spec.has_rdoc = true
-  spec.extra_rdoc_files = %w{README LICENSE COPYING}
+  spec.extra_rdoc_files = %w{HACKING README LICENSE COPYING}
   spec.rdoc_options << '--title' << 'Prawn Documentation' <<
                        '--main'  << 'README' << '-q'
   spec.author = "Gregory Brown"

data/examples/bounding_box/stretched_nesting.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+#
+# This example demonstrates how nested bounding boxes work when the outer box is
+# stretchy and includes several inner boxes of different sizes.
+
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("stretched_nesting.pdf", :page_layout => :landscape) do
+
+  def stroke_dashed_bounds
+    dash(1)
+    stroke_bounds
+    undash
+  end
+
+  bounding_box [100,400], :width => 500 do
+
+    bounding_box [0, bounds.top], :width => 200, :height => 100 do
+      stroke_bounds
+    end
+
+    bounding_box [200, bounds.top], :width => 150 do
+      indent(5) do
+        text "This box is longest, so it stretches the parent box. \n"*5
+      end
+    end
+
+    bounding_box [350, bounds.top], :width => 150 do
+      text "I AM SANTA CLAUS!!!"
+    end
+
+    stroke_dashed_bounds
+
+  end
+
+  bounding_box [100, 250], :width => 500 do
+
+    bounding_box [0, bounds.top], :width => 100, :height => 100 do
+      text "1"
+      stroke_bounds
+    end
+
+    bounding_box [125, bounds.top], :width => 50, :height => 25 do
+      text "2"
+      stroke_bounds
+    end
+
+    bounding_box [200, bounds.top - 50], :width => 50, :height => 125 do
+      text "3"
+      stroke_bounds
+    end
+
+    bounding_box [350, bounds.top - 100], :width => 20, :height => 20 do
+      text "4"
+      stroke_bounds
+    end
+
+    bounding_box [400, bounds.height - 150], :width => 100, :height => 100 do
+      text "5"
+      stroke_bounds
+    end
+
+    stroke_dashed_bounds
+
+  end
+
+end

data/examples/general/margin.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+#
+# This demonstrates the Prawn options for document and page margin, similar to CSS shorthand.
+#
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+LOREM = ("Lorem ipsum dolor sit amet, consectetur adipisicing elit, "+
+"sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. "+
+"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris "+
+"nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in "+
+"reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla "+
+"pariatur. Excepteur sint occaecat cupidatat non proident, sunt in " +
+"culpa qui officia deserunt mollit anim id est laborum. ") * 20
+
+Prawn::Document.generate("margin.pdf", :margin => 100) do |pdf|
+
+  pdf.text "100 on all sides", :style => :bold
+  pdf.text LOREM
+  
+  pdf.start_new_page(:margin => 100, :left_margin => 0)
+  pdf.text "100 on all sides but 0 on the left", :style => :bold
+  pdf.text LOREM
+
+  pdf.start_new_page(:margin => [100, 0])
+  pdf.text "100 top and bottom, 0 left and right.", :style => :bold
+  pdf.text LOREM
+  
+  pdf.start_new_page(:margin => [100, 0, 50])
+  pdf.text "100 top, 0 left and right, 50 bottom.", :style => :bold
+  pdf.text LOREM
+  
+  pdf.start_new_page(:margin => [0, 50, 100, 150])
+  pdf.text "0 top, 50 right, 100 bottom, 150 left.", :style => :bold
+  pdf.text LOREM
+
+end

data/examples/general/multi_page_layout.rb

@@ -13,4 +13,6 @@ Prawn::Document.generate("multi-layout.pdf", :page_layout => :landscape) do |pdf
    pdf.text "This is on legal paper size"      
    pdf.start_new_page(:left_margin => 150, :right_margin => 150)
    pdf.text "This page has very wide left and right margins, causing a squeeze"
-end
+   pdf.start_new_page(:margin => 300, :right_margin => 0)
+   pdf.text "This page has even wider margins on all sides except for the right side, where it's 0"
+end

data/examples/general/page_numbering.rb

@@ -0,0 +1,15 @@
+# encoding: utf-8
+#
+# This example demonstrates how to add a "page k of n"
+# template to your documents.
+#
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("page_with_numbering.pdf") do
+  text "Hai"
+  start_new_page
+  text "bai"
+  start_new_page
+  text "-- Hai again"
+  number_pages "<page> in a total of <total>", [bounds.right - 50, 0]  
+end

data/examples/general/stamp.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+#
+# Demonstrate use of stamps
+#
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("stamp.pdf") do
+
+  create_stamp("page_template") do
+    text "This is my page template", :at => [0, bounds.top - 4 * font.height] 
+    text "This is also in my page template", :at => [0, 0] 
+  end
+
+  create_stamp("odd_page_template") do
+    text "This is the odd page template", 
+      :at => [0, bounds.top - 4 * font.height] 
+    text "This is also in the odd page template", :at => [0, 0] 
+  end
+
+  create_stamp("even_page_template") do
+    text "This is the even page template", 
+      :at => [0, bounds.top - 4 * font.height] 
+    text "This is also in the even page template", :at => [0, 0] 
+  end
+  
+  stamp("odd_page_template")
+
+  create_stamp("MyStamp") do
+    fill_color("ff0000")
+    fill_circle_at([0, 0], :radius => 20)
+    fill_color("000000")
+    fill_circle_at([10, 10], :radius => 20)
+  end
+
+  10.times do |i|
+    10.times do |j|
+      stamp_at("MyStamp", [100 + j * 50, bounds.top - 100 - i * 50])
+    end
+  end
+
+  4.times do |i|
+    start_new_page
+    stamp("#{i % 2 == 0 ? 'even' : 'odd'}_page_template")
+  end
+end

data/examples/graphics/stroke_cap_and_join.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+#
+# Stroke dashing can be applied to any line or curve
+
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("stroke_cap_and_join.pdf") do
+  self.line_width = 25
+  x0 = bounds.left + 100
+  x1 = bounds.left + 200
+  x2 = bounds.left + 300
+
+  y = bounds.top - 125
+
+  3.times do |i|
+    case i
+    when 0
+      self.join_style = :miter
+    when 1
+      self.join_style = :round
+    when 2
+      self.join_style = :bevel
+    end
+    stroke do
+      move_to(x0, y)
+      line_to(x1, y + 100)
+      line_to(x2, y)
+    end
+    y -= 100
+  end
+  
+
+  3.times do |i|
+    case i
+    when 0
+      self.cap_style = :butt
+    when 1
+      self.cap_style = :round
+    when 2
+      self.cap_style = :projecting_square
+    end
+    stroke_line([x0, y, x2, y])
+    y -= 30
+  end
+end

data/examples/graphics/stroke_dash.rb

@@ -0,0 +1,42 @@
+# encoding: utf-8
+#
+# Stroke dashing can be applied to any line or curve
+
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("stroke_dash.pdf") do
+  self.line_width = 1
+  base_y = bounds.top
+
+  100.times do |i|
+    length = i / 4 + 1
+    # space between dashes same length as dash
+    space = length
+    # start with dash
+    phase = 0
+    case i % 4
+    when 0
+      base_y -= 10
+    when 1
+      # start with space between dashes
+      phase = length
+    when 2
+      base_y -= 10
+      # space between dashes half as long as dash
+      space = length * 0.5
+    when 3
+      # space between dashes half as long as dash
+      space = length * 0.5
+      # start with space between dashes
+      phase = length
+    end
+    dash(length, :space => space, :phase => phase)
+    points = [bounds.left, base_y - 2 * i, bounds.right, base_y - 2 * i]
+    stroke_line(points)
+  end
+  i = 100
+  base_y -= 10
+  undash
+  points = [bounds.left, base_y - 2 * i, bounds.right, base_y - 2 * i]
+  stroke_line(points)
+end

data/examples/graphics/transparency.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+#
+# Demonstrate use of transparency
+#
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("transparency.pdf") do
+  fill_color("ff0000")
+  fill_circle_at([200, 200], :radius => 200)
+  transparent(0.5, 1) do
+    fill_color("000000")
+    stroke_color("ffffff")
+    fill_and_stroke_circle_at([300, 300], :radius => 200)
+    fill_color("ffffff")
+    text "transparency " * 150, :size => 18
+  end
+  
+  start_new_page
+
+  fill_color("000000")
+  fill_rectangle([0, bounds.top], 200, 100)
+  transparent(0.5) do
+    fill_color("ff0000")
+    fill_rectangle([100, bounds.top - 50], 200, 100)
+  end
+end

data/examples/text/text_box_returning_excess.rb

@@ -0,0 +1,51 @@
+# encoding: utf-8
+#
+# A text box is positioned by a top-left corner, width, and height and is
+# essentially an invisible rectangle that the text will flow within.  If the
+# text exceeds the boundaries, it is either truncated, replaced with some
+# ellipses, or set to expand beyond the bottom boundary.
+#
+require "#{File.dirname(__FILE__)}/../example_helper.rb"
+
+Prawn::Document.generate("text_box_returning_excess.pdf") do
+
+  # Note that without the initial space in p_break, newlines may be eaten by
+  # the wrap/unwrap process that happens inside the text box.
+  p_break = " \n\n"
+  callout = "Lorem ipsum dolor sit amet"
+  lorem   = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.#{p_break}Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.#{p_break}Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
+
+  box_height = font.height * 5
+
+  # Add a callout box that the rest of the text should flow around
+  font_size(18) do
+    text_box callout, {
+      :width    => 100,
+      :height   => font.height * 3,
+      :overflow => :truncate,
+      :at       => [100, bounds.top - box_height - 4]
+    }
+  end
+
+  excess_text = text_box lorem + p_break + lorem, {
+    :width    => 300,
+    :height   => box_height,
+    :overflow => :truncate,
+    :at       => [100, bounds.top],
+  }
+
+  excess_text = text_box excess_text, {
+    :width    => 200,
+    :height   => box_height,
+    :overflow => :truncate,
+    :at       => [200, bounds.top - box_height],
+  }
+
+  text_box excess_text, {
+    :width    => 300,
+    :height   => box_height,
+    :overflow => :expand,
+    :at       => [100, bounds.top - box_height * 2],
+  }
+
+end

data/lib/prawn/byte_string.rb

@@ -0,0 +1,7 @@
+# encoding: utf-8
+module Prawn
+  # This is used to differentiate strings that must be encoded as
+  # a byte string, such as binary data from encrypted strings.
+  class ByteString < String #:nodoc:
+  end
+end

data/lib/prawn/core.rb

@@ -1,11 +1,9 @@
 # encoding: utf-8
-# 
 # Prawn : A library for PDF generation in Ruby
 #
 # Copyright April 2008, Gregory Brown. All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
-        
 %w[ttfunk/lib].each do |dep|
   $LOAD_PATH.unshift(File.dirname(__FILE__) + "/../../vendor/#{dep}")
 end
@@ -27,7 +25,7 @@ module Prawn
   # The base source directory for Prawn as installed on the system
   BASEDIR = File.expand_path(File.join(dir, '..', '..'))
   
-  VERSION = "0.5.1"
+  VERSION = "0.6.1"
   
   extend self
 
@@ -35,11 +33,10 @@ module Prawn
   # are used.  Off by default.
   #
   # Example:
-  #
-  #   >> Prawn::Document.new(:tomato => "Juicy")  
-  #   Prawn::Errors::UnknownOption:   
-  #   Detected unknown option(s): [:tomato] 
-  #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]  
+  #   >> Prawn::Document.new(:tomato => "Juicy")
+  #   Prawn::Errors::UnknownOption: 
+  #   Detected unknown option(s): [:tomato]
+  #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]
   #
   attr_accessor :debug
   
@@ -75,10 +72,12 @@ end
 require "prawn/compatibility"
 require "prawn/errors"
 require "prawn/pdf_object"
+require "prawn/object_store"
 require "prawn/graphics"
 require "prawn/images"
 require "prawn/images/jpg"
 require "prawn/images/png"
+require "prawn/stamp"
 require "prawn/document"
 require "prawn/reference"
 require "prawn/font"

data/lib/prawn/document/annotations.rb

@@ -14,15 +14,16 @@ module Prawn
     # Provides very low-level support for annotations.  These extensions are
     # mainly for use by prawn-format, so be sure to check that out if all
     # you need is basic internal or external links.
+    #
     module Annotations
       
       # Adds a new annotation (section 8.4 in PDF spec) to the current page.
       # +options+ must be a Hash describing the annotation.
       #
       def annotate(options)
-        @current_page.data[:Annots] ||= []
+        current_page.data[:Annots] ||= []
         options = sanitize_annotation_hash(options)
-        @current_page.data[:Annots] << ref(options)
+        current_page.data[:Annots] << ref(options)
         return options
       end
 

data/lib/prawn/document/bounding_box.rb

@@ -25,7 +25,7 @@ module Prawn
     # Usage:
     # 
     # * Bounding box 100pt x 100pt in the absolute bottom left of the 
-    # containing box:
+    #   containing box:
     # 
     #   pdf.bounding_box([0,100], :width => 100, :height => 100)
     #     stroke_bounds
@@ -56,10 +56,10 @@ module Prawn
     #      "and return to the margin_box"
     #   end
     #
-    # Note that this is a low level tool and is designed primarily for 
-    # building other abstractions.  If you just want to flow some text on
-    # a page, look into span() or text_box()
-    # 
+    # Note, this is a low level tool and is designed primarily for building
+    # other abstractions.  If you just need to flow text on the page, you
+    # will want to look at span() and text_box() instead
+    #
     # ==Translating Coordinates
     # 
     # When translating coordinates, the idea is to allow the user to draw
@@ -122,8 +122,8 @@ module Prawn
     # ==Stretchyness
     # 
     # If you do not specify a height to a bounding box, it will become stretchy
-    # and its height will be calculated according to the last drawing position
-    # within the bounding box:
+    # and its height will be calculated automatically as you stretch the box
+    # downwards.
     # 
     #  pdf.bounding_box([100,400], :width => 400) do
     #    pdf.text("The height of this box is #{pdf.bounds.height}")
@@ -141,8 +141,8 @@ module Prawn
     #  pdf.bounding_box([50,500], :width => 200, :height => 300) do
     #    pdf.stroke_bounds
     #    pdf.canvas do
+    #      Positioned outside the containing box at the 'real' (300,450)
     #      pdf.bounding_box([300,450], :width => 200, :height => 200) do
-    #        # Positioned outside the containing box at the 'real' (300,450)
     #        pdf.stroke_bounds
     #      end
     #    end
@@ -185,7 +185,9 @@ module Prawn
       user_block.call   
       self.y = @bounding_box.absolute_bottom unless options[:hold_position]
 
-      @bounding_box = parent_box 
+      created_box, @bounding_box = @bounding_box, parent_box
+
+      return created_box
     end   
 
     # Low level layout helper that simplifies coordinate math.
@@ -369,8 +371,11 @@ module Prawn
       # the box to the current drawing position.
       #
       def height  
-        @height || absolute_top - @parent.y
+        return @height if @height
+        @stretched_height = [(absolute_top - @parent.y), @stretched_height.to_f].max
       end    
+
+      alias_method :update_height, :height
        
       # Returns +false+ when the box has a defined height, +true+ when the height
       # is being calculated on the fly based on the current vertical position.

data/lib/prawn/document/column_box.rb

@@ -89,9 +89,7 @@ module Prawn
         absolute_right - (width_of_column * columns_from_right)
       end
 
-      # Wrap position to the next column, starting a new page if necessary
-      #
-      def move_past_bottom
+      def move_past_bottom #:nodoc:
         @current_column = (@current_column + 1) % @columns
         @parent.y = @y
         if 0 == @current_column