activesupport 4.0.13 → 4.2.11.3

data/lib/active_support/core_ext/hash/keys.rb

@@ -1,12 +1,13 @@
 class Hash
-  # Return a new hash with all keys converted using the block operation.
+  # Returns a new hash with all keys converted using the block operation.
   #
   #  hash = { name: 'Rob', age: '28' }
   #
   #  hash.transform_keys{ |key| key.to_s.upcase }
-  #  # => { "NAME" => "Rob", "AGE" => "28" }
+  #  # => {"NAME"=>"Rob", "AGE"=>"28"}
   def transform_keys
-    result = {}
+    return enum_for(:transform_keys) unless block_given?
+    result = self.class.new
     each_key do |key|
       result[yield(key)] = self[key]
     end
@@ -16,18 +17,19 @@ class Hash
   # Destructively convert all keys using the block operations.
   # Same as transform_keys but modifies +self+.
   def transform_keys!
+    return enum_for(:transform_keys!) unless block_given?
     keys.each do |key|
       self[yield(key)] = delete(key)
     end
     self
   end
 
-  # Return a new hash with all keys converted to strings.
+  # Returns a new hash with all keys converted to strings.
   #
   #   hash = { name: 'Rob', age: '28' }
   #
   #   hash.stringify_keys
-  #   #=> { "name" => "Rob", "age" => "28" }
+  #   # => {"name"=>"Rob", "age"=>"28"}
   def stringify_keys
     transform_keys{ |key| key.to_s }
   end
@@ -38,13 +40,13 @@ class Hash
     transform_keys!{ |key| key.to_s }
   end
 
-  # Return a new hash with all keys converted to symbols, as long as
+  # Returns a new hash with all keys converted to symbols, as long as
   # they respond to +to_sym+.
   #
   #   hash = { 'name' => 'Rob', 'age' => '28' }
   #
   #   hash.symbolize_keys
-  #   #=> { name: "Rob", age: "28" }
+  #   # => {:name=>"Rob", :age=>"28"}
   def symbolize_keys
     transform_keys{ |key| key.to_sym rescue key }
   end
@@ -57,28 +59,32 @@ class Hash
   end
   alias_method :to_options!, :symbolize_keys!
 
-  # Validate all keys in a hash match <tt>*valid_keys</tt>, raising ArgumentError
-  # on a mismatch. Note that keys are NOT treated indifferently, meaning if you
-  # use strings for keys but assert symbols as keys, this will fail.
+  # Validate all keys in a hash match <tt>*valid_keys</tt>, raising
+  # ArgumentError on a mismatch.
   #
-  #   { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: years"
-  #   { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: name"
+  # Note that keys are treated differently than HashWithIndifferentAccess,
+  # meaning that string and symbol keys will not match.
+  #
+  #   { name: 'Rob', years: '28' }.assert_valid_keys(:name, :age) # => raises "ArgumentError: Unknown key: :years. Valid keys are: :name, :age"
+  #   { name: 'Rob', age: '28' }.assert_valid_keys('name', 'age') # => raises "ArgumentError: Unknown key: :name. Valid keys are: 'name', 'age'"
   #   { name: 'Rob', age: '28' }.assert_valid_keys(:name, :age)   # => passes, raises nothing
   def assert_valid_keys(*valid_keys)
     valid_keys.flatten!
     each_key do |k|
-      raise ArgumentError.new("Unknown key: #{k}") unless valid_keys.include?(k)
+      unless valid_keys.include?(k)
+        raise ArgumentError.new("Unknown key: #{k.inspect}. Valid keys are: #{valid_keys.map(&:inspect).join(', ')}")
+      end
     end
   end
 
-  # Return a new hash with all keys converted by the block operation.
+  # Returns a new hash with all keys converted by the block operation.
   # This includes the keys from the root hash and from all
   # nested hashes and arrays.
   #
   #  hash = { person: { name: 'Rob', age: '28' } }
   #
   #  hash.deep_transform_keys{ |key| key.to_s.upcase }
-  #  # => { "PERSON" => { "NAME" => "Rob", "AGE" => "28" } }
+  #  # => {"PERSON"=>{"NAME"=>"Rob", "AGE"=>"28"}}
   def deep_transform_keys(&block)
     _deep_transform_keys_in_object(self, &block)
   end
