prawn 0.11.1.pre → 0.11.1

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

@@ -8,7 +8,6 @@ module Prawn
         module Wrap #:nodoc:
 
           def initialize(array, options)
-            super(array, options)
             @line_wrap = Prawn::Core::Text::Formatted::LineWrap.new
             @arranger = Prawn::Core::Text::Formatted::Arranger.new(@document)
           end
@@ -16,8 +15,7 @@ module Prawn
 
           # See the developer documentation for Prawn::Core::Text#wrap
           #
-          # Formatted#wrap should set some of the variables slightly differently
-          # than 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>::
@@ -26,56 +24,93 @@ module Prawn
           #   <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)
 
-            move_baseline = true
-            while @arranger.unfinished?
-              printed_fragments = []
-
-              line_to_print = @line_wrap.wrap_line(:document => @document,
-                                                   :kerning => @kerning,
-                                                   :width => available_width,
-                                                   :arranger => @arranger)
-
-              move_baseline = false
-              break unless enough_height_for_this_line?
-              move_baseline_down
-
-              accumulated_width = 0
-              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
-                format_and_draw_fragment(fragment, accumulated_width,
-                                         @line_wrap.width, word_spacing)
-                accumulated_width += fragment.width
+            stop = false
+            while !stop
+              @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
-              @printed_lines << printed_fragments.join("")
-              break if @single_line
-              move_baseline = true unless @arranger.finished?
+
+              stop ||= @single_line || @arranger.finished?
             end
-            move_baseline_down if move_baseline
             @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
-            required_height = @baseline_y == 0 ? @line_height : @line_height + @descender
-            if @baseline_y.abs + required_height > @height
+            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
@@ -95,6 +130,8 @@ module Prawn
             @baseline_y  = 0
 
             @printed_lines = []
+            @nothing_printed = true
+            @everything_printed = false
           end
 
           def format_and_draw_fragment(fragment, accumulated_width,

data/lib/prawn/document.rb

@@ -9,36 +9,37 @@
 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 
+  #
+  # 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
@@ -46,7 +47,7 @@ module Prawn
   #
   # 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
@@ -68,11 +69,11 @@ module Prawn
     # Example:
     #
     #   module MyFancyModule
-    #    
+    #
     #     def party!
     #       text "It's a big party!"
     #     end
-    #   
+    #
     #   end
     #
     #   Prawn::Document.extensions << MyFancyModule
@@ -152,7 +153,7 @@ module Prawn
     #
     # 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
@@ -167,9 +168,9 @@ module Prawn
     #   # New document, with background
     #   pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")
     #
-    def initialize(options={},&block)   
-       Prawn.verify_options [:page_size, :page_layout, :margin, :left_margin, 
-         :right_margin, :top_margin, :bottom_margin, :skip_page_creation, 
+    def initialize(options={},&block)
+       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
 
@@ -204,7 +205,7 @@ module Prawn
        end
 
        @bounding_box = @margin_box
-       
+
        if block
          block.arity < 1 ? instance_eval(&block) : block[self]
        end
@@ -233,6 +234,11 @@ module Prawn
      #   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)
+     #
      def start_new_page(options = {})
        if last_page = state.page
          last_page_size    = last_page.size
@@ -240,29 +246,36 @@ module Prawn
          last_page_margins = last_page.margins
        end
 
-       state.page = Prawn::Core::Page.new(self, 
-         :size    => options[:size]   || last_page_size, 
-         :layout  => options[:layout] || last_page_layout,
-         :margins => last_page_margins )
+       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)
+       state.page.new_content_stream if options[:template]
+       use_graphic_settings(options[:template])
 
-       use_graphic_settings
-      
        unless options[:orphan]
          state.insert_page(state.page, @page_number)
          @page_number += 1
 
-         save_graphics_state
-        
-         canvas { image(@background, :at => bounds.top_left) } if @background 
+         canvas { image(@background, :at => bounds.top_left) } if @background
          @y = @bounding_box.absolute_top
 
          float do
            state.on_page_create_action(self)
          end
        end
-    end
+
+     end
 
     # Returns the number of pages in the document
     #
@@ -274,9 +287,9 @@ module Prawn
     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. 
+    # draw on it.
     #
     # See Prawn::Document#number_pages for a sample usage of this capability.
     #
@@ -300,7 +313,7 @@ module Prawn
     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
@@ -314,9 +327,9 @@ module Prawn
     #     pdf.text "C"
     #   end
     #
-    #   pdf.text "B" 
-    #   
-    def float 
+    #   pdf.text "B"
+    #
+    def float
       mask(:y) { yield }
     end
 
@@ -353,12 +366,12 @@ module Prawn
     # 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)
@@ -366,17 +379,17 @@ module Prawn
     #      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
 
     # 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 
+    # 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.
     #
@@ -386,14 +399,14 @@ module Prawn
 
     # 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
@@ -438,8 +451,8 @@ module Prawn
       yield
       move_down(y)
     end
-    
-    
+
+
     # Indents the specified number of PDF points for the duration of the block
     #
     #  pdf.text "some text"
@@ -448,11 +461,14 @@ module Prawn
     #  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(x, &block)
-      bounds.indent(x, &block)
+    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
@@ -467,7 +483,8 @@ module Prawn
     # 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).
+    # (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.
@@ -488,48 +505,128 @@ module Prawn
         raise Prawn::Errors::CannotGroup if second_attempt
         old_bounding_box.move_past_bottom
         group(second_attempt=true) { yield }
-      end 
+      end
+
+      success
     end
 
-    # Specify a template for page numbering.  This should be called
+    # 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 doucment.
+    # <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.
     #
-    # Example:
+    # 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
-    #     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]  
+    #     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, position)
-      page_count.times do |i|
-        go_to_page(i+1)
-        str = string.gsub("<page>","#{i+1}").gsub("<total>","#{page_count}")
-        draw_text str, :at => position
+    def number_pages(string, options={})
+      opts = options.dup
+      start_count_at = opts.delete(:start_count_at).to_i
+      page_filter = opts.delete(:page_filter)
+      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
+      
+      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 use_graphic_settings
-      update_colors
-      line_width(line_width) unless line_width == 1
-      cap_style(cap_style) unless cap_style == :butt
-      join_style(join_style) unless join_style == :miter
-      dash(dash[:dash], dash) if dashed?
+    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 )
+    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
@@ -538,18 +635,25 @@ module Prawn
 
       @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.