activesupport 3.1.0 → 5.0.0

data/lib/active_support/core_ext/module/delegation.rb

@@ -1,26 +1,44 @@
-require "active_support/core_ext/module/remove_method"
+require 'set'
 
 class Module
-  # Provides a delegate class method to easily expose contained objects' methods
-  # as your own. Pass one or more methods (specified as symbols or strings)
-  # and the name of the target object via the <tt>:to</tt> option (also a symbol
-  # or string). At least one method and the <tt>:to</tt> option are required.
+  # Error generated by +delegate+ when a method is called on +nil+ and +allow_nil+
+  # option is not used.
+  class DelegationError < NoMethodError; end
+
+  DELEGATION_RESERVED_METHOD_NAMES = Set.new(
+    %w(_ arg args alias and BEGIN begin block break case class def defined? do
+       else elsif END end ensure false for if in module next nil not or redo
+       rescue retry return self super then true undef unless until when while
+       yield)
+  ).freeze
+
+  # Provides a +delegate+ class method to easily expose contained objects'
+  # public methods as your own.
+  #
+  # ==== Options
+  # * <tt>:to</tt> - Specifies the target object
+  # * <tt>:prefix</tt> - Prefixes the new method with the target name or a custom prefix
+  # * <tt>:allow_nil</tt> - if set to true, prevents a +NoMethodError+ from being raised
+  #
+  # The macro receives one or more method names (specified as symbols or
+  # strings) and the name of the target object via the <tt>:to</tt> option
+  # (also a symbol or string).
   #
   # Delegation is particularly useful with Active Record associations:
   #
   #   class Greeter < ActiveRecord::Base
   #     def hello
-  #       "hello"
+  #       'hello'
   #     end
   #
   #     def goodbye
-  #       "goodbye"
+  #       'goodbye'
   #     end
   #   end
   #
   #   class Foo < ActiveRecord::Base
   #     belongs_to :greeter
-  #     delegate :hello, :to => :greeter
+  #     delegate :hello, to: :greeter
   #   end
   #
   #   Foo.new.hello   # => "hello"
@@ -30,7 +48,7 @@ class Module
   #
   #   class Foo < ActiveRecord::Base
   #     belongs_to :greeter
-  #     delegate :hello, :goodbye, :to => :greeter
+  #     delegate :hello, :goodbye, to: :greeter
   #   end
   #
   #   Foo.new.goodbye # => "goodbye"
@@ -45,15 +63,27 @@ class Module
   #     def initialize
   #       @instance_array = [8,9,10,11]
   #     end
-  #     delegate :sum, :to => :CONSTANT_ARRAY
-  #     delegate :min, :to => :@@class_array
-  #     delegate :max, :to => :@instance_array
+  #     delegate :sum, to: :CONSTANT_ARRAY
+  #     delegate :min, to: :@@class_array
+  #     delegate :max, to: :@instance_array
   #   end
   #
   #   Foo.new.sum # => 6
   #   Foo.new.min # => 4
   #   Foo.new.max # => 11
   #
+  # It's also possible to delegate a method to the class by using +:class+:
+  #
+  #   class Foo
+  #     def self.hello
+  #       "world"
+  #     end
+  #
+  #     delegate :hello, to: :class
+  #   end
+  #
+  #   Foo.new.hello # => "world"
+  #
   # Delegates can optionally be prefixed using the <tt>:prefix</tt> option. If the value
   # is <tt>true</tt>, the delegate methods are prefixed with the name of the object being
   # delegated to.
@@ -61,10 +91,10 @@ class Module
   #   Person = Struct.new(:name, :address)
   #
   #   class Invoice < Struct.new(:client)
-  #     delegate :name, :address, :to => :client, :prefix => true
+  #     delegate :name, :address, to: :client, prefix: true
   #   end
   #
-  #   john_doe = Person.new("John Doe", "Vimmersvej 13")
+  #   john_doe = Person.new('John Doe', 'Vimmersvej 13')
   #   invoice = Invoice.new(john_doe)
   #   invoice.client_name    # => "John Doe"
   #   invoice.client_address # => "Vimmersvej 13"
@@ -72,71 +102,114 @@ class Module
   # It is also possible to supply a custom prefix.
   #
   #   class Invoice < Struct.new(:client)
