activesupport 3.2.22.5 → 4.0.0

data/lib/active_support/core_ext/object/try.rb

@@ -1,39 +1,58 @@
 class Object
-  # Invokes the method identified by the symbol +method+, passing it any arguments
-  # and/or the block specified, just like the regular Ruby <tt>Object#send</tt> does.
+  # Invokes the public method whose name goes as first argument just like
+  # +public_send+ does, except that if the receiver does not respond to it the
+  # call returns +nil+ rather than raising an exception.
   #
-  # *Unlike* that method however, a +NoMethodError+ exception will *not* be raised
-  # and +nil+ will be returned instead, if the receiving object is a +nil+ object or NilClass.
+  # This method is defined to be able to write
   #
-  # If try is called without a method to call, it will yield any given block with the object.
-  #
-  # Please also note that +try+ is defined on +Object+, therefore it won't work with
-  # subclasses of +BasicObject+. For example, using try with +SimpleDelegator+ will
-  # delegate +try+ to target instead of calling it on delegator itself.
+  #   @person.try(:name)
   #
-  # ==== Examples
+  # instead of
   #
-  # Without +try+
-  #   @person && @person.name
-  # or
   #   @person ? @person.name : nil
   #
-  # With +try+
-  #   @person.try(:name)
+  # +try+ returns +nil+ when called on +nil+ regardless of whether it responds
+  # to the method:
+  #
+  #   nil.try(:to_i) # => nil, rather than 0
+  #
+  # Arguments and blocks are forwarded to the method if invoked:
+  #
+  #   @posts.try(:each_slice, 2) do |a, b|
+  #     ...
+  #   end
+  #
+  # The number of arguments in the signature must match. If the object responds
+  # to the method the call is attempted and +ArgumentError+ is still raised
+  # otherwise.
+  #
+  # If +try+ is called without arguments it yields the receiver to a given
+  # block unless it is +nil+:
   #
-  # +try+ also accepts arguments and/or a block, for the method it is trying
-  #   Person.try(:find, 1)
-  #   @people.try(:collect) {|p| p.name}
+  #   @person.try do |p|
+  #     ...
+  #   end
   #
-  # Without a method argument try will yield to the block unless the receiver is nil.
-  #   @person.try { |p| "#{p.first_name} #{p.last_name}" }
-  #--
-  # +try+ behaves like +Object#send+, unless called on +NilClass+.
+  # Please also note that +try+ is defined on +Object+, therefore it won't work
+  # with instances of classes that do not have +Object+ among their ancestors,
+  # like direct subclasses of +BasicObject+. For example, using +try+ with
+  # +SimpleDelegator+ will delegate +try+ to the target instead of calling it on
+  # delegator itself.
   def try(*a, &b)
     if a.empty? && block_given?
       yield self
     else
-      __send__(*a, &b)
+      public_send(*a, &b) if respond_to?(a.first)
+    end
+  end
+
+  # Same as #try, but will raise a NoMethodError exception if the receiving is not nil and
+  # does not implemented the tried method.
+  def try!(*a, &b)
+    if a.empty? && block_given?
+      yield self
+    else
+      public_send(*a, &b)
     end
   end
 end
@@ -42,8 +61,6 @@ class NilClass
   # Calling +try+ on +nil+ always returns +nil+.
   # It becomes specially helpful when navigating through associations that may return +nil+.
   #
-  # === Examples
-  #
   #   nil.try(:name) # => nil
   #
   # Without +try+
@@ -54,4 +71,8 @@ class NilClass
   def try(*args)
     nil
   end
+
+  def try!(*args)
+    nil
+  end
 end

data/lib/active_support/core_ext/object/with_options.rb

@@ -10,16 +10,16 @@ class Object
   # Without <tt>with_options></tt>, this code contains duplication:
   #
   #   class Account < ActiveRecord::Base
