activesupport 3.2.22.5 → 4.0.0.beta1

data/lib/active_support/deprecation/reporting.rb

@@ -1,20 +1,34 @@
 module ActiveSupport
-  module Deprecation
-    class << self
+  class Deprecation
+    module Reporting
+      # Whether to print a message (silent mode)
       attr_accessor :silenced
+      # Name of gem where method is deprecated
+      attr_accessor :gem_name
 
-      # Outputs a deprecation warning to the output configured by <tt>ActiveSupport::Deprecation.behavior</tt>
+      # Outputs a deprecation warning to the output configured by
+      # <tt>ActiveSupport::Deprecation.behavior</tt>.
       #
-      #   ActiveSupport::Deprecation.warn("something broke!")
+      #   ActiveSupport::Deprecation.warn('something broke!')
       #   # => "DEPRECATION WARNING: something broke! (called from your_code.rb:1)"
-      def warn(message = nil, callstack = caller)
+      def warn(message = nil, callstack = nil)
         return if silenced
+
+        callstack ||= caller(2)
         deprecation_message(callstack, message).tap do |m|
           behavior.each { |b| b.call(m, callstack) }
         end
       end
 
       # Silence deprecation warnings within the block.
+      #
+      #   ActiveSupport::Deprecation.warn('something broke!')
+      #   # => "DEPRECATION WARNING: something broke! (called from your_code.rb:1)"
+      #
+      #   ActiveSupport::Deprecation.silence do
+      #     ActiveSupport::Deprecation.warn('something broke!')
+      #   end
+      #   # => nil
       def silence
         old_silenced, @silenced = @silenced, true
         yield
@@ -22,16 +36,31 @@ module ActiveSupport
         @silenced = old_silenced
       end
 
-      def deprecated_method_warning(method_name, message = nil)
-        warning = "#{method_name} is deprecated and will be removed from Rails #{deprecation_horizon}"
-        case message
-          when Symbol then "#{warning} (use #{message} instead)"
-          when String then "#{warning} (#{message})"
-          else warning
+      def deprecation_warning(deprecated_method_name, message = nil, caller_backtrace = nil)
+        caller_backtrace ||= caller(2)
+        deprecated_method_warning(deprecated_method_name, message).tap do |msg|
+          warn(msg, caller_backtrace)
         end
       end
 
       private
+        # Outputs a deprecation warning message
+        #
+        #   ActiveSupport::Deprecation.deprecated_method_warning(:method_name)
+        #   # => "method_name is deprecated and will be removed from Rails #{deprecation_horizon}"
+        #   ActiveSupport::Deprecation.deprecated_method_warning(:method_name, :another_method)
+        #   # => "method_name is deprecated and will be removed from Rails #{deprecation_horizon} (use another_method instead)"
+        #   ActiveSupport::Deprecation.deprecated_method_warning(:method_name, "Optional message")
+        #   # => "method_name is deprecated and will be removed from Rails #{deprecation_horizon} (Optional message)"
+        def deprecated_method_warning(method_name, message = nil)
+          warning = "#{method_name} is deprecated and will be removed from #{gem_name} #{deprecation_horizon}"
+          case message
+            when Symbol then "#{warning} (use #{message} instead)"
+            when String then "#{warning} (#{message})"
+            else warning
+          end
+        end
+
         def deprecation_message(callstack, message = nil)
           message ||= "You are using deprecated behavior which will be removed from the next major or minor release."
           message += '.' unless message =~ /\.$/

data/lib/active_support/descendants_tracker.rb

@@ -2,35 +2,50 @@ module ActiveSupport
   # This module provides an internal implementation to track descendants
   # which is faster than iterating through ObjectSpace.
   module DescendantsTracker
-    @@direct_descendants = Hash.new { |h, k| h[k] = [] }
+    @@direct_descendants = {}
 
-    def self.direct_descendants(klass)
-      @@direct_descendants[klass]
-    end
+    class << self
+      def direct_descendants(klass)
+        @@direct_descendants[klass] || []
+      end
 
