prawn-core 0.7.2 → 0.8.4

data/lib/prawn/pdf_object.rb

@@ -48,7 +48,7 @@ module Prawn
     when String
       obj = "\xFE\xFF" + obj.unpack("U*").pack("n*") unless in_content_stream
       "<" << obj.unpack("H*").first << ">"
-    when Symbol                                                         
+     when Symbol                                                         
        if (obj = obj.to_s) =~ /\s/
          raise Prawn::Errors::FailedObjectConversion, 
            "A PDF Name cannot contain whitespace"  
@@ -57,14 +57,14 @@ module Prawn
        end 
     when Hash           
       output = "<< "
-      obj.each do |k,v|                                                        
+      obj.each do |k,v|  
         unless String === k || Symbol === k
           raise Prawn::Errors::FailedObjectConversion, 
             "A PDF Dictionary must be keyed by names"
         end                          
         output << PdfObject(k.to_sym, in_content_stream) << " " << 
                   PdfObject(v, in_content_stream) << "\n"
-      end   
+      end  
       output << ">>"  
     when Prawn::Reference
       obj.to_s      
@@ -72,6 +72,8 @@ module Prawn
       PdfObject(obj.to_hash)
     when Prawn::NameTree::Value
       PdfObject(obj.name) + " " + PdfObject(obj.value)
+    when Prawn::OutlineRoot, Prawn::OutlineItem
+      PdfObject(obj.to_hash)
     else
       raise Prawn::Errors::FailedObjectConversion, 
         "This object cannot be serialized to PDF"

data/lib/prawn/repeater.rb

@@ -31,43 +31,50 @@ module Prawn
     #   some_range  -- repeats on every page included in the range
     #   some_lambda -- yields page number and repeats for true return values 
     #
+    # Also accepts an optional second argument for dynamic content which executes the code 
+    # in the context of the filtered pages without using a Stamp. 
+    #
     # Example:
     #
     #   Prawn::Document.generate("repeat.pdf", :skip_page_creation => true) do
     #
     #     repeat :all do
-    #       text "ALLLLLL", :at => bounds.top_left
+    #       draw_text "ALLLLLL", :at => bounds.top_left
     #     end
     #
     #     repeat :odd do
-    #       text "ODD", :at => [0,0]
+    #       draw_text "ODD", :at => [0,0]
     #     end
     #
     #     repeat :even do
-    #       text "EVEN", :at => [0,0]
+    #       draw_text "EVEN", :at => [0,0]
     #     end
     # 
     #     repeat [1,2] do 
-    #       text "[1,2]", :at => [100,0]
+    #       draw_text "[1,2]", :at => [100,0]
     #     end
     #
     #     repeat 2..4 do
-    #       text "2..4", :at => [200,0]
+    #       draw_text "2..4", :at => [200,0]
     #     end
     #
     #     repeat(lambda { |pg| pg % 3 == 0 }) do
-    #       text "Every third", :at => [250, 20]
+    #       draw_text "Every third", :at => [250, 20]
     #     end
     #
     #     10.times do 
     #       start_new_page
-    #       text "A wonderful page", :at => [400,400]
+    #       draw_text "A wonderful page", :at => [400,400]
+    #     end
+    #     
+    #     repeat(:all, :dynamic => true) do
+    #       text page_number, :at => [500, 0]
     #     end
     #
     #   end
     #
-    def repeat(page_filter, &block)
-      repeaters << Prawn::Repeater.new(self, page_filter, &block)
+    def repeat(page_filter, options={}, &block)
+      repeaters << Prawn::Repeater.new(self, page_filter, !!options[:dynamic], &block)
     end
   end
 
@@ -82,12 +89,13 @@ module Prawn
 
     attr_reader :name
 
-    def initialize(document, page_filter, &block)
+    def initialize(document, page_filter, dynamic = false, &block)
       @document    = document
       @page_filter = page_filter
+      @dynamic = dynamic
       @stamp_name  = "prawn_repeater(#{Repeater.count})"
-
-      @document.create_stamp(@stamp_name, &block)
+      @document.create_stamp(@stamp_name, &block) unless dynamic
+      @block = block if dynamic
 
       Repeater.count += 1
     end
