omg-activesupport 8.0.0.alpha1

data/lib/active_support/dependencies.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "set"
+require "active_support/dependencies/interlock"
+
+module ActiveSupport # :nodoc:
+  module Dependencies # :nodoc:
+    require_relative "dependencies/require_dependency"
+
+    singleton_class.attr_accessor :interlock
+    @interlock = Interlock.new
+
+    # :doc:
+
+    # Execute the supplied block without interference from any
+    # concurrent loads.
+    def self.run_interlock(&block)
+      interlock.running(&block)
+    end
+
+    # Execute the supplied block while holding an exclusive lock,
+    # preventing any other thread from being inside a #run_interlock
+    # block at the same time.
+    def self.load_interlock(&block)
+      interlock.loading(&block)
+    end
+
+    # Execute the supplied block while holding an exclusive lock,
+    # preventing any other thread from being inside a #run_interlock
+    # block at the same time.
+    def self.unload_interlock(&block)
+      interlock.unloading(&block)
+    end
+
+    # :nodoc:
+
+    # The array of directories from which we autoload and reload, if reloading
+    # is enabled. The public interface to push directories to this collection
+    # from applications or engines is config.autoload_paths.
+    #
+    # This collection is allowed to have intersection with autoload_once_paths.
+    # Common directories are not reloaded.
+    singleton_class.attr_accessor :autoload_paths
+    self.autoload_paths = []
+
+    # The array of directories from which we autoload and never reload, even if
+    # reloading is enabled. The public interface to push directories to this
+    # collection from applications or engines is config.autoload_once_paths.
+    singleton_class.attr_accessor :autoload_once_paths
+    self.autoload_once_paths = []
+
+    # This is a private set that collects all eager load paths during bootstrap.
+    # Useful for Zeitwerk integration. The public interface to push custom
+    # directories to this collection from applications or engines is
+    # config.eager_load_paths.
+    singleton_class.attr_accessor :_eager_load_paths
+    self._eager_load_paths = Set.new
+
+    # If reloading is enabled, this private set holds autoloaded classes tracked
+    # by the descendants tracker. It is populated by an on_load callback in the
+    # main autoloader. Used to clear state.
+    singleton_class.attr_accessor :_autoloaded_tracked_classes
+    self._autoloaded_tracked_classes = Set.new
+
+    # If reloading is enabled, this private attribute stores the main autoloader
+    # of a Rails application. It is `nil` otherwise.
+    #
+    # The public interface for this autoloader is `Rails.autoloaders.main`.
+    singleton_class.attr_accessor :autoloader
+
+    # Private method that reloads constants autoloaded by the main autoloader.
+    #
+    # Rails.application.reloader.reload! is the public interface for application
+    # reload. That involves more things, like deleting unloaded classes from the
+    # internal state of the descendants tracker, or reloading routes.
+    def self.clear
+      unload_interlock do
+        _autoloaded_tracked_classes.clear
+        autoloader.reload
+      end
+    end
+
+    # Private method used by require_dependency.
+    def self.search_for_file(relpath)
+      relpath += ".rb" unless relpath.end_with?(".rb")
+      autoload_paths.each do |autoload_path|
+        abspath = File.join(autoload_path, relpath)
+        return abspath if File.file?(abspath)
+      end
+      nil
+    end
+
+    # Private method that helps configuring the autoloaders.
+    def self.eager_load?(path)
+      _eager_load_paths.member?(path)
+    end
+  end
+end

