activesupport 3.2.22.5 → 4.0.0

data/lib/active_support/deprecation/behaviors.rb

@@ -1,49 +1,63 @@
 require "active_support/notifications"
-require "active_support/core_ext/array/wrap"
 
 module ActiveSupport
-  module Deprecation
-    class << self
+  class Deprecation
+    # Default warning behaviors per Rails.env.
+    DEFAULT_BEHAVIORS = {
+      :stderr => Proc.new { |message, callstack|
+        $stderr.puts(message)
+        $stderr.puts callstack.join("\n  ") if debug
+      },
+      :log => Proc.new { |message, callstack|
+        logger =
+            if defined?(Rails) && Rails.logger
+              Rails.logger
+            else
+              require 'active_support/logger'
+              ActiveSupport::Logger.new($stderr)
+            end
+        logger.warn message
+        logger.debug callstack.join("\n  ") if debug
+      },
+      :notify => Proc.new { |message, callstack|
+        ActiveSupport::Notifications.instrument("deprecation.rails",
+                                                :message => message, :callstack => callstack)
+      },
+      :silence => Proc.new { |message, callstack| }
+    }
+
+    module Behavior
       # Whether to print a backtrace along with the warning.
       attr_accessor :debug
 
-      # Returns the set behavior or if one isn't set, defaults to +:stderr+
+      # Returns the current behavior or if one isn't set, defaults to +:stderr+.
       def behavior
         @behavior ||= [DEFAULT_BEHAVIORS[:stderr]]
       end
 
-      # Sets the behavior to the specified value. Can be a single value or an array.
+      # Sets the behavior to the specified value. Can be a single value, array,
+      # or an object that responds to +call+.
+      #
+      # Available behaviors:
       #
-      # Examples
+      # [+stderr+]  Log all deprecation warnings to +$stderr+.
+      # [+log+]     Log all deprecation warnings to +Rails.logger+.
+      # [+notify+]  Use +ActiveSupport::Notifications+ to notify +deprecation.rails+.
+      # [+silence+] Do nothing.
+      #
+      # Setting behaviors only affects deprecations that happen after boot time.
+      # Deprecation warnings raised by gems are not affected by this setting
+      # because they happen before Rails boots up.
       #
       #   ActiveSupport::Deprecation.behavior = :stderr
       #   ActiveSupport::Deprecation.behavior = [:stderr, :log]
+      #   ActiveSupport::Deprecation.behavior = MyCustomHandler
+      #   ActiveSupport::Deprecation.behavior = proc { |message, callstack|
+      #     # custom stuff
+      #   }
       def behavior=(behavior)
-        @behavior = Array.wrap(behavior).map { |b| DEFAULT_BEHAVIORS[b] || b }
+        @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || b }
       end
     end
-
-    # Default warning behaviors per Rails.env.
-    DEFAULT_BEHAVIORS = {
-      :stderr => Proc.new { |message, callstack|
-         $stderr.puts(message)
-         $stderr.puts callstack.join("\n  ") if debug
-       },
-      :log => Proc.new { |message, callstack|
-         logger =
-           if defined?(Rails) && Rails.logger
-             Rails.logger
-           else
-             require 'logger'
-             Logger.new($stderr)
-           end
-         logger.warn message
-         logger.debug callstack.join("\n  ") if debug
-       },
-       :notify => Proc.new { |message, callstack|
-          ActiveSupport::Notifications.instrument("deprecation.rails",
-            :message => message, :callstack => callstack)
-       }
-    }
   end
 end

data/lib/active_support/deprecation/instance_delegator.rb

@@ -0,0 +1,24 @@
+require 'active_support/core_ext/kernel/singleton_class'
+require 'active_support/core_ext/module/delegation'
+
+module ActiveSupport
+  class Deprecation
+    module InstanceDelegator # :nodoc:
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.public_class_method :new
+      end
+
+      module ClassMethods # :nodoc:
+        def include(included_module)
+          included_module.instance_methods.each { |m| method_added(m) }
+          super
+        end
+
+        def method_added(method_name)
+          singleton_class.delegate(method_name, to: :instance)
+        end
+      end
+    end
+  end
+end

data/lib/active_support/deprecation/method_wrappers.rb

@@ -1,27 +1,42 @@
-require 'active_support/core_ext/module/deprecation'
 require 'active_support/core_ext/module/aliasing'
 require 'active_support/core_ext/array/extract_options'
 
 module ActiveSupport
