Refactored TextHelper#truncate, highlight, excerpt, word_wrap and auto_link to accept options hash [#705 state:resolved]

Signed-off-by: Joshua Peek <josh@joshpeek.com>

3 files changed, 191 insertions, 68 deletions

diff --git a/actionpack/lib/action_view/helpers/active_record_helper.rb b/actionpack/lib/action_view/helpers/active_record_helper.rb
index ff70ce9aae..fce03ff605 100644
--- a/actionpack/lib/action_view/helpers/active_record_helper.rb
+++ b/actionpack/lib/action_view/helpers/active_record_helper.rb
@@ -109,7 +109,7 @@ module ActionView
       def error_message_on(object, method, *args)
         options = args.extract_options!
         unless args.empty?
-          ActiveSupport::Deprecation.warn('error_message_on takes an option hash instead of separate' +
+          ActiveSupport::Deprecation.warn('error_message_on takes an option hash instead of separate ' +
             'prepend_text, append_text, and css_class arguments', caller)
 
           options[:prepend_text] = args[0] || ''
diff --git a/actionpack/lib/action_view/helpers/text_helper.rb b/actionpack/lib/action_view/helpers/text_helper.rb
index 9342b38680..3c9f7230c3 100644
--- a/actionpack/lib/action_view/helpers/text_helper.rb
+++ b/actionpack/lib/action_view/helpers/text_helper.rb
@@ -34,40 +34,69 @@ module ActionView
       end
 
       if RUBY_VERSION < '1.9'
-        # If +text+ is longer than +length+, +text+ will be truncated to the length of
-        # +length+ (defaults to 30) and the last characters will be replaced with the +truncate_string+
-        # (defaults to "...").
+        # Truncates a given +text+ after a given <tt>:length</tt> if +text+ is longer than <tt>:length</tt>
+        # (defaults to 30). The last characters will be replaced with the <tt>:omission</tt> (defaults to "...").
         #
         # ==== Examples
-        #   truncate("Once upon a time in a world far far away", 14)
-        #   # => Once upon a...
         #
         #   truncate("Once upon a time in a world far far away")
         #   # => Once upon a time in a world f...
         #
-        #   truncate("And they found that many people were sleeping better.", 25, "(clipped)")
+        #   truncate("Once upon a time in a world far far away", :length => 14)
+        #   # => Once upon a...
+        #
+        #   truncate("And they found that many people were sleeping better.", :length => 25, "(clipped)")
         #   # => And they found that many (clipped)
         #
+        #   truncate("And they found that many people were sleeping better.", :omission => "... (continued)", :length => 15)
+        #   # => And they found... (continued)
+        #
+        # You can still use <tt>truncate</tt> with the old API that accepts the
+        # +length+ as its optional second and the +ellipsis+ as its
+        # optional third parameter:
+        #   truncate("Once upon a time in a world far far away", 14)
+        #   # => Once upon a time in a world f...
+        #
         #   truncate("And they found that many people were sleeping better.", 15, "... (continued)")
         #   # => And they found... (continued)
-        def truncate(text, length = 30, truncate_string = "...")
+        def truncate(text, *args)
+          options = args.extract_options!
+          unless args.empty?
+            ActiveSupport::Deprecation.warn('truncate takes an option hash instead of separate ' +
+              'length and omission arguments', caller)
+
+            options[:length] = args[0] || 30
+            options[:omission] = args[1] || "..."
+          end
+          options.reverse_merge!(:length => 30, :omission => "...")
+
           if text
-            l = length - truncate_string.chars.length
+            l = options[:length] - options[:omission].chars.length
             chars = text.chars
-            (chars.length > length ? chars[0...l] + truncate_string : text).to_s
+            (chars.length > options[:length] ? chars[0...l] + options[:omission] : text).to_s
           end
         end
       else
-        def truncate(text, length = 30, truncate_string = "...") #:nodoc:
+        def truncate(text, *args) #:nodoc:
+          options = args.extract_options!
+          unless args.empty?
+            ActiveSupport::Deprecation.warn('truncate takes an option hash instead of separate ' +
+              'length and omission arguments', caller)
+
+            options[:length] = args[0] || 30
+            options[:omission] = args[1] || "..."
+          end
+          options.reverse_merge!(:length => 30, :omission => "...")
+
           if text
-            l = length - truncate_string.length
-            (text.length > length ? text[0...l] + truncate_string : text).to_s
+            l = options[:length].to_i - options[:omission].length
+            (text.length > options[:length].to_i ? text[0...l] + options[:omission] : text).to_s
           end
         end
       end
 
       # Highlights one or more +phrases+ everywhere in +text+ by inserting it into
-      # a +highlighter+ string. The highlighter can be specialized by passing +highlighter+
+      # a <tt>:highlighter</tt> string. The highlighter can be specialized by passing <tt>:highlighter</tt>
       # as a single-quoted string with \1 where the phrase is to be inserted (defaults to
       # '<strong class="highlight">\1</strong>')
       #
@@ -78,52 +107,75 @@ module ActionView
       #   highlight('You searched for: ruby, rails, dhh', 'actionpack')
       #   # => You searched for: ruby, rails, dhh
       #
-      #   highlight('You searched for: rails', ['for', 'rails'], '<em>\1</em>')
+      #   highlight('You searched for: rails', ['for', 'rails'], :highlighter => '<em>\1</em>')
       #   # => You searched <em>for</em>: <em>rails</em>
       #
-      #   highlight('You searched for: rails', 'rails', "<a href='search?q=\1'>\1</a>")
-      #   # => You searched for: <a href='search?q=rails>rails</a>
-      def highlight(text, phrases, highlighter = '<strong class="highlight">\1</strong>')
+      #   highlight('You searched for: rails', 'rails', :highlighter => '<a href="search?q=\1">\1</a>')
+      #   # => You searched for: <a href="search?q=rails">rails</a>
+      #
+      # You can still use <tt>highlight</tt> with the old API that accepts the
+      # +highlighter+ as its optional third parameter:
+      #   highlight('You searched for: rails', 'rails', '<a href="search?q=\1">\1</a>')     # => You searched for: <a href="search?q=rails">rails</a>
+      def highlight(text, phrases, *args)
+        options = args.extract_options!
+        unless args.empty?
+          options[:highlighter] = args[0] || '<strong class="highlight">\1</strong>'
+        end
+        options.reverse_merge!(:highlighter => '<strong class="highlight">\1</strong>')
+
         if text.blank? || phrases.blank?
           text
         else
           match = Array(phrases).map { |p| Regexp.escape(p) }.join('|')
-          text.gsub(/(#{match})/i, highlighter)
+          text.gsub(/(#{match})/i, options[:highlighter])
         end
       end
 
       if RUBY_VERSION < '1.9'
         # Extracts an excerpt from +text+ that matches the first instance of +phrase+.
-        # The +radius+ expands the excerpt on each side of the first occurrence of +phrase+ by the number of characters
-        # defined in +radius+ (which defaults to 100). If the excerpt radius overflows the beginning or end of the +text+,
-        # then the +excerpt_string+ will be prepended/appended accordingly. The resulting string will be stripped in any case.
-        # If the +phrase+ isn't found, nil is returned.
+        # The <tt>:radius</tt> option expands the excerpt on each side of the first occurrence of +phrase+ by the number of characters
+        # defined in <tt>:radius</tt> (which defaults to 100). If the excerpt radius overflows the beginning or end of the +text+,
+        # then the <tt>:omission</tt> option (which defaults to "...") will be prepended/appended accordingly. The resulting string
+        # will be stripped in any case. If the +phrase+ isn't found, nil is returned.
         #
         # ==== Examples
-        #   excerpt('This is an example', 'an', 5)
-        #   # => "...s is an exam..."
+        #   excerpt('This is an example', 'an', :radius => 5)
+        #   # => ...s is an exam...
         #
-        #   excerpt('This is an example', 'is', 5)
-        #   # => "This is a..."
+        #   excerpt('This is an example', 'is', :radius => 5)
+        #   # => This is a...
         #
         #   excerpt('This is an example', 'is')
-        #   # => "This is an example"
+        #   # => This is an example
         #
-        #   excerpt('This next thing is an example', 'ex', 2)
-        #   # => "...next..."
+        #   excerpt('This next thing is an example', 'ex', :radius => 2)
+        #   # => ...next...
         #
-        #   excerpt('This is also an example', 'an', 8, '<chop> ')
-        #   # => "<chop> is also an example"
-        def excerpt(text, phrase, radius = 100, excerpt_string = "...")
+        #   excerpt('This is also an example', 'an', :radius => 8, :omission => '<chop> ')
+        #   # => <chop> is also an example
+        #
+        # You can still use <tt>excerpt</tt> with the old API that accepts the
+        # +radius+ as its optional third and the +ellipsis+ as its
+        # optional forth parameter:
+        #   excerpt('This is an example', 'an', 5)                   # => ...s is an exam...
+        #   excerpt('This is also an example', 'an', 8, '<chop> ')   # => <chop> is also an example
+        def excerpt(text, phrase, *args)
+          options = args.extract_options!
+          unless args.empty?
+            options[:radius] = args[0] || 100
+            options[:omission] = args[1] || "..."
+          end
+          options.reverse_merge!(:radius => 100, :omission => "...")
+
           if text && phrase
             phrase = Regexp.escape(phrase)
 
             if found_pos = text.chars =~ /(#{phrase})/i
-              start_pos = [ found_pos - radius, 0 ].max
-              end_pos   = [ [ found_pos + phrase.chars.length + radius - 1, 0].max, text.chars.length ].min
+              start_pos = [ found_pos - options[:radius], 0 ].max
+              end_pos   = [ [ found_pos + phrase.chars.length + options[:radius] - 1, 0].max, text.chars.length ].min
 
-              prefix  = start_pos > 0 ? excerpt_string : ""
-              postfix = end_pos < text.chars.length - 1 ? excerpt_string : ""
+              prefix  = start_pos > 0 ? options[:omission] : ""
+              postfix = end_pos < text.chars.length - 1 ? options[:omission] : ""
 
               prefix + text.chars[start_pos..end_pos].strip + postfix
             else
@@ -132,16 +184,23 @@ module ActionView
           end
         end
       else
-        def excerpt(text, phrase, radius = 100, excerpt_string = "...") #:nodoc:
+        def excerpt(text, phrase, *args) #:nodoc:
+          options = args.extract_options!
+          unless args.empty?
+            options[:radius] = args[0] || 100
+            options[:omission] = args[1] || "..."
+          end
+          options.reverse_merge!(:radius => 100, :omission => "...")
+
           if text && phrase
             phrase = Regexp.escape(phrase)
 
             if found_pos = text =~ /(#{phrase})/i
-              start_pos = [ found_pos - radius, 0 ].max
-              end_pos   = [ [ found_pos + phrase.length + radius - 1, 0].max, text.length ].min
+              start_pos = [ found_pos - options[:radius], 0 ].max
+              end_pos   = [ [ found_pos + phrase.length + options[:radius] - 1, 0].max, text.length ].min
 
-              prefix  = start_pos > 0 ? excerpt_string : ""
-              postfix = end_pos < text.length - 1 ? excerpt_string : ""
+              prefix  = start_pos > 0 ? options[:omission] : ""
+              postfix = end_pos < text.length - 1 ? options[:omission] : ""
 
               prefix + text[start_pos..end_pos].strip + postfix
             else
@@ -176,20 +235,31 @@ module ActionView
       # (which is 80 by default).
       #
       # ==== Examples
-      #   word_wrap('Once upon a time', 4)
-      #   # => Once\nupon\na\ntime
-      #
-      #   word_wrap('Once upon a time', 8)
-      #   # => Once upon\na time
       #
       #   word_wrap('Once upon a time')
       #   # => Once upon a time
       #
-      #   word_wrap('Once upon a time', 1)
+      #   word_wrap('Once upon a time, in a kingdom called Far Far Away, a king fell ill, and finding a successor to the throne turned out to be more trouble than anyone could have imagined...')
+      #   # => Once upon a time, in a kingdom called Far Far Away, a king fell ill, and finding\n a successor to the throne turned out to be more trouble than anyone could have\n imagined...
+      #
+      #   word_wrap('Once upon a time', :line_width => 8)
+      #   # => Once upon\na time
+      #
+      #   word_wrap('Once upon a time', :line_width => 1)
       #   # => Once\nupon\na\ntime
-      def word_wrap(text, line_width = 80)
+      #
+      # You can still use <tt>word_wrap</tt> with the old API that accepts the
+      # +line_width+ as its optional second parameter:
+      #   word_wrap('Once upon a time', 8)     # => Once upon\na time
+      def word_wrap(text, *args)
+        options = args.extract_options!
+        unless args.blank?
+          options[:line_width] = args[0] || 80
+        end
+        options.reverse_merge!(:line_width => 80)
+
         text.split("\n").collect do |line|
-          line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1\n").strip : line
+          line.length > options[:line_width] ? line.gsub(/(.{1,#{options[:line_width]}})(\s+|$)/, "\\1\n").strip : line
         end * "\n"
       end
 
@@ -336,12 +406,32 @@ module ActionView
       #   # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.m...</a>.
       #         Please e-mail me at <a href=\"mailto:me@email.com\">me@email.com</a>."
       #
-      def auto_link(text, link = :all, href_options = {}, &block)
+      #
+      # You can still use <tt>auto_link</tt> with the old API that accepts the
+      # +link+ as its optional second parameter and the +html_options+ hash
+      # as its optional third parameter:
+      #   post_body = "Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com."
+      #   auto_link(post_body, :urls)     # => Once upon\na time
+      #   # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\">http://www.myblog.com</a>.
+      #         Please e-mail me at me@email.com."
+      #
+      #   auto_link(post_body, :all, :target => "_blank")     # => Once upon\na time
+      #   # => "Welcome to my new blog at <a href=\"http://www.myblog.com/\" target=\"_blank\">http://www.myblog.com</a>.
+      #         Please e-mail me at <a href=\"mailto:me@email.com\">me@email.com</a>."
+      def auto_link(text, *args, &block)#link = :all, href_options = {}, &block)
         return '' if text.blank?
-        case link
-          when :all             then auto_link_email_addresses(auto_link_urls(text, href_options, &block), &block)
-          when :email_addresses then auto_link_email_addresses(text, &block)
-          when :urls            then auto_link_urls(text, href_options, &block)
+
+        options = args.size == 2 ? {} : args.extract_options! # this is necessary because the old auto_link API has a Hash as its last parameter
+        unless args.empty?
+          options[:link] = args[0] || :all
+          options[:html] = args[1] || {}
+        end
+        options.reverse_merge!(:link => :all, :html => {})
+
+        case options[:link].to_sym
+          when :all                         then auto_link_email_addresses(auto_link_urls(text, options[:html], &block), &block)
+          when :email_addresses             then auto_link_email_addresses(text, &block)
+          when :urls                        then auto_link_urls(text, options[:html], &block)
         end
       end
 
@@ -468,7 +558,7 @@ module ActionView
                           [-\w]+                   # subdomain or domain
                           (?:\.[-\w]+)*            # remaining subdomains or domain
                           (?::\d+)?                # port
-                          (?:/(?:(?:[~\w\+@%=\(\)-]|(?:[,.;:'][^\s$])))*)* # path
+                          (?:/(?:(?:[~\w\+@%=\(\)-]|(?:[,.;:'][^\s$]))+)?)* # path
                           (?:\?[\w\+@%&=.;-]+)?     # query string
                           (?:\#[\w\-]*)?           # trailing anchor
                         )
@@ -477,8 +567,8 @@ module ActionView
 
         # Turns all urls into clickable links.  If a block is given, each url
         # is yielded and the result is used as the link text.
-        def auto_link_urls(text, href_options = {})
-          extra_options = tag_options(href_options.stringify_keys) || ""
+        def auto_link_urls(text, html_options = {})
+          extra_options = tag_options(html_options.stringify_keys) || ""
           text.gsub(AUTO_LINK_RE) do
             all, a, b, c, d = $&, $1, $2, $3, $4
             if a =~ /<a\s/i # don't replace URL's that are already linked
@@ -508,4 +598,4 @@ module ActionView
         end
     end
   end
-end
+end
\ No newline at end of file
diff --git a/actionpack/test/template/text_helper_test.rb b/actionpack/test/template/text_helper_test.rb
index 4999525939..a31d532567 100644
--- a/actionpack/test/template/text_helper_test.rb
+++ b/actionpack/test/template/text_helper_test.rb
@@ -35,8 +35,8 @@ class TextHelperTest < ActionView::TestCase
   end
 
   def test_truncate
-    assert_equal "Hello World!", truncate("Hello World!", 12)
-    assert_equal "Hello Wor...", truncate("Hello World!!", 12)
+    assert_equal "Hello World!", truncate("Hello World!", :length => 12)
+    assert_equal "Hello Wor...", truncate("Hello World!!", :length => 12)
   end
 
   def test_truncate_should_use_default_length_of_30
@@ -44,23 +44,29 @@ class TextHelperTest < ActionView::TestCase
     assert_equal str[0...27] + "...", truncate(str)
   end
 
+  def test_truncate_with_options_hash
+    assert_equal "This is a string that wil[...]", truncate("This is a string that will go longer then the default truncate length of 30", :omission => "[...]")
+    assert_equal "Hello W...", truncate("Hello World!", :length => 10)
+    assert_equal "Hello[...]", truncate("Hello World!", :omission => "[...]", :length => 10)
+  end
+
   if RUBY_VERSION < '1.9.0'
     def test_truncate_multibyte
       with_kcode 'none' do
-        assert_equal "\354\225\210\353\205\225\355...", truncate("\354\225\210\353\205\225\355\225\230\354\204\270\354\232\224", 10)
+        assert_equal "\354\225\210\353\205\225\355...", truncate("\354\225\210\353\205\225\355\225\230\354\204\270\354\232\224", :length => 10)
       end
       with_kcode 'u' do
         assert_equal "\354\225\204\353\246\254\353\236\221 \354\225\204\353\246\254 ...",
-          truncate("\354\225\204\353\246\254\353\236\221 \354\225\204\353\246\254 \354\225\204\353\235\274\353\246\254\354\230\244", 10)
+          truncate("\354\225\204\353\246\254\353\236\221 \354\225\204\353\246\254 \354\225\204\353\235\274\353\246\254\354\230\244", :length => 10)
       end
     end
   else
     def test_truncate_multibyte
       assert_equal "\354\225\210\353\205\225\355...",
-        truncate("\354\225\210\353\205\225\355\225\230\354\204\270\354\232\224", 10)
+        truncate("\354\225\210\353\205\225\355\225\230\354\204\270\354\232\224", :length => 10)
 
       assert_equal "\354\225\204\353\246\254\353\236\221 \354\225\204\353\246\254 ...".force_encoding('UTF-8'),
-        truncate("\354\225\204\353\246\254\353\236\221 \354\225\204\353\246\254 \354\225\204\353\235\274\353\246\254\354\230\244".force_encoding('UTF-8'), 10)
+        truncate("\354\225\204\353\246\254\353\236\221 \354\225\204\353\246\254 \354\225\204\353\235\274\353\246\254\354\230\244".force_encoding('UTF-8'), :length => 10)
     end
   end
 
@@ -88,7 +94,7 @@ class TextHelperTest < ActionView::TestCase
     assert_equal '   ', highlight('   ', 'blank text is returned verbatim')
   end
 
-  def test_highlighter_with_regexp
+  def test_highlight_with_regexp
     assert_equal(
       "This is a <strong class=\"highlight\">beautiful!</strong> morning",
       highlight("This is a beautiful! morning", "beautiful!")
@@ -105,10 +111,17 @@ class TextHelperTest < ActionView::TestCase
     )
   end
 
-  def test_highlighting_multiple_phrases_in_one_pass
+  def test_highlight_with_multiple_phrases_in_one_pass
     assert_equal %(<em>wow</em> <em>em</em>), highlight('wow em', %w(wow em), '<em>\1</em>')
   end
 
+  def test_highlight_with_options_hash
+    assert_equal(
+      "This is a <b>beautiful</b> morning, but also a <b>beautiful</b> day",
+      highlight("This is a beautiful morning, but also a beautiful day", "beautiful", :highlighter => '<b>\1</b>')
+    )
+  end
+
   def test_excerpt
     assert_equal("...is a beautiful morn...", excerpt("This is a beautiful morning", "beautiful", 5))
     assert_equal("This is a...", excerpt("This is a beautiful morning", "this", 5))
@@ -138,6 +151,16 @@ class TextHelperTest < ActionView::TestCase
     assert_equal('...is a beautiful? mor...', excerpt('This is a beautiful? morning', 'beautiful', 5))
   end
 
+  def test_excerpt_with_options_hash
+    assert_equal("...is a beautiful morn...", excerpt("This is a beautiful morning", "beautiful", :radius => 5))
+    assert_equal("[...]is a beautiful morn[...]", excerpt("This is a beautiful morning", "beautiful", :omission => "[...]",:radius => 5))
+    assert_equal(
+      "This is the ultimate supercalifragilisticexpialidoceous very looooooooooooooooooong looooooooooooong beautiful morning with amazing sunshine and awesome tempera[...]",
+      excerpt("This is the ultimate supercalifragilisticexpialidoceous very looooooooooooooooooong looooooooooooong beautiful morning with amazing sunshine and awesome temperatures. So what are you gonna do about it?", "very",
+      :omission => "[...]")
+    )
+  end
+
   if RUBY_VERSION < '1.9'
     def test_excerpt_with_utf8
       with_kcode('u') do
@@ -162,6 +185,10 @@ class TextHelperTest < ActionView::TestCase
     assert_equal("my very very\nvery long\nstring\n\nwith another\nline", word_wrap("my very very very long string\n\nwith another line", 15))
   end
 
+  def test_word_wrap_with_options_hash
+    assert_equal("my very very\nvery long\nstring", word_wrap("my very very very long string", :line_width => 15))
+  end
+
   def test_pluralization
     assert_equal("1 count", pluralize(1, "count"))
     assert_equal("2 counts", pluralize(2, "count"))
@@ -285,7 +312,13 @@ class TextHelperTest < ActionView::TestCase
     url = "http://api.rubyonrails.com/Foo.html"
     email = "fantabulous@shiznadel.ic"
 
-    assert_equal %(<p><a href="#{url}">#{url[0...7]}...</a><br /><a href="mailto:#{email}">#{email[0...7]}...</a><br /></p>), auto_link("<p>#{url}<br />#{email}<br /></p>") { |url| truncate(url, 10) }
+    assert_equal %(<p><a href="#{url}">#{url[0...7]}...</a><br /><a href="mailto:#{email}">#{email[0...7]}...</a><br /></p>), auto_link("<p>#{url}<br />#{email}<br /></p>") { |url| truncate(url, :length => 10) }
+  end
+
+  def test_auto_link_with_options_hash
+    assert_equal 'Welcome to my new blog at <a href="http://www.myblog.com/" class="menu" target="_blank">http://www.myblog.com/</a>. Please e-mail me at <a href="mailto:me@email.com">me@email.com</a>.',
+      auto_link("Welcome to my new blog at http://www.myblog.com/. Please e-mail me at me@email.com.",
+                :link => :all, :html => { :class => "menu", :target => "_blank" })
   end
 
   def test_cycle_class