@@ -108,7 +116,11 @@ module Prawn
     end
 
     def run(page_number)
-      @document.stamp(@stamp_name) if match?(page_number)
+      if !@dynamic
+        @document.stamp(@stamp_name) if match?(page_number)
+      elsif @block
+        @block.arity < 1 ? @document.instance_eval(&@block) : @block[@document]
+      end
     end
 
   end

data/lib/prawn/stamp.rb

@@ -22,7 +22,7 @@ module Prawn
   # Example:
   #   pdf.create_stamp("my_stamp") {
   #     pdf.fill_circle_at([10, 15], :radius => 5)
-  #     pdf.text("hello world", :at => [20, 10])
+  #     pdf.draw_text("hello world", :at => [20, 10])
   #   }
   #   pdf.stamp("my_stamp")
   #
@@ -43,7 +43,7 @@ module Prawn
     def stamp(name)
       dictionary_name, dictionary = stamp_dictionary(name)
       add_content "/#{dictionary_name} Do"
-      page_xobjects.merge!(dictionary_name => dictionary)
+      page.xobjects.merge!(dictionary_name => dictionary)
     end
 
     # Renders the stamp named <tt>name</tt> at a position offset from
@@ -60,19 +60,7 @@ module Prawn
     # See stamp() for exceptions that might be raised
     #
     def stamp_at(name, point)
-      # Save the graphics state
-      add_content "q"
-
-      # Translate the user space
-      x,y = point
-      translate_position = "1 0 0 1 %.3f %.3f cm" % [x, y]
-      add_content translate_position
-      
-      # Draw the stamp in the now translated user space
-      stamp(name)
-      
-      # Restore the graphics state to remove the translation
-      add_content "Q"
+      translate(point[0], point[1]) { stamp(name) }
     end
 
     # Creates a re-usable stamp named <tt>name</tt>
@@ -84,24 +72,13 @@ module Prawn
     # Example:
     #   pdf.create_stamp("my_stamp") {
     #     pdf.fill_circle_at([10, 15], :radius => 5)
-    #     pdf.text("hello world", :at => [20, 10])
+    #     pdf.draw_text("hello world", :at => [20, 10])
     #   }
     #
     def create_stamp(name, &block)
       dictionary = create_stamp_dictionary(name)
 
-      @active_stamp_stream = ""
-      @active_stamp_dictionary = dictionary
-
-      update_colors
-      yield if block_given?
-      update_colors
-
-      dictionary.data[:Length] = @active_stamp_stream.length + 1
-      dictionary << @active_stamp_stream
-
-      @active_stamp_stream = nil
-      @active_stamp_dictionary = nil
+      page.stamp_stream(dictionary, &block)
     end
     
     private
@@ -136,7 +113,7 @@ module Prawn
       dictionary = ref!(:Type    => :XObject,
                         :Subtype => :Form,
                         :BBox    => [0, 0,
-                                     page_dimensions[2], page_dimensions[3]])
+                                     page.dimensions[2], page.dimensions[3]])
 
       dictionary_name = "Stamp#{next_stamp_dictionary_id}"
 

data/lib/prawn/text.rb

@@ -5,25 +5,33 @@
 # Copyright May 2008, Gregory Brown. All Rights Reserved.
 #
 # This is free software. Please see the LICENSE and COPYING files for details.
-require "zlib"
+
+require "prawn/core/text"
 require "prawn/text/box"
+require "zlib"
 
 module Prawn
   module Text
-    attr_reader :text_options
-    attr_reader :skip_encoding
 
-    ruby_18 { $KCODE="U" }
+    include Prawn::Core::Text
 
-    # Gets height of text in PDF points. See text() for valid options.
+    VALID_OPTIONS = Prawn::Core::Text::VALID_OPTIONS + [:at, :rotate]
+
+    # Gets height of text in PDF points.
+    # Same options as text(), except as noted.
+    # Not compatible with :indent_paragraphs option
+    #
+    # Raises <tt>Prawn::Errors::UnknownOption</tt> if
+    # <tt>:indent_paragraphs</tt> option included and debug flag is set
     #
     def height_of(string, options={})
+      process_final_gap_option(options)
       box = Text::Box.new(string,
                           options.merge(:height   => 100000000,
                                         :document => self))
       box.render(:dry_run => true)
       height = box.height - box.descender