-  #     has_many :customers, :dependent => :destroy
-  #     has_many :products,  :dependent => :destroy
-  #     has_many :invoices,  :dependent => :destroy
-  #     has_many :expenses,  :dependent => :destroy
+  #     has_many :customers, dependent: :destroy
+  #     has_many :products,  dependent: :destroy
+  #     has_many :invoices,  dependent: :destroy
+  #     has_many :expenses,  dependent: :destroy
   #   end
   #
   # Using <tt>with_options</tt>, we can remove the duplication:
   #
   #   class Account < ActiveRecord::Base
-  #     with_options :dependent => :destroy do |assoc|
+  #     with_options dependent: :destroy do |assoc|
   #       assoc.has_many :customers
   #       assoc.has_many :products
   #       assoc.has_many :invoices
@@ -29,14 +29,13 @@ class Object
   #
   # It can also be used with an explicit receiver:
   #
-  #   I18n.with_options :locale => user.locale, :scope => "newsletter" do |i18n|
+  #   I18n.with_options locale: user.locale, scope: 'newsletter' do |i18n|
   #     subject i18n.t :subject
-  #     body    i18n.t :body, :user_name => user.name
+  #     body    i18n.t :body, user_name: user.name
   #   end
   #
   # <tt>with_options</tt> can also be nested since the call is forwarded to its receiver.
   # Each nesting level will merge inherited defaults in addition to their own.
-  #
   def with_options(options)
     yield ActiveSupport::OptionMerger.new(self, options)
   end

data/lib/active_support/core_ext/object.rb

@@ -1,6 +1,7 @@
 require 'active_support/core_ext/object/acts_like'
 require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/object/duplicable'
+require 'active_support/core_ext/object/deep_dup'
 require 'active_support/core_ext/object/try'
 require 'active_support/core_ext/object/inclusion'
 

data/lib/active_support/core_ext/proc.rb

@@ -1,7 +1,10 @@
 require "active_support/core_ext/kernel/singleton_class"
+require "active_support/deprecation"
 
 class Proc #:nodoc:
   def bind(object)
+    ActiveSupport::Deprecation.warn 'Proc#bind is deprecated and will be removed in future versions'
+
     block, time = self, Time.now
     object.class_eval do
       method_name = "__bind_#{time.to_i}_#{time.usec}"

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

@@ -5,8 +5,6 @@ class Range
 
   # Gives a human readable format of the range.
   #
-  # ==== Example
-  #
   #   (1..100).to_formatted_s # => "1..100"
   def to_formatted_s(format = :default)
     if formatter = RANGE_FORMATS[format]

data/lib/active_support/core_ext/range/include_range.rb

@@ -1,3 +1,5 @@
+require 'active_support/core_ext/module/aliasing'
+
 class Range
   # Extends the default Range#include? to support range comparisons.
   #  (1..5).include?(1..5) # => true
@@ -5,7 +7,7 @@ class Range
   #  (1..5).include?(2..6) # => false
   #
   # The native Range#include? behavior is untouched.
-  #  ("a".."f").include?("c") # => true
+  #  ('a'..'f').include?('c') # => true
   #  (5..9).include?(11) # => false
   def include_with_range?(value)
     if value.is_a?(::Range)

data/lib/active_support/core_ext/range/overlaps.rb

@@ -3,6 +3,6 @@ class Range
   #  (1..5).overlaps?(4..6) # => true
   #  (1..5).overlaps?(7..9) # => false
   def overlaps?(other)
-    include?(other.first) || other.include?(first)
+    cover?(other.first) || other.cover?(first)
   end
 end

data/lib/active_support/core_ext/range.rb

@@ -1,5 +1,3 @@
-require 'active_support/core_ext/range/blockless_step'
 require 'active_support/core_ext/range/conversions'
 require 'active_support/core_ext/range/include_range'
 require 'active_support/core_ext/range/overlaps'
-require 'active_support/core_ext/range/cover'

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

@@ -1,99 +1,104 @@
-require "active_support/multibyte"
-
 class String
