prawn 0.14.0 → 0.15.0

data/lib/prawn/images/image.rb

@@ -10,6 +10,7 @@ require 'digest/sha1'
 module Prawn
   module Images
     class Image
+      # @group Extension API
 
       def calc_image_dimensions(options)
         w = options[:width] || width

data/lib/prawn/images/jpg.rb

@@ -10,10 +10,13 @@ require 'stringio'
 
 module Prawn
   module Images
+
     # A convenience class that wraps the logic for extracting the parts
     # of a JPG image that we need to embed them in a PDF
     #
     class JPG < Image
+      # @group Extension API
+      
       attr_reader :width, :height, :bits, :channels
       attr_accessor :scaled_width, :scaled_height
 

data/lib/prawn/images/png.rb

@@ -17,6 +17,8 @@ module Prawn
     # of a PNG image that we need to embed them in a PDF
     #
     class PNG < Image
+      # @group Extension API
+
       attr_reader :palette, :img_data, :transparency
       attr_reader :width, :height, :bits
       attr_reader :color_type, :compression_method, :filter_method

data/lib/prawn/layout.rb

@@ -2,19 +2,14 @@ require_relative "table"
 require_relative "layout/grid"
 
 module Prawn
+  module Errors
 
- module Errors
+    # This error is raised when table data is malformed
+    #
+    InvalidTableData = Class.new(StandardError)
 
-   # This error is raised when table data is malformed
-   #
-   InvalidTableData = Class.new(StandardError)
-
-   # This error is raised when an empty or nil table is rendered
-   #
-   EmptyTable = Class.new(StandardError)
- end
-
- module Layout
-
- end
+    # This error is raised when an empty or nil table is rendered
+    #
+    EmptyTable = Class.new(StandardError)
+  end
 end

data/lib/prawn/layout/grid.rb

@@ -1,11 +1,18 @@
 module Prawn
   class Document
+    # @group Experimental API
 
     # Defines the grid system for a particular document.  Takes the number of
     # rows and columns and the width to use for the gutter as the
     # keys :rows, :columns, :gutter, :row_gutter, :column_gutter
     #
+    # Note that a completely new grid object is built each time define_grid()
+    # is called. This means that all subsequent calls to grid() will use
+    # the newly defined Grid object -- grids are not nestable like 
+    # bounding boxes are.
+
     def define_grid(options = {})
+      @boxes = nil
       @grid = Grid.new(self, options)
     end
 
@@ -33,6 +40,8 @@ module Prawn
 
     # A Grid represents the entire grid system of a Page and calculates
     # the column width and row height of the base box.
+    #
+    # @private
     class Grid
       attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter
       def initialize(pdf, options = {}) # :nodoc:
@@ -86,7 +95,8 @@ module Prawn
     # A Grid object has methods that allow easy access to the coordinates of
     # its corners, which can be plugged into most existing prawnmethods.
     #
-    class Box #:nodoc:
+    # @private
+    class GridBox
       attr_reader :pdf
 
       def initialize(pdf, i, j)
@@ -187,7 +197,9 @@ module Prawn
     end
 
     # A MultiBox is specified by 2 Boxes and spans the areas between.
-    class MultiBox < Box #:nodoc:
+    #
+    # @private
+    class MultiBox < GridBox #:nodoc:
       def initialize(pdf, b1, b2)
         @pdf = pdf
         @bs = [b1, b2]
@@ -249,7 +261,7 @@ module Prawn
 
     private
     def single_box(i, j)
-      Box.new(self, i, j)
+      GridBox.new(self, i, j)
     end
 
     def multi_box(b1, b2)

data/lib/prawn/measurement_extensions.rb

@@ -7,11 +7,15 @@
 
 require_relative 'measurements'
 
+# @group Stable API
+
 class Numeric
   include Prawn::Measurements
   # prawns' basic unit is PostScript-Point
   # 72 points per inch
 
+  # @group Experimental API
+  
   def mm
     return mm2pt(self)
   end

data/lib/prawn/measurements.rb

@@ -4,6 +4,8 @@
 # Copyright December 2008, Florian Witteler.  All Rights Reserved.
 #
 module Prawn
+  # @group Stable API
+
   module Measurements
 
     # ============================================================================

data/lib/prawn/outline.rb

@@ -5,12 +5,14 @@
 # Author Jonathan Greenberg
 
 require 'forwardable'
-require_relative "../pdf/core/outline"
+require "pdf/core/outline"
 
 module Prawn
 
   class Document
 
+    # @group Experimental API
+
     # Lazily instantiates an Outline object for document. This is used as point of entry
     # to methods to build the outline tree.
     def outline

data/lib/prawn/repeater.rb

@@ -11,14 +11,16 @@
 module Prawn
 
   class Document
