activesupport 3.0.20 → 3.1.0

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

@@ -1,25 +1,25 @@
 class Object
   # An object is blank if it's false, empty, or a whitespace string.
-  # For example, "", "   ", +nil+, [], and {} are blank.
+  # For example, "", "   ", +nil+, [], and {} are all blank.
   #
   # This simplifies:
   #
-  #   if !address.nil? && !address.empty?
+  #   if address.nil? || address.empty?
   #
   # ...to:
   #
-  #   if !address.blank?
+  #   if address.blank?
   def blank?
     respond_to?(:empty?) ? empty? : !self
   end
 
-  # An object is present if it's not blank.
+  # An object is present if it's not <tt>blank?</tt>.
   def present?
     !blank?
   end
 
-  # Returns object if it's #present? otherwise returns nil.
-  # object.presence is equivalent to object.present? ? object : nil.
+  # Returns object if it's <tt>present?</tt> otherwise returns +nil+.
+  # <tt>object.presence</tt> is equivalent to <tt>object.present? ? object : nil</tt>.
   #
   # This is handy for any representation of objects where blank is the same
   # as not present at all.  For example, this simplifies a common check for
@@ -37,39 +37,72 @@ class Object
   end
 end
 
-class NilClass #:nodoc:
+class NilClass
+  # +nil+ is blank:
+  #
+  #   nil.blank? # => true
+  #
   def blank?
     true
   end
 end
 
-class FalseClass #:nodoc:
+class FalseClass
+  # +false+ is blank:
+  #
+  #   false.blank? # => true
+  #
   def blank?
     true
   end
 end
 
-class TrueClass #:nodoc:
+class TrueClass
+  # +true+ is not blank:
+  #
+  #   true.blank? # => false
+  #
   def blank?
     false
   end
 end
 
-class Array #:nodoc:
+class Array
+  # An array is blank if it's empty:
+  #
+  #   [].blank?      # => true
+  #   [1,2,3].blank? # => false
+  #
   alias_method :blank?, :empty?
 end
 
-class Hash #:nodoc:
+class Hash
+  # A hash is blank if it's empty:
+  #
+  #   {}.blank?                # => true
+  #   {:key => 'value'}.blank? # => false
+  #
   alias_method :blank?, :empty?
 end
 
-class String #:nodoc:
+class String
+  # A string is blank if it's empty or contains whitespaces only:
+  #
+  #   "".blank?                 # => true
+  #   "   ".blank?              # => true
+  #   " something here ".blank? # => false
+  #
   def blank?
     self !~ /\S/
   end
 end
 
 class Numeric #:nodoc:
+  # No number is blank:
+  #
+  #   1.blank? # => false
+  #   0.blank? # => false
+  #
   def blank?
     false
   end

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

@@ -1,3 +1,4 @@
+#--
 # Most objects are cloneable, but not all. For example you can't dup +nil+:
 #
 #   nil.dup # => TypeError: can't dup NilClass
@@ -14,51 +15,91 @@
 #
 # That's why we hardcode the following cases and check duplicable? instead of
 # using that rescue idiom.
+#++
 class Object
-  # Can you safely .dup this object?
-  # False for nil, false, true, symbols, numbers, class and module objects; true otherwise.
+  # Can you safely dup this object?
+  #
+  # False for +nil+, +false+, +true+, symbols, numbers, class and module objects;
+  # true otherwise.
   def duplicable?
     true
   end
 end
 
-class NilClass #:nodoc:
+class NilClass
+  # +nil+ is not duplicable:
+  #
+  #   nil.duplicable? # => false
+  #   nil.dup         # => TypeError: can't dup NilClass
+  #
   def duplicable?
     false
   end
 end
 
-class FalseClass #:nodoc:
+class FalseClass
+  # +false+ is not duplicable:
+  #
+  #   false.duplicable? # => false
+  #   false.dup         # => TypeError: can't dup FalseClass
+  #
   def duplicable?
     false
   end
 end
 
-class TrueClass #:nodoc:
+class TrueClass
+  # +true+ is not duplicable:
+  #
+  #   true.duplicable? # => false
+  #   true.dup         # => TypeError: can't dup TrueClass
+  #
   def duplicable?
     false
   end
 end
 
