activesupport 4.0.13 → 4.2.11.3

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

@@ -0,0 +1,135 @@
+require 'active_support/concern'
+
+class Module
+  # = Bite-sized separation of concerns
+  #
+  # We often find ourselves with a medium-sized chunk of behavior that we'd
+  # like to extract, but only mix in to a single class.
+  #
+  # Extracting a plain old Ruby object to encapsulate it and collaborate or
+  # delegate to the original object is often a good choice, but when there's
+  # no additional state to encapsulate or we're making DSL-style declarations
+  # about the parent class, introducing new collaborators can obfuscate rather
+  # than simplify.
+  #
+  # The typical route is to just dump everything in a monolithic class, perhaps
+  # with a comment, as a least-bad alternative. Using modules in separate files
+  # means tedious sifting to get a big-picture view.
+  #
+  # = Dissatisfying ways to separate small concerns
+  #
+  # == Using comments:
+  #
+  #   class Todo
+  #     # Other todo implementation
+  #     # ...
+  #
+  #     ## Event tracking
+  #     has_many :events
+  #
+  #     before_create :track_creation
+  #     after_destroy :track_deletion
+  #
+  #     private
+  #       def track_creation
+  #         # ...
+  #       end
+  #   end
+  #
+  # == With an inline module:
+  #
+  # Noisy syntax.
+  #
+  #   class Todo
+  #     # Other todo implementation
+  #     # ...
+  #
+  #     module EventTracking
+  #       extend ActiveSupport::Concern
+  #
+  #       included do
+  #         has_many :events
+  #         before_create :track_creation
+  #         after_destroy :track_deletion
+  #       end
+  #
+  #       private
+  #         def track_creation
+  #           # ...
+  #         end
+  #     end
+  #     include EventTracking
+  #   end
+  #
+  # == Mix-in noise exiled to its own file:
+  #
+  # Once our chunk of behavior starts pushing the scroll-to-understand it's
+  # boundary, we give in and move it to a separate file. At this size, the
+  # overhead feels in good proportion to the size of our extraction, despite
+  # diluting our at-a-glance sense of how things really work.
+  #
+  #   class Todo
+  #     # Other todo implementation
+  #     # ...
+  #
+  #     include TodoEventTracking
+  #   end
+  #
+  # = Introducing Module#concerning
+  #
+  # By quieting the mix-in noise, we arrive at a natural, low-ceremony way to
+  # separate bite-sized concerns.
+  #
+  #   class Todo
+  #     # Other todo implementation
+  #     # ...
+  #
+  #     concerning :EventTracking do
+  #       included do
+  #         has_many :events
+  #         before_create :track_creation
+  #         after_destroy :track_deletion
+  #       end
+  #
+  #       private
+  #         def track_creation
+  #           # ...
+  #         end
+  #     end
+  #   end
+  #
+  #   Todo.ancestors
+  #   # => Todo, Todo::EventTracking, Object
+  #
+  # This small step has some wonderful ripple effects. We can
+  # * grok the behavior of our class in one glance,
+  # * clean up monolithic junk-drawer classes by separating their concerns, and
+  # * stop leaning on protected/private for crude "this is internal stuff" modularity.
+  module Concerning
+    # Define a new concern and mix it in.
+    def concerning(topic, &block)
+      include concern(topic, &block)
+    end
+
+    # A low-cruft shortcut to define a concern.
+    #
+    #   concern :EventTracking do
+    #     ...
+    #   end
+    #
+    # is equivalent to
+    #
+    #   module EventTracking
+    #     extend ActiveSupport::Concern
+    #
+    #     ...
+    #   end
+    def concern(topic, &module_definition)
+      const_set topic, Module.new {
+        extend ::ActiveSupport::Concern
+        module_eval(&module_definition)
+      }
+    end
+  end
+  include Concerning
+end

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

@@ -1,7 +1,32 @@
+require 'set'
+
 class Module
