activesupport 3.0.0.rc → 3.0.0.rc2

data/lib/active_support/cache/mem_cache_store.rb

@@ -16,8 +16,7 @@ module ActiveSupport
     # Special features:
     # - Clustering and load balancing. One can specify multiple memcached servers,
     #   and MemCacheStore will load balance between all available servers. If a
-    #   server goes down, then MemCacheStore will ignore it until it goes back
-    #   online.
+    #   server goes down, then MemCacheStore will ignore it until it comes back up.
     #
     # MemCacheStore implements the Strategy::LocalCache strategy which implements
     # an in memory cache inside of a block.
@@ -69,7 +68,7 @@ module ActiveSupport
         extend LocalCacheWithRaw
       end
 
-      # Reads multiple keys from the cache using a single call to the
+      # Reads multiple values from the cache using a single call to the
       # servers for all keys. Options can be passed in the last argument.
       def read_multi(*names)
         options = names.extract_options!
@@ -113,7 +112,7 @@ module ActiveSupport
       end
 
       # Clear the entire cache on all memcached servers. This method should
-      # be used with care when using a shared cache.
+      # be used with care when shared cache is being used.
       def clear(options = nil)
         @data.flush_all
       end

data/lib/active_support/cache/memory_store.rb

@@ -5,9 +5,9 @@ module ActiveSupport
     # A cache store implementation which stores everything into memory in the
     # same process. If you're running multiple Ruby on Rails server processes
     # (which is the case if you're using mongrel_cluster or Phusion Passenger),
-    # then this means that your Rails server process instances won't be able
+    # then this means that Rails server process instances won't be able
     # to share cache data with each other and this may not be the most
-    # appropriate cache for you.
+    # appropriate cache in that scenario.
     #
     # This cache has a bounded size specified by the :size options to the
     # initializer (default is 32Mb). When the cache exceeds the allotted size,
@@ -47,8 +47,8 @@ module ActiveSupport
         end
       end
 
-      # Prune the cache down so the entries fit within the specified memory size by removing
-      # the least recently accessed entries.
+      # To ensure entries fit within the specified memory prune the cache by removing the least
+      # recently accessed entries.
       def prune(target_size, max_time = nil)
         return if pruning?
         @pruning = true
@@ -67,7 +67,7 @@ module ActiveSupport
         end
       end
 
-      # Return true if the cache is currently be pruned to remove older entries.
+      # Returns true if the cache is currently being pruned.
       def pruning?
         @pruning
       end

data/lib/active_support/cache/strategy/local_cache.rb

@@ -8,7 +8,7 @@ module ActiveSupport
       # duration of a block. Repeated calls to the cache for the same key will hit the
       # in memory cache for faster access.
       module LocalCache
-        # Simple memory backed cache. This cache is not thread safe but is intended only
+        # Simple memory backed cache. This cache is not thread safe and is intended only
         # for serving as a temporary memory cache for a single thread.
         class LocalStore < Store
           def initialize
@@ -16,7 +16,7 @@ module ActiveSupport
             @data = {}
           end
 
-          # Since it isn't thread safe, don't allow synchronizing.
+          # Don't allow synchronizing since it isn't thread safe,
           def synchronize # :nodoc:
             yield
           end
@@ -39,7 +39,7 @@ module ActiveSupport
           end
         end
 
-        # Use a local cache to front for the cache for the duration of a block.
+        # Use a local cache for the duration of block.
         def with_local_cache
           save_val = Thread.current[thread_local_key]
           begin
@@ -50,8 +50,8 @@ module ActiveSupport
           end
         end
 
-        # Middleware class can be inserted as a Rack handler to use a local cache for the
-        # duration of a request.
+        # Middleware class can be inserted as a Rack handler to be local cache for the
+        # duration of request.
         def middleware
           @middleware ||= begin
             klass = Class.new

data/lib/active_support/callbacks.rb

@@ -93,6 +93,11 @@ module ActiveSupport
       send("_run_#{kind}_callbacks", *args, &block)
     end
 
+    def callback(kind)
+      ActiveSupport::Deprecation.warn("callback is deprecated. Please use run_callbacks")
+      send("_run_#{kind}_callbacks")
+    end
+
     class Callback
       @@_callback_sequence = 0
 