-  unless '1.9'.respond_to?(:force_encoding)
-    # Returns the character at the +position+ treating the string as an array (where 0 is the first character).
-    #
-    # Examples:
-    #   "hello".at(0)  # => "h"
-    #   "hello".at(4)  # => "o"
-    #   "hello".at(10) # => ERROR if < 1.9, nil in 1.9
-    def at(position)
-      mb_chars[position, 1].to_s
-    end
-
-    # Returns the remaining of the string from the +position+ treating the string as an array (where 0 is the first character).
-    #
-    # Examples:
-    #   "hello".from(0)  # => "hello"
-    #   "hello".from(2)  # => "llo"
-    #   "hello".from(10) # => "" if < 1.9, nil in 1.9
-    def from(position)
-      mb_chars[position..-1].to_s
-    end
-
-    # Returns the beginning of the string up to the +position+ treating the string as an array (where 0 is the first character).
-    #
-    # Examples:
-    #   "hello".to(0)  # => "h"
-    #   "hello".to(2)  # => "hel"
-    #   "hello".to(10) # => "hello"
-    def to(position)
-      mb_chars[0..position].to_s
-    end
-
-    # Returns the first character of the string or the first +limit+ characters.
-    #
-    # Examples:
-    #   "hello".first     # => "h"
-    #   "hello".first(2)  # => "he"
-    #   "hello".first(10) # => "hello"
-    def first(limit = 1)
-      if limit == 0
-        ''
-      elsif limit >= size
-        self
-      else
-        mb_chars[0...limit].to_s
-      end
-    end
-
-    # Returns the last character of the string or the last +limit+ characters.
-    #
-    # Examples:
-    #   "hello".last     # => "o"
-    #   "hello".last(2)  # => "lo"
-    #   "hello".last(10) # => "hello"
-    def last(limit = 1)
-      if limit == 0
-        ''
-      elsif limit >= size
-        self
-      else
-        mb_chars[(-limit)..-1].to_s
-      end
-    end
-  else
-    def at(position)
-      self[position]
-    end
+  # If you pass a single Fixnum, 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
+  # offset is negative, it is counted from the end of the string. Returns nil
+  # if the initial offset falls outside the string. Returns an empty string if
+  # 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)  #=> ""
+  #
+  # 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
+  def at(position)
+    self[position]
+  end
 
-    def from(position)
-      self[position..-1]
-    end
+  # Returns a substring from the given position to the end of the 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"
+  #
+  # 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"
+  def from(position)
+    self[position..-1]
+  end
 
-    def to(position)
-      self[0..position]
-    end
+  # Returns a substring from the beginning of the string to the given position.
+  # 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"
+  #
+  # 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"
+  def to(position)
+    self[0..position]
+  end
 
-    def first(limit = 1)
-      if limit == 0
-        ''
-      elsif limit >= size
-        self
-      else
-        to(limit - 1)
-      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.
+  #
+  #   str = "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
+    else
+      to(limit - 1)
     end
+  end
 
-    def last(limit = 1)
-      if limit == 0
-        ''
-      elsif limit >= size
-        self
-      else
-        from(-limit)
-      end
+  # 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.
+  #
+  #   str = "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
+    else
+      from(-limit)
     end
   end
 end

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

@@ -1,43 +1,36 @@
-# encoding: utf-8
 require 'date'
-require 'active_support/core_ext/time/publicize_conversion_methods'
 require 'active_support/core_ext/time/calculations'
 
 class String
-  # Returns the codepoint of the first character of the string, assuming a
-  # single-byte character encoding:
+  # Converts a string to a Time value.
+  # The +form+ can be either :utc or :local (default :local).
   #
-  #   "a".ord # => 97
-  #   "à".ord # => 224, in ISO-8859-1
+  # The time is parsed using Time.parse method.
+  # If +form+ is :local, then the time is in the system timezone.
+  # If the date part is missing then the current date is used and if
+  # the time part is missing then it is assumed to be 00:00:00.
   #