-  #     delegate :name, :address, :to => :client, :prefix => :customer
+  #     delegate :name, :address, to: :client, prefix: :customer
   #   end
   #
   #   invoice = Invoice.new(john_doe)
-  #   invoice.customer_name    # => "John Doe"
-  #   invoice.customer_address # => "Vimmersvej 13"
-  #
-  # If the delegate object is +nil+ an exception is raised, and that happens
-  # no matter whether +nil+ responds to the delegated method. You can get a
-  # +nil+ instead with the +:allow_nil+ option.
-  #
-  #  class Foo
-  #    attr_accessor :bar
-  #    def initialize(bar = nil)
-  #      @bar = bar
-  #    end
-  #    delegate :zoo, :to => :bar
-  #  end
-  #
-  #  Foo.new.zoo   # raises NoMethodError exception (you called nil.zoo)
-  #
-  #  class Foo
-  #    attr_accessor :bar
-  #    def initialize(bar = nil)
-  #      @bar = bar
-  #    end
-  #    delegate :zoo, :to => :bar, :allow_nil => true
-  #  end
-  #
-  #  Foo.new.zoo   # returns nil
-  #
-  def delegate(*methods)
-    options = methods.pop
-    unless options.is_a?(Hash) && to = options[:to]
-      raise ArgumentError, "Delegation needs a target. Supply an options hash with a :to key as the last argument (e.g. delegate :hello, :to => :greeter)."
+  #   invoice.customer_name    # => 'John Doe'
+  #   invoice.customer_address # => 'Vimmersvej 13'
+  #
+  # If the target is +nil+ and does not respond to the delegated method a
+  # +NoMethodError+ is raised, as with any other value. Sometimes, however, it
+  # makes sense to be robust to that situation and that is the purpose of the
+  # <tt>:allow_nil</tt> option: If the target is not +nil+, or it is and
+  # responds to the method, everything works as usual. But if it is +nil+ and
+  # does not respond to the delegated method, +nil+ is returned.
+  #
+  #   class User < ActiveRecord::Base
+  #     has_one :profile
+  #     delegate :age, to: :profile
+  #   end
+  #
+  #   User.new.age # raises NoMethodError: undefined method `age'
+  #
+  # But if not having a profile yet is fine and should not be an error
+  # condition:
+  #
+  #   class User < ActiveRecord::Base
+  #     has_one :profile
+  #     delegate :age, to: :profile, allow_nil: true
+  #   end
+  #
+  #   User.new.age # nil
+  #
+  # Note that if the target is not +nil+ then the call is attempted regardless of the
+  # <tt>:allow_nil</tt> option, and thus an exception is still raised if said object
+  # does not respond to the method:
+  #
+  #   class Foo
+  #     def initialize(bar)
+  #       @bar = bar
+  #     end
+  #
+  #     delegate :name, to: :@bar, allow_nil: true
+  #   end
+  #
+  #   Foo.new("Bar").name # raises NoMethodError: undefined method `name'
+  #
+  # The target method must be public, otherwise it will raise +NoMethodError+.
+  #
+  def delegate(*methods, to: nil, prefix: nil, allow_nil: nil)
+    unless to
+      raise ArgumentError, 'Delegation needs a target. Supply an options hash with a :to key as the last argument (e.g. delegate :hello, to: :greeter).'
     end
 
-    if options[:prefix] == true && options[:to].to_s =~ /^[^a-z_]/
-      raise ArgumentError, "Can only automatically set the delegation prefix when delegating to a method."
+    if prefix == true && to =~ /^[^a-z_]/
+      raise ArgumentError, 'Can only automatically set the delegation prefix when delegating to a method.'
     end
 
-    prefix = options[:prefix] && "#{options[:prefix] == true ? to : options[:prefix]}_" || ''
+    method_prefix = \
+      if prefix
+        "#{prefix == true ? to : prefix}_"
+      else
+        ''
+      end
 
-    file, line = caller.first.split(':', 2)
-    line = line.to_i
+    location = caller_locations(1, 1).first
+    file, line = location.path, location.lineno
+
+    to = to.to_s
+    to = "self.#{to}" if DELEGATION_RESERVED_METHOD_NAMES.include?(to)
 
     methods.each do |method|