-      height += box.line_height + box.leading - box.ascender # if final_gap
+      height += box.line_height + box.leading - box.ascender if @final_gap
       height
     end
 
@@ -32,19 +40,12 @@ module Prawn
     # the flow of a document (for captions, labels, charts, etc.), use Text::Box
     # or its convenience method text_box.
     # 
-    # Draws text on the page. If a point is specified via the <tt>:at</tt>
-    # option the text will begin exactly at that point, and the string is
-    # assumed to be pre-formatted to properly fit the page.
-    # 
-    #   pdf.text "Hello World", :at => [100,100]
-    #   pdf.text "Goodbye World", :at => [50,50], :size => 16
-    #
-    # When <tt>:at</tt> is not specified, Prawn attempts to wrap the text to
-    # fit within your current bounding box (or margin_box if no bounding box
-    # is being used ). Text will flow onto the next page when it reaches
-    # the bottom of the bounding box. Text wrap in Prawn does not re-flow
-    # linebreaks, so if you want fully automated text wrapping, be sure to
-    # remove newlines before attempting to draw your string.  
+    # Draws text on the page. Prawn attempts to wrap the text to fit within your
+    # current bounding box (or margin_box if no bounding box is being used).
+    # Text will flow onto the next page when it reaches the bottom of the
+    # bounding box. Text wrap in Prawn does not re-flow linebreaks, so if you
+    # want fully automated text wrapping, be sure to remove newlines before
+    # attempting to draw your string.
     #
     #   pdf.text "Will be wrapped when it hits the edge of your bounding box"
     #   pdf.text "This will be centered", :align => :center
@@ -55,20 +56,10 @@ module Prawn
     # <tt>:kerning => false</tt>.
     #
     # === Text Positioning Details:
-    #
-    # When using the :at parameter, Prawn will position your text by the
-    # left-most edge of its baseline, and flow along a single line.  (This
-    # means that :align will not work)
     # 
-    # Otherwise, the text is positioned at font.ascender below the baseline,
+    # The text is positioned at font.ascender below the baseline,
     # making it easy to use this method within bounding boxes and spans.
     #
-    # == Rotation
-    #
-    # Text can be rotated before it is placed on the canvas by specifying the
-    # <tt>:rotate</tt> option with a given angle. Rotation occurs counter-clockwise.
-    # Note that <tt>:rotate</tt> is only compatible when using the <tt>:at</tt> option
-    #
     # == Encoding
     #
     # Note that strings passed to this function should be encoded as UTF-8.
@@ -90,14 +81,9 @@ module Prawn
     #                  size]
     # <tt>:style</tt>:: The style to use. The requested style must be part of
     #                   the current font familly. [current style]
-    #
-    # === Additional options available when <tt>:at</tt> option is provided
-    #
-    # <tt>:at</tt>:: <tt>[x, y]</tt>. The position at which to start the text
-    # <tt>:rotate</tt>:: <tt>number</tt>. The angle to which to rotate text
-    #
-    # === Additional options available when <tt>:at</tt> option is omitted
-    #
+    # <tt>:indent_paragraphs</tt>:: <tt>number</tt>. The amount to indent the
+    #                               first line of each paragraph. Omit this
+    #                               option if you do not want indenting
     # <tt>:align</tt>:: <tt>:left</tt>, <tt>:center</tt>, or <tt>:right</tt>.
     #                   Alignment within the bounding box [:left]
     # <tt>:valign</tt>:: <tt>:top</tt>, <tt>:center</tt>, or <tt>:bottom</tt>.
@@ -121,69 +107,113 @@ module Prawn
     #                        <tt>:kerning</tt>:: boolean
     #                        <tt>:size</tt>:: the font size
     #
-    # Raises <tt>ArgumentError</tt> if both <tt>:at</tt> and <tt>:align</tt>
-    # options included
-    #
-    # Raises <tt>ArgumentError</tt> if <tt>:rotate</tt> option included, but
-    # <tt>:at</tt> option omitted
+    # Raises <tt>ArgumentError</tt> if <tt>:at</tt> option included
     #