-    def self.descendants(klass)
-      @@direct_descendants[klass].inject([]) do |descendants, _klass|
-        descendants << _klass
-        descendants.concat _klass.descendants
+      def descendants(klass)
+        arr = []
+        accumulate_descendants(klass, arr)
+        arr
       end
-    end
 
-    def self.clear
-      if defined? ActiveSupport::Dependencies
-        @@direct_descendants.each do |klass, descendants|
-          if ActiveSupport::Dependencies.autoloaded?(klass)
-            @@direct_descendants.delete(klass)
-          else
-            descendants.reject! { |v| ActiveSupport::Dependencies.autoloaded?(v) }
+      def clear
+        if defined? ActiveSupport::Dependencies
+          @@direct_descendants.each do |klass, descendants|
+            if ActiveSupport::Dependencies.autoloaded?(klass)
+              @@direct_descendants.delete(klass)
+            else
+              descendants.reject! { |v| ActiveSupport::Dependencies.autoloaded?(v) }
+            end
           end
+        else
+          @@direct_descendants.clear
+        end
+      end
+
+      # This is the only method that is not thread safe, but is only ever called
+      # during the eager loading phase.
+      def store_inherited(klass, descendant)
+        (@@direct_descendants[klass] ||= []) << descendant
+      end
+
+      private
+      def accumulate_descendants(klass, acc)
+        if direct_descendants = @@direct_descendants[klass]
+          acc.concat(direct_descendants)
+          direct_descendants.each { |direct_descendant| accumulate_descendants(direct_descendant, acc) }
         end
-      else
-        @@direct_descendants.clear
       end
     end
 
     def inherited(base)
-      self.direct_descendants << base
+      DescendantsTracker.store_inherited(self, base)
       super
     end
 

data/lib/active_support/duration.rb

@@ -1,16 +1,14 @@
-require 'active_support/basic_object'
+require 'active_support/proxy_object'
 require 'active_support/core_ext/array/conversions'
 require 'active_support/core_ext/object/acts_like'
 
 module ActiveSupport
   # Provides accurate date and time measurements using Date#advance and
   # Time#advance, respectively. It mainly supports the methods on Numeric.
-  # Example:
   #
-  #   1.month.ago       # equivalent to Time.now.advance(:months => -1)
-  class Duration < BasicObject
+  #   1.month.ago       # equivalent to Time.now.advance(months: -1)
+  class Duration < ProxyObject
     attr_accessor :value, :parts
-    delegate :duplicable?, :to => :value # required when using ActiveSupport's BasicObject on 1.8
 
     def initialize(value, parts) #:nodoc:
       @value, @parts = value, parts
@@ -41,8 +39,8 @@ module ActiveSupport
     end
     alias :kind_of? :is_a?
 
-    # Returns true if <tt>other</tt> is also a Duration instance with the
-    # same <tt>value</tt>, or if <tt>other == value</tt>.
+    # Returns +true+ if +other+ is also a Duration instance with the
+    # same +value+, or if <tt>other == value</tt>.
     def ==(other)
       if Duration === other
         other.value == value
@@ -72,7 +70,7 @@ module ActiveSupport
     alias :until :ago
 
     def inspect #:nodoc:
-      consolidated = parts.inject(::Hash.new(0)) { |h,part| h[part.first] += part.last; h }
+      consolidated = parts.inject(::Hash.new(0)) { |h,(l,r)| h[l] += r; h }
       parts = [:years, :months, :days, :minutes, :seconds].map do |length|
         n = consolidated[length]
         "#{n} #{n == 1 ? length.to_s.singularize : length.to_s}" if n.nonzero?

data/lib/active_support/file_update_checker.rb

@@ -1,26 +1,21 @@
-require "active_support/core_ext/array/wrap"
-require "active_support/core_ext/array/extract_options"
-
 module ActiveSupport
-  # \FileUpdateChecker specifies the API used by Rails to watch files
+  # FileUpdateChecker specifies the API used by Rails to watch files
   # and control reloading. The API depends on four methods:
   #
   # * +initialize+ which expects two parameters and one block as