@@ -90,14 +96,14 @@ class Hash
     _deep_transform_keys_in_object!(self, &block)
   end
 
-  # Return a new hash with all keys converted to strings.
+  # Returns a new hash with all keys converted to strings.
   # This includes the keys from the root hash and from all
   # nested hashes and arrays.
   #
   #   hash = { person: { name: 'Rob', age: '28' } }
   #
   #   hash.deep_stringify_keys
-  #   # => { "person" => { "name" => "Rob", "age" => "28" } }
+  #   # => {"person"=>{"name"=>"Rob", "age"=>"28"}}
   def deep_stringify_keys
     deep_transform_keys{ |key| key.to_s }
   end
@@ -109,14 +115,14 @@ class Hash
     deep_transform_keys!{ |key| key.to_s }
   end
 
-  # Return a new hash with all keys converted to symbols, as long as
+  # Returns a new hash with all keys converted to symbols, as long as
   # they respond to +to_sym+. This includes the keys from the root hash
   # and from all nested hashes and arrays.
   #
   #   hash = { 'person' => { 'name' => 'Rob', 'age' => '28' } }
   #
   #   hash.deep_symbolize_keys
-  #   # => { person: { name: "Rob", age: "28" } }
+  #   # => {:person=>{:name=>"Rob", :age=>"28"}}
   def deep_symbolize_keys
     deep_transform_keys{ |key| key.to_sym rescue key }
   end

data/lib/active_support/core_ext/hash/slice.rb

@@ -1,6 +1,12 @@
 class Hash
-  # Slice a hash to include only the given keys. This is useful for
-  # limiting an options hash to valid keys before passing to a method:
+  # Slice a hash to include only the given keys. Returns a hash containing 
+  # the given keys.
+  # 
+  #   { a: 1, b: 2, c: 3, d: 4 }.slice(:a, :b)
+  #   # => {:a=>1, :b=>2}
+  # 
+  # This is useful for limiting an options hash to valid keys before 
+  # passing to a method:
   #
   #   def search(criteria = {})
   #     criteria.assert_valid_keys(:mass, :velocity, :time)

data/lib/active_support/core_ext/hash/transform_values.rb

@@ -0,0 +1,23 @@
+class Hash
+  # Returns a new hash with the results of running +block+ once for every value.
+  # The keys are unchanged.
+  #
+  #   { a: 1, b: 2, c: 3 }.transform_values { |x| x * 2 }
+  #   # => { a: 2, b: 4, c: 6 }
+  def transform_values
+    return enum_for(:transform_values) unless block_given?
+    result = self.class.new
+    each do |key, value|
+      result[key] = yield(value)
+    end
+    result
+  end unless method_defined? :transform_values
+
+  # Destructive +transform_values+
+  def transform_values!
+    return enum_for(:transform_values!) unless block_given?
+    each do |key, value|
+      self[key] = yield(value)
+    end
+  end unless method_defined? :transform_values!
+end

data/lib/active_support/core_ext/hash.rb

@@ -1,8 +1,9 @@
+require 'active_support/core_ext/hash/compact'
 require 'active_support/core_ext/hash/conversions'
 require 'active_support/core_ext/hash/deep_merge'
-require 'active_support/core_ext/hash/diff'
 require 'active_support/core_ext/hash/except'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/core_ext/hash/keys'
 require 'active_support/core_ext/hash/reverse_merge'
 require 'active_support/core_ext/hash/slice'
+require 'active_support/core_ext/hash/transform_values'

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

@@ -17,21 +17,6 @@ class Integer
   #
   #   # equivalent to Time.now.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 months
     ActiveSupport::Duration.new(self * 30.days, [[:months, self]])
   end

data/lib/active_support/core_ext/kernel/concern.rb

@@ -0,0 +1,10 @@
+require 'active_support/core_ext/module/concerning'
+
+module Kernel
+  # A shortcut to define a toplevel concern, not within a module.
+  #
+  # See Module::Concerning for more.
+  def concern(topic, &module_definition)
+    Object.concern topic, &module_definition
+  end
+end

data/lib/active_support/core_ext/kernel/debugger.rb