-    def text(text, options={})
-      # we might modify the options. don't change the user's hash
+    def text(string, options={})
+      # we modify the options. don't change the user's hash
       options = options.dup
-      if options[:at]
-        inspect_options_for_text_at(options)
-        # we'll be messing with the strings encoding, don't change the user's
-        # original string
-        text = text.to_s.dup
-        options = @text_options.merge(options)
-        save_font do
-          process_text_options(options)
-          font.normalize_encoding!(text) unless @skip_encoding
-          font_size(options[:size]) { text_at(text, options) }
-        end
-      else
-        remaining_text = fill_text_box(text, options)
-        while remaining_text.length > 0
-          @bounding_box.move_past_bottom
-          previous_remaining_text = remaining_text
+      inspect_options_for_text(options)
+
+      if @indent_paragraphs
+        string.split("\n").each do |paragraph|
+          options[:skip_encoding] = false
+          remaining_text = draw_indented_line(paragraph, options)
+          options[:skip_encoding] = true
+          if remaining_text == paragraph
+            # we were too close to the bottom of the page to print even one line
+            @bounding_box.move_past_bottom
+            remaining_text = draw_indented_line(paragraph, options)
+          end
           remaining_text = fill_text_box(remaining_text, options)
-          break if remaining_text == previous_remaining_text
+          draw_remaining_text_on_new_pages(remaining_text, options)
         end
+      else
+        remaining_text = fill_text_box(string, options)
+        options[:skip_encoding] = true
+        draw_remaining_text_on_new_pages(remaining_text, options)
       end
     end
 
-    # Low level text placement method. All font and size alterations
-    # should already be set
+    # Draws text on the page, beginning at the point specified by the :at option
+    # the string is assumed to be pre-formatted to properly fit the page.
+    # 
+    #   pdf.draw_text "Hello World", :at => [100,100]
+    #   pdf.draw_text "Goodbye World", :at => [50,50], :size => 16
+    #
+    # If your font contains kerning pairs data that Prawn can parse, the 
+    # text will be kerned by default.  You can disable this feature by passing
+    # <tt>:kerning => false</tt>.
+    #
+    # === Text Positioning Details:
+    #
+    # Prawn will position your text by the left-most edge of its baseline, and
+    # flow along a single line.  (This means that :align will not work)
+    #
+    # == Rotation
+    #
+    # Text can be rotated before it is placed on the canvas by specifying the
+    # <tt>:rotate</tt> option with a given angle. Rotation occurs counter-clockwise.
+    #
+    # == Encoding
     #
-    def text_at(text, options)
-      x,y = translate(options[:at])
-      add_text_content(text,x,y,options)
+    # Note that strings passed to this function should be encoded as UTF-8.
+    # If you get unexpected characters appearing in your rendered document, 
+    # check this.
+    #
+    # If the current font is a built-in one, although the string must be
+    # encoded as UTF-8, only characters that are available in WinAnsi
+    # are allowed.
+    #
+    # If an empty box is rendered to your PDF instead of the character you 
+    # wanted it usually means the current font doesn't include that character.
+    #
+    # == Options (default values marked in [])
+    #
+    # <tt>:at</tt>:: <tt>[x, y]</tt>(required). The position at which to start the text
+    # <tt>:kerning</tt>:: <tt>boolean</tt>. Whether or not to use kerning (if it
+    #                     is available with the current font) [true]
+    # <tt>:size</tt>:: <tt>number</tt>. The font size to use. [current font
+    #                  size]
+    # <tt>:style</tt>:: The style to use. The requested style must be part of
+    #                   the current font familly. [current style]
+    #
+    # <tt>:rotate</tt>:: <tt>number</tt>. The angle to which to rotate text
+    #
+    # Raises <tt>ArgumentError</tt> if <tt>:at</tt> option omitted
+    # Raises <tt>ArgumentError</tt> if <tt>:align</tt> option included
+    #
+    def draw_text(text, options)
+      # we modify the options. don't change the user's hash
+      options = options.dup
+      inspect_options_for_draw_text(options)
+      # dup because normalize_encoding changes the string
+      text = text.to_s.dup
+      options = @text_options.merge(options)
+      save_font do
+        process_text_options(options)
+        font.normalize_encoding!(text) unless @skip_encoding
+        font_size(options[:size]) { draw_text!(text, options) }
+      end
     end
 