-class Symbol #:nodoc:
+class Symbol
+  # Symbols are not duplicable:
+  #
+  #   :my_symbol.duplicable? # => false
+  #   :my_symbol.dup         # => TypeError: can't dup Symbol
+  #
   def duplicable?
     false
   end
 end
 
-class Numeric #:nodoc:
+class Numeric
+  # Numbers are not duplicable:
+  #
+  #  3.duplicable? # => false
+  #  3.dup         # => TypeError: can't dup Fixnum
+  #
   def duplicable?
     false
   end
 end
 
-class Class #:nodoc:
+class Class
+  # Classes are not duplicable:
+  #
+  #  c = Class.new # => #<Class:0x10328fd80>
+  #  c.dup         # => #<Class:0x10328fd80>
+  #
+  # Note +dup+ returned the same class object.
   def duplicable?
     false
   end
 end
 
-class Module #:nodoc:
+class Module
+  # Modules are not duplicable:
+  #
+  #  m = Module.new # => #<Module:0x10328b6e0>
+  #  m.dup          # => #<Module:0x10328b6e0>
+  #
+  # Note +dup+ returned the same module object.
   def duplicable?
     false
   end

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

@@ -0,0 +1,15 @@
+class Object
+  # Returns true if this object is included in the argument. Argument must be
+  # any object which responds to +#include?+. Usage:
+  #
+  #   characters = ["Konata", "Kagami", "Tsukasa"]
+  #   "Konata".in?(characters) # => true
+  #
+  # This will throw an ArgumentError if the argument doesn't respond
+  # to +#include?+.
+  def in?(another_object)
+    another_object.include?(self)
+  rescue NoMethodError
+    raise ArgumentError.new("The parameter passed to #in? must respond to #include?")
+  end
+end

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

@@ -10,10 +10,7 @@ class Object
   #
   #   C.new(0, 1).instance_values # => {"x" => 0, "y" => 1}
   def instance_values #:nodoc:
-    instance_variables.inject({}) do |values, name|
-      values[name.to_s[1..-1]] = instance_variable_get(name)
-      values
-    end
+    Hash[instance_variables.map { |name| [name.to_s[1..-1], instance_variable_get(name)] }]
   end
 
   # Returns an array of instance variable names including "@". They are strings
@@ -33,35 +30,4 @@ class Object
   else
     alias_method :instance_variable_names, :instance_variables
   end
-
-  # Copies the instance variables of +object+ into +self+.
-  #
-  # Instance variable names in the +exclude+ array are ignored. If +object+
-  # responds to <tt>protected_instance_variables</tt> the ones returned are
-  # also ignored. For example, Rails controllers implement that method.
-  #
-  # In both cases strings and symbols are understood, and they have to include
-  # the at sign.
-  #
-  #   class C
-  #     def initialize(x, y, z)
-  #       @x, @y, @z = x, y, z
-  #     end
-  #
-  #     def protected_instance_variables
-  #       %w(@z)
-  #     end
-  #   end
-  #
-  #   a = C.new(0, 1, 2)
-  #   b = C.new(3, 4, 5)
-  #
-  #   a.copy_instance_variables_from(b, [:@y])
-  #   # a is now: @x = 3, @y = 1, @z = 2
-  def copy_instance_variables_from(object, exclude = []) #:nodoc:
-    exclude += object.protected_instance_variables if object.respond_to? :protected_instance_variables
-
-    vars = object.instance_variables.map(&:to_s) - exclude.map(&:to_s)
-    vars.each { |name| instance_variable_set(name, object.instance_variable_get(name)) }
-  end
 end

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

@@ -1,5 +1,3 @@
-
-
 class Object
   # Alias of <tt>to_s</tt>.
   def to_param
@@ -34,14 +32,21 @@ class Array
 end
 
 class Hash
-  # Converts a hash into a string suitable for use as a URL query string. An optional <tt>namespace</tt> can be
-  # passed to enclose the param names (see example below). The string pairs "key=value" that conform the query
-  # string are sorted lexicographically in ascending order.
+  # Returns a string representation of the receiver suitable for use as a URL
+  # query string:
+  #
+  #   {:name => 'David', :nationality => 'Danish'}.to_param
+  #   # => "name=David&nationality=Danish"
+  #
+  # An optional namespace can be passed to enclose the param names:
+  #
+  #   {:name => 'David', :nationality => 'Danish'}.to_param('user')
+  #   # => "user[name]=David&user[nationality]=Danish"
   #