@@ -419,7 +424,10 @@ module ActiveSupport
         @_keyed_callbacks ||= {}
         @_keyed_callbacks[name] ||= begin
           str = send("_#{kind}_callbacks").compile(name, object)
-          class_eval "def #{name}() #{str} end", __FILE__, __LINE__
+          class_eval <<-RUBY_EVAL, __FILE__, __LINE__ + 1
+            def #{name}() #{str} end
+            protected :#{name}
+          RUBY_EVAL
           true
         end
       end
@@ -476,7 +484,7 @@ module ActiveSupport
           end
 
           filters.each do |filter|
-            chain.delete_if {|c| c.matches?(type, filter) } 
+            chain.delete_if {|c| c.matches?(type, filter) }
           end
 
           options[:prepend] ? chain.unshift(*mapped) : chain.push(*mapped)
@@ -568,7 +576,9 @@ module ActiveSupport
       #
       # would trigger <tt>Audit#before_save</tt> instead. That's constructed by calling
       # <tt>"#{kind}_#{name}"</tt> on the given instance. In this case "kind" is "before" and
-      # "name" is "save".
+      # "name" is "save". In this context ":kind" and ":name" have special meanings: ":kind"
+      # refers to the kind of callback (before/after/around) and ":name" refers to the
+      # method on which callbacks are being defined.
       #
       # A declaration like
       #

data/lib/active_support/concern.rb

@@ -1,3 +1,38 @@
+# A typical module looks like this
+#
+#   module M
+#     def self.included(base)
+#       base.send(:extend, ClassMethods)
+#       base.send(:include, InstanceMethods)
+#       scope :foo, :conditions => { :created_at => nil }
+#     end
+#
+#     module ClassMethods
+#       def cm; puts 'I am a class method'; end
+#     end
+#
+#     module InstanceMethods
+#       def im; puts 'I am an instance method'; end
+#     end
+#   end
+#
+# By using <tt>ActiveSupport::Concern</tt> the above module could instead be written as:
+#
+#   module M
+#     extend ActiveSupport::Concern
+#
+#     included do
+#       scope :foo, :conditions => { :created_at => nil }
+#     end
+#
+#     module ClassMethods
+#       def cm; puts 'I am a class method'; end
+#     end
+#
+#     module InstanceMethods
+#       def im; puts 'I am an instance method'; end
+#     end
+#   end
 module ActiveSupport
   module Concern
     def self.extended(base)

data/lib/active_support/configurable.rb

@@ -9,7 +9,7 @@ module ActiveSupport
 
     module ClassMethods
       def config
-        @config ||= ActiveSupport::InheritableOptions.new(superclass.respond_to?(:config) ? superclass.config : {})
+        @_config ||= ActiveSupport::InheritableOptions.new(superclass.respond_to?(:config) ? superclass.config : {})
       end
 
       def configure
@@ -30,7 +30,7 @@ module ActiveSupport
     end
 
     def config
-      @config ||= ActiveSupport::InheritableOptions.new(self.class.config)
+      @_config ||= ActiveSupport::InheritableOptions.new(self.class.config)
     end
   end
 end

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

@@ -26,7 +26,7 @@ class Array
       when 0
         ""
       when 1
-        self[0].to_s
+        self[0].to_s.dup
       when 2
         "#{self[0]}#{options[:two_words_connector]}#{self[1]}"
       else
@@ -58,12 +58,12 @@ class Array
   alias_method :to_default_s, :to_s
   alias_method :to_s, :to_formatted_s
 
-  # Returns a string that represents this array in XML by sending +to_xml+
-  # to each element. Active Record collections delegate their representation
+  # Returns a string that represents the array in XML by invoking +to_xml+
+  # on each element. Active Record collections delegate their representation
   # in XML to this method.
   #
   # All elements are expected to respond to +to_xml+, if any of them does
-  # not an exception is raised.
+  # not then an exception is raised.
   #
   # The root node reflects the class name of the first element in plural
   # if all elements belong to the same type and that's not Hash:
@@ -115,8 +115,8 @@ class Array
   #   <?xml version="1.0" encoding="UTF-8"?>
   #   <projects type="array"/>
   #
