prawn 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d83c112e79d7d99ade30524585cf7d7cb7d4de52
-  data.tar.gz: a0143b1b1ebf8db3776daafe04dbceeedb62db6b
+  metadata.gz: 97e70822529ce4c7edb736c4c57f2c6a015ddb02
+  data.tar.gz: 685b8386302414f80c7ac7a7c714987e0a8d2ff9
 SHA512:
-  metadata.gz: 6f9ac40edd92c31df1f2a63e73684f983069edcb8f1dd15ffb26f9bcc85256ac4adc0f476aa6ef5b4fa2248318515c56a39dc68e5f2352711e30dd4863aa4989
-  data.tar.gz: 7ecbae3e281cae29a8a7234fc32c0148eaae4d27dabc35cecba01073d28319c5480c50dcc1cce2f1bdb5b1c99b4a11e80168d62b8c7c94faa8a1a1f7995f0043
+  metadata.gz: dad2cab43e9fdda28fa1a4c364507fd7ecff16d2120a65b3c8ab9a07130d8c6fd73a6a9ae44a98be6faad680b20e894e9d6d1d8b88a870b824f08b9a5a28e527
+  data.tar.gz: 3c61667b13c7ed6aa815728ec777e8d12b04f7219184682d8b2b37d9fe046c942529c957f35597c3ccfe2a48131c701834d209a5cd77a454be9395e695450be3

data/.yardopts

@@ -1,7 +1,8 @@
 --charset UTF-8
 --main README.md
 --title 'Prawn Documentation'
-lib/**/*.rb
+--no-private
+lib/prawn/**/*.rb
 -
 CONTRIBUTING.md
 COPYING

data/Rakefile

@@ -40,3 +40,15 @@ Gem::PackageTask.new(spec) do |pkg|
   pkg.need_zip = true
   pkg.need_tar = true
 end
+
+desc "Run a console with Prawn loaded"
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require_relative 'lib/prawn'
+  Prawn.debug = true
+
+  ARGV.clear
+  IRB.start
+end
+

data/lib/prawn.rb

@@ -1,26 +1,13 @@
 # Welcome to Prawn, the best PDF Generation library ever.
 # This documentation covers user level functionality.
 #
-# Those looking to contribute code or write extensions should look
-# into the lib/prawn/core/* source tree.
-#
-%w[ttfunk/lib].each do |dep|
-  $LOAD_PATH.unshift(File.dirname(__FILE__) + "/../../vendor/#{dep}")
-end
-
-begin
-  require 'ttfunk'
-rescue LoadError
-  puts "Failed to load ttfunk. If you are running Prawn from git:"
-  puts "  git submodule init"
-  puts "  git submodule update"
-  exit
-end
-
 require "set"
 
+require 'ttfunk'
+require "pdf/core"
+
 module Prawn
-  VERSION = "0.14.0"
+  VERSION = "0.15.0"
 
   extend self
 
@@ -33,6 +20,8 @@ module Prawn
   #
   BASEDIR = File.expand_path(File.join(dir, '..'))
   DATADIR = File.expand_path(File.join(dir, '..', 'data'))
+  
+  FLOAT_PRECISION = 1.0e-9
 
   # Whe set to true, Prawn will verify hash options to ensure only valid keys
   # are used.  Off by default.
@@ -43,9 +32,9 @@ module Prawn
   #   Detected unknown option(s): [:tomato]
   #   Accepted options are: [:page_size, :page_layout, :left_margin, ...]
   #
-  attr_accessor :debug
+  attr_accessor :debug # @private
 
-  def verify_options(accepted, actual) #:nodoc:
+  def verify_options(accepted, actual) # @private
     return unless debug || $DEBUG
     unless (act=Set[*actual.keys]).subset?(acc=Set[*accepted])
       raise Prawn::Errors::UnknownOption,
@@ -55,7 +44,7 @@ module Prawn
     yield if block_given?
   end
 
-  module Configurable #:nodoc:
+  module Configurable # @private
     def configuration(*args)
       @config ||= Marshal.load(Marshal.dump(default_configuration))
       if Hash === args[0]
@@ -75,7 +64,6 @@ end
 
 require_relative "prawn/errors"
 
-require_relative "pdf/core"
 
 require_relative "prawn/utilities"
 require_relative "prawn/text"

data/lib/prawn/document.rb

@@ -7,6 +7,7 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 
 require "stringio"
+
 require_relative "document/bounding_box"
 require_relative "document/column_box"
 require_relative "document/internals"
@@ -62,6 +63,8 @@ module Prawn
     include Prawn::Stamp
     include Prawn::SoftMask
 
