activesupport 3.1.0 → 5.0.0

data/lib/active_support/deprecation/behaviors.rb

@@ -1,49 +1,90 @@
 require "active_support/notifications"
-require "active_support/core_ext/array/wrap"
 
 module ActiveSupport
-  module Deprecation
-    class << self
+  # Raised when <tt>ActiveSupport::Deprecation::Behavior#behavior</tt> is set with <tt>:raise</tt>.
+  # You would set <tt>:raise</tt>, as a behaviour to raise errors and proactively report exceptions from deprecations.
+  class DeprecationException < StandardError
+  end
+
+  class Deprecation
+    # Default warning behaviors per Rails.env.
+    DEFAULT_BEHAVIORS = {
+      raise: ->(message, callstack) {
+        e = DeprecationException.new(message)
+        e.set_backtrace(callstack.map(&:to_s))
+        raise e
+      },
+
+      stderr: ->(message, callstack) {
+        $stderr.puts(message)
+        $stderr.puts callstack.join("\n  ") if debug
+      },
+
+      log: ->(message, callstack) {
+        logger =
+            if defined?(Rails.logger) && 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: ->(message, callstack) {
+        ActiveSupport::Notifications.instrument("deprecation.rails",
+                                                :message => message, :callstack => callstack)
+      },
+
+      silence: ->(message, callstack) {},
+    }
+
+    # Behavior module allows to determine how to display deprecation messages.
+    # You can create a custom behavior or set any from the +DEFAULT_BEHAVIORS+
+    # constant. Available behaviors are:
+    #
+    # [+raise+]   Raise <tt>ActiveSupport::DeprecationException</tt>.
+    # [+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.
+    # For more information you can read the documentation of the +behavior=+ method.
+    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:
+      #
+      # [+raise+]   Raise <tt>ActiveSupport::DeprecationException</tt>.
+      # [+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.
       #
-      # Examples
+      # 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 = ->(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,28 +1,69 @@
-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 aaa; end
+      #     def bbb; end
+      #     def ccc; end
+      #     def ddd; end
+      #     def eee; end
+      #   end
+      #
+      # Using the default deprecator:
+      #   ActiveSupport::Deprecation.deprecate_methods(Fred, :aaa, bbb: :zzz, ccc: 'use Bar#ccc instead')
+      #   # => [:aaa, :bbb, :ccc]
+      #
+      #   Fred.aaa
+      #   # DEPRECATION WARNING: aaa is deprecated and will be removed from Rails 5.1. (called from irb_binding at (irb):10)
+      #   # => nil
+      #
+      #   Fred.bbb
+      #   # DEPRECATION WARNING: bbb is deprecated and will be removed from Rails 5.1 (use zzz instead). (called from irb_binding at (irb):11)
+      #   # => nil
+      #
+      #   Fred.ccc
+      #   # DEPRECATION WARNING: ccc is deprecated and will be removed from Rails 5.1 (use Bar#ccc instead). (called from irb_binding at (irb):12)
+      #   # => nil
+      #
+      # Passing in a custom deprecator:
+      #   custom_deprecator = ActiveSupport::Deprecation.new('next-release', 'MyGem')
+      #   ActiveSupport::Deprecation.deprecate_methods(Fred, ddd: :zzz, deprecator: custom_deprecator)
+      #   # => [:ddd]
+      #
+      #   Fred.ddd
+      #   DEPRECATION WARNING: ddd is deprecated and will be removed from MyGem next-release (use zzz instead). (called from irb_binding at (irb):15)
+      #   # => nil
+      #
+      # Using a custom deprecator directly:
+      #   custom_deprecator = ActiveSupport::Deprecation.new('next-release', 'MyGem')
+      #   custom_deprecator.deprecate_methods(Fred, eee: :zzz)
+      #   # => [:eee]
+      #
+      #   Fred.eee
+      #   DEPRECATION WARNING: eee is deprecated and will be removed from MyGem next-release (use zzz instead). (called from irb_binding at (irb):18)
+      #   # => nil
+      def deprecate_methods(target_module, *method_names)
+        options = method_names.extract_options!
+        deprecator = options.delete(:deprecator) || self
+        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)
+        mod = Module.new do
+          method_names.each do |method_name|
+            define_method(method_name) do |*args, &block|
+              deprecator.deprecation_warning(method_name, options[method_name])
+              super(*args, &block)
             end
-          end_eval
+          end
         end
+
+        target_module.prepend(mod)
       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
@@ -20,15 +20,27 @@ module ActiveSupport
 
       private
         def method_missing(called, *args, &block)
-          warn caller, called, args
+          warn caller_locations, called, args
           target.__send__(called, *args, &block)
         end
     end
 
-    class DeprecatedObjectProxy < DeprecationProxy #:nodoc:
-      def initialize(object, message)
+    # DeprecatedObjectProxy transforms an object into a deprecated one. It
+    # takes an object, a deprecation message and optionally a deprecator. The
+    # deprecator defaults to +ActiveSupport::Deprecator+ if none is specified.
+    #
+    #   deprecated_object = ActiveSupport::Deprecation::DeprecatedObjectProxy.new(Object.new, "This object is now deprecated")
+    #   # => #<Object:0x007fb9b34c34b0>
+    #
+    #   deprecated_object.to_s
+    #   DEPRECATION WARNING: This object is now deprecated.
+    #   (Backtrace)
+    #   # => "#<Object:0x007fb9b34c34b0>"
+    class DeprecatedObjectProxy < DeprecationProxy
+      def initialize(object, message, deprecator = ActiveSupport::Deprecation.instance)
         @object = object
         @message = message
