nurettin-prawn 1.0.0.rc1

data/lib/prawn/core/text/formatted/line_wrap.rb

@@ -0,0 +1,288 @@
+# encoding: utf-8
+
+# core/text/formatted/line_wrap.rb : Implements individual line wrapping of 
+#                                    formatted text
+#
+# Copyright February 2010, Daniel Nelson. All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+#
+
+module Prawn
+  module Core
+    module Text
+      module Formatted #:nodoc:
+        
+        class LineWrap #:nodoc:
+
+          # The width of the last wrapped line
+          #
+          def width
+            @accumulated_width || 0
+          end
+
+          # The number of spaces in the last wrapped line
+          attr_reader :space_count
+
+          # Whether this line is the last line in the paragraph
+          def paragraph_finished?
+            @newline_encountered || is_next_string_newline? || @arranger.finished?
+          end
+
+          # Work in conjunction with the Prawn::Core::Formatted::Arranger
+          # defined in the :arranger option to determine what formatted text
+          # will fit within the width defined by the :width option
+          #
+          def wrap_line(options)
+            initialize_line(options)
+
+            while fragment = @arranger.next_string
+              @fragment_output = ""
+
+              fragment.lstrip! if first_fragment_on_this_line?(fragment)
+              next if empty_line?(fragment)
+
+              unless apply_font_settings_and_add_fragment_to_line(fragment)
+                break
+              end
+            end
+            @arranger.finalize_line
+            @accumulated_width = @arranger.line_width
+            @space_count = @arranger.space_count
+            @arranger.line
+          end
+
+          private
+
+          def first_fragment_on_this_line?(fragment)
+            line_empty? && fragment != "\n"
+          end
+
+          def empty_line?(fragment)
+            empty = line_empty? && fragment.empty? && is_next_string_newline?
+            @arranger.update_last_string("", "", soft_hyphen) if empty
+            empty
+          end
+
+          def is_next_string_newline?
+            @arranger.preview_next_string == "\n"
+          end
+
+          def apply_font_settings_and_add_fragment_to_line(fragment)
+            result = nil
+            @arranger.apply_font_settings do
+              # if font has changed from Unicode to non-Unicode, or vice versa, the characters used for soft hyphens
+              #   and zero-width spaces will be different
+              set_soft_hyphen_and_zero_width_space
+              result = add_fragment_to_line(fragment)
+            end
+            result
+          end
+
+          # returns true iff all text was printed without running into the end of
+          # the line
+          #
+          def add_fragment_to_line(fragment)
+            if fragment == ""
+              true
+            elsif fragment == "\n"
+              @newline_encountered = true
+              false
+            else
+              fragment.scan(scan_pattern).each do |segment|
+                if segment == zero_width_space
+                  segment_width = 0
+                else
+                  segment_width = @document.width_of(segment, :kerning => @kerning)
+                end
+
+                if @accumulated_width + segment_width <= @width
+                  @accumulated_width += segment_width
+                  @fragment_output += segment
+                else
+                  end_of_the_line_reached(segment)
+                  fragment_finished(fragment)
+                  return false
+                end
+              end
+
+              fragment_finished(fragment)
+              true
+            end
+          end
+
+          # The pattern used to determine chunks of text to place on a given line
+          #
+          def scan_pattern
+            pattern = "[^#{break_chars}]+#{soft_hyphen}|" +
+              "[^#{break_chars}]+#{hyphen}+|" +
+              "[^#{break_chars}]+|" +
+              "[#{whitespace}]+|" +
+              "#{hyphen}+[^#{break_chars}]*|" +
+              "#{soft_hyphen}"
+            new_regexp(pattern)
+          end
+
+          # The pattern used to determine whether any word breaks exist on a
+          # current line, which in turn determines whether character level
+          # word breaking is needed
+          #
+          def word_division_scan_pattern
+            new_regexp("\\s|[#{zero_width_space}#{soft_hyphen}#{hyphen}]")
+          end
+
+          def break_chars
+            "#{whitespace}#{soft_hyphen}#{hyphen}"
+          end
+
+          def whitespace
+            " \\t#{zero_width_space}"
+          end
+
+          def hyphen
+            "-"
+          end
+
+          def soft_hyphen
+            @soft_hyphen
+          end
+
+          def zero_width_space
+            @zero_width_space 
+          end
+
+          def line_empty?
+            @line_empty && @accumulated_width == 0
+          end
+
+          def initialize_line(options)
+            @document = options[:document]
+            @kerning = options[:kerning]
+            @width = options[:width]
+
+            @accumulated_width = 0
+            @line_empty = true
+            @line_contains_more_than_one_word = false
+
+            @arranger = options[:arranger]
+            @arranger.initialize_line
+
+            @newline_encountered = false
+            @line_full = false
+          end
+
+          def set_soft_hyphen_and_zero_width_space
+            # this is done once per fragment, after the font settings for the fragment are applied --
+            #   it could actually be skipped if the font hasn't changed
+            font = @document.font
+            @soft_hyphen = font.normalize_encoding(Prawn::Text::SHY) 
+            @zero_width_space = font.unicode? ? Prawn::Text::ZWSP : ""
+          end
+
+          def fragment_finished(fragment)
+            if fragment == "\n"
+              @newline_encountered = true
+              @line_empty = false
+            else
+              update_output_based_on_last_fragment(fragment, soft_hyphen)
+              update_line_status_based_on_last_output
+              determine_whether_to_pull_preceding_fragment_to_join_this_one(fragment)
+            end
+            remember_this_fragment_for_backward_looking_ops
+          end
+
+          def update_output_based_on_last_fragment(fragment, normalized_soft_hyphen=nil)
+            remaining_text = fragment.slice(@fragment_output.length..fragment.length)
+            raise Errors::CannotFit if line_finished? && line_empty? &&
+              @fragment_output.empty? && !fragment.strip.empty?
+            @arranger.update_last_string(@fragment_output, remaining_text, normalized_soft_hyphen)
+          end
+
+          def determine_whether_to_pull_preceding_fragment_to_join_this_one(current_fragment)
+            if @fragment_output.empty? &&
+                !current_fragment.empty? &&
+                @line_contains_more_than_one_word
+              unless previous_fragment_ended_with_breakable? ||
+                  fragment_begins_with_breakable?(current_fragment)
+                @fragment_output = @previous_fragment_output_without_last_word
+                update_output_based_on_last_fragment(@previous_fragment)
+              end
+            end
+          end
+
+          def remember_this_fragment_for_backward_looking_ops
+            @previous_fragment = @fragment_output.dup
+            pf = @previous_fragment
+            @previous_fragment_ended_with_breakable = pf =~ /[#{break_chars}]$/
+            last_word = pf.slice(/[^#{break_chars}]*$/)
+            last_word_length = last_word.nil? ? 0 : last_word.length
+            @previous_fragment_output_without_last_word = pf.slice(0, pf.length - last_word_length)
+          end
+
+          def previous_fragment_ended_with_breakable?
+            @previous_fragment_ended_with_breakable
+          end
+
+          def fragment_begins_with_breakable?(fragment)
+            fragment =~ /^[#{break_chars}]/
+          end
+
+          def line_finished?
+            @line_full || paragraph_finished?
+          end
+
+          def update_line_status_based_on_last_output
+            @line_contains_more_than_one_word = true if @fragment_output =~ word_division_scan_pattern
+          end
+
+          def end_of_the_line_reached(segment)
+            update_line_status_based_on_last_output
+            wrap_by_char(segment) unless @line_contains_more_than_one_word
+            @line_full = true
+          end
+
+          def wrap_by_char(segment)
+            # this conditional is only necessary for Ruby 1.8 compatibility
+            # String#unicode_characters is a helper which iterates over UTF-8 characters
+            #   under Ruby 1.9, it is implemented simply by aliasing #each_char
+            font = @document.font
+            if font.unicode?
+              segment.unicode_characters do |char|
+                break unless append_char(char,font)
+              end
+            else
+              segment.each_char do |char|
+                break unless append_char(char,font)
+              end
+            end
+          end
+
+          def append_char(char,font)
+            # kerning doesn't make sense in the context of a single character
+            char_width = font.compute_width_of(char)
+
+            if @accumulated_width + char_width <= @width
+              @accumulated_width += char_width
+              @fragment_output << char
+              true
+            else
+              false
+            end
+          end
+
+          def new_regexp(pattern)
+            regexp = ruby_19 {
+              Regexp.new(pattern)
+            }
+            regexp = regexp || ruby_18 {
+              lang = @document.font.unicode? ? 'U' : 'N'
+              Regexp.new(pattern, 0, lang)
+            }
+            regexp
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/prawn/core/text/formatted/wrap.rb

@@ -0,0 +1,153 @@
+require "prawn/core/text/formatted/line_wrap"
+require "prawn/core/text/formatted/arranger"
+
+module Prawn
+  module Core
+    module Text
+      module Formatted #:nodoc:
+        module Wrap #:nodoc:
+
+          def initialize(array, options)
+            @line_wrap = Prawn::Core::Text::Formatted::LineWrap.new
+            @arranger = Prawn::Core::Text::Formatted::Arranger.new(@document,
+              :kerning => options[:kerning])
+          end
+          
+
+          # See the developer documentation for Prawn::Core::Text#wrap
+          #
+          # Formatted#wrap should set the following variables:
+          #   <tt>@line_height</tt>::
+          #        the height of the tallest fragment in the last printed line
+          #   <tt>@descender</tt>::
+          #        the descender height of the tallest fragment in the last
+          #        printed line
+          #   <tt>@ascender</tt>::
+          #        the ascender heigth of the tallest fragment in the last
+          #        printed line
+          #   <tt>@baseline_y</tt>::
+          #       the baseline of the current line
+          #   <tt>@nothing_printed</tt>::
+          #       set to true until something is printed, then false
+          #   <tt>@everything_printed</tt>::
+          #       set to false until everything printed, then true
+          #
+          # Returns any formatted text that was not printed
+          #
+          def wrap(array) #:nodoc:
+            initialize_wrap(array)
+
+            stop = false
+            while !stop
+              # wrap before testing if enough height for this line because the
+              # height of the highest fragment on this line will be used to
+              # determine the line height
+              @line_wrap.wrap_line(:document => @document,
+                                   :kerning => @kerning,
+                                   :width => available_width,
+                                   :arranger => @arranger)
+
+              if enough_height_for_this_line?
+                move_baseline_down
+                print_line
+              else
+                stop = true
+              end
+
+              stop ||= @single_line || @arranger.finished?
+            end
+            @text = @printed_lines.join("\n")
+            @everything_printed = @arranger.finished?
+            @arranger.unconsumed
+          end
+
+          private
+
+          def print_line
+            @nothing_printed = false
+            printed_fragments = []
+            fragments_this_line = []
+
+            word_spacing = word_spacing_for_this_line
+            while fragment = @arranger.retrieve_fragment
+              fragment.word_spacing = word_spacing
+              if fragment.text == "\n"
+                printed_fragments << "\n" if @printed_lines.last == ""
+                break
+              end
+              printed_fragments << fragment.text
+              fragments_this_line << fragment
+            end
+
+            accumulated_width = 0
+            fragments_this_line.reverse! if @direction == :rtl
+            fragments_this_line.each do |fragment|
+              fragment.default_direction = @direction
+              format_and_draw_fragment(fragment, accumulated_width,
+                                       @line_wrap.width, word_spacing)
+              accumulated_width += fragment.width
+            end
+
+            if "".respond_to?(:force_encoding)
+              printed_fragments.map! { |s| s.force_encoding("utf-8") }
+            end
+            @printed_lines << printed_fragments.join
+          end
+
+          def word_spacing_for_this_line
+            if @align == :justify &&
+                @line_wrap.space_count > 0 &&
+                !@line_wrap.paragraph_finished?
+              (available_width - @line_wrap.width) / @line_wrap.space_count
+            else
+              0
+            end
+          end
+
+          def enough_height_for_this_line?
+            @line_height = @arranger.max_line_height
+            @descender   = @arranger.max_descender
+            @ascender    = @arranger.max_ascender
+            if @baseline_y == 0
+              diff = @ascender + @descender
+            else
+              diff = @descender + @line_height + @leading
+            end
+            required_total_height = @baseline_y.abs + diff
+            if required_total_height > @height + 0.0001
+              # no room for the full height of this line
+              @arranger.repack_unretrieved
+              false
+            else
+              true
+            end
+          end
+
+          def initialize_wrap(array)
+            @text = nil
+            @arranger.format_array = array
+
+            # these values will depend on the maximum value within a given line
+            @line_height = 0
+            @descender   = 0
+            @ascender    = 0
+            @baseline_y  = 0
+
+            @printed_lines = []
+            @nothing_printed = true
+            @everything_printed = false
+          end
+
+          def format_and_draw_fragment(fragment, accumulated_width,
+                                       line_width, word_spacing)
+            @arranger.apply_color_and_font_settings(fragment) do
+              draw_fragment(fragment, accumulated_width,
+                            line_width, word_spacing)
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/prawn/document.rb

@@ -0,0 +1,707 @@
+# encoding: utf-8
+
+# document.rb : Implements PDF document generation for Prawn
+#
+# Copyright April 2008, Gregory Brown.  All Rights Reserved.
+#
+# This is free software. Please see the LICENSE and COPYING files for details.
+
+require "stringio"
+require "prawn/document/page_geometry"
+require "prawn/document/bounding_box"
+require "prawn/document/column_box"
+require "prawn/document/internals"
+require "prawn/document/span"
+require "prawn/document/snapshot"
+require "prawn/document/graphics_state"
+
+module Prawn
+
+  # The Prawn::Document class is how you start creating a PDF document.
+  #
+  # There are three basic ways you can instantiate PDF Documents in Prawn, they
+  # are through assignment, implicit block or explicit block.  Below is an exmple
+  # of each type, each example does exactly the same thing, makes a PDF document
+  # with all the defaults and puts in the default font "Hello There" and then
+  # saves it to the current directory as "example.pdf"
+  #
+  # For example, assignment can be like this:
+  #
+  #   pdf = Prawn::Document.new
+  #   pdf.text "Hello There"
+  #   pdf.render_file "example.pdf"
+  #
+  # Or you can do an implied block form:
+  #
+  #   Prawn::Document.generate "example.pdf" do
+  #     text "Hello There"
+  #   end
+  #
+  # Or if you need to access a variable outside the scope of the block, the
+  # explicit block form:
+  #
+  #   words = "Hello There"
+  #   Prawn::Document.generate "example.pdf" do |pdf|
+  #     pdf.text words
+  #   end
+  #
+  # Usually, the block forms are used when you are simply creating a PDF document
+  # that you want to immediately save or render out.
+  #
+  # See the new and generate methods for further details on the above.
+  #
+  class Document
+    include Prawn::Document::Internals
+    include Prawn::Core::Annotations
+    include Prawn::Core::Destinations
+    include Prawn::Document::Snapshot
+    include Prawn::Document::GraphicsState
+    include Prawn::Document::Security
+    include Prawn::Text
+    include Prawn::Graphics
+    include Prawn::Images
+    include Prawn::Stamp
+    include Prawn::SoftMask
+
+    # Any module added to this array will be included into instances of
+    # Prawn::Document at the per-object level.  These will also be inherited by
+    # any subclasses.
+    #
+    # Example:
+    #
+    #   module MyFancyModule
+    #
+    #     def party!
+    #       text "It's a big party!"
+    #     end
+    #
+    #   end
+    #
+    #   Prawn::Document.extensions << MyFancyModule
+    #
+    #   Prawn::Document.generate("foo.pdf") do
+    #     party!
+    #   end
+    #
+    def self.extensions
+      @extensions ||= []
+    end
+
+    def self.inherited(base) #:nodoc:
+      extensions.each { |e| base.extensions << e }
+    end
+
+    # Creates and renders a PDF document.
+    #
+    # When using the implicit block form, Prawn will evaluate the block
+    # within an instance of Prawn::Document, simplifying your syntax.
+    # However, please note that you will not be able to reference variables
+    # from the enclosing scope within this block.
+    #
+    #   # Using implicit block form and rendering to a file
+    #   Prawn::Document.generate "example.pdf" do
+    #     # self here is set to the newly instantiated Prawn::Document
+    #     # and so any variables in the outside scope are unavailable
+    #     font "Times-Roman"
+    #     draw_text "Hello World", :at => [200,720], :size => 32
+    #   end
+    #
+    # If you need to access your local and instance variables, use the explicit
+    # block form shown below.  In this case, Prawn yields an instance of
+    # PDF::Document and the block is an ordinary closure:
+    #
+    #   # Using explicit block form and rendering to a file
+    #   content = "Hello World"
+    #   Prawn::Document.generate "example.pdf" do |pdf|
+    #     # self here is left alone
+    #     pdf.font "Times-Roman"
+    #     pdf.draw_text content, :at => [200,720], :size => 32
+    #   end
+    #
+    def self.generate(filename,options={},&block)
+      pdf = new(options,&block)
+      pdf.render_file(filename)
+    end
+
+    # Creates a new PDF Document.  The following options are available (with
+    # the default values marked in [])
+    #
+    # <tt>:page_size</tt>:: One of the Document::PageGeometry sizes [LETTER]
+    # <tt>:page_layout</tt>:: Either <tt>:portrait</tt> or <tt>:landscape</tt>
+    # <tt>:margin</tt>:: Sets the margin on all sides in points [0.5 inch]
+    # <tt>:left_margin</tt>:: Sets the left margin in points [0.5 inch]
+    # <tt>:right_margin</tt>:: Sets the right margin in points [0.5 inch]
+    # <tt>:top_margin</tt>:: Sets the top margin in points [0.5 inch]
+    # <tt>:bottom_margin</tt>:: Sets the bottom margin in points [0.5 inch]
+    # <tt>:skip_page_creation</tt>:: Creates a document without starting the first page [false]
+    # <tt>:compress</tt>:: Compresses content streams before rendering them [false]
+    # <tt>:optimize_objects</tt>:: Reduce number of PDF objects in output, at expense of render time [false]
+    # <tt>:background</tt>:: An image path to be used as background on all pages [nil]
+    # <tt>:background_scale</tt>:: Backgound image scale [1] [nil]
+    # <tt>:info</tt>:: Generic hash allowing for custom metadata properties [nil]
+    # <tt>:template</tt>:: The path to an existing PDF file to use as a template [nil]
+    #
+    # Setting e.g. the :margin to 100 points and the :left_margin to 50 will result in margins
+    # of 100 points on every side except for the left, where it will be 50.
+    #
+    # The :margin can also be an array much like CSS shorthand:
+    #
+    #   # Top and bottom are 20, left and right are 100.
+    #   :margin => [20, 100]
+    #   # Top is 50, left and right are 100, bottom is 20.
+    #   :margin => [50, 100, 20]
+    #   # Top is 10, right is 20, bottom is 30, left is 40.
+    #   :margin => [10, 20, 30, 40]
+    #
+    # Additionally, :page_size can be specified as a simple two value array giving
+    # the width and height of the document you need in PDF Points.
+    #
+    # Usage:
+    #
+    #   # New document, US Letter paper, portrait orientation
+    #   pdf = Prawn::Document.new
+    #
+    #   # New document, A4 paper, landscaped
+    #   pdf = Prawn::Document.new(:page_size => "A4", :page_layout => :landscape)
+    #
+    #   # New document, Custom size
+    #   pdf = Prawn::Document.new(:page_size => [200, 300])
+    #
+    #   # New document, with background
+    #   pdf = Prawn::Document.new(:background => "#{Prawn::DATADIR}/images/pigs.jpg")
+    #
+    def initialize(options={},&block)
+      options = options.dup
+
+      Prawn.verify_options [:page_size, :page_layout, :margin, :left_margin,
+        :right_margin, :top_margin, :bottom_margin, :skip_page_creation,
+        :compress, :skip_encoding, :background, :info,
+        :optimize_objects, :template], options
+
+      # need to fix, as the refactoring breaks this
+      # raise NotImplementedError if options[:skip_page_creation]
+
+      self.class.extensions.reverse_each { |e| extend e }
+      @internal_state = Prawn::Core::DocumentState.new(options)
+      @internal_state.populate_pages_from_store(self)
+      min_version(state.store.min_version) if state.store.min_version
+
+      @background = options[:background]
+      @background_scale = options[:background_scale] || 1
+      @font_size  = 12
+
+      @bounding_box  = nil
+      @margin_box    = nil
+
+      @page_number = 0
+
+      options[:size] = options.delete(:page_size)
+      options[:layout] = options.delete(:page_layout)
+
+      if options[:template]
+        fresh_content_streams(options)
+        go_to_page(1)
+      else
+        if options[:skip_page_creation] || options[:template]
+          start_new_page(options.merge(:orphan => true))
+        else
+          start_new_page(options)
+        end
+      end
+
+      @bounding_box = @margin_box
+
+      if block
+        block.arity < 1 ? instance_eval(&block) : block[self]
+      end
+    end
+
+    attr_accessor :margin_box
+    attr_reader   :margins, :y
+    attr_writer   :font_size
+    attr_accessor :page_number
+
+    def state
+      @internal_state
+    end
+
+    def page
+      state.page
+    end
+
+    # Creates and advances to a new page in the document.
+    #
+    # Page size, margins, and layout can also be set when generating a
+    # new page. These values will become the new defaults for page creation
+    #
+    #   pdf.start_new_page #=> Starts new page keeping current values
+    #   pdf.start_new_page(:size => "LEGAL", :layout => :landscape)
+    #   pdf.start_new_page(:left_margin => 50, :right_margin => 50)
+    #   pdf.start_new_page(:margin => 100)
+    #
+    # A template for a page can be specified by pointing to the path of and existing pdf.
+    # One can also specify which page of the template which defaults otherwise to 1.
+    #
+    #  pdf.start_new_page(:template => multipage_template.pdf, :template_page => 2)
+    #
+    # Note: templates get indexed by either the object_id of the filename or stream
+    # entered so that if you reuse the same template multiple times be sure to use the
+    # same instance for more efficient use of resources and smaller rendered pdfs.
+    def start_new_page(options = {})
+      if last_page = state.page
+        last_page_size    = last_page.size
+        last_page_layout  = last_page.layout
+        last_page_margins = last_page.margins
+      end
+
+      page_options = {:size => options[:size] || last_page_size,
+                      :layout  => options[:layout] || last_page_layout,
+                      :margins => last_page_margins}
+      if last_page
+        new_graphic_state = last_page.graphic_state.dup
+        #erase the color space so that it gets reset on new page for fussy pdf-readers
+        new_graphic_state.color_space = {}
+        page_options.merge!(:graphic_state => new_graphic_state)
+      end
+      merge_template_options(page_options, options) if options[:template]
+
+      state.page = Prawn::Core::Page.new(self, page_options)
+
+      apply_margin_options(options)
+      generate_margin_box
+
+      # Reset the bounding box if the new page has different size or layout
+      if last_page && (last_page.size != state.page.size ||
+                       last_page.layout != state.page.layout)
+        @bounding_box = @margin_box
+      end
+
+      state.page.new_content_stream if options[:template]
+      use_graphic_settings(options[:template])
+
+      unless options[:orphan]
+        state.insert_page(state.page, @page_number)
+        @page_number += 1
+
+        canvas { image(@background, :scale => @background_scale, :at => bounds.top_left) } if @background
+        @y = @bounding_box.absolute_top
+
+        float do
+          state.on_page_create_action(self)
+        end
+      end
+    end
+
+    # Returns the number of pages in the document
+    #
+    #   pdf = Prawn::Document.new
+    #   pdf.page_count #=> 1
+    #   3.times { pdf.start_new_page }
+    #   pdf.page_count #=> 4
+    #
+    def page_count
+      state.page_count
+    end
+
+    # Re-opens the page with the given (1-based) page number so that you can
+    # draw on it.
+    #
+    # See Prawn::Document#number_pages for a sample usage of this capability.
+    #
+    def go_to_page(k)
+      @page_number = k
+      state.page = state.pages[k-1]
+      generate_margin_box
+      @y = @bounding_box.absolute_top
+    end
+
+    def y=(new_y)
+      @y = new_y
+      bounds.update_height
+    end
+
+    # The current y drawing position relative to the innermost bounding box,
+    # or to the page margins at the top level.
+    #
+    def cursor
+      y - bounds.absolute_bottom
+    end
+
+    # Moves to the specified y position in relative terms to the bottom margin.
+    #
+    def move_cursor_to(new_y)
+      self.y = new_y + bounds.absolute_bottom
+    end
+
+    # Executes a block and then restores the original y position. If new pages
+    # were created during this block, it will teleport back to the original
+    # page when done.
+    #
+    #   pdf.text "A"
+    #
+    #   pdf.float do
+    #     pdf.move_down 100
+    #     pdf.text "C"
+    #   end
+    #
+    #   pdf.text "B"
+    #
+    def float
+      original_page = page_number
+      original_y = y
+      yield
+      go_to_page(original_page) unless page_number == original_page
+      self.y = original_y
+    end
+
+    # Renders the PDF document to string
+    #
+    def render
+      output = StringIO.new
+      finalize_all_page_contents
+
+      render_header(output)
+      render_body(output)
+      render_xref(output)
+      render_trailer(output)
+      str = output.string
+      str.force_encoding("ASCII-8BIT") if str.respond_to?(:force_encoding)
+      str
+    end
+
+    # Renders the PDF document to file.
+    #
+    #   pdf.render_file "foo.pdf"
+    #
+    def render_file(filename)
+      Kernel.const_defined?("Encoding") ? mode = "wb:ASCII-8BIT" : mode = "wb"
+      File.open(filename,mode) { |f| f << render }
+    end
+
+    # The bounds method returns the current bounding box you are currently in,
+    # which is by default the box represented by the margin box on the
+    # document itself.  When called from within a created <tt>bounding_box</tt>
+    # block, the box defined by that call will be returned instead of the
+    # document margin box.
+    #
+    # Another important point about bounding boxes is that all x and y measurements
+    # within a bounding box code block are relative to the bottom left corner of the
+    # bounding box.
+    #
+    # For example:
+    #
+    #  Prawn::Document.new do
+    #    # In the default "margin box" of a Prawn document of 0.5in along each edge
+    #
+    #    # Draw a border around the page (the manual way)
+    #    stroke do
+    #      line(bounds.bottom_left, bounds.bottom_right)
+    #      line(bounds.bottom_right, bounds.top_right)
+    #      line(bounds.top_right, bounds.top_left)
+    #      line(bounds.top_left, bounds.bottom_left)
+    #    end
+    #
+    #    # Draw a border around the page (the easy way)
+    #    stroke_bounds
+    #  end
+    #
+    def bounds
+      @bounding_box
+    end
+
+    # Returns the innermost non-stretchy bounding box.
+    #
+    def reference_bounds
+      @bounding_box.reference_bounds
+    end
+
+    # Sets Document#bounds to the BoundingBox provided.  See above for a brief
+    # description of what a bounding box is.  This function is useful if you
+    # really need to change the bounding box manually, but usually, just entering
+    # and exiting bounding box code blocks is good enough.
+    #
+    def bounds=(bounding_box)
+      @bounding_box = bounding_box
+    end
+
+    # Moves up the document by n points relative to the current position inside
+    # the current bounding box.
+    #
+    def move_up(n)
+      self.y += n
+    end
+
+    # Moves down the document by n points relative to the current position inside
+    # the current bounding box.
+    #
+    def move_down(n)
+      self.y -= n
+    end
+
+    # Moves down the document and then executes a block.
+    #
+    #   pdf.text "some text"
+    #   pdf.pad_top(100) do
+    #     pdf.text "This is 100 points below the previous line of text"
+    #   end
+    #   pdf.text "This text appears right below the previous line of text"
+    #
+    def pad_top(y)
+      move_down(y)
+      yield
+    end
+
+    # Executes a block then moves down the document
+    #
+    #   pdf.text "some text"
+    #   pdf.pad_bottom(100) do
+    #     pdf.text "This text appears right below the previous line of text"
+    #   end
+    #   pdf.text "This is 100 points below the previous line of text"
+    #
+    def pad_bottom(y)
+      yield
+      move_down(y)
+    end
+
+    # Moves down the document by y, executes a block, then moves down the
+    # document by y again.
+    #
+    #   pdf.text "some text"
+    #   pdf.pad(100) do
+    #     pdf.text "This is 100 points below the previous line of text"
+    #   end
+    #   pdf.text "This is 100 points below the previous line of text"
+    #
+    def pad(y)
+      move_down(y)
+      yield
+      move_down(y)
+    end
+
+
+    # Indents the specified number of PDF points for the duration of the block
+    #
+    #  pdf.text "some text"
+    #  pdf.indent(20) do
+    #    pdf.text "This is indented 20 points"
+    #  end
+    #  pdf.text "This starts 20 points left of the above line " +
+    #           "and is flush with the first line"
+    #  pdf.indent 20, 20 do
+    #    pdf.text "This line is indented on both sides."
+    #  end
+    #
+    def indent(left, right = 0, &block)
+      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
+    # <total> refers to the total amount of pages in the document.  Page numbering should
+    # occur at the end of your Prawn::Document.generate block because the method iterates
+    # through existing pages after they are created.
+    #
+    # Parameters are:
+    #
+    # <tt>string</tt>:: Template string for page number wording.
+    #                   Should include '<page>' and, optionally, '<total>'.
+    # <tt>options</tt>:: A hash for page numbering and text box options.
+    #     <tt>:page_filter</tt>:: A filter to specify which pages to place page numbers on.
+    #                             Refer to the method 'page_match?'
+    #     <tt>:start_count_at</tt>:: The starting count to increment pages from.
+    #     <tt>:total_pages</tt>:: If provided, will replace <total> with the value given.
+    #                             Useful to override the total number of pages when using
+    #                             the start_count_at option.
+    #     <tt>:color</tt>:: Text fill color.
+    #
+    #     Please refer to Prawn::Text::text_box for additional options concerning text
+    #     formatting and placement.
+    #
+    # Example: Print page numbers on every page except for the first.  Start counting from
+    #          five.
+    #
+    #   Prawn::Document.generate("page_with_numbering.pdf") do
+    #     number_pages "<page> in a total of <total>",
+    #                                          {:start_count_at => 5,
+    #                                           :page_filter => lambda{ |pg| pg != 1 },
+    #                                           :at => [bounds.right - 50, 0],
+    #                                           :align => :right,
+    #                                           :size => 14}
+    #   end
+    #
+    def number_pages(string, options={})
+      opts = options.dup
+      start_count_at = opts.delete(:start_count_at).to_i
+      page_filter = if opts.has_key?(:page_filter)
+        opts.delete(:page_filter)
+      else
+        :all
+      end
+      total_pages = opts.delete(:total_pages)
+      txtcolor = opts.delete(:color)
+      # An explicit height so that we can draw page numbers in the margins
+      opts[:height] = 50 unless opts.has_key?(:height)
+
+      start_count = false
+      pseudopage = 0
+      (1..page_count).each do |p|
+        unless start_count
+          pseudopage = case start_count_at
+                       when 0
+                         1
+                       else
+                         start_count_at.to_i
+                       end
+        end
+        if page_match?(page_filter, p)
+          go_to_page(p)
+          # have to use fill_color here otherwise text reverts back to default fill color
+          fill_color txtcolor unless txtcolor.nil?
+          total_pages = total_pages.nil? ? page_count : total_pages
+          str = string.gsub("<page>","#{pseudopage}").gsub("<total>","#{total_pages}")
+          text_box str, opts
+          start_count = true  # increment page count as soon as first match found
+        end
+        pseudopage += 1 if start_count
+      end
+    end
+
+    # Provides a way to execute a block of code repeatedly based on a
+    # page_filter.
+    #
+    # Available page filters are:
+    #   :all         repeats on every page
+    #   :odd         repeats on odd pages
+    #   :even        repeats on even pages
+    #   some_array   repeats on every page listed in the array
+    #   some_range   repeats on every page included in the range
+    #   some_lambda  yields page number and repeats for true return values
+    def page_match?(page_filter, page_number)
+      case page_filter
+      when :all
+        true
+      when :odd
+        page_number % 2 == 1
+      when :even
+        page_number % 2 == 0
+      when Range, Array
+        page_filter.include?(page_number)
+      when Proc
+        page_filter.call(page_number)
+      end
+    end
+
+
+    # Returns true if content streams will be compressed before rendering,
+    # false otherwise
+    #
+    def compression_enabled?
+      !!state.compress
+    end
+
+    private
+
+    def merge_template_options(page_options, options)
+      object_id = state.store.import_page(options[:template], options[:template_page] || 1)
+      page_options.merge!(:object_id => object_id, :page_template => true)
+    end
+
+    # setting override_settings to true ensures that a new graphic state does not end up using
+    # previous settings especially from imported template streams
+    def use_graphic_settings(override_settings = false)
+      set_fill_color if current_fill_color != "000000" || override_settings
+      set_stroke_color if current_stroke_color != "000000" || override_settings
+      write_line_width if line_width != 1 || override_settings
+      write_stroke_cap_style if cap_style != :butt || override_settings
+      write_stroke_join_style if join_style != :miter || override_settings
+      write_stroke_dash if dashed? || override_settings
+    end
+
+    def generate_margin_box
+      old_margin_box = @margin_box
+      page           = state.page
+
+      @margin_box = BoundingBox.new(
+        self,
+        nil,  # margin box has no parent
+        [ page.margins[:left], page.dimensions[-1] - page.margins[:top] ] ,
+        :width => page.dimensions[-2] - (page.margins[:left] + page.margins[:right]),
+        :height => page.dimensions[-1] - (page.margins[:top] + page.margins[:bottom])
+      )
+
+      # This check maintains indentation settings across page breaks
+      if old_margin_box
+        @margin_box.add_left_padding(old_margin_box.total_left_padding)
+        @margin_box.add_right_padding(old_margin_box.total_right_padding)
+      end
+
+      # we must update bounding box if not flowing from the previous page
+      #
+      # FIXME: This may have a bug where the old margin is restored
+      # when the bounding box exits.
+      @bounding_box = @margin_box if old_margin_box == @bounding_box
+    end
+
+    def apply_margin_options(options)
+      if options[:margin]
+        # Treat :margin as CSS shorthand with 1-4 values.
+        margin = Array(options[:margin])
+        positions = { 4 => [0,1,2,3], 3 => [0,1,2,1],
+                      2 => [0,1,0,1], 1 => [0,0,0,0] }[margin.length]
+
+        [:top, :right, :bottom, :left].zip(positions).each do |p,i|
+          options[:"#{p}_margin"] ||= margin[i]
+        end
+      end
+
+      [:left,:right,:top,:bottom].each do |side|
+         if margin = options[:"#{side}_margin"]
+           state.page.margins[side] = margin
+         end
+      end
+    end
+  end
+end