+    # @group Extension API
+
     # NOTE: We probably need to rethink the options validation system, but this
     # constant temporarily allows for extensions to modify the list.
 
@@ -90,14 +93,28 @@ module Prawn
     #     party!
     #   end
     #
+    #
     def self.extensions
       @extensions ||= []
     end
 
-    def self.inherited(base) #:nodoc:
+    # @private
+    def self.inherited(base) 
       extensions.each { |e| base.extensions << e }
     end
 
+    # @group Stable Attributes
+
+    attr_accessor :margin_box
+    attr_reader   :margins, :y
+    attr_accessor :page_number
+
+    # @group Extension Attributes
+
+    attr_accessor :text_formatter
+
+    # @group Stable API
+
     # Creates and renders a PDF document.
     #
     # When using the implicit block form, Prawn will evaluate the block
@@ -215,27 +232,7 @@ module Prawn
       end
     end
 
-    attr_accessor :margin_box
-    attr_reader   :margins, :y
-    attr_writer   :font_size
-    attr_accessor :page_number
-    attr_accessor :text_formatter
-
-    def state
-      @internal_state
-    end
-
-    def page
-      state.page
-    end
-
-    def initialize_first_page(options)
-      if options[:skip_page_creation]
-        start_new_page(options.merge(:orphan => true))
-      else
-        start_new_page(options)
-      end
-    end
+    # @group Stable API
 
     # Creates and advances to a new page in the document.
     #
@@ -356,6 +353,9 @@ module Prawn
     # Pass an open file descriptor to render to file.
     #
     def render(output = StringIO.new)
+      if output.instance_of?(StringIO)
+        output.set_encoding(::Encoding::ASCII_8BIT)
+      end
       finalize_all_page_contents
 
       render_header(output)
@@ -412,6 +412,7 @@ module Prawn
 
     # Returns the innermost non-stretchy bounding box.
     #
+    # @private
     def reference_bounds
       @bounding_box.reference_bounds
     end
@@ -497,47 +498,6 @@ module Prawn
       bounds.indent(left, right, &block)
     end
 
-
-    def mask(*fields) # :nodoc:
-     # Stores the current state of the named attributes, executes the block, and
-     # then restores the original values after the block has executed.
-     # -- I will remove the nodoc if/when this feature is a little less hacky
-      stored = {}
-      fields.each { |f| stored[f] = send(f) }
-      yield
-      fields.each { |f| send("#{f}=", stored[f]) }
-    end
-
-    # Attempts to group the given block vertically within the current context.
-    # First attempts to render it in the current position on the current page.
-    # If that attempt overflows, it is tried anew after starting a new context
-    # (page or column). Returns a logically true value if the content fits in
-    # one page/column, false if a new page or column was needed.
-    #
-    # Raises CannotGroup if the provided content is too large to fit alone in
-    # the current page or column.
-    #
-    def group(second_attempt=false)
-      old_bounding_box = @bounding_box
-      @bounding_box = SimpleDelegator.new(@bounding_box)
-
-      def @bounding_box.move_past_bottom
-        raise RollbackTransaction
-      end
-
-      success = transaction { yield }
-
-      @bounding_box = old_bounding_box
-
-      unless success
-        raise Prawn::Errors::CannotGroup if second_attempt
-        old_bounding_box.move_past_bottom
-        group(second_attempt=true) { yield }
-      end
-
-      success
-    end
-
     # Places a text box on specified pages for page numbering.  This should be called
     # towards the end of document creation, after all your content is already in
     # place.  In your template string, <page> refers to the current page, and
@@ -610,6 +570,46 @@ module Prawn
       end
     end
 
+    # Returns true if content streams will be compressed before rendering,
+    # false otherwise
+    #
+    def compression_enabled?
+      !!state.compress
+    end
+
+    # @group Experimental API
+
+    # Attempts to group the given block vertically within the current context.
+    # First attempts to render it in the current position on the current page.
+    # If that attempt overflows, it is tried anew after starting a new context
+    # (page or column). Returns a logically true value if the content fits in
+    # one page/column, false if a new page or column was needed.
+    #
+    # Raises CannotGroup if the provided content is too large to fit alone in
+    # the current page or column.
+    #
+    def group(second_attempt=false)
+      old_bounding_box = @bounding_box
+      @bounding_box = SimpleDelegator.new(@bounding_box)
+
+      # @private
+      def @bounding_box.move_past_bottom
+        raise RollbackTransaction
+      end
+
+      success = transaction { yield }
+
+      @bounding_box = old_bounding_box
+
+      unless success
+        raise Prawn::Errors::CannotGroup if second_attempt
+        old_bounding_box.move_past_bottom
+        group(second_attempt=true) { yield }
+      end
+
+      success
+    end
+
     # Provides a way to execute a block of code repeatedly based on a
     # page_filter.
     #