-
     # A list of all repeaters in the document.
     # See Document#repeat for details
     #
+    # @private
     def repeaters
       @repeaters ||= []
     end
 
+    # @group Experimental API
+
     # Provides a way to execute a block of code repeatedly based on a
     # page_filter.  Since Stamp is used under the hood, this method is very space
     # efficient.

data/lib/prawn/security.rb

@@ -7,9 +7,10 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require 'digest/md5'
-require 'rc4'
 
-require_relative '../pdf/core/byte_string'
+require 'pdf/core/byte_string'
+
+require 'prawn/security/arcfour'
 
 module Prawn
   class Document
@@ -19,6 +20,8 @@ module Prawn
     module Security
       include PDF::Core
 
+      # @group Experimental API
+
       # Encrypts the document, to protect confidential data or control
       # modifications to the document. The encryption algorithm used is
       # detailed in the PDF Reference 1.3, section 3.5 "Encryption", and it is
@@ -117,7 +120,7 @@ module Prawn
 
         # Compute the RC4 key from the extended key and perform the encryption
         rc4_key = Digest::MD5.digest(extended_key)[0, 10]
-        RC4.new(rc4_key).encrypt(str)
+        Arcfour.new(rc4_key).encrypt(str)
       end
 
       private
@@ -187,13 +190,13 @@ module Prawn
       def owner_password_hash
         @owner_password_hash ||= begin
           key = Digest::MD5.digest(pad_password(@owner_password))[0, 5]
-          RC4.new(key).encrypt(pad_password(@user_password))
+          Arcfour.new(key).encrypt(pad_password(@user_password))
         end
       end
 
       # The U (user) value in the encryption dictionary. Algorithm 3.4.
       def user_password_hash
-        RC4.new(user_encryption_key).encrypt(PasswordPadding)
+        Arcfour.new(user_encryption_key).encrypt(PasswordPadding)
       end
 
     end
@@ -201,14 +204,17 @@ module Prawn
   end
 end
 
-module PDF #:nodoc:
+# @private
+module PDF
   module Core
     module_function
 
     # Like PdfObject, but returns an encrypted result if required.
     # For direct objects, requires the object identifier and generation number
     # from the indirect object referencing obj.