-  # ==== Examples
-  #   { :name => 'David', :nationality => 'Danish' }.to_param # => "name=David&nationality=Danish"
+  # The string pairs "key=value" that conform the query string
+  # are sorted lexicographically in ascending order.
   #
-  #   { :name => 'David', :nationality => 'Danish' }.to_param('user') # => "user[name]=David&user[nationality]=Danish"
+  # This method is also aliased as +to_query+.
   def to_param(namespace = nil)
     collect do |key, value|
       value.to_query(namespace ? "#{namespace}[#{key}]" : key)

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

@@ -7,7 +7,7 @@ class Object
   # Note: This method is defined as a default implementation for all Objects for Hash#to_query to work.
   def to_query(key)
     require 'cgi' unless defined?(CGI) && defined?(CGI::escape)
-    "#{CGI.escape(key.to_s).gsub(/%(5B|5D)/n) { [$1].pack('H*') }}=#{CGI.escape(to_param.to_s)}"
+    "#{CGI.escape(key.to_s)}=#{CGI.escape(to_param.to_s)}"
   end
 end
 
@@ -15,7 +15,7 @@ class Array
   # Converts an array into a string suitable for use as a URL query string,
   # using the given +key+ as the param name.
   #
-  #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies[]=Rails&hobbies[]=coding"
+  #   ['Rails', 'coding'].to_query('hobbies') # => "hobbies%5B%5D=Rails&hobbies%5B%5D=coding"
   def to_query(key)
     prefix = "#{key}[]"
     collect { |value| value.to_query(prefix) }.join '&'

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

@@ -5,31 +5,50 @@ class Object
   # *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.
   #
+  # If try is called without a method to call, it will yield any given block with the object.
+  #
   # ==== Examples
   #
-  # Without try
+  # Without +try+
   #   @person && @person.name
   # or
   #   @person ? @person.name : nil
   #
-  # With try
+  # With +try+
   #   @person.try(:name)
   #
   # +try+ also accepts arguments and/or a block, for the method it is trying
   #   Person.try(:find, 1)
   #   @people.try(:collect) {|p| p.name}
+  #
+  # Without a method argument try will yield to the block unless the receiver is nil.
+  #   @person.try { |p| "#{p.first_name} #{p.last_name}" }
   #--
-  # This method definition below is for rdoc purposes only. The alias_method call
-  # below overrides it as an optimization since +try+ behaves like +Object#send+,
-  # unless called on +NilClass+.
-  def try(method, *args, &block)
-    send(method, *args, &block)
+  # +try+ behaves like +Object#send+, unless called on +NilClass+.
+  def try(*a, &b)
+    if a.empty? && block_given?
+      yield self
+    elsif !a.empty? && !respond_to?(a.first)
+      nil
+    else
+      __send__(*a, &b)
+    end
   end
-  remove_method :try
-  alias_method :try, :__send__
 end
 
-class NilClass #:nodoc:
+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+
+  #   @person && !@person.children.blank? && @person.children.first.name
+  #
+  # With +try+
+  #   @person.try(:children).try(:first).try(:name)
   def try(*args)
     nil
   end

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

@@ -7,19 +7,36 @@ class Object
   # provided. Each method called on the block variable must take an options
   # hash as its final argument.
   #
-  #   with_options :order => 'created_at', :class_name => 'Comment' do |post|
-  #     post.has_many :comments, :conditions => ['approved = ?', true], :dependent => :delete_all
-  #     post.has_many :unapproved_comments, :conditions => ['approved = ?', false]
-  #     post.has_many :all_comments
+  # 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
   #   end
   #
-  # Can also be used with an explicit receiver:
+  # Using <tt>with_options</tt>, we can remove the duplication:
   #
-  #   map.with_options :controller => "people" do |people|
-  #     people.connect "/people",     :action => "index"
-  #     people.connect "/people/:id", :action => "show"
+  #   class Account < ActiveRecord::Base
+  #     with_options :dependent => :destroy do |assoc|
+  #       assoc.has_many :customers
+  #       assoc.has_many :products
+  #       assoc.has_many :invoices
+  #       assoc.has_many :expenses
+  #     end
   #   end
   #
