activesupport 4.0.13 → 4.2.11.3

data/lib/active_support/core_ext/string/access.rb

@@ -1,5 +1,5 @@
 class String
-  # If you pass a single Fixnum, returns a substring of one character at that
+  # If you pass a single integer, returns a substring of one character at that
   # position. The first character of the string is at position 0, the next at
   # position 1, and so on. If a range is supplied, a substring containing
   # characters at offsets given by the range is returned. In both cases, if an
@@ -8,22 +8,22 @@ class String
   # the beginning of the range is greater than the end of the string.
   #
   #   str = "hello"
-  #   str.at(0)      #=> "h"
-  #   str.at(1..3)   #=> "ell"
-  #   str.at(-2)     #=> "l"
-  #   str.at(-2..-1) #=> "lo"
-  #   str.at(5)      #=> nil
-  #   str.at(5..-1)  #=> ""
+  #   str.at(0)      # => "h"
+  #   str.at(1..3)   # => "ell"
+  #   str.at(-2)     # => "l"
+  #   str.at(-2..-1) # => "lo"
+  #   str.at(5)      # => nil
+  #   str.at(5..-1)  # => ""
   #
   # If a Regexp is given, the matching portion of the string is returned.
   # If a String is given, that given string is returned if it occurs in
   # the string. In both cases, nil is returned if there is no match.
   #
   #   str = "hello"
-  #   str.at(/lo/) #=> "lo"
-  #   str.at(/ol/) #=> nil
-  #   str.at("lo") #=> "lo"
-  #   str.at("ol") #=> nil
+  #   str.at(/lo/) # => "lo"
+  #   str.at(/ol/) # => nil
+  #   str.at("lo") # => "lo"
+  #   str.at("ol") # => nil
   def at(position)
     self[position]
   end
@@ -32,15 +32,15 @@ class String
   # If the position is negative, it is counted from the end of the string.
   #
   #   str = "hello"
-  #   str.from(0)  #=> "hello"
-  #   str.from(3)  #=> "lo"
-  #   str.from(-2) #=> "lo"
+  #   str.from(0)  # => "hello"
+  #   str.from(3)  # => "lo"
+  #   str.from(-2) # => "lo"
   #
   # You can mix it with +to+ method and do fun things like:
   #
   #   str = "hello"
-  #   str.from(0).to(-1) #=> "hello"
-  #   str.from(1).to(-2) #=> "ell"
+  #   str.from(0).to(-1) # => "hello"
+  #   str.from(1).to(-2) # => "ell"
   def from(position)
     self[position..-1]
   end
@@ -49,34 +49,34 @@ class String
   # If the position is negative, it is counted from the end of the string.
   #
   #   str = "hello"
-  #   str.to(0)  #=> "h"
-  #   str.to(3)  #=> "hell"
-  #   str.to(-2) #=> "hell"
+  #   str.to(0)  # => "h"
+  #   str.to(3)  # => "hell"
+  #   str.to(-2) # => "hell"
   #
   # You can mix it with +from+ method and do fun things like:
   #
   #   str = "hello"
-  #   str.from(0).to(-1) #=> "hello"
-  #   str.from(1).to(-2) #=> "ell"
+  #   str.from(0).to(-1) # => "hello"
+  #   str.from(1).to(-2) # => "ell"
   def to(position)
     self[0..position]
   end
 
   # Returns the first character. If a limit is supplied, returns a substring
   # from the beginning of the string until it reaches the limit value. If the
-  # given limit is greater than or equal to the string length, returns self.
+  # given limit is greater than or equal to the string length, returns a copy of self.
   #
   #   str = "hello"
-  #   str.first    #=> "h"
-  #   str.first(1) #=> "h"
-  #   str.first(2) #=> "he"
-  #   str.first(0) #=> ""
-  #   str.first(6) #=> "hello"
+  #   str.first    # => "h"
+  #   str.first(1) # => "h"
+  #   str.first(2) # => "he"
+  #   str.first(0) # => ""
+  #   str.first(6) # => "hello"
   def first(limit = 1)
     if limit == 0
       ''
     elsif limit >= size
-      self
+      self.dup
     else
       to(limit - 1)
     end