@@ -3,7 +3,7 @@ module Kernel
     # Starts a debugging session if the +debugger+ gem has been loaded (call rails server --debugger to do load it).
     def debugger
       message = "\n***** Debugger requested, but was not available (ensure the debugger gem is listed in Gemfile/installed as gem): Start server with --debugger to enable *****\n"
-      defined?(Rails) ? Rails.logger.info(message) : $stderr.puts(message)
+      defined?(Rails.logger) ? Rails.logger.info(message) : $stderr.puts(message)
     end
     alias breakpoint debugger unless respond_to?(:breakpoint)
   end

data/lib/active_support/core_ext/kernel/reporting.rb

@@ -1,5 +1,6 @@
 require 'rbconfig'
 require 'tempfile'
+require 'active_support/deprecation'
 
 module Kernel
   # Sets $VERBOSE to nil for the duration of the block and back to its original
@@ -31,9 +32,13 @@ module Kernel
 
   # For compatibility
   def silence_stderr #:nodoc:
+    ActiveSupport::Deprecation.warn(
+      "`#silence_stderr` is deprecated and will be removed in the next release."
+    ) #not thread-safe
     silence_stream(STDERR) { yield }
   end
 
+  # Deprecated : this method is not thread safe
   # Silences any stream for the duration of the block.
   #
   #   silence_stream(STDOUT) do
@@ -63,8 +68,7 @@ module Kernel
   #   puts 'This code gets executed and nothing related to ZeroDivisionError was seen'
   def suppress(*exception_classes)
     yield
-  rescue Exception => e
-    raise unless exception_classes.any? { |cls| e.kind_of?(cls) }
+  rescue *exception_classes
   end
 
   # Captures the given stream and returns it:
@@ -83,6 +87,9 @@ module Kernel
   #   stream = capture(:stderr) { system('echo error 1>&2') }
   #   stream # => "error\n"
   def capture(stream)
+    ActiveSupport::Deprecation.warn(
+      "`#capture(stream)` is deprecated and will be removed in the next release."
+    ) #not thread-safe
     stream = stream.to_s
     captured_stream = Tempfile.new(stream)
     stream_io = eval("$#{stream}")
@@ -94,6 +101,7 @@ module Kernel
     stream_io.rewind
     return captured_stream.read
   ensure
+    captured_stream.close
     captured_stream.unlink
     stream_io.reopen(origin_stream)
   end
@@ -105,6 +113,9 @@ module Kernel
   #
   # This method is not thread-safe.
   def quietly
+    ActiveSupport::Deprecation.warn(
+      "`#quietly` is deprecated and will be removed in the next release."
+    ) #not thread-safe
     silence_stream(STDOUT) do
       silence_stream(STDERR) do
         yield

data/lib/active_support/core_ext/kernel.rb

@@ -1,4 +1,5 @@
-require 'active_support/core_ext/kernel/reporting'
 require 'active_support/core_ext/kernel/agnostics'
-require 'active_support/core_ext/kernel/debugger'
+require 'active_support/core_ext/kernel/concern'
+require 'active_support/core_ext/kernel/debugger' if RUBY_VERSION < '2.0.0'
+require 'active_support/core_ext/kernel/reporting'
 require 'active_support/core_ext/kernel/singleton_class'

data/lib/active_support/core_ext/load_error.rb

@@ -7,6 +7,7 @@ class LoadError
   ]
 
   unless method_defined?(:path)
+    # Returns the path which was unable to be loaded.
     def path
       @path ||= begin
         REGEXPS.find do |regex|
@@ -17,9 +18,11 @@ class LoadError
     end
   end
 
+  # Returns true if the given path name (except perhaps for the ".rb"
+  # extension) is the missing file which caused the exception to be raised.
   def is_missing?(location)
     location.sub(/\.rb$/, '') == path.sub(/\.rb$/, '')
   end
 end
 
-MissingSourceFile = LoadError
+MissingSourceFile = LoadError

data/lib/active_support/core_ext/marshal.rb

@@ -2,13 +2,16 @@ require 'active_support/core_ext/module/aliasing'
 
 module Marshal
   class << self
-    def load_with_autoloading(source)
-      load_without_autoloading(source)
+    def load_with_autoloading(source, proc = nil)
+      load_without_autoloading(source, proc)
     rescue ArgumentError, NameError => exc