+  # It can also be used with an explicit receiver:
+  #
+  #   I18n.with_options :locale => user.locale, :scope => "newsletter" do |i18n|
+  #     subject i18n.t :subject
+  #     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

@@ -2,7 +2,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/try'
-require 'active_support/core_ext/object/returning'
+require 'active_support/core_ext/object/inclusion'
 
 require 'active_support/core_ext/object/conversions'
 require 'active_support/core_ext/object/instance_variables'

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

@@ -0,0 +1,3 @@
+class Range
+  alias_method(:cover?, :include?) unless instance_methods.include?(:cover?)
+end

data/lib/active_support/core_ext/range.rb

@@ -2,3 +2,4 @@ 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/behavior.rb

@@ -1,6 +1,5 @@
 class String
-  # Enable more predictable duck-typing on String-like classes. See
-  # Object#acts_like?.
+  # Enable more predictable duck-typing on String-like classes. See <tt>Object#acts_like?</tt>.
   def acts_like_string?
     true
   end

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

@@ -1,3 +1,4 @@
+# encoding: utf-8
 require 'date'
 require 'active_support/core_ext/time/publicize_conversion_methods'
 require 'active_support/core_ext/time/calculations'

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

@@ -1,5 +1,5 @@
 class String
-  # The inverse of String#include?. Returns true if the string does not include the other string.
+  # The inverse of <tt>String#include?</tt>. Returns true if the string does not include the other string.
   def exclude?(string)
     !include?(string)
   end

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

@@ -25,13 +25,13 @@ class String
   #   "Once upon a time in a world far far away".truncate(27)
   #   # => "Once upon a time in a wo..."
   #
-  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...")
-  # for a total length not exceeding <tt>:length</tt>:
+  # Pass a <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..."
   #
-  # Pass a <tt>:separator</tt> to truncate +text+ at a natural break:
+  # The last characters will be replaced with the <tt>:omission</tt> string (defaults to "...")
+  # for a total length not exceeding <tt>:length</tt>:
   #
   #   "And they found that many people were sleeping better.".truncate(25, :omission => "... (continued)")
   #   # => "And they f... (continued)"

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

@@ -3,7 +3,7 @@ require 'active_support/inflector/inflections'
 require 'active_support/inflector/transliterate'
 
 # String inflections define new methods on the String class to transform names for different purposes.
-# For instance, you can figure out the name of a database from the name of a class.
+# For instance, you can figure out the name of a table from the name of a class.
 #
 #   "ScaleScore".tableize # => "scale_scores"
 #

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

@@ -0,0 +1,13 @@
+require 'active_support/string_inquirer'
+
+class String
+  # Wraps the current string in the <tt>ActiveSupport::StringInquirer</tt> class,
+  # which gives you a prettier way to test for equality. Example:
+  #
+  #   env = "production".inquiry
+  #   env.production?  # => true
+  #   env.development? # => false
+  def inquiry
+    ActiveSupport::StringInquirer.new(self)
+  end
+end

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

@@ -9,7 +9,7 @@ class String
     #
     # In Ruby 1.8 and older it creates and returns an instance of the ActiveSupport::Multibyte::Chars class which
     # encapsulates the original string. A Unicode safe version of all the String methods are defined on this proxy
-    # class. If the proxy class doesn't respond to a certain method, it's forwarded to the encapsuled string.
+    # class. If the proxy class doesn't respond to a certain method, it's forwarded to the encapsulated string.
     #
     #   name = 'Claus Müller'
     #   name.reverse # => "rell??M sualC"
@@ -35,7 +35,7 @@ class String
     # object. Interoperability problems can be resolved easily with a +to_s+ call.
     #
     # For more information about the methods defined on the Chars proxy see ActiveSupport::Multibyte::Chars. For
-    # information about how to change the default Multibyte behaviour see ActiveSupport::Multibyte.
+    # information about how to change the default Multibyte behavior see ActiveSupport::Multibyte.
     def mb_chars
       if ActiveSupport::Multibyte.proxy_class.consumes?(self)
         ActiveSupport::Multibyte.proxy_class.new(self)