+  # Error generated by +delegate+ when a method is called on +nil+ and +allow_nil+
+  # option is not used.
+  class DelegationError < NoMethodError; end
+
+  RUBY_RESERVED_WORDS = Set.new(
+    %w(alias and BEGIN begin 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
+
+  DELEGATION_RESERVED_KEYWORDS = Set.new(
+    %w(_ arg args block)
+  )
+
+  DELEGATION_RESERVED_METHOD_NAMES = Set.new(
+    RUBY_RESERVED_WORDS + DELEGATION_RESERVED_KEYWORDS
+  ).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+ to be 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).
@@ -129,6 +154,8 @@ class Module
   #
   #   Foo.new("Bar").name # raises NoMethodError: undefined method `name'
   #
+  # The target method must be public, otherwise it will raise +NoMethodError+.
+  #
   def delegate(*methods)
     options = methods.pop
     unless options.is_a?(Hash) && to = options[:to]
@@ -152,46 +179,47 @@ class Module
     line = line.to_i
 
     to = to.to_s
-    to = 'self.class' if to == 'class'
+    to = "self.#{to}" if RUBY_RESERVED_WORDS.include?(to)
 
     methods.each do |method|
       # Attribute writer methods only accept one argument. Makes sure []=
       # methods still accept two arguments.
       definition = (method =~ /[^\]]=$/) ? 'arg' : '*args, &block'
 
-      # The following generated methods call the target exactly once, storing
+      # 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 conceptualy, from the user point of view, the delegator should
+      # whereas conceptually, from the user point of view, the delegator should
       # be doing one call.
       if allow_nil