-      if exc.message.match(%r|undefined class/module (.+)|)
+      if exc.message.match(%r|undefined class/module (.+?)(::)?\z|)
         # try loading the class/module
-        $1.constantize
-        # if it is a IO we need to go back to read the object
+        loaded = $1.constantize
+
+        raise unless $1 == loaded.name
+
+        # if it is an IO we need to go back to read the object
         source.rewind if source.respond_to?(:rewind)
         retry
       else

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

@@ -19,9 +19,9 @@ class Module
   #   alias_method :foo_without_feature?, :foo?
   #   alias_method :foo?, :foo_with_feature?
   #
-  # so you can safely chain foo, foo?, and foo! with the same feature.
+  # so you can safely chain foo, foo?, foo! and/or foo= with the same feature.
   def alias_method_chain(target, feature)
-    # Strip out punctuation on predicates or bang methods since
+    # Strip out punctuation on predicates, bang or writer methods since
     # e.g. target?_without_feature is not a valid method name.
     aliased_target, punctuation = target.to_s.sub(/([?!=])$/, ''), $1
     yield(aliased_target, punctuation) if block_given?

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

@@ -27,7 +27,8 @@ class Module
 
     def attr_internal_define(attr_name, type)
       internal_name = attr_internal_ivar_name(attr_name).sub(/\A@/, '')
-      class_eval do # class_eval is necessary on 1.9 or else the methods a made private
+      # class_eval is necessary on 1.9 or else the methods are made private
+      class_eval do
         # use native attr_* methods as they are faster on some Ruby implementations
         send("attr_#{type}", internal_name)
       end

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

@@ -1,10 +1,59 @@
 require 'active_support/core_ext/array/extract_options'
 
+# Extends the module object with class/module and instance accessors for
+# class/module attributes, just like the native attr* accessors for instance
+# attributes.
 class Module
+  # Defines a class attribute and creates a class and instance reader methods.
+  # The underlying the class variable is set to +nil+, if it is not previously
+  # defined.
+  #
+  #   module HairColors
+  #     mattr_reader :hair_colors
+  #   end
+  #
+  #   HairColors.hair_colors # => nil
+  #   HairColors.class_variable_set("@@hair_colors", [:brown, :black])
+  #   HairColors.hair_colors # => [:brown, :black]
+  #
+  # The attribute name must be a valid method name in Ruby.
+  #
+  #   module Foo
+  #     mattr_reader :"1_Badname "
+  #   end
+  #   # => NameError: invalid attribute name
+  #
+  # If you want to opt out the creation on the instance reader method, pass
+  # <tt>instance_reader: false</tt> or <tt>instance_accessor: false</tt>.
+  #
+  #   module HairColors
+  #     mattr_writer :hair_colors, instance_reader: false
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.new.hair_colors # => NoMethodError
+  #
+  #
+  # Also, you can pass a block to set up the attribute with a default value.
+  #
+  #   module HairColors
+  #     cattr_reader :hair_colors do
+  #       [:brown, :black, :blonde, :red]
+  #     end
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.hair_colors # => [:brown, :black, :blonde, :red]
   def mattr_reader(*syms)
     options = syms.extract_options!
     syms.each do |sym|
-      raise NameError.new('invalid attribute name') unless sym =~ /^[_A-Za-z]\w*$/
+      raise NameError.new("invalid attribute name: #{sym}") unless sym =~ /^[_A-Za-z]\w*$/
       class_eval(<<-EOS, __FILE__, __LINE__ + 1)
         @@#{sym} = nil unless defined? @@#{sym}
 
@@ -20,14 +69,60 @@ class Module
           end
         EOS
       end
+      class_variable_set("@@#{sym}", yield) if block_given?
     end
   end
+  alias :cattr_reader :mattr_reader
 