data/lib/active_support/deprecation/behaviors.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module ActiveSupport
+  # Raised when ActiveSupport::Deprecation::Behavior#behavior is set with <tt>:raise</tt>.
+  # You would set <tt>:raise</tt>, as a behavior 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, deprecator) do
+        e = DeprecationException.new(message)
+        e.set_backtrace(callstack.map(&:to_s))
+        raise e
+      end,
+
+      stderr: ->(message, callstack, deprecator) do
+        $stderr.puts(message)
+        $stderr.puts callstack.join("\n  ") if deprecator.debug
+      end,
+
+      log: ->(message, callstack, deprecator) do
+        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 deprecator.debug
+      end,
+
+      notify: ->(message, callstack, deprecator) do
+        ActiveSupport::Notifications.instrument(
+          "deprecation.#{deprecator.gem_name.underscore.tr("/", "_")}",
+          message: message,
+          callstack: callstack,
+          gem_name: deprecator.gem_name,
+          deprecation_horizon: deprecator.deprecation_horizon,
+        )
+      end,
+
+      silence: ->(message, callstack, deprecator) { },
+
+      report: ->(message, callstack, deprecator) do
+        error = DeprecationException.new(message)
+        error.set_backtrace(callstack.map(&:to_s))
+        ActiveSupport.error_reporter.report(error)
+      end
+    }
+
+    # 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 ActiveSupport::DeprecationException.
+    # [+:stderr+]  Log all deprecation warnings to <tt>$stderr</tt>.
+    # [+:log+]     Log all deprecation warnings to +Rails.logger+.
+    # [+:notify+]  Use ActiveSupport::Notifications to notify +deprecation.rails+.
+    # [+:report+]  Use ActiveSupport::ErrorReporter to report deprecations.
+    # [+:silence+] Do nothing. On \Rails, set <tt>config.active_support.report_deprecations = false</tt> to disable all behaviors.
+    #
+    # 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 current behavior or if one isn't set, defaults to +:stderr+.
+      def behavior
+        @behavior ||= [DEFAULT_BEHAVIORS[:stderr]]
+      end
+
+      # Returns the current behavior for disallowed deprecations or if one isn't set, defaults to +:raise+.
+      def disallowed_behavior
+        @disallowed_behavior ||= [DEFAULT_BEHAVIORS[:raise]]
+      end
+
+      # Sets the behavior to the specified value. Can be a single value, array,
+      # or an object that responds to +call+.
+      #
+      # Available behaviors:
+      #
+      # [+:raise+]   Raise ActiveSupport::DeprecationException.
+      # [+:stderr+]  Log all deprecation warnings to <tt>$stderr</tt>.
+      # [+:log+]     Log all deprecation warnings to +Rails.logger+.
+      # [+:notify+]  Use ActiveSupport::Notifications to notify +deprecation.rails+.
+      # [+:report+]  Use ActiveSupport::ErrorReporter to report deprecations.
+      # [+: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.
+      #
+      #   deprecator = ActiveSupport::Deprecation.new
+      #   deprecator.behavior = :stderr
+      #   deprecator.behavior = [:stderr, :log]
+      #   deprecator.behavior = MyCustomHandler
+      #   deprecator.behavior = ->(message, callstack, deprecation_horizon, gem_name) {
+      #     # custom stuff
+      #   }
+      #
+      # If you are using \Rails, you can set
+      # <tt>config.active_support.report_deprecations = false</tt> to disable
+      # all deprecation behaviors. This is similar to the +:silence+ option but
+      # more performant.
+      def behavior=(behavior)
+        @behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) }
+      end
+
+      # Sets the behavior for disallowed deprecations (those configured by
+      # ActiveSupport::Deprecation#disallowed_warnings=) to the specified
+      # value. As with #behavior=, this can be a single value, array, or an
+      # object that responds to +call+.
+      def disallowed_behavior=(behavior)
+        @disallowed_behavior = Array(behavior).map { |b| DEFAULT_BEHAVIORS[b] || arity_coerce(b) }
+      end
+
+      private
+        def arity_coerce(behavior)
+          unless behavior.respond_to?(:call)
+            raise ArgumentError, "#{behavior.inspect} is not a valid deprecation behavior."
+          end
+
+          case arity_of_callable(behavior)
+          when 2
+            ->(message, callstack, deprecator) do
+              behavior.call(message, callstack)
+            end
+          when -2..3
+            behavior
+          else
+            ->(message, callstack, deprecator) do
+              behavior.call(message, callstack, deprecator.deprecation_horizon, deprecator.gem_name)
+            end
+          end
+        end
+
+        def arity_of_callable(callable)
+          callable.respond_to?(:arity) ? callable.arity : callable.method(:call).arity
+        end
+    end
+  end
+end