+        @deprecator = deprecator
       end
 
       private
@@ -37,15 +49,48 @@ 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
+    # DeprecatedInstanceVariableProxy transforms an instance variable into a
+    # deprecated one. It takes an instance of a class, a method on that class
+    # and an instance variable. It optionally takes a deprecator as the last
+    # argument. The deprecator defaults to +ActiveSupport::Deprecator+ if none
+    # is specified.
+    #
+    #   class Example
+    #     def initialize
+    #       @request = ActiveSupport::Deprecation::DeprecatedInstanceVariableProxy.new(self, :request, :@request)
+    #       @_request = :special_request
+    #     end
+    #
+    #     def request
+    #       @_request
+    #     end
+    #
+    #     def old_request
+    #       @request
+    #     end
+    #   end
+    #
+    #   example = Example.new
+    #   # => #<Example:0x007fb9b31090b8 @_request=:special_request, @request=:special_request>
+    #
+    #   example.old_request.to_s
+    #   # => DEPRECATION WARNING: @request is deprecated! Call request.to_s instead of
+    #      @request.to_s
+    #      (Backtrace information…)
+    #      "special_request"
+    #
+    #   example.request.to_s
+    #   # => "special_request"
+    class DeprecatedInstanceVariableProxy < DeprecationProxy
+      def initialize(instance, method, var = "@#{method}", deprecator = ActiveSupport::Deprecation.instance)
+        @instance = instance
+        @method = method
+        @var = var
+        @deprecator = deprecator
       end
 
       private
@@ -54,16 +99,39 @@ 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)
+    # DeprecatedConstantProxy transforms a constant into a deprecated one. It
+    # takes the names of an old (deprecated) constant and of a new constant
+    # (both in string form) and optionally a deprecator. The deprecator defaults
+    # to +ActiveSupport::Deprecator+ if none is specified. The deprecated constant
+    # now returns the value of the new one.
+    #
+    #   PLANETS = %w(mercury venus earth mars jupiter saturn uranus neptune pluto)
+    #
+    #   (In a later update, the original implementation of `PLANETS` has been removed.)
+    #
+    #   PLANETS_POST_2006 = %w(mercury venus earth mars jupiter saturn uranus neptune)
+    #   PLANETS = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('PLANETS', 'PLANETS_POST_2006')
+    #
+    #   PLANETS.map { |planet| planet.capitalize }
+    #   # => DEPRECATION WARNING: PLANETS is deprecated! Use PLANETS_POST_2006 instead.
+    #        (Backtrace information…)
+    #        ["Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune"]
+    class DeprecatedConstantProxy < DeprecationProxy
+      def initialize(old_const, new_const, deprecator = ActiveSupport::Deprecation.instance)
         @old_const = old_const
         @new_const = new_const
+        @deprecator = deprecator
       end
 
+      # Returns the class of the new constant.
+      #
+      #   PLANETS_POST_2006 = %w(mercury venus earth mars jupiter saturn uranus neptune)
+      #   PLANETS = ActiveSupport::Deprecation::DeprecatedConstantProxy.new('PLANETS', 'PLANETS_POST_2006')
+      #   PLANETS.class # => Array
       def class
         target.class
       end
@@ -74,7 +142,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,36 @@
+require 'rbconfig'
+
 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_locations(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,19 +38,33 @@ 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_locations(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 =~ /\.$/
           "DEPRECATION WARNING: #{message} #{deprecation_caller_message(callstack)}"
         end
 
@@ -50,8 +80,19 @@ module ActiveSupport
         end
 
         def extract_callstack(callstack)
-          rails_gem_root = File.expand_path("../../../../..", __FILE__) + "/"
-          offending_line = callstack.find { |line| !line.start_with?(rails_gem_root) } || callstack.first
+          return _extract_callstack(callstack) if callstack.first.is_a? String
+
+          offending_line = callstack.find { |frame|
+            frame.absolute_path && !ignored_callstack(frame.absolute_path)
+          } || callstack.first
+
+          [offending_line.path, offending_line.lineno, offending_line.label]
+        end
+
+        def _extract_callstack(callstack)
+          warn "Please pass `caller_locations` to the deprecation API" if $VERBOSE
+          offending_line = callstack.find { |line| !ignored_callstack(line) } || callstack.first
+
           if offending_line
             if md = offending_line.match(/^(.+?):(\d+)(?::in `(.*?)')?/)
               md.captures
@@ -60,6 +101,12 @@ module ActiveSupport
             end
           end
         end
+
+        RAILS_GEM_ROOT = File.expand_path("../../../../..", __FILE__) + "/"
+
+        def ignored_callstack(path)
+          path.start_with?(RAILS_GEM_ROOT) || path.start_with?(RbConfig::CONFIG['rubylibdir'])
+        end
     end
   end
 end

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 = '3.2'
+  # \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 number in which the deprecated behavior will be removed, by default.
+    attr_accessor :deprecation_horizon
+
+    # It accepts two parameters on initialization. The first is a version of library
+    # and the second is a library name
+    #
+    #   ActiveSupport::Deprecation.new('2.0', 'MyLibrary')
+    def initialize(deprecation_horizon = '5.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

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