-  # By default root children have as node name the one of the root
-  # singularized. You can change it with the <tt>:children</tt> option.
+  # By default name of the node for the children of root is <tt>root.singularize</tt>.
+  # You can change it with the <tt>:children</tt> option.
   #
   # The +options+ hash is passed downwards:
   #

data/lib/active_support/core_ext/array/random_access.rb

@@ -1,10 +1,10 @@
 class Array
   # Backport of Array#sample based on Marc-Andre Lafortune's http://github.com/marcandre/backports/
-  # Returns a random element or +n+ random elements from the array. 
+  # Returns a random element or +n+ random elements from the array.
   # If the array is empty and +n+ is nil, returns <tt>nil</tt>. if +n+ is passed, returns <tt>[]</tt>.
-  # 
-  #   [1,2,3,4,5,6].sample    # => 4 
-  #   [1,2,3,4,5,6].sample(3) # => [2, 4, 5] 
+  #
+  #   [1,2,3,4,5,6].sample    # => 4
+  #   [1,2,3,4,5,6].sample(3) # => [2, 4, 5]
   #              [].sample    # => nil
   #              [].sample(3) # => []
   def sample(n=nil)

data/lib/active_support/core_ext/array/uniq_by.rb

@@ -2,7 +2,7 @@ class Array
   # Return an unique array based on the criteria given as a proc.
   #
   #   [1, 2, 3, 4].uniq_by { |i| i.odd? }
-  #   #=> [1, 2]
+  #   # => [1, 2]
   #
   def uniq_by
     hash, array = {}, []

data/lib/active_support/core_ext/array/wrap.rb

@@ -1,15 +1,41 @@
 class Array
-  # Wraps the object in an Array unless it's an Array.  Converts the
-  # object to an Array using #to_ary if it implements that.
+  # Wraps its argument in an array unless it is already an array (or array-like).
   #
-  # It differs with Array() in that it does not call +to_a+ on
-  # the argument:
+  # Specifically:
+  #
+  # * If the argument is +nil+ an empty list is returned.
+  # * Otherwise, if the argument responds to +to_ary+ it is invoked, and its result returned.
+  # * Otherwise, returns an array with the argument as its single element.
+  #
+  #   Array.wrap(nil)       # => []
+  #   Array.wrap([1, 2, 3]) # => [1, 2, 3]
+  #   Array.wrap(0)         # => [0]
+  #
+  # This method is similar in purpose to <tt>Kernel#Array</tt>, but there are some differences:
+  #
+  # * If the argument responds to +to_ary+ the method is invoked. <tt>Kernel#Array</tt>
+  # moves on to try +to_a+ if the returned value is +nil+, but <tt>Arraw.wrap</tt> returns
+  # such a +nil+ right away.
+  # * If the returned value from +to_ary+ is neither +nil+ nor an +Array+ object, <tt>Kernel#Array</tt>
+  # raises an exception, while <tt>Array.wrap</tt> does not, it just returns the value.
+  # * It does not call +to_a+ on the argument, though special-cases +nil+ to return an empty array.
+  #
+  # The last point is particularly worth comparing for some enumerables:
   #
   #   Array(:foo => :bar)      # => [[:foo, :bar]]
   #   Array.wrap(:foo => :bar) # => [{:foo => :bar}]
   #
   #   Array("foo\nbar")        # => ["foo\n", "bar"], in Ruby 1.8
   #   Array.wrap("foo\nbar")   # => ["foo\nbar"]
+  #
+  # There's also a related idiom that uses the splat operator:
+  #
+  #   [*object]
+  #
+  # which returns <tt>[nil]</tt> for +nil+, and calls to <tt>Array(object)</tt> otherwise.
+  #
+  # Thus, in this case the behavior is different for +nil+, and the differences with
+  # <tt>Kernel#Array</tt> explained above apply to the rest of +object+s.
   def self.wrap(object)
     if object.nil?
       []

data/lib/active_support/core_ext/class/attribute.rb

@@ -2,8 +2,8 @@ require 'active_support/core_ext/kernel/singleton_class'
 require 'active_support/core_ext/module/remove_method'
 
 class Class
-  # Declare a class-level attribute whose value is inheritable and
-  # overwritable by subclasses:
+  # Declare a class-level attribute whose value is inheritable by subclasses.
+  # Subclasses can change their own value and it will not impact parent class.
   #
   #   class Base
   #     class_attribute :setting
