prawn 1.0.0.rc2 → 1.0.0

data/lib/prawn/text/formatted/box.rb

@@ -10,7 +10,8 @@
 module Prawn
   module Text
     module Formatted
-
+      # @group Stable API
+      
       # Draws the requested formatted text into a box. When the text overflows
       # the rectangle shrink to fit or truncate the text. Text boxes are
       # independent of the document y position.
@@ -45,10 +46,16 @@ module Prawn
       #     the appropriate tags if you which to draw attention to the link
       # <tt>:anchor</tt>::
       #     a destination that has already been or will be registered using
-      #     Prawn::Core::Destinations#add_dest. A clickable link will be
+      #     PDF::Core::Destinations#add_dest. A clickable link will be
       #     created to that destination. Note that you must explicitly underline
       #     and color using the appropriate tags if you which to draw attention
       #     to the link
+      # <tt>:local</tt>::
+      #     a file or application to be opened locally. A clickable link will be
+      #     created to the provided local file or application. If the file is
+      #     another PDF, it will be opened in a new window. Note that you must
+      #     explicitly underline and color using the appropriate tags if you which
+      #     to draw attention to the link
       # <tt>:draw_text_callback</tt>:
       #     if provided, this Proc will be called instead of #draw_text! once
       #     per fragment for every low-level addition of text to the page.
@@ -92,21 +99,9 @@ module Prawn
       # vertical space was consumed by the printed text
       #
       class Box
-        include Prawn::Core::Text::Formatted::Wrap
+        include Prawn::Text::Formatted::Wrap
 
-        def valid_options
-          Prawn::Core::Text::VALID_OPTIONS + [:at, :height, :width,
-                                              :align, :valign,
-                                              :rotate, :rotate_around,
-                                              :overflow, :min_font_size,
-                                              :leading, :character_spacing,
-                                              :mode, :single_line,
-                                              :skip_encoding,
-                                              :document,
-                                              :direction,
-                                              :fallback_fonts,
-                                              :draw_text_callback]
-        end
+        # @group Experimental API
 
         # The text that was successfully printed (or, if <tt>dry_run</tt> was
         # used, the text that would have been successfully printed)
@@ -139,42 +134,6 @@ module Prawn
           line_height - (ascender + descender)
         end
 
-        #
-        # Example (see Prawn::Text::Core::Formatted::Wrap for what is required
-        # of the wrap method if you want to override the default wrapping
-        # algorithm):
-        # 
-        #
-        #   module MyWrap
-        #
-        #     def wrap(array)
-        #       initialize_wrap([{ :text => 'all your base are belong to us' }])
-        #       @line_wrap.wrap_line(:document => @document,
-        #                            :kerning => @kerning,
-        #                            :width => 10000,
-        #                            :arranger => @arranger)
-        #       fragment = @arranger.retrieve_fragment
-        #       format_and_draw_fragment(fragment, 0, @line_wrap.width, 0)
-        #       []
-        #     end
-        #
-        #   end
-        #
-        #   Prawn::Text::Formatted::Box.extensions << MyWrap
-        #
-        #   box = Prawn::Text::Formatted::Box.new('hello world')
-        #   box.render('why can't I print anything other than' +
-        #              '"all your base are belong to us"?')
-        #
-        #
-        def self.extensions
-          @extensions ||= []
-        end
-
-        def self.inherited(base) #:nodoc:
-          extensions.each { |e| base.extensions << e }
-        end
-
         # See Prawn::Text#text_box for valid options
         #
         def initialize(formatted_text, options={})
@@ -211,6 +170,11 @@ module Prawn
           @skip_encoding     = options[:skip_encoding] || @document.skip_encoding
           @draw_text_callback = options[:draw_text_callback]
 
+          # if the text rendering mode is :unknown, force it back to :fill
+          if @mode == :unknown
+            @mode = :fill
+          end
+
           if @overflow == :expand
             # if set to expand, then we simply set the bottom
             # as the bottom of the document bounds, since that
@@ -278,7 +242,7 @@ module Prawn
         end
 
         # The height actually used during the previous <tt>render</tt>
-        # 
+        #
         def height
           return 0 if @baseline_y.nil? || @descender.nil?
           (@baseline_y - @descender).abs
@@ -328,6 +292,58 @@ module Prawn
           end
         end
 
+        # @group Extension API
+        
+        # Example (see Prawn::Text::Core::Formatted::Wrap for what is required
+        # of the wrap method if you want to override the default wrapping
+        # algorithm):
+        #
+        #
+        #   module MyWrap
+        #
+        #     def wrap(array)
+        #       initialize_wrap([{ :text => 'all your base are belong to us' }])
+        #       @line_wrap.wrap_line(:document => @document,
+        #                            :kerning => @kerning,
+        #                            :width => 10000,
+        #                            :arranger => @arranger)
+        #       fragment = @arranger.retrieve_fragment
+        #       format_and_draw_fragment(fragment, 0, @line_wrap.width, 0)
+        #       []
+        #     end
+        #
+        #   end
+        #
+        #   Prawn::Text::Formatted::Box.extensions << MyWrap
+        #
+        #   box = Prawn::Text::Formatted::Box.new('hello world')
+        #   box.render('why can't I print anything other than' +
+        #              '"all your base are belong to us"?')
+        #
+        #
+        def self.extensions
+          @extensions ||= []
+        end
+
+        # @private
+        def self.inherited(base)
+          extensions.each { |e| base.extensions << e }
+        end
+
+        def valid_options
+          PDF::Core::Text::VALID_OPTIONS + [:at, :height, :width,
+                                              :align, :valign,
+                                              :rotate, :rotate_around,
+                                              :overflow, :min_font_size,
+                                              :leading, :character_spacing,
+                                              :mode, :single_line,
+                                              :skip_encoding,
+                                              :document,
+                                              :direction,
+                                              :fallback_fonts,
+                                              :draw_text_callback]
+        end
+
         private
 
         def original_text