-  #   described below;
+  #   described below.
   #
   # * +updated?+ which returns a boolean if there were updates in
-  #   the filesystem or not;
+  #   the filesystem or not.
   #
   # * +execute+ which executes the given block on initialization
-  #   and updates the counter to the latest timestamp;
+  #   and updates the latest watched files and timestamp.
   #
-  # * +execute_if_updated+ which just executes the block if it was updated;
+  # * +execute_if_updated+ which just executes the block if it was updated.
   #
   # After initialization, a call to +execute_if_updated+ must execute
   # the block only if there was really a change in the filesystem.
   #
-  # == Examples
-  #
   # This class is used by Rails to reload the I18n framework whenever
   # they are changed upon a new request.
   #
@@ -31,52 +26,55 @@ module ActiveSupport
   #   ActionDispatch::Reloader.to_prepare do
   #     i18n_reloader.execute_if_updated
   #   end
-  #
   class FileUpdateChecker
     # It accepts two parameters on initialization. The first is an array
     # of files and the second is an optional hash of directories. The hash must
     # have directories as keys and the value is an array of extensions to be
     # watched under that directory.
     #
-    # This method must also receive a block that will be called once a path changes.
-    #
-    # == Implementation details
-    #
-    # This particular implementation checks for added and updated files,
-    # but not removed files. Directories lookup are compiled to a glob for
-    # performance. Therefore, while someone can add new files to the +files+
-    # array after initialization (and parts of Rails do depend on this feature),
-    # adding new directories after initialization is not allowed.
-    #
-    # Notice that other objects that implements FileUpdateChecker API may
-    # not even allow new files to be added after initialization. If this
-    # is the case, we recommend freezing the +files+ after initialization to
-    # avoid changes that won't make effect.
+    # This method must also receive a block that will be called once a path
+    # changes. The array of files and list of directories cannot be changed
+    # after FileUpdateChecker has been initialized.
     def initialize(files, dirs={}, &block)
-      @files = files
+      @files = files.freeze
       @glob  = compile_glob(dirs)
       @block = block
+
+      @watched    = nil
       @updated_at = nil
-      @last_update_at = updated_at
+
+      @last_watched   = watched
+      @last_update_at = updated_at(@last_watched)
     end
 
-    # Check if any of the entries were updated. If so, the updated_at
-    # value is cached until the block is executed via +execute+ or +execute_if_updated+
+    # Check if any of the entries were updated. If so, the watched and/or
+    # updated_at values are cached until the block is executed via +execute+
+    # or +execute_if_updated+.
     def updated?
-      current_updated_at = updated_at
-      if @last_update_at < current_updated_at
-        @updated_at = updated_at
+      current_watched = watched
+      if @last_watched.size != current_watched.size
+        @watched = current_watched
         true
       else
-        false
+        current_updated_at = updated_at(current_watched)
+        if @last_update_at < current_updated_at
+          @watched    = current_watched
+          @updated_at = current_updated_at
+          true
+        else
+          false
+        end
       end
     end
 
-    # Executes the given block and updates the counter to latest timestamp.
+    # Executes the given block and updates the latest watched files and
+    # timestamp.
     def execute
-      @last_update_at = updated_at
+      @last_watched   = watched
+      @last_update_at = updated_at(@last_watched)
       @block.call
     ensure
+      @watched = nil
       @updated_at = nil
     end
 
@@ -92,28 +90,46 @@ module ActiveSupport
 
     private
 
-    def updated_at #:nodoc:
-      @updated_at || begin
-        all = []
-        all.concat @files.select { |f| File.exists?(f) }
-        all.concat Dir[@glob] if @glob
-        all.map { |path| File.mtime(path) }.max || Time.at(0)
+    def watched
+      @watched || begin
+        all = @files.select { |f| File.exists?(f) }
+        all.concat(Dir[@glob]) if @glob
+        all
       end
     end
 