-  # This method is defined in Ruby 1.8 for Ruby 1.9 forward compatibility on
-  # these character encodings.
-  #
-  # <tt>ActiveSupport::Multibyte::Chars#ord</tt> is forward compatible with
-  # Ruby 1.9 on UTF8 strings:
-  #
-  #   "a".mb_chars.ord # => 97
-  #   "à".mb_chars.ord # => 224, in UTF8
-  #
-  # Note that the 224 is different in both examples. In ISO-8859-1 "à" is
-  # represented as a single byte, 224. In UTF8 it is represented with two
-  # bytes, namely 195 and 160, but its Unicode codepoint is 224. If we
-  # call +ord+ on the UTF8 string "à" the return value will be 195. That is
-  # not an error, because UTF8 is unsupported, the call itself would be
-  # bogus.
-  def ord
-    self[0]
-  end unless method_defined?(:ord)
+  #   "13-12-2012".to_time               # => 2012-12-13 00:00:00 +0100
+  #   "06:12".to_time                    # => 2012-12-13 06:12:00 +0100
+  #   "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
+  def to_time(form = :local)
+    parts = Date._parse(self, false)
+    return if parts.empty?
 
-  # +getbyte+ backport from Ruby 1.9
-  alias_method :getbyte, :[] unless method_defined?(:getbyte)
+    now = Time.now
+    time = Time.new(
+      parts.fetch(:year, now.year),
+      parts.fetch(:mon, now.month),
+      parts.fetch(:mday, now.day),
+      parts.fetch(:hour, 0),
+      parts.fetch(:min, 0),
+      parts.fetch(:sec, 0) + parts.fetch(:sec_fraction, 0),
+      parts.fetch(:offset, form == :utc ? 0 : nil)
+    )
 
-  # Form can be either :utc (default) or :local.
-  def to_time(form = :utc)
-    return nil if self.blank?
-    d = ::Date._parse(self, false).values_at(:year, :mon, :mday, :hour, :min, :sec, :sec_fraction, :offset).map { |arg| arg || 0 }
-    d[6] *= 1000000
-    ::Time.send("#{form}_time", *d[0..6]) - d[7]
+    form == :utc ? time.utc : time.getlocal
   end
 
   # Converts a string to a Date value.
@@ -47,8 +40,7 @@ class String
   #   "2012-12-13".to_date #=> Thu, 13 Dec 2012
   #   "12/13/2012".to_date #=> ArgumentError: invalid date
   def to_date
-    return nil if self.blank?
-    ::Date.new(*::Date._parse(self, false).values_at(:year, :mon, :mday))
+    ::Date.parse(self, false) unless blank?
   end
 
   # Converts a string to a DateTime value.
@@ -58,9 +50,6 @@ class String
   #   "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
-    return nil if self.blank?
-    d = ::Date._parse(self, false).values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :sec_fraction).map { |arg| arg || 0 }
-    d[5] += d.pop
-    ::DateTime.civil(*d)
+    ::DateTime.parse(self, false) unless blank?
   end
 end

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

@@ -1,11 +1,8 @@
+require 'active_support/deprecation'
+
 class String
-  if defined?(Encoding) && "".respond_to?(:encode)
-    def encoding_aware?
-      true
-    end
-  else
-    def encoding_aware?
-      false
-    end
+  def encoding_aware?
+    ActiveSupport::Deprecation.warn 'String#encoding_aware? is deprecated'
+    true
   end
-end
+end

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

@@ -1,11 +1,10 @@
-require 'active_support/core_ext/string/multibyte'
-
 class String
   # Returns the string, first removing all whitespace on both ends of
   # the string, and then changing remaining consecutive whitespace
   # groups into one space each.
   #
-  # Examples:
+  # Note that it handles both ASCII and Unicode whitespace like mongolian vowel separator (U+180E).
+  #
   #   %{ Multi-line
   #      string }.squish                   # => "Multi-line string"
   #   " foo   bar    \n   \t   boo".squish # => "foo bar boo"
@@ -15,35 +14,42 @@ class String
 
   # Performs a destructive squish. See String#squish.
   def squish!