@@ -18,12 +18,34 @@ class Class
   #   Subclass.setting            # => false
   #   Base.setting                # => true
   #
+  # In the above case as long as Subclass does not assign a value to setting
+  # by performing <tt>Subclass.setting = _something_ </tt>, <tt>Subclass.setting</tt>
+  # would read value assigned to parent class. Once Subclass assigns a value then
+  # the value assigned by Subclass would be returned.
+  #
   # This matches normal Ruby method inheritance: think of writing an attribute
-  # on a subclass as overriding the reader method.
+  # on a subclass as overriding the reader method. However, you need to be aware
+  # when using +class_attribute+ with mutable structures as +Array+ or +Hash+.
+  # In such cases, you don't want to do changes in places but use setters:
+  #
+  #   Base.setting = []
+  #   Base.setting                # => []
+  #   Subclass.setting            # => []
+  #
+  #   # Appending in child changes both parent and child because it is the same object:
+  #   Subclass.setting << :foo
+  #   Base.setting               # => [:foo]
+  #   Subclass.setting           # => [:foo]
+  #
+  #   # Use setters to not propagate changes:
+  #   Base.setting = []
+  #   Subclass.setting += [:foo]
+  #   Base.setting               # => []
+  #   Subclass.setting           # => [:foo]
   #
   # For convenience, a query method is defined as well:
   #
-  #   Subclass.setting?           # => false
+  #   Subclass.setting?       # => false
   #
   # Instances may overwrite the class value in the same way:
   #