-    def compile_glob(hash) #:nodoc:
+    def updated_at(paths)
+      @updated_at || max_mtime(paths) || Time.at(0)
+    end
+
+    # This method returns the maximum mtime of the files in +paths+, or +nil+
+    # if the array is empty.
+    #
+    # Files with a mtime in the future are ignored. Such abnormal situation
+    # can happen for example if the user changes the clock by hand. It is
+    # healthy to consider this edge case because with mtimes in the future
+    # reloading is not triggered.
+    def max_mtime(paths)
+      time_now = Time.now
+      paths.map {|path| File.mtime(path)}.reject {|mtime| time_now < mtime}.max
+    end
+
+    def compile_glob(hash)
       hash.freeze # Freeze so changes aren't accidently pushed
       return if hash.empty?
 
-      globs = []
-      hash.each do |key, value|
-        globs << "#{key}/**/*#{compile_ext(value)}"
+      globs = hash.map do |key, value|
+        "#{escape(key)}/**/*#{compile_ext(value)}"
       end
       "{#{globs.join(",")}}"
     end
 
-    def compile_ext(array) #:nodoc:
-      array = Array.wrap(array)
+    def escape(key)
+      key.gsub(',','\,')
+    end
+
+    def compile_ext(array)
+      array = Array(array)
       return if array.empty?
       ".{#{array.join(",")}}"
     end

data/lib/active_support/gzip.rb

@@ -1,14 +1,20 @@
 require 'zlib'
 require 'stringio'
-require 'active_support/core_ext/string/encoding'
 
 module ActiveSupport
-  # A convenient wrapper for the zlib standard library that allows compression/decompression of strings with gzip.
+  # A convenient wrapper for the zlib standard library that allows
+  # compression/decompression of strings with gzip.
+  #
+  #   gzip = ActiveSupport::Gzip.compress('compress me!')
+  #   # => "\x1F\x8B\b\x00o\x8D\xCDO\x00\x03K\xCE\xCF-(J-.V\xC8MU\x04\x00R>n\x83\f\x00\x00\x00"
+  #
+  #   ActiveSupport::Gzip.decompress(gzip)
+  #   # => "compress me!" 
   module Gzip
     class Stream < StringIO
       def initialize(*)
         super
-        set_encoding "BINARY" if "".encoding_aware?
+        set_encoding "BINARY"
       end
       def close; rewind; end
     end
@@ -19,9 +25,9 @@ module ActiveSupport
     end
 
     # Compresses a string using gzip.
-    def self.compress(source)
+    def self.compress(source, level=Zlib::DEFAULT_COMPRESSION, strategy=Zlib::DEFAULT_STRATEGY)
       output = Stream.new
-      gz = Zlib::GzipWriter.new(output)
+      gz = Zlib::GzipWriter.new(output, level, strategy)
       gz.write(source)
       gz.close
       output.string

data/lib/active_support/hash_with_indifferent_access.rb

@@ -1,13 +1,47 @@
 require 'active_support/core_ext/hash/keys'
 
-# This class has dubious semantics and we only have it so that
-# people can write <tt>params[:key]</tt> instead of <tt>params['key']</tt>
-# and they get the same value for both keys.
-
 module ActiveSupport
+  # Implements a hash where keys <tt>:foo</tt> and <tt>"foo"</tt> are considered
+  # to be the same.
+  #
+  #   rgb = ActiveSupport::HashWithIndifferentAccess.new
+  #
+  #   rgb[:black] = '#000000'
+  #   rgb[:black]  # => '#000000'
+  #   rgb['black'] # => '#000000'
+  #
+  #   rgb['white'] = '#FFFFFF'
+  #   rgb[:white]  # => '#FFFFFF'
+  #   rgb['white'] # => '#FFFFFF'
+  #
+  # Internally symbols are mapped to strings when used as keys in the entire
+  # writing interface (calling <tt>[]=</tt>, <tt>merge</tt>, etc). This
+  # mapping belongs to the public interface. For example, given:
+  #
+  #   hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1)
+  #
+  # You are guaranteed that the key is returned as a string:
+  #
+  #   hash.keys # => ["a"]
+  #
+  # Technically other types of keys are accepted:
+  #
+  #   hash = ActiveSupport::HashWithIndifferentAccess.new(a: 1)
+  #   hash[0] = 0
+  #   hash # => {"a"=>1, 0=>0}
+  #
+  # but this class is intended for use cases where strings or symbols are the
+  # expected keys and it is convenient to understand both as the same. For
+  # example the +params+ hash in Ruby on Rails.
+  #
+  # Note that core extensions define <tt>Hash#with_indifferent_access</tt>:
+  #
+  #   rgb = { black: '#000000', white: '#FFFFFF' }.with_indifferent_access
+  #
+  # which may be handy.
   class HashWithIndifferentAccess < Hash