-      on_nil =
-        if options[:allow_nil]
-          'return'
-        else
-          %(raise "#{self}##{prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
-        end
+      # Attribute writer methods only accept one argument. Makes sure []=
+      # methods still accept two arguments.
+      definition = (method =~ /[^\]]=$/) ? 'arg' : '*args, &block'
+
+      # The following generated method calls the target exactly once, storing
+      # the returned value in a dummy variable.
+      #
+      # Reason is twofold: On one hand doing less calls is in general better.
+      # On the other hand it could be that the target has side-effects,
+      # whereas conceptually, from the user point of view, the delegator should
+      # be doing one call.
+      if allow_nil
+        method_def = [
+          "def #{method_prefix}#{method}(#{definition})",
+          "_ = #{to}",
+          "if !_.nil? || nil.respond_to?(:#{method})",
+          "  _.#{method}(#{definition})",
+          "end",
+        "end"
+        ].join ';'
+      else
+        exception = %(raise DelegationError, "#{self}##{method_prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
+
+        method_def = [
+          "def #{method_prefix}#{method}(#{definition})",
+          " _ = #{to}",
+          "  _.#{method}(#{definition})",
+          "rescue NoMethodError => e",
+          "  if _.nil? && e.name == :#{method}",
+          "    #{exception}",
+          "  else",
+          "    raise",
+          "  end",
+          "end"
+        ].join ';'
+      end
 
-      module_eval(<<-EOS, file, line - 1)
-        def #{prefix}#{method}(*args, &block)               # def customer_name(*args, &block)
-          #{to}.__send__(#{method.inspect}, *args, &block)  #   client.__send__(:name, *args, &block)
-        rescue NoMethodError                                # rescue NoMethodError
-          if #{to}.nil?                                     #   if client.nil?
-            #{on_nil}                                       #     return # depends on :allow_nil
-          else                                              #   else
-            raise                                           #     raise
-          end                                               #   end
-        end                                                 # end
-      EOS
+      module_eval(method_def, file, line)
     end
   end
 end

data/lib/active_support/core_ext/module/deprecation.rb

@@ -1,8 +1,22 @@
 class Module
-  # Declare that a method has been deprecated.
   #   deprecate :foo
-  #   deprecate :bar => 'message'
-  #   deprecate :foo, :bar, :baz => 'warning!', :qux => 'gone!'
+  #   deprecate bar: 'message'
+  #   deprecate :foo, :bar, baz: 'warning!', qux: 'gone!'
+  #
+  # You can also use custom deprecator instance:
+  #
+  #   deprecate :foo, deprecator: MyLib::Deprecator.new
+  #   deprecate :foo, bar: "warning!", deprecator: MyLib::Deprecator.new
+  #
+  # \Custom deprecators must respond to <tt>deprecation_warning(deprecated_method_name, message, caller_backtrace)</tt>
+  # method where you can implement your custom warning behavior.
+  #
+  #   class MyLib::Deprecator
+  #     def deprecation_warning(deprecated_method_name, message, caller_backtrace = nil)
+  #       message = "#{deprecated_method_name} is deprecated and will be removed from MyLibrary | #{message}"
+  #       Kernel.warn message
+  #     end
+  #   end
   def deprecate(*method_names)
     ActiveSupport::Deprecation.deprecate_methods(self, *method_names)
   end

data/lib/active_support/core_ext/module/introspection.rb

@@ -5,10 +5,11 @@ class Module
   #
   #   M::N.parent_name # => "M"
   def parent_name
-    unless defined? @parent_name
+    if defined? @parent_name
+      @parent_name
+    else
       @parent_name = name =~ /::[^:]+\Z/ ? $`.freeze : nil
     end
-    @parent_name
   end
 
   # Returns the module which contains this one according to its name.
@@ -26,7 +27,6 @@ class Module
   #
   #   M.parent          # => Object
   #   Module.new.parent # => Object
-  #
   def parent
     parent_name ? ActiveSupport::Inflector.constantize(parent_name) : Object
   end
@@ -43,7 +43,6 @@ class Module
   #   M.parents    # => [Object]
   #   M::N.parents # => [M, Object]
   #   X.parents    # => [M, Object]
-  #
   def parents
     parents = []
     if parent_name
@@ -57,32 +56,11 @@ class Module
     parents
   end
 
-  if RUBY_VERSION < '1.9'
-    # Returns the constants that have been defined locally by this object and
-    # not in an ancestor. This method is exact if running under Ruby 1.9. In
-    # previous versions it may miss some constants if their definition in some
-    # ancestor is identical to their definition in the receiver.
-    def local_constants
-      inherited = {}
-
-      ancestors.each do |anc|
-        next if anc == self
-        anc.constants.each { |const| inherited[const] = anc.const_get(const) }
-      end
-
-      constants.select do |const|
-        !inherited.key?(const) || inherited[const].object_id != const_get(const).object_id
-      end
-    end
-  else
-    def local_constants #:nodoc:
-      constants(false)
-    end
-  end
-
-  # Returns the names of the constants defined locally rather than the
-  # constants themselves. See <tt>local_constants</tt>.
-  def local_constant_names
-    local_constants.map { |c| c.to_s }
+  def local_constants #:nodoc:
+    ActiveSupport::Deprecation.warn(<<-MSG.squish)
+      Module#local_constants is deprecated and will be removed in Rails 5.1.
+      Use Module#constants(false) instead.
+    MSG
+    constants(false)
   end
 end

data/lib/active_support/core_ext/module/method_transplanting.rb

@@ -0,0 +1,3 @@
+require 'active_support/deprecation'
+
+ActiveSupport::Deprecation.warn("This file is deprecated and will be removed in Rails 5.1 with no replacement.")

data/lib/active_support/core_ext/module/qualified_const.rb

@@ -0,0 +1,70 @@
+require 'active_support/core_ext/string/inflections'
+
+#--
+# Allows code reuse in the methods below without polluting Module.
+#++
+
+module ActiveSupport
+  module QualifiedConstUtils
+    def self.raise_if_absolute(path)
+      raise NameError.new("wrong constant name #$&") if path =~ /\A::[^:]+/
+    end
+
+    def self.names(path)
+      path.split('::')
+    end
+  end
+end
+
+##
+# Extends the API for constants to be able to deal with qualified names. Arguments
+# are assumed to be relative to the receiver.
+#
+#--
+# Qualified names are required to be relative because we are extending existing
+# methods that expect constant names, ie, relative paths of length 1. For example,
+# Object.const_get('::String') raises NameError and so does qualified_const_get.
+#++
+class Module
+  def qualified_const_defined?(path, search_parents=true)
+    ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+      Module#qualified_const_defined? is deprecated in favour of the builtin
+      Module#const_defined? and will be removed in Rails 5.1.
+    MESSAGE
+
+    ActiveSupport::QualifiedConstUtils.raise_if_absolute(path)
+
+    ActiveSupport::QualifiedConstUtils.names(path).inject(self) do |mod, name|
+      return unless mod.const_defined?(name, search_parents)
+      mod.const_get(name)
+    end
+    return true
+  end
+
+  def qualified_const_get(path)
+    ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+      Module#qualified_const_get is deprecated in favour of the builtin
+      Module#const_get and will be removed in Rails 5.1.
+    MESSAGE
+
+    ActiveSupport::QualifiedConstUtils.raise_if_absolute(path)
+
+    ActiveSupport::QualifiedConstUtils.names(path).inject(self) do |mod, name|
+      mod.const_get(name)
+    end
+  end
+
+  def qualified_const_set(path, value)
+    ActiveSupport::Deprecation.warn(<<-MESSAGE.squish)
+      Module#qualified_const_set is deprecated in favour of the builtin
+      Module#const_set and will be removed in Rails 5.1.
+    MESSAGE
+
+    ActiveSupport::QualifiedConstUtils.raise_if_absolute(path)
+
+    const_name = path.demodulize
+    mod_name = path.deconstantize
+    mod = mod_name.empty? ? self : const_get(mod_name)
+    mod.const_set(const_name, value)
+  end
+end

data/lib/active_support/core_ext/module/reachable.rb

@@ -3,8 +3,6 @@ require 'active_support/core_ext/string/inflections'
 
 class Module
   def reachable? #:nodoc:
-    !anonymous? && name.constantize.equal?(self)
-  rescue NameError
-    false
+    !anonymous? && name.safe_constantize.equal?(self)
   end
 end

data/lib/active_support/core_ext/module/remove_method.rb

@@ -1,16 +1,35 @@
 class Module
+  # Removes the named method, if it exists.
   def remove_possible_method(method)
     if method_defined?(method) || private_method_defined?(method)
-      remove_method(method)
+      undef_method(method)
     end
-  rescue NameError
-    # If the requested method is defined on a superclass or included module,
-    # method_defined? returns true but remove_method throws a NameError.
-    # Ignore this.
   end
 
+  # Removes the named singleton method, if it exists.
+  def remove_possible_singleton_method(method)
+    singleton_class.instance_eval do
+      remove_possible_method(method)
+    end
+  end
+
+  # Replaces the existing method definition, if there is one, with the passed
+  # block as its body.
   def redefine_method(method, &block)
+    visibility = method_visibility(method)
     remove_possible_method(method)
     define_method(method, &block)
+    send(visibility, method)
+  end
+
+  def method_visibility(method) # :nodoc:
+    case
+    when private_method_defined?(method)
+      :private
+    when protected_method_defined?(method)
+      :protected
+    else
+      :public
+    end
   end
 end

data/lib/active_support/core_ext/module.rb

@@ -3,10 +3,10 @@ require 'active_support/core_ext/module/introspection'
 require 'active_support/core_ext/module/anonymous'
 require 'active_support/core_ext/module/reachable'
 require 'active_support/core_ext/module/attribute_accessors'
+require 'active_support/core_ext/module/attribute_accessors_per_thread'
 require 'active_support/core_ext/module/attr_internal'
-require 'active_support/core_ext/module/attr_accessor_with_default'
+require 'active_support/core_ext/module/concerning'
 require 'active_support/core_ext/module/delegation'
-require 'active_support/core_ext/module/synchronization'
 require 'active_support/core_ext/module/deprecation'
 require 'active_support/core_ext/module/remove_method'
-require 'active_support/core_ext/module/method_names'
+require 'active_support/core_ext/module/qualified_const'

data/lib/active_support/core_ext/name_error.rb

@@ -1,5 +1,12 @@
 class NameError
   # Extract the name of the missing constant from the exception message.
+  #
+  #   begin
+  #     HelloWorld
+  #   rescue NameError => e
+  #     e.missing_name
+  #   end
+  #   # => "HelloWorld"
   def missing_name
     if /undefined local variable or method/ !~ message
       $1 if /((::)?([A-Z]\w*)(::[A-Z]\w*)*)$/ =~ message
@@ -7,10 +14,16 @@ class NameError
   end
 
   # Was this exception raised because the given name was missing?
+  #
+  #   begin
+  #     HelloWorld
+  #   rescue NameError => e
+  #     e.missing_name?("HelloWorld")
+  #   end
+  #   # => true
   def missing_name?(name)
     if name.is_a? Symbol
-      last_name = (missing_name || '').split('::').last
-      last_name == name.to_s
+      self.name == name
     else
       missing_name == name.to_s
     end

data/lib/active_support/core_ext/numeric/bytes.rb

@@ -7,36 +7,56 @@ class Numeric
   EXABYTE  = PETABYTE * 1024
 
   # Enables the use of byte calculations and declarations, like 45.bytes + 2.6.megabytes
+  #
+  #   2.bytes # => 2
   def bytes
     self
   end
   alias :byte :bytes
 
+  # Returns the number of bytes equivalent to the kilobytes provided.
+  #
+  #   2.kilobytes # => 2048
   def kilobytes
     self * KILOBYTE
   end
   alias :kilobyte :kilobytes
 
+  # Returns the number of bytes equivalent to the megabytes provided.
+  #
+  #   2.megabytes # => 2_097_152
   def megabytes
     self * MEGABYTE
   end
   alias :megabyte :megabytes
 
+  # Returns the number of bytes equivalent to the gigabytes provided.
+  #
+  #   2.gigabytes # => 2_147_483_648
   def gigabytes
     self * GIGABYTE
   end
   alias :gigabyte :gigabytes
 
+  # Returns the number of bytes equivalent to the terabytes provided.
+  #
+  #   2.terabytes # => 2_199_023_255_552
   def terabytes
     self * TERABYTE
   end
   alias :terabyte :terabytes
 
+  # Returns the number of bytes equivalent to the petabytes provided.
+  #
+  #   2.petabytes # => 2_251_799_813_685_248
   def petabytes
     self * PETABYTE
   end
   alias :petabyte :petabytes
 
+  # Returns the number of bytes equivalent to the exabytes provided.
+  #
+  #   2.exabytes # => 2_305_843_009_213_693_952
   def exabytes
     self * EXABYTE
   end