-    strip!
-    gsub!(/\s+/, ' ')
+    gsub!(/\A[[:space:]]+/, '')
+    gsub!(/[[:space:]]+\z/, '')
+    gsub!(/[[:space:]]+/, ' ')
     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)
+  #   'Once upon a time in a world far far away'.truncate(27)
   #   # => "Once upon a time in a wo..."
   #
-  # Pass a <tt>:separator</tt> to truncate +text+ at a natural break:
+  # Pass a string or regexp <tt>:separator</tt> to truncate +text+ at a natural break:
+  #
+  #   'Once upon a time in a world far far away'.truncate(27, separator: ' ')
+  #   # => "Once upon a time in a..."
   #
-  #   "Once upon a time in a world far far away".truncate(27, :separator => ' ')
+  #   'Once upon a time in a world far far away'.truncate(27, separator: /\s/)
   #   # => "Once upon a time in a..."
   #
   # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...")
-  # for a total length not exceeding <tt>:length</tt>:
+  # for a total length not exceeding <tt>length</tt>:
   #
-  #   "And they found that many people were sleeping better.".truncate(25, :omission => "... (continued)")
+  #   'And they found that many people were sleeping better.'.truncate(25, omission: '... (continued)')
   #   # => "And they f... (continued)"
-  def truncate(length, options = {})
-    text = self.dup
-    options[:omission] ||= "..."
+  def truncate(truncate_at, options = {})
+    return dup unless length > truncate_at
 
-    length_with_room_for_omission = length - options[:omission].mb_chars.length
-    chars = text.mb_chars
-    stop = options[:separator] ?
-      (chars.rindex(options[:separator].mb_chars, length_with_room_for_omission) || length_with_room_for_omission) : length_with_room_for_omission
+    options[:omission] ||= '...'
+    length_with_room_for_omission = truncate_at - options[:omission].length
+    stop = \
+      if options[:separator]
+        rindex(options[:separator], length_with_room_for_omission) || length_with_room_for_omission
+      else
+        length_with_room_for_omission
+      end
 
-    (chars.length > length ? chars[0...stop] + options[:omission] : text).to_s
+    "#{self[0...stop]}#{options[:omission]}"
   end
 end

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

@@ -0,0 +1,43 @@
+class String
+  # Same as +indent+, except it indents the receiver in-place.
+  #
+  # Returns the indented string, or +nil+ if there was nothing to indent.
+  def indent!(amount, indent_string=nil, indent_empty_lines=false)
+    indent_string = indent_string || self[/^[ \t]/] || ' '
+    re = indent_empty_lines ? /^/ : /^(?!$)/
+    gsub!(re, indent_string * amount)
+  end
+
+  # Indents the lines in the receiver:
+  #
+  #   <<EOS.indent(2)
+  #   def some_method
+  #     some_code
+  #   end
+  #   EOS
+  #   # =>
+  #     def some_method
+  #       some_code
+  #     end
+  #
+  # The second argument, +indent_string+, specifies which indent string to
+  # use. The default is +nil+, which tells the method to make a guess by
+  # peeking at the first indented line, and fallback to a space if there is
+  # none.
+  #
+  #   "  foo".indent(2)        # => "    foo"
+  #   "foo\n\t\tbar".indent(2) # => "\t\tfoo\n\t\t\t\tbar"
+  #   "foo".indent(2, "\t")    # => "\t\tfoo"
+  #
+  # While +indent_string+ is typically one space or tab, it may be any string.
+  #
+  # The third argument, +indent_empty_lines+, is a flag that says whether
+  # empty lines should be indented. Default is false.
+  #
+  #   "foo\n\nbar".indent(2)            # => "  foo\n\n  bar"
+  #   "foo\n\nbar".indent(2, nil, true) # => "  foo\n  \n  bar"
+  #
+  def indent(amount, indent_string=nil, indent_empty_lines=false)
+    dup.tap {|_| _.indent!(amount, indent_string, indent_empty_lines)}
+  end
+end