-
-    # Always returns true, so that <tt>Array#extract_options!</tt> finds members of this class.
+    # Returns +true+ so that <tt>Array#extract_options!</tt> finds members of
+    # this class.
     def extractable_options?
       true
     end
@@ -43,35 +77,60 @@ module ActiveSupport
       end
     end
 
+    def self.[](*args)
+      new.merge(Hash[*args])
+    end
+
     alias_method :regular_writer, :[]= unless method_defined?(:regular_writer)
     alias_method :regular_update, :update unless method_defined?(:regular_update)
 
     # Assigns a new value to the hash:
     #
-    #   hash = HashWithIndifferentAccess.new
-    #   hash[:key] = "value"
+    #   hash = ActiveSupport::HashWithIndifferentAccess.new
+    #   hash[:key] = 'value'
     #
+    # This value can be later fetched using either +:key+ or +'key'+.
     def []=(key, value)
       regular_writer(convert_key(key), convert_value(value))
     end
 
     alias_method :store, :[]=
 
-    # Updates the instantized hash with values from the second:
+    # Updates the receiver in-place, merging in the hash passed as argument:
     #
-    #   hash_1 = HashWithIndifferentAccess.new
-    #   hash_1[:key] = "value"
+    #   hash_1 = ActiveSupport::HashWithIndifferentAccess.new
+    #   hash_1[:key] = 'value'
     #
-    #   hash_2 = HashWithIndifferentAccess.new
-    #   hash_2[:key] = "New Value!"
+    #   hash_2 = ActiveSupport::HashWithIndifferentAccess.new
+    #   hash_2[:key] = 'New Value!'
     #
     #   hash_1.update(hash_2) # => {"key"=>"New Value!"}
     #
+    # The argument can be either an
+    # <tt>ActiveSupport::HashWithIndifferentAccess</tt> or a regular +Hash+.
+    # In either case the merge respects the semantics of indifferent access.
+    #
+    # If the argument is a regular hash with keys +:key+ and +"key"+ only one
+    # of the values end up in the receiver, but which one is unspecified.
+    #
+    # When given a block, the value for duplicated keys will be determined
+    # by the result of invoking the block with the duplicated key, the value
+    # in the receiver, and the value in +other_hash+. The rules for duplicated
+    # keys follow the semantics of indifferent access:
+    #
+    #   hash_1[:key] = 10
+    #   hash_2['key'] = 12
+    #   hash_1.update(hash_2) { |key, old, new| old + new } # => {"key"=>22}
     def update(other_hash)
       if other_hash.is_a? HashWithIndifferentAccess
         super(other_hash)
       else
-        other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) }
+        other_hash.each_pair do |key, value|
+          if block_given? && key?(key)
+            value = yield(convert_key(key), self[key], value)
+          end
+          regular_writer(convert_key(key), convert_value(value))
+        end
         self
       end
     end
@@ -80,11 +139,10 @@ module ActiveSupport
 
     # Checks the hash for a key matching the argument passed in:
     #
-    #   hash = HashWithIndifferentAccess.new
-    #   hash["key"] = "value"
-    #   hash.key? :key  # => true
-    #   hash.key? "key" # => true
-    #
+    #   hash = ActiveSupport::HashWithIndifferentAccess.new
+    #   hash['key'] = 'value'
+    #   hash.key?(:key)  # => true
+    #   hash.key?('key') # => true
     def key?(key)
       super(convert_key(key))
     end