-        module_eval(<<-EOS, file, line - 3)
-          def #{method_prefix}#{method}(#{definition})        # def customer_name(*args, &block)
-            _ = #{to}                                         #   _ = client
-            if !_.nil? || nil.respond_to?(:#{method})         #   if !_.nil? || nil.respond_to?(:name)
-              _.#{method}(#{definition})                      #     _.name(*args, &block)
-            end                                               #   end
-          end                                                 # end
-        EOS
+        method_def = [
+          "def #{method_prefix}#{method}(#{definition})",
+          "_ = #{to}",
+          "if !_.nil? || nil.respond_to?(:#{method})",
+          "  _.#{method}(#{definition})",
+          "end",
+        "end"
+        ].join ';'
       else
-        exception = %(raise "#{self}##{method_prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
+        exception = %(raise DelegationError, "#{self}##{method_prefix}#{method} delegated to #{to}.#{method}, but #{to} is nil: \#{self.inspect}")
 
-        module_eval(<<-EOS, file, line - 2)
-          def #{method_prefix}#{method}(#{definition})                                          # def customer_name(*args, &block)
-            _ = #{to}                                                                           #   _ = client
-            _.#{method}(#{definition})                                                          #   _.name(*args, &block)
-          rescue NoMethodError => e                                                             # rescue NoMethodError => e
-            location = "%s:%d:in `%s'" % [__FILE__, __LINE__ - 2, '#{method_prefix}#{method}']  #   location = "%s:%d:in `%s'" % [__FILE__, __LINE__ - 2, 'customer_name']
-            if _.nil? && e.backtrace.first == location                                          #   if _.nil? && e.backtrace.first == location
-              #{exception}                                                                      #     # add helpful message to the exception
-            else                                                                                #   else
-              raise                                                                             #     raise
-            end                                                                                 #   end
-          end                                                                                   # end
-        EOS
+        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(method_def, file, line)
     end
   end
 end

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

@@ -1,5 +1,3 @@
-require 'active_support/deprecation/method_wrappers'
-
 class Module
   #   deprecate :foo
   #   deprecate bar: 'message'

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

@@ -59,20 +59,4 @@ class Module
   def local_constants #:nodoc:
     constants(false)
   end
-
-  # *DEPRECATED*: Use +local_constants+ instead.
-  #
-  # Returns the names of the constants defined locally as strings.
-  #
-  #   module M
-  #     X = 1
-  #   end
-  #   M.local_constant_names # => ["X"]
-  #
-  # This method is useful for forward compatibility, since Ruby 1.8 returns
-  # constant names as strings, whereas 1.9 returns them as symbols.
-  def local_constant_names
-    ActiveSupport::Deprecation.warn 'Module#local_constant_names is deprecated, use Module#local_constants instead'
-    local_constants.map { |c| c.to_s }
-  end
 end

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

@@ -0,0 +1,13 @@
+class Module
+  ###
+  # TODO: remove this after 1.9 support is dropped
+  def methods_transplantable? # :nodoc:
+    x = Module.new {
+      def foo; end # :nodoc:
+    }
+    Module.new { define_method :bar, x.instance_method(:foo) }
+    true
+  rescue TypeError
+    false
+  end
+end

data/lib/active_support/core_ext/module.rb

@@ -4,6 +4,7 @@ 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/attr_internal'
+require 'active_support/core_ext/module/concerning'
 require 'active_support/core_ext/module/delegation'
 require 'active_support/core_ext/module/deprecation'
 require 'active_support/core_ext/module/remove_method'

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

@@ -41,7 +41,7 @@ class Numeric
   #  1000.to_s(:percentage, delimiter: '.', separator: ',') # => 1.000,000%
   #  302.24398923423.to_s(:percentage, precision: 5)        # => 302.24399%
   #  1000.to_s(:percentage, locale: :fr)                    # => 1 000,000%
-  #  100.to_s(:percentage, format: '%n  %')                 # => 100  %
+  #  100.to_s(:percentage, format: '%n  %')                 # => 100.000  %
   #
   #  Delimited:
   #  12345678.to_s(:delimited)                     # => 12,345,678
@@ -78,7 +78,7 @@ class Numeric
   #  1234567.to_s(:human_size, precision: 2)                 # => 1.2 MB
   #  483989.to_s(:human_size, precision: 2)                  # => 470 KB
   #  1234567.to_s(:human_size, precision: 2, separator: ',') # => 1,2 MB
-  #  1234567890123.to_s(:human_size, precision: 5)           # => "1.1229 TB"
+  #  1234567890123.to_s(:human_size, precision: 5)           # => "1.1228 TB"
   #  524288000.to_s(:human_size, precision: 5)               # => "500 MB"
   #
   #  Human-friendly format:
@@ -118,7 +118,15 @@ class Numeric
     end
   end
 
-  [Float, Fixnum, Bignum, BigDecimal].each do |klass|
+  klasses = [Float, BigDecimal]
+  # Ruby 2.4+ unifies Fixnum & Bignum into Integer.
+  if 0.class == Integer
+    klasses << Integer
+  else
+    klasses << Fixnum << Bignum
+  end
+
+  klasses.each do |klass|
     klass.send(:alias_method, :to_default_s, :to_s)
 
     klass.send(:define_method, :to_s) do |*args|

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

@@ -16,21 +16,6 @@ class Numeric
   #
   #   # equivalent to Time.current.advance(months: 4, years: 5)
   #   (4.months + 5.years).from_now
-  #
-  # While these methods provide precise calculation when used as in the examples above, care
-  # should be taken to note that this is not true if the result of `months', `years', etc is
-  # converted before use:
-  #
-  #   # equivalent to 30.days.to_i.from_now
-  #   1.month.to_i.from_now
-  #
-  #   # equivalent to 365.25.days.to_f.from_now
-  #   1.year.to_f.from_now
-  #
-  # In such cases, Ruby's core
-  # Date[http://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html] and
-  # Time[http://ruby-doc.org/stdlib/libdoc/time/rdoc/Time.html] should be used for precision
-  # date and time arithmetic.
   def seconds
     ActiveSupport::Duration.new(self, [[:seconds, self]])
   end
@@ -61,19 +46,9 @@ class Numeric
   end
   alias :fortnight :fortnights
 
-  # Reads best without arguments:  10.minutes.ago
-  def ago(time = ::Time.current)
-    time - self
+  # Used with the standard time durations, like 1.hour.in_milliseconds --
+  # so we can feed them to JavaScript functions like getTime().
+  def in_milliseconds
+    self * 1000
   end
-
-  # Reads best with argument:  10.minutes.until(time)
-  alias :until :ago
-
-  # Reads best with argument:  10.minutes.since(time)
-  def since(time = ::Time.current)
-    time + self
-  end
-
-  # Reads best without arguments:  10.minutes.from_now
-  alias :from_now :since
 end

data/lib/active_support/core_ext/object/blank.rb

@@ -2,38 +2,44 @@
 
 class Object
   # An object is blank if it's false, empty, or a whitespace string.
-  # For example, '', '   ', +nil+, [], and {} are all blank.
+  # For example, +false+, '', '   ', +nil+, [], and {} are all blank.
   #
-  # This simplifies:
+  # This simplifies
   #
-  #   if address.nil? || address.empty?
+  #   !address || address.empty?
   #
-  # ...to:
+  # to
   #
-  #   if address.blank?
+  #   address.blank?
+  #
+  # @return [true, false]
   def blank?
-    respond_to?(:empty?) ? empty? : !self
+    respond_to?(:empty?) ? !!empty? : !self
   end
 
-  # An object is present if it's not <tt>blank?</tt>.
+  # An object is present if it's not blank.
+  #
+  # @return [true, false]
   def present?
     !blank?
   end
 
-  # Returns object if it's <tt>present?</tt> otherwise returns +nil+.
-  # <tt>object.presence</tt> is equivalent to <tt>object.present? ? object : nil</tt>.
+  # Returns the receiver if it's present otherwise returns +nil+.
+  # <tt>object.presence</tt> is equivalent to
   #
-  # This is handy for any representation of objects where blank is the same
-  # as not present at all. For example, this simplifies a common check for
-  # HTTP POST/query parameters:
+  #    object.present? ? object : nil
+  #
+  # For example, something like
   #
   #   state   = params[:state]   if params[:state].present?
   #   country = params[:country] if params[:country].present?
   #   region  = state || country || 'US'
   #
-  # ...becomes:
+  # becomes
   #
   #   region = params[:state].presence || params[:country].presence || 'US'
+  #
+  # @return [Object]
   def presence
     self if present?
   end
@@ -43,6 +49,8 @@ class NilClass
   # +nil+ is blank:
   #
   #   nil.blank? # => true
+  #
+  # @return [true]
   def blank?
     true
   end
@@ -52,6 +60,8 @@ class FalseClass
   # +false+ is blank:
   #
   #   false.blank? # => true
+  #
+  # @return [true]
   def blank?
     true
   end
@@ -61,6 +71,8 @@ class TrueClass
   # +true+ is not blank:
   #
   #   true.blank? # => false
+  #
+  # @return [false]
   def blank?
     false
   end
@@ -71,6 +83,8 @@ class Array
   #
   #   [].blank?      # => true
   #   [1,2,3].blank? # => false
+  #
+  # @return [true, false]
   alias_method :blank?, :empty?
 end
 
@@ -79,18 +93,28 @@ class Hash
   #
   #   {}.blank?                # => true
   #   { key: 'value' }.blank?  # => false
+  #
+  # @return [true, false]
   alias_method :blank?, :empty?
 end
 
 class String
+  BLANK_RE = /\A[[:space:]]*\z/
+
   # A string is blank if it's empty or contains whitespaces only:
   #
-  #   ''.blank?                 # => true
-  #   '   '.blank?              # => true
-  #   '　'.blank?               # => true
-  #   ' something here '.blank? # => false
+  #   ''.blank?       # => true
+  #   '   '.blank?    # => true
+  #   "\t\n\r".blank? # => true
+  #   ' blah '.blank? # => false
+  #
+  # Unicode whitespace is supported:
+  #
+  #   "\u00a0".blank? # => true
+  #
+  # @return [true, false]
   def blank?
-    self !~ /[^[:space:]]/
+    BLANK_RE === self
   end
 end
 
@@ -99,6 +123,8 @@ class Numeric #:nodoc:
   #
   #   1.blank? # => false
   #   0.blank? # => false
+  #
+  # @return [false]
   def blank?
     false
   end

data/lib/active_support/core_ext/object/deep_dup.rb

@@ -8,8 +8,8 @@ class Object
   #   dup    = object.deep_dup
   #   dup.instance_variable_set(:@a, 1)
   #
-  #   object.instance_variable_defined?(:@a) #=> false
-  #   dup.instance_variable_defined?(:@a)    #=> true
+  #   object.instance_variable_defined?(:@a) # => false
+  #   dup.instance_variable_defined?(:@a)    # => true
   def deep_dup
     duplicable? ? dup : self
   end
@@ -22,8 +22,8 @@ class Array
   #   dup   = array.deep_dup
   #   dup[1][2] = 4
   #
-  #   array[1][2] #=> nil
-  #   dup[1][2]   #=> 4
+  #   array[1][2] # => nil
+  #   dup[1][2]   # => 4
   def deep_dup
     map { |it| it.deep_dup }
   end
@@ -36,8 +36,8 @@ class Hash
   #   dup  = hash.deep_dup
   #   dup[:a][:c] = 'c'
   #
-  #   hash[:a][:c] #=> nil
-  #   dup[:a][:c]  #=> "c"
+  #   hash[:a][:c] # => nil
+  #   dup[:a][:c]  # => "c"
   def deep_dup
     each_with_object(dup) do |(key, value), hash|
       hash[key.deep_dup] = value.deep_dup