data/lib/active_support/deprecation/constant_accessor.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  class Deprecation
+    module DeprecatedConstantAccessor
+      def self.included(base)
+        require "active_support/inflector/methods"
+
+        extension = Module.new do
+          def const_missing(missing_const_name)
+            if class_variable_defined?(:@@_deprecated_constants)
+              if (replacement = class_variable_get(:@@_deprecated_constants)[missing_const_name.to_s])
+                replacement[:deprecator].warn(replacement[:message] || "#{name}::#{missing_const_name} is deprecated! Use #{replacement[:new]} instead.", caller_locations)
+                return ActiveSupport::Inflector.constantize(replacement[:new].to_s)
+              end
+            end
+            super
+          end
+
+          # Provides a way to rename constants with a deprecation cycle in which
+          # both the old and new names work, but using the old one prints a
+          # deprecation message.
+          #
+          # In order to rename <tt>A::B</tt> to <tt>C::D</tt>, you need to delete the
+          # definition of <tt>A::B</tt> and declare the deprecation in +A+:
+          #
+          #   require "active_support/deprecation"
+          #
+          #   module A
+          #     include ActiveSupport::Deprecation::DeprecatedConstantAccessor
+          #
+          #     deprecate_constant "B", "C::D", deprecator: ActiveSupport::Deprecation.new
+          #   end
+          #
+          # The first argument is a constant name (no colons). It is the name of
+          # the constant you want to deprecate in the enclosing class or module.
+          #
+          # The second argument is the constant path of the replacement. That
+          # has to be a full path even if the replacement is defined in the same
+          # namespace as the deprecated one was.
+          #
+          # In both cases, strings and symbols are supported.
+          #
+          # The +deprecator+ keyword argument is the object that will print the
+          # deprecation message, an instance of ActiveSupport::Deprecation.
+          #
+          # With that in place, references to <tt>A::B</tt> still work, they
+          # evaluate to <tt>C::D</tt> now, and trigger a deprecation warning:
+          #
+          #   DEPRECATION WARNING: A::B is deprecated! Use C::D instead.
+          #   (called from ...)
+          #
+          # The message can be customized with the optional +message+ keyword
+          # argument.
+          #
+          # For this to work, a +const_missing+ hook is installed. When client
+          # code references the deprecated constant, the callback prints the
+          # message and constantizes the replacement.
+          #
+          # Caveat: If the deprecated constant name is reachable in a different
+          # namespace and Ruby constant lookup finds it, the hook won't be
+          # called and the deprecation won't work as intended. This may happen,
+          # for example, if an ancestor of the enclosing namespace has a
+          # constant with the same name. This is an unsupported edge case.
+          def deprecate_constant(old_constant_name, new_constant_path, deprecator:, message: nil)
+            class_variable_set(:@@_deprecated_constants, {}) unless class_variable_defined?(:@@_deprecated_constants)
+            class_variable_get(:@@_deprecated_constants)[old_constant_name.to_s] = { new: new_constant_path, message: message, deprecator: deprecator }
+          end
+        end
+        base.singleton_class.prepend extension
+      end
+    end
+  end
+end

data/lib/active_support/deprecation/deprecators.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  class Deprecation
+    # A managed collection of deprecators. Configuration methods, such as
+    # #behavior=, affect all deprecators in the collection. Additionally, the
+    # #silence method silences all deprecators in the collection for the
+    # duration of a given block.
+    class Deprecators
+      def initialize
+        @options = {}
+        @deprecators = {}
+      end
+
+      # Returns a deprecator added to this collection via #[]=.
+      def [](name)
+        @deprecators[name]
+      end
+
+      # Adds a given +deprecator+ to this collection. The deprecator will be
+      # immediately configured with any options previously set on this
+      # collection.
+      #
+      #   deprecators = ActiveSupport::Deprecation::Deprecators.new
+      #   deprecators.debug = true
+      #
+      #   foo_deprecator = ActiveSupport::Deprecation.new("2.0", "Foo")
+      #   foo_deprecator.debug    # => false
+      #
+      #   deprecators[:foo] = foo_deprecator
+      #   deprecators[:foo].debug # => true
+      #   foo_deprecator.debug    # => true
+      #
+      def []=(name, deprecator)
+        apply_options(deprecator)
+        @deprecators[name] = deprecator
+      end
+
+      # Iterates over all deprecators in this collection. If no block is given,
+      # returns an +Enumerator+.
+      def each(&block)
+        return to_enum(__method__) unless block
+        @deprecators.each_value(&block)
+      end
+
+      # Sets the silenced flag for all deprecators in this collection.
+      def silenced=(silenced)
+        set_option(:silenced, silenced)
+      end
+
+      # Sets the debug flag for all deprecators in this collection.
+      def debug=(debug)
+        set_option(:debug, debug)
+      end
+
+      # Sets the deprecation warning behavior for all deprecators in this
+      # collection.
+      #
+      # See ActiveSupport::Deprecation#behavior=.
+      def behavior=(behavior)
+        set_option(:behavior, behavior)
+      end
+
+      # Sets the disallowed deprecation warning behavior for all deprecators in
+      # this collection.
+      #
+      # See ActiveSupport::Deprecation#disallowed_behavior=.
+      def disallowed_behavior=(disallowed_behavior)
+        set_option(:disallowed_behavior, disallowed_behavior)
+      end
+
+      # Sets the disallowed deprecation warnings for all deprecators in this
+      # collection.
+      #
+      # See ActiveSupport::Deprecation#disallowed_warnings=.
+      def disallowed_warnings=(disallowed_warnings)
+        set_option(:disallowed_warnings, disallowed_warnings)
+      end
+
+      # Silences all deprecators in this collection for the duration of the
+      # given block.
+      #
+      # See ActiveSupport::Deprecation#silence.
+      def silence(&block)
+        each { |deprecator| deprecator.begin_silence }
+        block.call
+      ensure
+        each { |deprecator| deprecator.end_silence }
+      end
+
+      private
+        def set_option(name, value)
+          @options[name] = value
+          each { |deprecator| deprecator.public_send("#{name}=", value) }
+        end
+
+        def apply_options(deprecator)
+          @options.each do |name, value|
+            deprecator.public_send("#{name}=", value)
+          end
+        end
+    end
+  end
+end