@@ -84,19 +84,19 @@ class String
 
   # Returns the last character of the string. If a limit is supplied, returns a substring
   # from the end of the string until it reaches the limit value (counting backwards). If
-  # the given limit is greater than or equal to the string length, returns self.
+  # the given limit is greater than or equal to the string length, returns a copy of self.
   #
   #   str = "hello"
-  #   str.last    #=> "o"
-  #   str.last(1) #=> "o"
-  #   str.last(2) #=> "lo"
-  #   str.last(0) #=> ""
-  #   str.last(6) #=> "hello"
+  #   str.last    # => "o"
+  #   str.last(1) # => "o"
+  #   str.last(2) # => "lo"
+  #   str.last(0) # => ""
+  #   str.last(6) # => "hello"
   def last(limit = 1)
     if limit == 0
       ''
     elsif limit >= size
-      self
+      self.dup
     else
       from(-limit)
     end

data/lib/active_support/core_ext/string/conversions.rb

@@ -15,6 +15,7 @@ class String
   #   "2012-12-13 06:12".to_time         # => 2012-12-13 06:12:00 +0100
   #   "2012-12-13T06:12".to_time         # => 2012-12-13 06:12:00 +0100
   #   "2012-12-13T06:12".to_time(:utc)   # => 2012-12-13 05:12:00 UTC
+  #   "12/13/2012".to_time               # => ArgumentError: argument out of range
   def to_time(form = :local)
     parts = Date._parse(self, false)
     return if parts.empty?
@@ -30,25 +31,25 @@ class String
       parts.fetch(:offset, form == :utc ? 0 : nil)
     )
 
-    form == :utc ? time.utc : time.getlocal
+    form == :utc ? time.utc : time.to_time
   end
 
   # Converts a string to a Date value.
   #
-  #   "1-1-2012".to_date   #=> Sun, 01 Jan 2012
-  #   "01/01/2012".to_date #=> Sun, 01 Jan 2012
-  #   "2012-12-13".to_date #=> Thu, 13 Dec 2012
-  #   "12/13/2012".to_date #=> ArgumentError: invalid date
+  #   "1-1-2012".to_date   # => Sun, 01 Jan 2012
+  #   "01/01/2012".to_date # => Sun, 01 Jan 2012
+  #   "2012-12-13".to_date # => Thu, 13 Dec 2012
+  #   "12/13/2012".to_date # => ArgumentError: invalid date
   def to_date
     ::Date.parse(self, false) unless blank?
   end
 
   # Converts a string to a DateTime value.
   #
-  #   "1-1-2012".to_datetime            #=> Sun, 01 Jan 2012 00:00:00 +0000
-  #   "01/01/2012 23:59:59".to_datetime #=> Sun, 01 Jan 2012 23:59:59 +0000
-  #   "2012-12-13 12:50".to_datetime    #=> Thu, 13 Dec 2012 12:50:00 +0000
-  #   "12/13/2012".to_datetime          #=> ArgumentError: invalid date
+  #   "1-1-2012".to_datetime            # => Sun, 01 Jan 2012 00:00:00 +0000
+  #   "01/01/2012 23:59:59".to_datetime # => Sun, 01 Jan 2012 23:59:59 +0000
+  #   "2012-12-13 12:50".to_datetime    # => Thu, 13 Dec 2012 12:50:00 +0000
+  #   "12/13/2012".to_datetime          # => ArgumentError: invalid date
   def to_datetime
     ::DateTime.parse(self, false) unless blank?
   end

data/lib/active_support/core_ext/string/exclude.rb

@@ -2,9 +2,9 @@ class String
   # The inverse of <tt>String#include?</tt>. Returns true if the string
   # does not include the other string.
   #
-  #   "hello".exclude? "lo" #=> false
-  #   "hello".exclude? "ol" #=> true
-  #   "hello".exclude? ?h   #=> false
+  #   "hello".exclude? "lo" # => false
+  #   "hello".exclude? "ol" # => true
+  #   "hello".exclude? ?h   # => false
   def exclude?(string)
     !include?(string)
   end

data/lib/active_support/core_ext/string/filters.rb

@@ -13,6 +13,9 @@ class String
   end
 
   # Performs a destructive squish. See String#squish.