-  class << Deprecation
-    # Declare that a method has been deprecated.
-    def deprecate_methods(target_module, *method_names)
-      options = method_names.extract_options!
-      method_names += options.keys
+  class Deprecation
+    module MethodWrapper
+      # Declare that a method has been deprecated.
+      #
+      #   module Fred
+      #     extend self
+      #
+      #     def foo; end
+      #     def bar; end
+      #     def baz; end
+      #   end
+      #
+      #   ActiveSupport::Deprecation.deprecate_methods(Fred, :foo, bar: :qux, baz: 'use Bar#baz instead')
+      #   # => [:foo, :bar, :baz]
+      #
+      #   Fred.foo
+      #   # => "DEPRECATION WARNING: foo is deprecated and will be removed from Rails 4.1."
+      #
+      #   Fred.bar
+      #   # => "DEPRECATION WARNING: bar is deprecated and will be removed from Rails 4.1 (use qux instead)."
+      #
+      #   Fred.baz
+      #   # => "DEPRECATION WARNING: baz is deprecated and will be removed from Rails 4.1 (use Bar#baz instead)."
+      def deprecate_methods(target_module, *method_names)
+        options = method_names.extract_options!
+        deprecator = options.delete(:deprecator) || ActiveSupport::Deprecation.instance
+        method_names += options.keys
 