data/lib/active_support/deprecation/disallowed.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ActiveSupport
+  class Deprecation
+    module Disallowed
+      # Sets the criteria used to identify deprecation messages which should be
+      # disallowed. Can be an array containing strings, symbols, or regular
+      # expressions. (Symbols are treated as strings.) These are compared against
+      # the text of the generated deprecation warning.
+      #
+      # Additionally the scalar symbol +:all+ may be used to treat all
+      # deprecations as disallowed.
+      #
+      # Deprecations matching a substring or regular expression will be handled
+      # using the configured Behavior#disallowed_behavior rather than
+      # Behavior#behavior.
+      attr_writer :disallowed_warnings
+
+      # Returns the configured criteria used to identify deprecation messages
+      # which should be treated as disallowed.
+      def disallowed_warnings
+        @disallowed_warnings ||= []
+      end
+
+      private
+        def deprecation_disallowed?(message)
+          return false if explicitly_allowed?(message)
+          return true if disallowed_warnings == :all
+          message && disallowed_warnings.any? do |rule|
+            case rule
+            when String, Symbol
+              message.include?(rule.to_s)
+            when Regexp
+              rule.match?(message)
+            end
+          end
+        end
+
+        def explicitly_allowed?(message)
+          allowances = @explicitly_allowed_warnings.value
+          return false unless allowances
+          return true if allowances == :all
+          message && Array(allowances).any? do |rule|
+            case rule
+            when String, Symbol
+              message.include?(rule.to_s)
+            when Regexp
+              rule.match?(message)
+            end
+          end
+        end
+    end
+  end
+end

data/lib/active_support/deprecation/method_wrappers.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/array/extract_options"
+require "active_support/core_ext/module/redefine_method"
+
+module ActiveSupport
+  class Deprecation
+    module MethodWrapper
+      # Declare that a method has been deprecated.
+      #
+      #   class Fred
+      #     def aaa; end
+      #     def bbb; end
+      #     def ccc; end
+      #     def ddd; end
+      #     def eee; end
+      #   end
+      #
+      #   deprecator = ActiveSupport::Deprecation.new('next-release', 'MyGem')
+      #
+      #   deprecator.deprecate_methods(Fred, :aaa, bbb: :zzz, ccc: 'use Bar#ccc instead')
+      #   # => Fred
+      #
+      #   Fred.new.aaa
+      #   # DEPRECATION WARNING: aaa is deprecated and will be removed from MyGem next-release. (called from irb_binding at (irb):10)
+      #   # => nil
+      #
+      #   Fred.new.bbb
+      #   # DEPRECATION WARNING: bbb is deprecated and will be removed from MyGem next-release (use zzz instead). (called from irb_binding at (irb):11)
+      #   # => nil
+      #
+      #   Fred.new.ccc
+      #   # DEPRECATION WARNING: ccc is deprecated and will be removed from MyGem next-release (use Bar#ccc instead). (called from irb_binding at (irb):12)
+      #   # => nil
+      def deprecate_methods(target_module, *method_names)
+        options = method_names.extract_options!
+        deprecator = options.delete(:deprecator) || self
+        method_names += options.keys
+        mod = nil
+
+        method_names.each do |method_name|
+          message = options[method_name]
+          if target_module.method_defined?(method_name) || target_module.private_method_defined?(method_name)
+            method = target_module.instance_method(method_name)
+            target_module.module_eval do
+              redefine_method(method_name) do |*args, &block|
+                deprecator.deprecation_warning(method_name, message)
+                method.bind_call(self, *args, &block)
+              end
+              ruby2_keywords(method_name)
+            end
+          else
+            mod ||= Module.new
+            mod.module_eval do
+              define_method(method_name) do |*args, &block|
+                deprecator.deprecation_warning(method_name, message)
+                super(*args, &block)
+              end
+              ruby2_keywords(method_name)
+            end
+          end
+        end
+
+        target_module.prepend(mod) if mod
+      end
+    end
+  end
+end