@@ -50,6 +72,7 @@ class Class
             remove_possible_method(:#{name})
             define_method(:#{name}) { val }
           end
+          val
         end
 
         def #{name}

data/lib/active_support/core_ext/class/attribute_accessors.rb

@@ -3,11 +3,27 @@ require 'active_support/core_ext/array/extract_options'
 # Extends the class object with class and instance accessors for class attributes,
 # just like the native attr* accessors for instance attributes.
 #
+# Note that unlike +class_attribute+, if a subclass changes the value then that would
+# also change the value for parent class. Similarly if parent class changes the value
+# then that would change the value of subclasses too.
+#
 #  class Person
 #    cattr_accessor :hair_colors
 #  end
 #
 #  Person.hair_colors = [:brown, :black, :blonde, :red]
+#  Person.hair_colors     # => [:brown, :black, :blonde, :red]
+#  Person.new.hair_colors # => [:brown, :black, :blonde, :red]
+#
+# To opt out of the instance writer method, pass :instance_writer => false.
+# To opt out of the instance reader method, pass :instance_reader => false.
+#
+#   class Person
+#     cattr_accessor :hair_colors, :instance_writer => false, :instance_reader => false
+#   end
+#
+#   Person.new.hair_colors = [:brown]  # => NoMethodError
+#   Person.new.hair_colors             # => NoMethodError
 class Class
   def cattr_reader(*syms)
     options = syms.extract_options!

data/lib/active_support/core_ext/class/inheritable_attributes.rb

@@ -1,17 +1,39 @@
 require 'active_support/core_ext/object/duplicable'
 require 'active_support/core_ext/array/extract_options'
 
-# Retain for backward compatibility.  Methods are now included in Class.
+# Retained for backward compatibility.  Methods are now included in Class.
 module ClassInheritableAttributes # :nodoc:
 end
 
-# Allows attributes to be shared within an inheritance hierarchy, but where each descendant gets a copy of
+# It is recommended to use <tt>class_attribute</tt> over methods defined in this file. Please
+# refer to documentation for <tt>class_attribute</tt> for more information. Officially it is not
+# deprecated but <tt>class_attribute</tt> is faster.
+#
+# Allows attributes to be shared within an inheritance hierarchy. Each descendant gets a copy of
 # their parents' attributes, instead of just a pointer to the same. This means that the child can add elements
 # to, for example, an array without those additions being shared with either their parent, siblings, or
-# children, which is unlike the regular class-level attributes that are shared across the entire hierarchy.
+# children. This is unlike the regular class-level attributes that are shared across the entire hierarchy.
 #
 # The copies of inheritable parent attributes are added to subclasses when they are created, via the
 # +inherited+ hook.
+#
+#  class Person
+#    class_inheritable_accessor :hair_colors
+#  end
+#
+#  Person.hair_colors = [:brown, :black, :blonde, :red]
+#  Person.hair_colors     # => [:brown, :black, :blonde, :red]
+#  Person.new.hair_colors # => [:brown, :black, :blonde, :red]
+#
+# To opt out of the instance writer method, pass :instance_writer => false.
+# To opt out of the instance reader method, pass :instance_reader => false.
+#
+#   class Person
+#     class_inheritable_accessor :hair_colors :instance_writer => false, :instance_reader => false
+#   end
+#
+#   Person.new.hair_colors = [:brown]  # => NoMethodError
+#   Person.new.hair_colors             # => NoMethodError
 class Class # :nodoc:
   def class_inheritable_reader(*syms)
     options = syms.extract_options!

data/lib/active_support/core_ext/date/calculations.rb

@@ -7,7 +7,7 @@ require 'active_support/core_ext/time/zones'
 class Date
   if RUBY_VERSION < '1.9'
     undef :>>
-    
+
     # Backported from 1.9. The one in 1.8 leads to incorrect next_month and
     # friends for dates where the calendar reform is involved. It additionally
     # prevents an infinite loop fixed in r27013.
@@ -40,23 +40,23 @@ class Date
     end
   end
 
-  # Tells whether the Date object's date lies in the past
+  # Returns true if the Date object's date lies in the past. Otherwise returns false.
   def past?
     self < ::Date.current
   end
 
-  # Tells whether the Date object's date is today
+  # Returns true if the Date object's date is today.
   def today?
     self.to_date == ::Date.current # we need the to_date because of DateTime
   end
 
-  # Tells whether the Date object's date lies in the future
+  # Returns true if the Date object's date lies in the future.
   def future?
     self > ::Date.current
   end
 
   # Converts Date to a Time (or DateTime if necessary) with the time portion set to the beginning of the day (0:00)
-  # and then subtracts the specified number of seconds
+  # and then subtracts the specified number of seconds.
   def ago(seconds)
     to_time_in_current_zone.since(-seconds)
   end
@@ -127,22 +127,22 @@ class Date
     )
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified months ago
+  # Returns a new Date/DateTime representing the time a number of specified months ago.
   def months_ago(months)
     advance(:months => -months)
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified months in the future
+  # Returns a new Date/DateTime representing the time a number of specified months in the future.
   def months_since(months)
     advance(:months => months)
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified years ago
+  # Returns a new Date/DateTime representing the time a number of specified years ago.
   def years_ago(years)
     advance(:years => -years)
   end
 
-  # Returns a new Date/DateTime representing the time a number of specified years in the future
+  # Returns a new Date/DateTime representing the time a number of specified years in the future.
   def years_since(years)
     advance(:years => years)
   end
@@ -152,22 +152,22 @@ class Date
     years_ago(1)
   end unless method_defined?(:prev_year)
 
-  # Short-hand for years_since(1)
+  # Shorthand for years_since(1)
   def next_year
     years_since(1)
   end unless method_defined?(:next_year)
-  
-  # Short-hand for months_ago(1)
+
+  # Shorthand for months_ago(1)
   def prev_month
     months_ago(1)
   end unless method_defined?(:prev_month)
 
-  # Short-hand for months_since(1)
+  # Shorthand for months_since(1)
   def next_month
     months_since(1)
   end unless method_defined?(:next_month)
 
-  # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00)
+  # Returns a new Date/DateTime representing the "start" of this week (i.e, Monday; DateTime objects will have time set to 0:00).
   def beginning_of_week
     days_to_monday = self.wday!=0 ? self.wday-1 : 6
     result = self - days_to_monday
@@ -176,7 +176,7 @@ class Date
   alias :monday :beginning_of_week
   alias :at_beginning_of_week :beginning_of_week
 
-  # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59)
+  # Returns a new Date/DateTime representing the end of this week (Sunday, DateTime objects will have time set to 23:59:59).
   def end_of_week
     days_to_sunday = self.wday!=0 ? 7-self.wday : 0
     result = self + days_to_sunday.days