@@ -96,25 +154,23 @@ module ActiveSupport
     # Same as <tt>Hash#fetch</tt> where the key passed as argument can be
     # either a string or a symbol:
     #
-    #   counters = HashWithIndifferentAccess.new
+    #   counters = ActiveSupport::HashWithIndifferentAccess.new
     #   counters[:foo] = 1
     #
-    #   counters.fetch("foo")          # => 1
+    #   counters.fetch('foo')          # => 1
     #   counters.fetch(:bar, 0)        # => 0
     #   counters.fetch(:bar) {|key| 0} # => 0
     #   counters.fetch(:zoo)           # => KeyError: key not found: "zoo"
-    #
     def fetch(key, *extras)
       super(convert_key(key), *extras)
     end
 
     # Returns an array of the values at the specified indices:
     #
-    #   hash = HashWithIndifferentAccess.new
-    #   hash[:a] = "x"
-    #   hash[:b] = "y"
-    #   hash.values_at("a", "b") # => ["x", "y"]
-    #
+    #   hash = ActiveSupport::HashWithIndifferentAccess.new
+    #   hash[:a] = 'x'
+    #   hash[:b] = 'y'
+    #   hash.values_at('a', 'b') # => ["x", "y"]
     def values_at(*indices)
       indices.collect {|key| self[convert_key(key)]}
     end
@@ -126,34 +182,52 @@ module ActiveSupport
       end
     end
 
-    # Merges the instantized and the specified hashes together, giving precedence to the values from the second hash.
-    # Does not overwrite the existing hash.
-    def merge(hash)
-      self.dup.update(hash)
+    # This method has the same semantics of +update+, except it does not
+    # modify the receiver but rather returns a new hash with indifferent
+    # access with the result of the merge.
+    def merge(hash, &block)
+      self.dup.update(hash, &block)
     end
 
-    # Performs the opposite of merge, with the keys and values from the first hash taking precedence over the second.
-    # This overloaded definition prevents returning a regular hash, if reverse_merge is called on a <tt>HashWithDifferentAccess</tt>.
+    # Like +merge+ but the other way around: Merges the receiver into the
+    # argument and returns a new hash with indifferent access as result:
+    #
+    #   hash = ActiveSupport::HashWithIndifferentAccess.new
+    #   hash['a'] = nil
+    #   hash.reverse_merge(a: 0, b: 1) # => {"a"=>nil, "b"=>1}
     def reverse_merge(other_hash)
-      super self.class.new_from_hash_copying_default(other_hash)
+      super(self.class.new_from_hash_copying_default(other_hash))
     end
 
+    # Same semantics as +reverse_merge+ but modifies the receiver in-place.
     def reverse_merge!(other_hash)
       replace(reverse_merge( other_hash ))
     end
 
-    # Removes a specified key from the hash.
+    # Replaces the contents of this hash with other_hash.
+    #
+    #   h = { "a" => 100, "b" => 200 }
+    #   h.replace({ "c" => 300, "d" => 400 }) #=> {"c"=>300, "d"=>400}
+    def replace(other_hash)
+      super(self.class.new_from_hash_copying_default(other_hash))
+    end
+
+    # Removes the specified key from the hash.
     def delete(key)
       super(convert_key(key))
     end
 
     def stringify_keys!; self end
+    def deep_stringify_keys!; self end
     def stringify_keys; dup end
+    def deep_stringify_keys; dup end
     undef :symbolize_keys!
+    undef :deep_symbolize_keys!
     def symbolize_keys; to_hash.symbolize_keys end
+    def deep_symbolize_keys; to_hash.deep_symbolize_keys end
     def to_options!; self end
 
-    # Convert to a Hash with String keys.
+    # Convert to a regular hash with string keys.
     def to_hash
       Hash.new(default).merge!(self)
     end
@@ -167,7 +241,8 @@ module ActiveSupport
         if value.is_a? Hash
           value.nested_under_indifferent_access
         elsif value.is_a?(Array)
-          value.dup.replace(value.map { |e| convert_value(e) })
+          value = value.dup if value.frozen?
+          value.map! { |e| convert_value(e) }
         else
           value
         end