prawn 0.11.1 → 0.15.0

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 "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"
+
+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"
 
 module Prawn
 
@@ -52,8 +52,8 @@ module Prawn
   #
   class Document
     include Prawn::Document::Internals
-    include Prawn::Core::Annotations
-    include Prawn::Core::Destinations
+    include PDF::Core::Annotations
+    include PDF::Core::Destinations
     include Prawn::Document::Snapshot
     include Prawn::Document::GraphicsState
     include Prawn::Document::Security
@@ -61,6 +61,17 @@ 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
@@ -82,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
@@ -136,8 +161,9 @@ 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>:template</tt>:: The path to an existing PDF file to use as a template [nil]
+    # <tt>:text_formatter</tt>: The text formatter to use for <tt>:inline_format</tt>ted text [Prawn::Text::Formatted::Parser]
     #
     # 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.
@@ -166,116 +192,100 @@ module Prawn
     #   pdf = Prawn::Document.new(:page_size => [200, 300])
     #
     #   # New document, with background
-    #   pdf = Prawn::Document.new(:background => "#{Prawn::BASEDIR}/data/images/pigs.jpg")
+    #   pdf = Prawn::Document.new(:background => "#{Prawn::DATADIR}/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,
-         :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]
-       @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)
-     #
-     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)
-       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, :at => bounds.top_left) } if @background
-         @y = @bounding_box.absolute_top
-
-         float do
-           state.on_page_create_action(self)
-         end
-       end
+      options = options.dup
+
+      Prawn.verify_options VALID_OPTIONS, 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.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
+      @margin_box    = nil
+
+      @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)
+
+      @bounding_box = @margin_box
+
+      if block
+        block.arity < 1 ? instance_eval(&block) : block[self]
+      end
+    end
+
+    # @group Stable API
+
+    # 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)
+    #
+    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  if last_page.graphic_state
+        #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
+        page_options.merge!(:graphic_state => new_graphic_state)
+      end
+
+      state.page = PDF::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
+
+      use_graphic_settings
 
-     end
+      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
     #
@@ -318,7 +328,9 @@ module Prawn
       self.y = new_y + bounds.absolute_bottom
     end
 
-    # Executes a block and then restores the original y position
+    # 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"
     #
@@ -330,22 +342,33 @@ module Prawn
     #   pdf.text "B"
     #
     def float
-      mask(:y) { yield }
+      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
+    # Renders the PDF document to string.
+    # Pass an open file descriptor to render to file.
     #
-    def render
-      output = StringIO.new
+    def render(output = StringIO.new)
+      if output.instance_of?(StringIO)
+        output.set_encoding(::Encoding::ASCII_8BIT)
+      end
       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
+      if output.instance_of?(StringIO)
+        str = output.string
+        str.force_encoding(::Encoding::ASCII_8BIT)
+        return str
+      else
+        return nil
+      end
     end
 
     # Renders the PDF document to file.
@@ -353,8 +376,7 @@ module Prawn
     #   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 }
+      File.open(filename, "wb") { |f| render(f) }
     end
 
     # The bounds method returns the current bounding box you are currently in,
@@ -388,6 +410,13 @@ module Prawn
       @bounding_box
     end
 
+    # Returns the innermost non-stretchy bounding box.
+    #
+    # @private
+    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
@@ -469,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
@@ -518,15 +506,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.
     #
@@ -537,7 +525,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],
@@ -548,12 +536,16 @@ module Prawn
     def number_pages(string, options={})
       opts = options.dup
       start_count_at = opts.delete(:start_count_at).to_i
-      page_filter = opts.delete(:page_filter)
+      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
-      
+      opts[:height] = 50 unless opts.has_key?(:height)
+
       start_count = false
       pseudopage = 0
       (1..page_count).each do |p|
@@ -564,7 +556,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
@@ -573,13 +565,53 @@ 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
@@ -587,7 +619,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
@@ -601,25 +633,47 @@ module Prawn
       when Proc
         page_filter.call(page_number)
       end
-    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
 
-    private
+    ## Internals. Don't depend on them!
 
-    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 )
+    # @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 especially from imported template streams
+    # previous settings.
     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
@@ -642,7 +696,7 @@ module Prawn
       )
 
       # This check maintains indentation settings across page breaks
-      if (old_margin_box)
+      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
@@ -671,8 +725,10 @@ module Prawn
            state.page.margins[side] = margin
          end
       end
+    end
 
-      generate_margin_box
+    def font_metric_cache #:nodoc:
+      @font_metric_cache ||= FontMetricCache.new( self )
     end
   end
 end

data/lib/prawn/encoding.rb

@@ -5,7 +5,7 @@
 # This is free software. Please see the LICENSE and COPYING files for details.
 #
 module Prawn
-  module Encoding
+  module Encoding # @private
     # Map between unicode and WinAnsiEnoding
     #
     class WinAnsi #:nodoc:
@@ -18,7 +18,7 @@ module Prawn
         .notdef       .notdef        .notdef        .notdef
         .notdef       .notdef        .notdef        .notdef
         .notdef       .notdef        .notdef        .notdef
-        
+
         space         exclam         quotedbl       numbersign
         dollar        percent        ampersand      quotesingle
         parenleft     parenright     asterisk       plus
@@ -54,7 +54,7 @@ module Prawn
         quotedblright bullet         endash         emdash
         tilde         trademark      scaron         guilsinglright
         oe            .notdef        zcaron         ydieresis
-       
+
         space         exclamdown     cent           sterling
         currency      yen            brokenbar      section
         dieresis      copyright      ordfeminine    guillemotleft
@@ -81,10 +81,10 @@ module Prawn
         ocircumflex   otilde         odieresis      divide
         oslash        ugrave         uacute         ucircumflex
         udieresis     yacute         thorn          ydieresis
-      ]    
-      
+      ]
+
       def initialize
-        @mapping_file = "#{Prawn::BASEDIR}/data/encodings/win_ansi.txt"
+        @mapping_file = "#{Prawn::DATADIR}/encodings/win_ansi.txt"
         load_mapping if self.class.mapping.empty?
       end
 
@@ -100,7 +100,7 @@ module Prawn
         # Replace anything else with an underscore
         self.class.mapping[codepoint] || 95
       end
-      
+
       def self.mapping
         @mapping ||= {}
       end
@@ -108,10 +108,9 @@ module Prawn
       private
 
       def load_mapping
-        RUBY_VERSION >= "1.9" ? mode = "r:BINARY" : mode = "r"
-        File.open(@mapping_file, mode) do |f|
+        File.open(@mapping_file, "r:BINARY") do |f|
           f.each do |l|
-            m, single_byte, unicode = *l.match(/([0-9A-Za-z]+);([0-9A-F]{4})/)
+            _, single_byte, unicode = *l.match(/([0-9A-Za-z]+);([0-9A-F]{4})/)
             self.class.mapping["0x#{unicode}".hex] = "0x#{single_byte}".hex if single_byte
           end
         end