+  #   str = " foo   bar    \n   \t   boo"
+  #   str.squish!                         # => "foo bar boo"
+  #   str                                 # => "foo bar boo"
   def squish!
     gsub!(/\A[[:space:]]+/, '')
     gsub!(/[[:space:]]+\z/, '')
@@ -20,6 +23,27 @@ class String
     self
   end
 
+  # Returns a new string with all occurrences of the patterns removed.
+  #   str = "foo bar test"
+  #   str.remove(" test")                 # => "foo bar"
+  #   str.remove(" test", /bar/)          # => "foo "
+  #   str                                 # => "foo bar test"
+  def remove(*patterns)
+    dup.remove!(*patterns)
+  end
+
+  # Alters the string by removing all occurrences of the patterns.
+  #   str = "foo bar test"
+  #   str.remove!(" test", /bar/)         # => "foo "
+  #   str                                 # => "foo "
+  def remove!(*patterns)
+    patterns.each do |pattern|
+      gsub! pattern, ""
+    end
+
+    self
+  end
+
   # Truncates a given +text+ after a given <tt>length</tt> if +text+ is longer than <tt>length</tt>:
   #
   #   'Once upon a time in a world far far away'.truncate(27)
@@ -41,8 +65,8 @@ class String
   def truncate(truncate_at, options = {})
     return dup unless length > truncate_at
 
-    options[:omission] ||= '...'
-    length_with_room_for_omission = truncate_at - options[:omission].length
+    omission = options[:omission] || '...'
+    length_with_room_for_omission = truncate_at - omission.length
     stop = \
       if options[:separator]
         rindex(options[:separator], length_with_room_for_omission) || length_with_room_for_omission
@@ -50,6 +74,30 @@ class String
         length_with_room_for_omission
       end
 
