prawn 0.15.0 → 1.0.0.rc1

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

@@ -7,13 +7,13 @@
 # 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"
-require_relative "document/span"
-require_relative "document/snapshot"
-require_relative "document/graphics_state"
+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
 
@@ -52,8 +52,8 @@ module Prawn
   #
   class Document
     include Prawn::Document::Internals
-    include PDF::Core::Annotations
-    include PDF::Core::Destinations
+    include Prawn::Core::Annotations
+    include Prawn::Core::Destinations
     include Prawn::Document::Snapshot
     include Prawn::Document::GraphicsState
     include Prawn::Document::Security
@@ -61,17 +61,6 @@ module Prawn
     include Prawn::Graphics
     include Prawn::Images
     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.
-
-    VALID_OPTIONS = [:page_size, :page_layout, :margin, :left_margin,
-                     :right_margin, :top_margin, :bottom_margin, :skip_page_creation,
-                     :compress, :skip_encoding, :background, :info,
-                     :optimize_objects, :text_formatter, :print_scaling]
 
     # 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
@@ -93,28 +82,14 @@ module Prawn
     #     party!
     #   end
     #
-    #
     def self.extensions
       @extensions ||= []
     end
 
-    # @private
-    def self.inherited(base) 
+    def self.inherited(base) #:nodoc:
       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
@@ -161,9 +136,8 @@ module Prawn
     # <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>:text_formatter</tt>: The text formatter to use for <tt>:inline_format</tt>ted text [Prawn::Text::Formatted::Parser]
+    # <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.
@@ -192,25 +166,25 @@ module Prawn
     #   pdf = Prawn::Document.new(:page_size => [200, 300])
     #
     #   # New document, with background
-    #   pdf = Prawn::Document.new(:background => "#{Prawn::DATADIR}/images/pigs.jpg")
+    #   pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")
     #
     def initialize(options={},&block)
       options = options.dup
 
-      Prawn.verify_options VALID_OPTIONS, options
+      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 = PDF::Core::DocumentState.new(options)
+      @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
 
-      min_version(1.6) if options[:print_scaling] == :none
-
       @background = options[:background]
-      @background_scale = options[:background_scale] || 1
       @font_size  = 12
 
       @bounding_box  = nil
@@ -218,12 +192,19 @@ module Prawn
 
       @page_number = 0
 
-      @text_formatter = options.delete(:text_formatter) || Text::Formatted::Parser
-
       options[:size] = options.delete(:page_size)
       options[:layout] = options.delete(:page_layout)
 
-      initialize_first_page(options)
+      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
 
@@ -232,7 +213,18 @@ module Prawn
       end
     end
 
-    # @group Stable API
+    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.
     #
@@ -244,6 +236,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
@@ -255,13 +252,14 @@ module Prawn
                       :layout  => options[:layout] || last_page_layout,
                       :margins => last_page_margins}
       if last_page
-        new_graphic_state = last_page.graphic_state.dup  if last_page.graphic_state
+        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 = {} if new_graphic_state
+        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 = PDF::Core::Page.new(self, page_options)
+      state.page = Prawn::Core::Page.new(self, page_options)
 
       apply_margin_options(options)
       generate_margin_box
@@ -272,13 +270,14 @@ module Prawn
         @bounding_box = @margin_box
       end
 
-      use_graphic_settings
+      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
+        canvas { image(@background, :at => bounds.top_left) } if @background
         @y = @bounding_box.absolute_top
 
         float do
@@ -349,26 +348,19 @@ module Prawn
       self.y = original_y
     end
 
-    # Renders the PDF document to string.
-    # Pass an open file descriptor to render to file.
+    # Renders the PDF document to string
     #
-    def render(output = StringIO.new)
-      if output.instance_of?(StringIO)
-        output.set_encoding(::Encoding::ASCII_8BIT)
-      end
+    def render
+      output = StringIO.new
       finalize_all_page_contents
 
       render_header(output)
       render_body(output)
       render_xref(output)
       render_trailer(output)
-      if output.instance_of?(StringIO)
-        str = output.string
-        str.force_encoding(::Encoding::ASCII_8BIT)
-        return str
-      else
-        return nil
-      end
+      str = output.string
+      str.force_encoding("ASCII-8BIT") if str.respond_to?(:force_encoding)
+      str
     end
 
     # Renders the PDF document to file.
@@ -376,7 +368,8 @@ module Prawn
     #   pdf.render_file "foo.pdf"
     #
     def render_file(filename)
-      File.open(filename, "wb") { |f| render(f) }
+      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,
@@ -412,7 +405,6 @@ module Prawn
 
     # Returns the innermost non-stretchy bounding box.
     #
-    # @private
     def reference_bounds
       @bounding_box.reference_bounds
     end
@@ -498,6 +490,47 @@ 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
@@ -506,15 +539,15 @@ module Prawn
     # through existing pages after they are created.
     #
     # Parameters are:
-    #
-    # <tt>string</tt>:: Template string for page number wording.
+    # 
+    # <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.
+    #     <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
+    #                             Useful to override the total number of pages when using 
     #                             the start_count_at option.
     #     <tt>:color</tt>:: Text fill color.
     #
@@ -525,7 +558,7 @@ module Prawn
     #          five.
     #
     #   Prawn::Document.generate("page_with_numbering.pdf") do
-    #     number_pages "<page> in a total of <total>",
+    #     number_pages "<page> in a total of <total>", 
     #                                          {:start_count_at => 5,
     #                                           :page_filter => lambda{ |pg| pg != 1 },
     #                                           :at => [bounds.right - 50, 0],
@@ -544,8 +577,8 @@ module Prawn
       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)
-
+      opts[:height] = 50
+      
       start_count = false
       pseudopage = 0
       (1..page_count).each do |p|
@@ -556,7 +589,7 @@ module Prawn
                        else
                          start_count_at.to_i
                        end
-        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
@@ -565,53 +598,13 @@ module Prawn
           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
+        end 
         pseudopage += 1 if start_count
       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.
+    # page_filter.  
     #
     # Available page filters are:
     #   :all         repeats on every page
@@ -619,7 +612,7 @@ module Prawn
     #   :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
+    #   some_lambda  yields page number and repeats for true return values 
     def page_match?(page_filter, page_number)
       case page_filter
       when :all
@@ -633,47 +626,25 @@ module Prawn
       when Proc
         page_filter.call(page_number)
       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
-
-    # @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
+    end  
 
-    ## Internals. Don't depend on them!
 
-    # @private
-    def state
-      @internal_state
-    end
-
-    # @private
-    def page
-      state.page
+    # 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 )
+    end
 
     # setting override_settings to true ensures that a new graphic state does not end up using
-    # previous settings.
+    # 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
@@ -726,9 +697,5 @@ module Prawn
          end
       end
     end
-
-    def font_metric_cache #:nodoc:
-      @font_metric_cache ||= FontMetricCache.new( self )
-    end
   end
 end