+  # Defines a class attribute and creates a class and instance writer methods to
+  # allow assignment to the attribute.
+  #
+  #   module HairColors
+  #     mattr_writer :hair_colors
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   HairColors.hair_colors = [:brown, :black]
+  #   Person.class_variable_get("@@hair_colors") # => [:brown, :black]
+  #   Person.new.hair_colors = [:blonde, :red]
+  #   HairColors.class_variable_get("@@hair_colors") # => [:blonde, :red]
+  #
+  # If you want to opt out the instance writer method, pass
+  # <tt>instance_writer: false</tt> or <tt>instance_accessor: false</tt>.
+  #
+  #   module HairColors
+  #     mattr_writer :hair_colors, instance_writer: false
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.new.hair_colors = [:blonde, :red] # => NoMethodError
+  #
+  # Also, you can pass a block to set up the attribute with a default value.
+  #
+  #   class HairColors
+  #     mattr_writer :hair_colors do
+  #       [:brown, :black, :blonde, :red]
+  #     end
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.class_variable_get("@@hair_colors") # => [:brown, :black, :blonde, :red]
   def mattr_writer(*syms)
     options = syms.extract_options!
     syms.each do |sym|
-      raise NameError.new('invalid attribute name') unless sym =~ /^[_A-Za-z]\w*$/
+      raise NameError.new("invalid attribute name: #{sym}") unless sym =~ /^[_A-Za-z]\w*$/
       class_eval(<<-EOS, __FILE__, __LINE__ + 1)
+        @@#{sym} = nil unless defined? @@#{sym}
+
         def self.#{sym}=(obj)
           @@#{sym} = obj
         end
@@ -40,27 +135,78 @@ class Module
           end
         EOS
       end
+      send("#{sym}=", yield) if block_given?
     end
   end
+  alias :cattr_writer :mattr_writer
 
-  # Extends the module object with module and instance accessors for class attributes,
-  # just like the native attr* accessors for instance attributes.
+  # Defines both class and instance accessors for class attributes.
   #
-  #   module AppConfiguration
-  #     mattr_accessor :google_api_key
+  #   module HairColors
+  #     mattr_accessor :hair_colors
+  #   end
   #
-  #     self.google_api_key = "123456789"
+  #   class Person
+  #     include HairColors
   #   end
   #
-  #   AppConfiguration.google_api_key # => "123456789"
-  #   AppConfiguration.google_api_key = "overriding the api key!"
-  #   AppConfiguration.google_api_key # => "overriding the api key!"
+  #   Person.hair_colors = [:brown, :black, :blonde, :red]
+  #   Person.hair_colors     # => [:brown, :black, :blonde, :red]
+  #   Person.new.hair_colors # => [:brown, :black, :blonde, :red]
+  #
+  # If a subclass changes the value then that would also change the value for
+  # parent class. Similarly if parent class changes the value then that would
+  # change the value of subclasses too.
+  #
+  #   class Male < Person
+  #   end
+  #
+  #   Male.hair_colors << :blue
+  #   Person.hair_colors # => [:brown, :black, :blonde, :red, :blue]
   #
   # To opt out of the instance writer method, pass <tt>instance_writer: false</tt>.
   # To opt out of the instance reader method, pass <tt>instance_reader: false</tt>.
-  # To opt out of both instance methods, pass <tt>instance_accessor: false</tt>.
-  def mattr_accessor(*syms)
-    mattr_reader(*syms)
-    mattr_writer(*syms)
+  #
+  #   module HairColors
+  #     mattr_accessor :hair_colors, instance_writer: false, instance_reader: false
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.new.hair_colors = [:brown]  # => NoMethodError
+  #   Person.new.hair_colors             # => NoMethodError
+  #
+  # Or pass <tt>instance_accessor: false</tt>, to opt out both instance methods.
+  #
+  #   module HairColors
+  #     mattr_accessor :hair_colors, instance_accessor: false
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.new.hair_colors = [:brown]  # => NoMethodError
+  #   Person.new.hair_colors             # => NoMethodError
+  #
+  # Also you can pass a block to set up the attribute with a default value.
+  #
+  #   module HairColors
+  #     mattr_accessor :hair_colors do
+  #       [:brown, :black, :blonde, :red]
+  #     end
+  #   end
+  #
+  #   class Person
+  #     include HairColors
+  #   end
+  #
+  #   Person.class_variable_get("@@hair_colors") #=> [:brown, :black, :blonde, :red]
+  def mattr_accessor(*syms, &blk)
+    mattr_reader(*syms, &blk)
+    mattr_writer(*syms, &blk)
   end
+  alias :cattr_accessor :mattr_accessor
 end