-    def EncryptedPdfObject(obj, key, id, gen, in_content_stream=false)
+    #
+    # @private
+    def EncryptedPdfObject(obj, key, id, gen, in_content_stream=false) 
       case obj
       when Array
         "[" << obj.map { |e|
@@ -248,6 +254,7 @@ module PDF #:nodoc:
     end
 
 
+    # @private
     class Stream
       def encrypted_object(key, id, gen)
         if filtered_stream
@@ -258,6 +265,7 @@ module PDF #:nodoc:
       end
     end
 
+    # @private
     class Reference
 
       # Returns the object definition for the object this references, keyed from

data/lib/prawn/security/arcfour.rb

@@ -0,0 +1,52 @@
+# Implementation of the "ARCFOUR" algorithm ("alleged RC4 (tm)"). Implemented
+# as described at:
+# http://www.mozilla.org/projects/security/pki/nss/draft-kaukonen-cipher-arcfour-03.txt
+#
+# "RC4" is a trademark of RSA Data Security, Inc.
+#
+# Copyright August 2009, Brad Ediger. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+# @private
+class Arcfour
+  def initialize(key)
+    # Convert string key to Array of integers
+    key = key.unpack('c*') if key.is_a?(String)
+
+    # 1. Allocate an 256 element array of 8 bit bytes to be used as an S-box
+    # 2. Initialize the S-box.  Fill each entry first with it's index
+    @sbox = (0..255).to_a
+    
+    # 3. Fill another array of the same size (256) with the key, repeating
+    #    bytes as necessary.
+    s2 = []
+    while s2.length < 256
+      s2 += key
+    end
+    s2 = s2[0, 256]
+
+    # 4. Set j to zero and initialize the S-box
+    j = 0
+    (0..255).each do |i|
+      j = (j + @sbox[i] + s2[i]) % 256
+      @sbox[i], @sbox[j] = @sbox[j], @sbox[i]
+    end
+
+    @i = @j = 0
+  end
+
+  def encrypt(string)
+    string.unpack('c*').map{|byte| byte ^ key_byte}.pack('c*')
+  end
+  
+  private
+
+  # Produces the next byte of key material in the stream (3.2 Stream Generation)
+  def key_byte
+    @i = (@i + 1) % 256
+    @j = (@j + @sbox[@i]) % 256
+    @sbox[@i], @sbox[@j] = @sbox[@j], @sbox[@i]
+    @sbox[(@sbox[@i] + @sbox[@j]) % 256]
+  end
+end

data/lib/prawn/soft_mask.rb

@@ -10,7 +10,7 @@
 module Prawn
 
   # The Prawn::SoftMask module is used to create arbitrary transparency in
-  # document. Using a soft mask allows creaing more visually rich documents.
+  # document. Using a soft mask allows creating more visually rich documents.
   #
   # You must group soft mask and graphics it's applied to under
   # save_graphics_state because soft mask is a part of graphic state in PDF.
@@ -26,6 +26,8 @@ module Prawn
   #   end
   #
   module SoftMask
+    # @group Stable API
+
     def soft_mask(&block)
       min_version(1.4)
 

data/lib/prawn/stamp.rb

@@ -28,6 +28,8 @@ module Prawn
   #
   module Stamp
 
+    # @group Stable API
+
     # Renders the stamp named <tt>name</tt> to the page
     # raises <tt>Prawn::Errors::InvalidName</tt> if name.empty?
     # raises <tt>Prawn::Errors::UndefinedObjectName</tt> if no stamp

data/lib/prawn/table.rb

@@ -19,6 +19,8 @@ module Prawn
 
   class Document
 
+    # @group Experimental API
+
     # Set up and draw a table on this document. A block can be given, which will
     # be run after cell setup but before layout and drawing.
     #

data/lib/prawn/table/cell.rb

@@ -10,6 +10,8 @@ require 'date'
 module Prawn
   class Document
 
+    # @group Experimental API
+
     # Instantiates and draws a cell on the document.
     #
     #   cell(:content => "Hello world!", :at => [12, 34])
@@ -151,7 +153,8 @@ module Prawn
       # this span group. They know their own width / height, but do not draw
       # anything.
       #
-      attr_reader :dummy_cells # :nodoc:
+      # @private
+      attr_reader :dummy_cells 
 
       # Instantiates a Cell based on the given options. The particular class of
       # cell returned depends on the :content argument. See the Prawn::Table

data/lib/prawn/table/cell/image.rb

@@ -9,8 +9,7 @@ module Prawn
   class Table
     class Cell
 
-      # A Cell that contains another table.
-      #
+      # @private
       class Image < Cell
 
         def initialize(pdf, point, options={})

data/lib/prawn/table/cell/in_table.rb

@@ -4,6 +4,8 @@
 
 module Prawn
   class Table
+
+    # @private
     class Cell
 
       # This module extends Cell objects when they are used in a table (as

data/lib/prawn/table/cell/span_dummy.rb

@@ -12,6 +12,7 @@ module Prawn
       # A Cell object used to represent all but the topmost cell in a span
       # group.
       #
+      # @private
       class SpanDummy < Cell
         def initialize(pdf, master_cell)
           super(pdf, [0, pdf.cursor])

data/lib/prawn/table/cells.rb

@@ -8,7 +8,6 @@
 
 module Prawn
   class Table
-
     # Selects the given rows (0-based) for styling. Returns a Cells object --
     # see the documentation on Cells for things you can do with cells.
     #
@@ -38,6 +37,8 @@ module Prawn
     #
     class Cells < Array
 
+      # @group Experimental API
+
       # Limits selection to the given row or rows. +row_spec+ can be anything
       # that responds to the === operator selecting a set of 0-based row
       # numbers; most commonly a number or a range.
@@ -254,7 +255,11 @@ module Prawn
 
             #calculate future return value
             new_sum = cell.send(meth) * cell.colspan
-            spanned_width_needs_fixing = (new_sum > old_sum)
+
+            #due to float rounding errors we need to ignore a small difference in the new 
+            #and the old sum the same had to be done in
+            #the column_width_calculator#natural_width
+            spanned_width_needs_fixing = ((new_sum - old_sum) > Prawn::FLOAT_PRECISION)
 
             if spanned_width_needs_fixing
               #not entirely sure why we need this line, but with it the tests pass

data/lib/prawn/table/column_width_calculator.rb

@@ -1,6 +1,7 @@
 module Prawn
   class Table
-    class ColumnWidthCalculator
+    # @private
+    class ColumnWidthCalculator 
       def initialize(cells)
         @cells = cells
 
@@ -37,7 +38,12 @@ module Prawn
                                .collect{|key, value| value}.inject(0, :+)
 
             #update the Hash only if the new with is at least equal to the old one
-            if cell.width.to_f > current_width_of_spanned_cells
+            #due to arithmetic errors we need to ignore a small difference in the new and the old sum
+            #the same had to be done in the column_widht_calculator#natural_width
+            update_hash = ((cell.width.to_f - current_width_of_spanned_cells) > 
+                           Prawn::FLOAT_PRECISION)
+            
+            if update_hash
               # Split the width of colspanned cells evenly by columns
               width_per_column = cell.width.to_f / cell.colspan
               # Update the Hash