@@ -635,16 +635,43 @@ module Prawn
       end
     end
 
+    # @private
+   
+    def mask(*fields) 
+     # Stores the current state of the named attributes, executes the block, and
+     # then restores the original values after the block has executed.
+     # -- I will remove the nodoc if/when this feature is a little less hacky
+      stored = {}
+      fields.each { |f| stored[f] = send(f) }
+      yield
+      fields.each { |f| send("#{f}=", stored[f]) }
+    end
 
-    # Returns true if content streams will be compressed before rendering,
-    # false otherwise
-    #
-    def compression_enabled?
-      !!state.compress
+    # @group Extension API
+
+    def initialize_first_page(options)
+      if options[:skip_page_creation]
+        start_new_page(options.merge(:orphan => true))
+      else
+        start_new_page(options)
+      end
+    end
+
+    ## Internals. Don't depend on them!
+
+    # @private
+    def state
+      @internal_state
+    end
+
+    # @private
+    def page
+      state.page
     end
 
     private
 
+
     # setting override_settings to true ensures that a new graphic state does not end up using
     # previous settings.
     def use_graphic_settings(override_settings = false)

data/lib/prawn/document/bounding_box.rb

@@ -8,6 +8,7 @@
 
 module Prawn
   class Document
+    # @group Stable API
 
     # :call-seq:
     #   bounding_box(point, options={}, &block)
@@ -219,7 +220,7 @@ module Prawn
     #
     class BoundingBox
 
-      def initialize(document, parent, point, options={}) #:nodoc:
+      def initialize(document, parent, point, options={}) # @private
         unless options[:width]
           raise ArgumentError, "BoundingBox needs the :width option to be set"
         end
@@ -233,15 +234,22 @@ module Prawn
         @stretched_height = nil
       end
 
+      # @private
+
       attr_reader :document, :parent
+
+      # @private
       # The current indentation of the left side of the bounding box.
       attr_reader :total_left_padding
+
+      # @private
       # The current indentation of the right side of the bounding box.
       attr_reader :total_right_padding
 
       # The translated origin (x,y-height) which describes the location
       # of the bottom left corner of the bounding box
       #
+      # @private
       def anchor
         [@x, @y - height]
       end
@@ -272,6 +280,7 @@ module Prawn
       #    text "indented on both sides"
       #  end
       #
+      # @private
       def indent(left_padding, right_padding = 0, &block)
         add_left_padding(left_padding)
         add_right_padding(right_padding)
@@ -282,6 +291,7 @@ module Prawn
       end
 
       # Increase the left padding of the bounding box.
+      # @private
       def add_left_padding(left_padding)
         @total_left_padding += left_padding
         @x += left_padding
@@ -289,6 +299,7 @@ module Prawn
       end
 
       # Decrease the left padding of the bounding box.
+      # @private
       def subtract_left_padding(left_padding)
         @total_left_padding -= left_padding
         @x -= left_padding
@@ -296,12 +307,14 @@ module Prawn
       end
 
       # Increase the right padding of the bounding box.
+      # @private
       def add_right_padding(right_padding)
         @total_right_padding += right_padding
         @width -= right_padding
       end
 
       # Decrease the right padding of the bounding box.
+      # @private
       def subtract_right_padding(right_padding)
         @total_right_padding -= right_padding
         @width += right_padding
@@ -452,15 +465,19 @@ module Prawn
       end
 
       # an alias for absolute_left
+      # @private
       def left_side
         absolute_left
       end
 
       # an alias for absolute_right
+      # @private
       def right_side
         absolute_right
       end
 
+      # @group Extension API
+
       # Moves to the top of the next page of the document, starting a new page
       # if necessary.
       #
@@ -472,9 +489,6 @@ module Prawn
         end
       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.
       #
@@ -493,9 +507,12 @@ module Prawn
         end
       end
 
+      alias_method :update_height, :height
+
       # Returns a deep copy of these bounds (including all parent bounds but
       # not copying the reference to the Document).
       #
+      # @private
       def deep_copy
         copy = dup
         # Deep-copy the parent bounds
@@ -510,6 +527,7 @@ module Prawn
       # context of the given +document+. Does *not* set the bounds of the
       # document to the resulting BoundingBox, only returns it.
       #
+      # @private
       def self.restore_deep_copy(bounds, document)
         bounds.instance_variable_set("@document", document)
         bounds