-    "#{self[0...stop]}#{options[:omission]}"
+    "#{self[0, stop]}#{omission}"
+  end
+
+  # Truncates a given +text+ after a given number of words (<tt>words_count</tt>):
+  #
+  #   'Once upon a time in a world far far away'.truncate_words(4)
+  #   # => "Once upon a time..."
+  #
+  # Pass a string or regexp <tt>:separator</tt> to specify a different separator of words:
+  #
+  #   'Once<br>upon<br>a<br>time<br>in<br>a<br>world'.truncate_words(5, separator: '<br>')
+  #   # => "Once<br>upon<br>a<br>time<br>in..."
+  #
+  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "..."):
+  #
+  #   'And they found that many people were sleeping better.'.truncate_words(5, omission: '... (continued)')
+  #   # => "And they found that many... (continued)"
+  def truncate_words(words_count, options = {})
+    sep = options[:separator] || /\s+/
+    sep = Regexp.escape(sep.to_s) unless Regexp === sep
+    if self =~ /\A((?>.+?#{sep}){#{words_count - 1}}.+?)#{sep}.*/m
+      $1 + (options[:omission] || '...')
+    else
+      dup
+    end
   end
 end

data/lib/active_support/core_ext/string/inflections.rb

@@ -31,7 +31,7 @@ class String
   def pluralize(count = nil, locale = :en)
     locale = count if count.is_a?(Symbol)
     if count == 1
-      self
+      self.dup
     else
       ActiveSupport::Inflector.pluralize(self, locale)
     end
@@ -130,6 +130,8 @@ class String
   #
   #   'ActiveRecord::CoreExtensions::String::Inflections'.demodulize # => "Inflections"
   #   'Inflections'.demodulize                                       # => "Inflections"
+  #   '::Inflections'.demodulize                                     # => "Inflections"
+  #   ''.demodulize                                                  # => ''
   #
   # See also +deconstantize+.
   def demodulize
@@ -182,21 +184,24 @@ class String
   #
   #   'egg_and_hams'.classify # => "EggAndHam"
   #   'posts'.classify        # => "Post"
-  #
-  # Singular names are not handled correctly.
-  #
-  #   'business'.classify # => "Busines"
   def classify
     ActiveSupport::Inflector.classify(self)
   end
 
-  # Capitalizes the first word, turns underscores into spaces, and strips '_id'.
+  # Capitalizes the first word, turns underscores into spaces, and strips a
+  # trailing '_id' if present.
   # Like +titleize+, this is meant for creating pretty output.
   #
-  #   'employee_salary'.humanize # => "Employee salary"
-  #   'author_id'.humanize       # => "Author"
-  def humanize
-    ActiveSupport::Inflector.humanize(self)
+  # The capitalization of the first word can be turned off by setting the
+  # optional parameter +capitalize+ to false.
+  # By default, this parameter is true.
+  #
+  #   'employee_salary'.humanize              # => "Employee salary"
+  #   'author_id'.humanize                    # => "Author"
+  #   'author_id'.humanize(capitalize: false) # => "author"
+  #   '_id'.humanize                          # => "Id"
+  def humanize(options = {})
+    ActiveSupport::Inflector.humanize(self, options)
   end
 
   # Creates a foreign key name from a class name.

data/lib/active_support/core_ext/string/output_safety.rb

@@ -1,12 +1,14 @@
 require 'erb'
 require 'active_support/core_ext/kernel/singleton_class'
+require 'active_support/deprecation'
 
 class ERB
   module Util
     HTML_ESCAPE = { '&' => '&amp;',  '>' => '&gt;',   '<' => '&lt;', '"' => '&quot;', "'" => '&#39;' }
-    JSON_ESCAPE = { '&' => '\u0026', '>' => '\u003E', '<' => '\u003C' }
-    HTML_ESCAPE_ONCE_REGEXP = /["><']|&(?!([a-zA-Z]+|(#\d+));)/
-    JSON_ESCAPE_REGEXP = /[&"><]/
+    JSON_ESCAPE = { '&' => '\u0026', '>' => '\u003e', '<' => '\u003c', "\u2028" => '\u2028', "\u2029" => '\u2029' }
+    HTML_ESCAPE_REGEXP = /[&"'><]/
+    HTML_ESCAPE_ONCE_REGEXP = /["><']|&(?!([a-zA-Z]+|(#\d+)|(#[xX][\dA-Fa-f]+));)/
+    JSON_ESCAPE_REGEXP = /[\u2028\u2029&><]/u
 
     # A utility method for escaping HTML tag characters.
     # This method is also aliased as <tt>h</tt>.
@@ -17,12 +19,7 @@ class ERB
     #   puts html_escape('is a > 0 & a < 10?')
     #   # => is a &gt; 0 &amp; a &lt; 10?
     def html_escape(s)
-      s = s.to_s
-      if s.html_safe?
-        s
-      else
-        s.gsub(/[&"'><]/, HTML_ESCAPE).html_safe
-      end
+      unwrapped_html_escape(s).html_safe
     end
 
     # Aliasing twice issues a warning "discarding old...". Remove first to avoid it.
@@ -34,6 +31,18 @@ class ERB
     singleton_class.send(:remove_method, :html_escape)
     module_function :html_escape
 
+    # HTML escapes strings but doesn't wrap them with an ActiveSupport::SafeBuffer.
+    # This method is not for public consumption! Seriously!
+    def unwrapped_html_escape(s) # :nodoc:
+      s = s.to_s
+      if s.html_safe?
+        s
+      else
+        s.gsub(HTML_ESCAPE_REGEXP, HTML_ESCAPE)
+      end
+    end
+    module_function :unwrapped_html_escape
+
     # A utility method for escaping HTML without affecting existing escaped entities.
     #
     #   html_escape_once('1 < 2 &amp; 3')
@@ -48,17 +57,56 @@ class ERB
 
     module_function :html_escape_once
 
-    # A utility method for escaping HTML entities in JSON strings
-    # using \uXXXX JavaScript escape sequences for string literals:
+    # A utility method for escaping HTML entities in JSON strings. Specifically, the
+    # &, > and < characters are replaced with their equivalent unicode escaped form -
+    # \u0026, \u003e, and \u003c. The Unicode sequences \u2028 and \u2029 are also
+    # escaped as they are treated as newline characters in some JavaScript engines.
+    # These sequences have identical meaning as the original characters inside the
+    # context of a JSON string, so assuming the input is a valid and well-formed
+    # JSON value, the output will have equivalent meaning when parsed:
+    #
+    #   json = JSON.generate({ name: "</script><script>alert('PWNED!!!')</script>"})
+    #   # => "{\"name\":\"</script><script>alert('PWNED!!!')</script>\"}"
+    #
+    #   json_escape(json)
+    #   # => "{\"name\":\"\\u003C/script\\u003E\\u003Cscript\\u003Ealert('PWNED!!!')\\u003C/script\\u003E\"}"
+    #
+    #   JSON.parse(json) == JSON.parse(json_escape(json))
+    #   # => true
+    #
+    # The intended use case for this method is to escape JSON strings before including
+    # them inside a script tag to avoid XSS vulnerability:
     #
-    #   json_escape('is a > 0 & a < 10?')
-    #   # => is a \u003E 0 \u0026 a \u003C 10?
+    #   <script>
+    #     var currentUser = <%= raw json_escape(current_user.to_json) %>;
+    #   </script>
     #
-    # Note that after this operation is performed the output is not
-    # valid JSON. In particular double quotes are removed:
+    # It is necessary to +raw+ the result of +json_escape+, so that quotation marks
+    # don't get converted to <tt>&quot;</tt> entities. +json_escape+ doesn't
+    # automatically flag the result as HTML safe, since the raw value is unsafe to
+    # use inside HTML attributes.
     #
-    #   json_escape('{"name":"john","created_at":"2010-04-28T01:39:31Z","id":1}')
-    #   # => {name:john,created_at:2010-04-28T01:39:31Z,id:1}
+    # If you need to output JSON elsewhere in your HTML, you can just do something
+    # like this, as any unsafe characters (including quotation marks) will be
+    # automatically escaped for you:
+    #
+    #   <div data-user-info="<%= current_user.to_json %>">...</div>
+    #
+    # WARNING: this helper only works with valid JSON. Using this on non-JSON values
+    # will open up serious XSS vulnerabilities. For example, if you replace the
+    # +current_user.to_json+ in the example above with user input instead, the browser
+    # will happily eval() that string as JavaScript.
+    #
+    # The escaping performed in this method is identical to those performed in the
+    # Active Support JSON encoder when +ActiveSupport.escape_html_entities_in_json+ is
+    # set to true. Because this transformation is idempotent, this helper can be
+    # applied even if +ActiveSupport.escape_html_entities_in_json+ is already true.
+    #
+    # Therefore, when you are unsure if +ActiveSupport.escape_html_entities_in_json+
+    # is enabled, or if you are unsure where your JSON string originated from, it
+    # is recommended that you always apply this helper (other libraries, such as the
+    # JSON gem, do not provide this kind of protection by default; also some gems
+    # might override +to_json+ to bypass Active Support's encoder).
     def json_escape(s)
       result = s.to_s.gsub(JSON_ESCAPE_REGEXP, JSON_ESCAPE)
       s.html_safe? ? result.html_safe : result
@@ -84,7 +132,7 @@ module ActiveSupport #:nodoc:
   class SafeBuffer < String
     UNSAFE_STRING_METHODS = %w(
       capitalize chomp chop delete downcase gsub lstrip next reverse rstrip
-      slice squeeze strip sub succ swapcase tr tr_s upcase prepend
+      slice squeeze strip sub succ swapcase tr tr_s upcase
     )
 
     alias_method :original_concat, :concat
@@ -104,7 +152,7 @@ module ActiveSupport #:nodoc:
           new_safe_buffer = super
 
           if new_safe_buffer
-            new_safe_buffer.instance_eval { @html_safe = true }
+            new_safe_buffer.instance_variable_set :@html_safe, true
           end
 
           new_safe_buffer
@@ -134,28 +182,32 @@ module ActiveSupport #:nodoc:
     end
 
     def concat(value)
-      if !html_safe? || value.html_safe?
-        super(value)
-      else
-        super(ERB::Util.h(value))
-      end
+      super(html_escape_interpolated_argument(value))
     end
     alias << concat
 
+    def prepend(value)
+      super(html_escape_interpolated_argument(value))
+    end
+
+    def prepend!(value)
+      ActiveSupport::Deprecation.deprecation_warning "ActiveSupport::SafeBuffer#prepend!", :prepend
+      prepend value
+    end
+
     def +(other)
       dup.concat(other)
     end
 
     def %(args)
-      args = Array(args).map do |arg|
-        if !html_safe? || arg.html_safe?
-          arg
-        else
-          ERB::Util.h(arg)
-        end
+      case args
+      when Hash
+        escaped_args = Hash[args.map { |k,arg| [k, html_escape_interpolated_argument(arg)] }]
+      else
+        escaped_args = Array(args).map { |arg| html_escape_interpolated_argument(arg) }
       end
 
-      self.class.new(super(args))
+      self.class.new(super(escaped_args))
     end
 
     def html_safe?
@@ -171,11 +223,11 @@ module ActiveSupport #:nodoc:
     end
 
     def encode_with(coder)
-      coder.represent_scalar nil, to_str
+      coder.represent_object nil, to_str
     end
 
     UNSAFE_STRING_METHODS.each do |unsafe_method|
-      if 'String'.respond_to?(unsafe_method)
+      if unsafe_method.respond_to?(unsafe_method)
         class_eval <<-EOT, __FILE__, __LINE__ + 1
           def #{unsafe_method}(*args, &block)       # def capitalize(*args, &block)
             to_str.#{unsafe_method}(*args, &block)  #   to_str.capitalize(*args, &block)
@@ -188,10 +240,22 @@ module ActiveSupport #:nodoc:
         EOT
       end
     end
+
+    private
+
+    def html_escape_interpolated_argument(arg)
+      (!html_safe? || arg.html_safe?) ? arg :
+        arg.to_s.gsub(ERB::Util::HTML_ESCAPE_REGEXP, ERB::Util::HTML_ESCAPE)
+    end
   end
 end
 
 class String
+  # Marks a string as trusted safe. It will be inserted into HTML with no
+  # additional escaping performed. It is your responsibilty to ensure that the
+  # string contains no malicious content. This method is equivalent to the
+  # `raw` helper in views. It is recommended that you use `sanitize` instead of
+  # this method. It should never be called on user input.
   def html_safe
     ActiveSupport::SafeBuffer.new(self)
   end

data/lib/active_support/core_ext/string/zones.rb

@@ -1,3 +1,4 @@
+require 'active_support/core_ext/string/conversions'
 require 'active_support/core_ext/time/zones'
 
 class String

data/lib/active_support/core_ext/thread.rb

@@ -33,14 +33,14 @@ class Thread
     _locals[key.to_sym] = value
   end
 
-  # Returns an an array of the names of the thread-local variables (as Symbols).
+  # Returns an array of the names of the thread-local variables (as Symbols).
   #
   #    thr = Thread.new do
   #      Thread.current.thread_variable_set(:cat, 'meow')
   #      Thread.current.thread_variable_set("dog", 'woof')
   #    end
-  #    thr.join               #=> #<Thread:0x401b3f10 dead>
-  #    thr.thread_variables   #=> [:dog, :cat]
+  #    thr.join               # => #<Thread:0x401b3f10 dead>
+  #    thr.thread_variables   # => [:dog, :cat]
   #
   # Note that these are not fiber local variables. Please see Thread#thread_variable_get
   # for more details.
@@ -53,8 +53,8 @@ class Thread
   #
   #    me = Thread.current
   #    me.thread_variable_set(:oliver, "a")
-  #    me.thread_variable?(:oliver)    #=> true
-  #    me.thread_variable?(:stanley)   #=> false
+  #    me.thread_variable?(:oliver)    # => true
+  #    me.thread_variable?(:stanley)   # => false
   #
   # Note that these are not fiber local variables. Please see Thread#thread_variable_get
   # for more details.
@@ -62,6 +62,13 @@ class Thread
     _locals.has_key?(key.to_sym)
   end
 
+  # Freezes the thread so that thread local variables cannot be set via
+  # Thread#thread_variable_set, nor can fiber local variables be set.
+  #
+  #   me = Thread.current
+  #   me.freeze
+  #   me.thread_variable_set(:oliver, "a")  #=> RuntimeError: can't modify frozen thread locals
+  #   me[:oliver] = "a"                     #=> RuntimeError: can't modify frozen thread locals
   def freeze
     _locals.freeze
     super