@@ -381,7 +397,7 @@ module Prawn
           # all fonts
           fallback_fonts << fragment_font
 
-          hash[:text].unicode_characters do |char|
+          hash[:text].each_char do |char|
             @document.font(fragment_font)
             font_glyph_pairs << [find_font_for_this_glyph(char,
                                                           @document.font.family,
@@ -450,7 +466,7 @@ module Prawn
           # we need to wait until render() is called so that the fonts are set
           # up properly for wrapping. So guard with a boolean to ensure this is
           # only run once.
-          return if @vertical_alignment_processed
+          return if defined?(@vertical_alignment_processed) && @vertical_alignment_processed
           @vertical_alignment_processed = true
 
           return if @vertical_align == :top
@@ -521,6 +537,7 @@ module Prawn
           draw_fragment_overlay_styles(fragment)
           draw_fragment_overlay_link(fragment)
           draw_fragment_overlay_anchor(fragment)
+          draw_fragment_overlay_local(fragment)
           fragment.callback_objects.each do |obj|
             obj.render_in_front(fragment) if obj.respond_to?(:render_in_front)
           end
@@ -533,7 +550,7 @@ module Prawn
                                     :Border => [0, 0, 0],
                                     :A => { :Type => :Action,
                                             :S => :URI,
-                                            :URI => Prawn::Core::LiteralString.new(fragment.link) })
+                                            :URI => PDF::Core::LiteralString.new(fragment.link) })
         end
 
         def draw_fragment_overlay_anchor(fragment)
@@ -544,12 +561,23 @@ module Prawn
                                     :Dest => fragment.anchor)
         end
 
+        def draw_fragment_overlay_local(fragment)
+          return unless fragment.local
+          box = fragment.absolute_bounding_box
+          @document.link_annotation(box,
+                                    :Border => [0, 0, 0],
+                                    :A => { :Type => :Action,
+                                            :S => :Launch,
+                                            :F => PDF::Core::LiteralString.new(fragment.local),
+                                            :NewWindow => true })
+        end
+
         def draw_fragment_overlay_styles(fragment)
           underline = fragment.styles.include?(:underline)
           if underline
             @document.stroke_line(fragment.underline_points)
           end
-          
+
           strikethrough = fragment.styles.include?(:strikethrough)
           if strikethrough
             @document.stroke_line(fragment.strikethrough_points)

data/lib/prawn/text/formatted/fragment.rb

@@ -10,9 +10,11 @@ module Prawn
   module Text
     module Formatted
 
+
       # Prawn::Text::Formatted::Fragment is a state store for a formatted text
       # fragment. It does not render anything.
       #
+      # @private
       class Fragment
 
         attr_reader :format_state, :text
@@ -91,6 +93,10 @@ module Prawn
           @format_state[:anchor]
         end
 
+        def local
+          @format_state[:local]
+        end
+
         def color
           @format_state[:color]
         end
@@ -208,11 +214,7 @@ module Prawn
           end
           case direction
           when :rtl
-            if ruby_18 { true }
-              string.scan(/./mu).reverse.join
-            else
-              string.reverse
-            end
+            string.reverse
           else
             string
           end
@@ -228,11 +230,9 @@ module Prawn
 
         def process_soft_hyphens(string)
           if string.length > 0 && normalized_soft_hyphen
-            ruby_19 {
-              if string.encoding != normalized_soft_hyphen.encoding
-                string.force_encoding(normalized_soft_hyphen.encoding)
-              end
-            }
+            if string.encoding != normalized_soft_hyphen.encoding
+              string.force_encoding(normalized_soft_hyphen.encoding)
+            end
             string[0..-2].gsub(normalized_soft_hyphen, "") + string[-1..-1]
           else
             string
@@ -240,7 +240,7 @@ module Prawn
         end
 
         def strip_zero_width_spaces(string)
-          if !"".respond_to?(:encoding) || string.encoding.to_s == "UTF-8"
+          if string.encoding == ::Encoding::UTF_8
             string.gsub(Prawn::Text::ZWSP, "")
           else
             string

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

@@ -0,0 +1,266 @@
+# 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 Text
+    module Formatted #:nodoc:
+
+      # @private
+      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 PDF::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}"
+          Regexp.new(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
+          Regexp.new("\\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 Prawn::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)
+          font = @document.font
+          segment.each_char do |char|
+            break unless append_char(char,font)
+          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
+      end
+    end
+  end
+end