-      method_names.each do |method_name|
-        target_module.alias_method_chain(method_name, :deprecation) do |target, punctuation|
-          target_module.module_eval(<<-end_eval, __FILE__, __LINE__ + 1)
-            def #{target}_with_deprecation#{punctuation}(*args, &block)
-              ::ActiveSupport::Deprecation.warn(
-                ::ActiveSupport::Deprecation.deprecated_method_warning(
-                  :#{method_name},
-                  #{options[method_name].inspect}),
-                caller
-              )
-              send(:#{target}_without_deprecation#{punctuation}, *args, &block)
+        method_names.each do |method_name|
+          target_module.alias_method_chain(method_name, :deprecation) do |target, punctuation|
+            target_module.send(:define_method, "#{target}_with_deprecation#{punctuation}") do |*args, &block|
+              deprecator.deprecation_warning(method_name, options[method_name])
+              send(:"#{target}_without_deprecation#{punctuation}", *args, &block)
             end
-          end_eval
+          end
         end
       end
     end

data/lib/active_support/deprecation/proxy_wrappers.rb

@@ -1,7 +1,7 @@
 require 'active_support/inflector/methods'
 
 module ActiveSupport
-  module Deprecation
+  class Deprecation
     class DeprecationProxy #:nodoc:
       def self.new(*args, &block)
         object = args.first
@@ -25,10 +25,20 @@ module ActiveSupport
         end
     end
 
-    class DeprecatedObjectProxy < DeprecationProxy #:nodoc:
-      def initialize(object, message)
+    # This DeprecatedObjectProxy transforms object to deprecated object.
+    #
+    #   @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!")
+    #   @old_object = DeprecatedObjectProxy.new(Object.new, "Don't use this object anymore!", deprecator_instance)
+    #
+    # When someone executes any method except +inspect+ on proxy object this will
+    # trigger +warn+ method on +deprecator_instance+.
+    #
+    # Default deprecator is <tt>ActiveSupport::Deprecation</tt>
+    class DeprecatedObjectProxy < DeprecationProxy
+      def initialize(object, message, deprecator = ActiveSupport::Deprecation.instance)
         @object = object
         @message = message
+        @deprecator = deprecator
       end
 
       private
@@ -37,15 +47,40 @@ module ActiveSupport
         end
 
         def warn(callstack, called, args)
-          ActiveSupport::Deprecation.warn(@message, callstack)
+          @deprecator.warn(@message, callstack)
         end
     end
 
-    # Stand-in for <tt>@request</tt>, <tt>@attributes</tt>, <tt>@params</tt>, etc.
-    # which emits deprecation warnings on any method call (except +inspect+).
-    class DeprecatedInstanceVariableProxy < DeprecationProxy #:nodoc:
-      def initialize(instance, method, var = "@#{method}")
-        @instance, @method, @var = instance, method, var
+    # This DeprecatedInstanceVariableProxy transforms instance variable to
+    # deprecated instance variable.
+    #
+    #   class Example
+    #     def initialize(deprecator)
+    #       @request = ActiveSupport::Deprecation::DeprecatedInstanceVariableProxy.new(self, :request, :@request, deprecator)
+    #       @_request = :a_request
+    #     end
+    #
+    #     def request
+    #       @_request
+    #     end
+    #
+    #     def old_request
+    #       @request
+    #     end
+    #   end
+    #
+    # When someone execute any method on @request variable this will trigger
+    # +warn+ method on +deprecator_instance+ and will fetch <tt>@_request</tt>
+    # variable via +request+ method and execute the same method on non-proxy
+    # instance variable.
+    #
+    # Default deprecator is <tt>ActiveSupport::Deprecation</tt>.
+    class DeprecatedInstanceVariableProxy < DeprecationProxy
+      def initialize(instance, method, var = "@#{method}", deprecator = ActiveSupport::Deprecation.instance)
+        @instance = instance
+        @method = method
+        @var = var
+        @deprecator = deprecator
       end
 
       private
@@ -54,14 +89,24 @@ module ActiveSupport
         end
 
         def warn(callstack, called, args)
-          ActiveSupport::Deprecation.warn("#{@var} is deprecated! Call #{@method}.#{called} instead of #{@var}.#{called}. Args: #{args.inspect}", callstack)
+          @deprecator.warn("#{@var} is deprecated! Call #{@method}.#{called} instead of #{@var}.#{called}. Args: #{args.inspect}", callstack)
         end
     end
 
-    class DeprecatedConstantProxy < DeprecationProxy #:nodoc:all
-      def initialize(old_const, new_const)
+    # This DeprecatedConstantProxy transforms constant to deprecated constant.
+    #
+    #   OLD_CONST = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('OLD_CONST', 'NEW_CONST')
+    #   OLD_CONST = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('OLD_CONST', 'NEW_CONST', deprecator_instance)
+    #
+    # When someone use old constant this will trigger +warn+ method on
+    # +deprecator_instance+.
+    #
+    # Default deprecator is <tt>ActiveSupport::Deprecation</tt>.
+    class DeprecatedConstantProxy < DeprecationProxy
+      def initialize(old_const, new_const, deprecator = ActiveSupport::Deprecation.instance)
         @old_const = old_const
         @new_const = new_const
+        @deprecator = deprecator
       end
 
       def class
@@ -74,7 +119,7 @@ module ActiveSupport
         end
 
         def warn(callstack, called, args)
-          ActiveSupport::Deprecation.warn("#{@old_const} is deprecated! Use #{@new_const} instead.", callstack)
+          @deprecator.warn("#{@old_const} is deprecated! Use #{@new_const} instead.", callstack)
         end
     end
   end

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/deprecation.rb

@@ -1,18 +1,43 @@
-require 'active_support/deprecation/behaviors'
-require 'active_support/deprecation/reporting'
-require 'active_support/deprecation/method_wrappers'
-require 'active_support/deprecation/proxy_wrappers'
+require 'singleton'
 
 module ActiveSupport
-  module Deprecation
-    class << self
-      # The version the deprecated behavior will be removed, by default.
-      attr_accessor :deprecation_horizon
-    end
-    self.deprecation_horizon = '4.0'
+  # \Deprecation specifies the API used by Rails to deprecate methods, instance
+  # variables, objects and constants.
+  class Deprecation
+    # active_support.rb sets an autoload for ActiveSupport::Deprecation.
+    #
+    # If these requires were at the top of the file the constant would not be
+    # defined by the time their files were loaded. Since some of them reopen
+    # ActiveSupport::Deprecation its autoload would be triggered, resulting in
+    # a circular require warning for active_support/deprecation.rb.
+    #
+    # So, we define the constant first, and load dependencies later.
+    require 'active_support/deprecation/instance_delegator'
+    require 'active_support/deprecation/behaviors'
+    require 'active_support/deprecation/reporting'
+    require 'active_support/deprecation/method_wrappers'
+    require 'active_support/deprecation/proxy_wrappers'
+    require 'active_support/core_ext/module/deprecation'
+
+    include Singleton
+    include InstanceDelegator
+    include Behavior
+    include Reporting
+    include MethodWrapper
 
-    # By default, warnings are not silenced and debugging is off.
-    self.silenced = false
-    self.debug = false
+    # The version the deprecated behavior will be removed, by default.
+    attr_accessor :deprecation_horizon
+
+    # It accepts two parameters on initialization. The first is an version of library
+    # and the second is an library name
+    #
+    #   ActiveSupport::Deprecation.new('2.0', 'MyLibrary')
+    def initialize(deprecation_horizon = '4.1', gem_name = 'Rails')
+      self.gem_name = gem_name
+      self.deprecation_horizon = deprecation_horizon
+      # By default, warnings are not silenced and debugging is off.
+      self.silenced = false
+      self.debug = false
+    end
   end
-end
+end

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?