activesupport 4.0.13 → 4.1.0.beta1

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

@@ -41,8 +41,6 @@ module Kernel
   #   end
   #
   #   puts 'But this will'
-  #
-  # This method is not thread-safe.
   def silence_stream(stream)
     old_stream = stream.dup
     stream.reopen(RbConfig::CONFIG['host_os'] =~ /mswin|mingw/ ? 'NUL:' : '/dev/null')
@@ -63,8 +61,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:
@@ -94,6 +91,7 @@ module Kernel
     stream_io.rewind
     return captured_stream.read
   ensure
+    captured_stream.close
     captured_stream.unlink
     stream_io.reopen(origin_stream)
   end
@@ -102,8 +100,6 @@ module Kernel
   # Silences both STDOUT and STDERR, even for subprocesses.
   #
   #   quietly { system 'bundle install' }
-  #
-  # This method is not thread-safe.
   def quietly
     silence_stream(STDOUT) do
       silence_stream(STDERR) do

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/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

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
+  # 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,16 @@
 class Module
+  # Error generated by +delegate+ when a method is called on +nil+ and +allow_nil+
+  # option is not used.
+  class DelegationError < NoMethodError; end
+
   # 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 +138,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]
@@ -164,7 +175,7 @@ class Module
       #
       # 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)
@@ -176,15 +187,14 @@ class Module
           end                                                 # end
         EOS
       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
+            if _.nil? && e.name == :#{method}                                                   #   if _.nil? && e.name == :name
               #{exception}                                                                      #     # add helpful message to the exception
             else                                                                                #   else
               raise                                                                             #     raise

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'