-    # These should be used as a base. Extensions may build on this list
-    VALID_TEXT_OPTIONS = [:kerning, :size, :style]
+    private
 
-    # Low level call to set the current font style and extract text options from
-    # an options hash. Should be called from within a save_font block
-    #
-    def process_text_options(options)
-      if options[:style]
-        raise "Bad font family" unless font.family
-        font(font.family, :style => options[:style])
+    def draw_remaining_text_on_new_pages(remaining_text, options)
+      while remaining_text.length > 0
+        @bounding_box.move_past_bottom
+        previous_remaining_text = remaining_text
+        remaining_text = fill_text_box(remaining_text, options)
+        break if remaining_text == previous_remaining_text
       end
+    end
 
-      # must compare against false to keep kerning on as default
-      unless options[:kerning] == false
-        options[:kerning] = font.has_kerning_data?
+    def draw_indented_line(string, options)
+      indent(@indent_paragraphs) do
+        fill_text_box(string, options.dup.merge(:single_line => true))
       end
-
-      options[:size] ||= font_size
     end
 
-    private
-
     def fill_text_box(text, options)
-      final_gap = inspect_options_for_text_box(options)
       bottom = @bounding_box.stretchy? ? @margin_box.absolute_bottom :
                                          @bounding_box.absolute_bottom
 
@@ -196,27 +226,39 @@ module Prawn
       remaining_text = box.render
 
       self.y -= box.height - box.descender
-      self.y -= box.line_height + box.leading - box.ascender if final_gap
-
+      if @final_gap
+        self.y -= box.line_height + box.leading - box.ascender
+      end
       remaining_text
     end
 
-    def inspect_options_for_text_at(options)
-      if options[:align]
-        raise ArgumentError, "The :align option does not work with :at"
+    def inspect_options_for_draw_text(options)
+      if options[:at].nil?
+        raise ArgumentError, "The :at option is required for draw_text"
+      elsif options[:align]
+        raise ArgumentError, "The :align option does not work with draw_text"
       end
-      valid_options = VALID_TEXT_OPTIONS.dup.concat([:at, :rotate])
-      Prawn.verify_options(valid_options, options)
+      Prawn.verify_options(VALID_OPTIONS, options)
     end
 
-    def inspect_options_for_text_box(options)
-      if options[:rotate]
-        raise ArgumentError, "Rotated text may only be used with :at"
+    def inspect_options_for_text(options)
+      if options[:at]
+        raise ArgumentError, ":at is no longer a valid option with text." +
+                             "use draw_text or text_box instead"
       end
-      options.merge!(:document => self)
-      final_gap = options[:final_gap].nil? ? true : options[:final_gap]
+      process_final_gap_option(options)
+      process_indent_paragraphs_option(options)
+      options[:document] = self
+    end
+
+    def process_final_gap_option(options)
+      @final_gap = options[:final_gap].nil? || options[:final_gap]
       options.delete(:final_gap)
-      final_gap
+    end
+
+    def process_indent_paragraphs_option(options)
+      @indent_paragraphs = options[:indent_paragraphs]
+      options.delete(:indent_paragraphs)
     end
 
     def move_text_position(dy)
@@ -227,29 +269,5 @@ module Prawn
 
       self.y -= dy
     end
-
-    def add_text_content(text, x, y, options)
-      chunks = font.encode_text(text,options)
-
-      add_content "\nBT"
-
-      if options[:rotate]
-        rad = options[:rotate].to_i * Math::PI / 180
-        arr = [ Math.cos(rad), Math.sin(rad), -Math.sin(rad), Math.cos(rad), x, y ]
-        add_content "%.3f %.3f %.3f %.3f %.3f %.3f Tm" % arr
-      else
-        add_content "#{x} #{y} Td"
-      end
-
-      chunks.each do |(subset, string)|
-        font.add_to_current_page(subset)
-        add_content "/#{font.identifier_for(subset)} #{font_size} Tf"
-
-        operation = options[:kerning] && string.is_a?(Array) ? "TJ" : "Tj"
-        add_content Prawn::PdfObject(string, true) << " " << operation
-      end
-
-      add_content "ET\n"
-    end
   end
 end