Merge pull request rails#37174

Closes rails#37174

Author: kaspth

activesupport/CHANGELOG.md

@@ -1,3 +1,23 @@
+*   Support `prepend` with `ActiveSupport::Concern`.
+
+    Allows a module with `extend ActiveSupport::Concern` to be prepended.
+
+        module Imposter
+          extend ActiveSupport::Concern
+
+          # Same as `included`, except only run when prepended.
+          prepended do
+          end
+        end
+
+        class Person
+          prepend Imposter
+        end
+
+    Concerning is also updated: `concerning :Imposter, prepend: true do`
+
+    *Jason Karns*
+
 *   Deprecate using `Range#include?` method to check the inclusion of a value
     in a date time range. It is recommended to use `Range#cover?` method
     instead of `Range#include?` to check the inclusion of a value

activesupport/lib/active_support/concern.rb

@@ -99,13 +99,27 @@ module ActiveSupport
   #   class Host
   #     include Bar # It works, now Bar takes care of its dependencies
   #   end
+  #
+  # === Prepending concerns
+  #
+  # Just like `include`, concerns also support `prepend` with a corresponding
+  # `prepended do` callback. `module ClassMethods` or `class_methods do` are
+  # still extended.
+  #
+  # `prepend` is also used for any dependencies.
   module Concern
     class MultipleIncludedBlocks < StandardError #:nodoc:
       def initialize
         super "Cannot define multiple 'included' blocks for a Concern"
       end
     end
 
+    class MultiplePrependBlocks < StandardError #:nodoc:
+      def initialize
+        super "Cannot define multiple 'prepended' blocks for a Concern"
+      end
+    end
+
     def self.extended(base) #:nodoc:
       base.instance_variable_set(:@_dependencies, [])
     end
@@ -123,6 +137,19 @@ def append_features(base) #:nodoc:
       end
     end
 
+    def prepend_features(base) #:nodoc:
+      if base.instance_variable_defined?(:@_dependencies)
+        base.instance_variable_get(:@_dependencies).unshift self
+        false
+      else
+        return false if base < self
+        @_dependencies.each { |dep| base.prepend(dep) }
+        super
+        base.extend const_get(:ClassMethods) if const_defined?(:ClassMethods)
+        base.class_eval(&@_prepended_block) if instance_variable_defined?(:@_prepended_block)
+      end
+    end
+
     # Evaluate given block in context of base class,
     # so that you can write class macros here.
     # When you define more than one +included+ block, it raises an exception.
@@ -140,6 +167,23 @@ def included(base = nil, &block)
       end
     end
 
+    # Evaluate given block in context of base class,
+    # so that you can write class macros here.
+    # When you define more than one +prepended+ block, it raises an exception.
+    def prepended(base = nil, &block)
+      if base.nil?
+        if instance_variable_defined?(:@_prepended_block)
+          if @_prepended_block.source_location != block.source_location
+            raise MultiplePrependBlocks
+          end
+        else
+          @_prepended_block = block
+        end
+      else
+        super
+      end
+    end
+
     # Define class methods from given block.
     # You can define private class methods as well.
     #

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

@@ -104,10 +104,16 @@ class Module
   # * 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.
+  #
+  # === Prepending `concerning`
+  #
+  # `concerning` supports a `prepend: true` argument which will `prepend` the
+  # concern instead of using `include` for it.
   module Concerning
     # Define a new concern and mix it in.
-    def concerning(topic, &block)
-      include concern(topic, &block)
+    def concerning(topic, prepend: false, &block)
+      method = prepend ? :prepend : :include
+      __send__(method, concern(topic, &block))
     end
 
     # A low-cruft shortcut to define a concern.

activesupport/test/concern_test.rb

@@ -13,18 +13,30 @@ def baz
       end
 
       def included_ran=(value)
-        @@included_ran = value
+        @included_ran = value
       end
 
       def included_ran
-        @@included_ran
+        @included_ran
+      end
+
+      def prepended_ran=(value)
+        @prepended_ran = value
+      end
+
+      def prepended_ran
+        @prepended_ran
       end
     end
 
     included do
       self.included_ran = true
     end
 
+    prepended do
+      self.prepended_ran = true
+    end
+
     def baz
       "baz"
     end
@@ -71,12 +83,24 @@ def test_module_is_included_normally
     assert_includes @klass.included_modules, ConcernTest::Baz
   end
 
+  def test_module_is_prepended_normally
+    @klass.prepend(Baz)
+    assert_equal "baz", @klass.new.baz
+    assert_includes @klass.included_modules, ConcernTest::Baz
+  end
+
   def test_class_methods_are_extended
     @klass.include(Baz)
     assert_equal "baz", @klass.baz
     assert_equal ConcernTest::Baz::ClassMethods, (class << @klass; included_modules; end)[0]
   end
 
+  def test_class_methods_are_extended_when_prepended
+    @klass.prepend(Baz)
+    assert_equal "baz", @klass.baz
+    assert_equal ConcernTest::Baz::ClassMethods, (class << @klass; included_modules; end)[0]
+  end
+
   def test_class_methods_are_extended_only_on_expected_objects
     ::Object.include(Qux)
     Object.extend(Qux::ClassMethods)
@@ -102,6 +126,21 @@ def test_included_block_is_ran
     assert_equal true, @klass.included_ran
   end
 
+  def test_included_block_is_not_ran_when_prepended
+    @klass.prepend(Baz)
+    assert_nil @klass.included_ran
+  end
+
+  def test_prepended_block_is_ran
+    @klass.prepend(Baz)
+    assert_equal true, @klass.prepended_ran
+  end
+
+  def test_prepended_block_is_not_ran_when_included
+    @klass.include(Baz)
+    assert_nil @klass.prepended_ran
+  end
+
   def test_modules_dependencies_are_met
     @klass.include(Bar)
     assert_equal "bar", @klass.new.bar
@@ -115,6 +154,11 @@ def test_dependencies_with_multiple_modules
     assert_equal [ConcernTest::Foo, ConcernTest::Bar, ConcernTest::Baz], @klass.included_modules[0..2]
   end
 
+  def test_dependencies_with_multiple_modules_when_prepended
+    @klass.prepend(Foo)
+    assert_equal [ConcernTest::Foo, ConcernTest::Bar, ConcernTest::Baz], @klass.included_modules[0..2]
+  end
+
   def test_raise_on_multiple_included_calls
     assert_raises(ActiveSupport::Concern::MultipleIncludedBlocks) do
       Module.new do
@@ -129,7 +173,21 @@ def test_raise_on_multiple_included_calls
     end
   end
 
-  def test_no_raise_on_same_included_call
+  def test_raise_on_multiple_prepended_calls
+    assert_raises(ActiveSupport::Concern::MultiplePrependBlocks) do
+      Module.new do
+        extend ActiveSupport::Concern
+
+        prepended do
+        end
+
+        prepended do
+        end
+      end
+    end
+  end
+
+  def test_no_raise_on_same_included_or_prepended_call
     assert_nothing_raised do
       2.times do
         load File.expand_path("../fixtures/concern/some_concern.rb", __FILE__)

activesupport/test/core_ext/module/concerning_test.rb

@@ -7,6 +7,21 @@ class ModuleConcerningTest < ActiveSupport::TestCase
   def test_concerning_declares_a_concern_and_includes_it_immediately
     klass = Class.new { concerning(:Foo) { } }
     assert_includes klass.ancestors, klass::Foo, klass.ancestors.inspect
+
+    klass = Class.new { concerning(:Foo, prepend: true) { } }
+    assert_includes klass.ancestors, klass::Foo, klass.ancestors.inspect
+  end
+
+  def test_concerning_can_prepend_concern
+    klass = Class.new do
+      def hi; "self"; end
+
+      concerning(:Foo, prepend: true) do
+        def hi; "hello, #{super}"; end
+      end
+    end
+
+    assert_equal "hello, self", klass.new.hi
   end
 end
 
@@ -15,6 +30,7 @@ def test_concern_creates_a_module_extended_with_active_support_concern
     klass = Class.new do
       concern :Baz do
         included { @foo = 1 }
+        prepended { @foo = 2 }
         def should_be_public; end
       end
     end
@@ -30,6 +46,9 @@ def should_be_public; end
 
     # Calls included hook
     assert_equal 1, Class.new { include klass::Baz }.instance_variable_get("@foo")
+
+    # Calls prepended hook
+    assert_equal 2, Class.new { prepend klass::Baz }.instance_variable_get("@foo")
   end
 
   class Foo
@@ -52,6 +71,26 @@ def nicer_dsl; end
         def doesnt_clobber; end
       end
     end
+
+    concerning :Baz, prepend:true do
+      module ClassMethods
+        def will_be_orphaned_also; end
+      end
+
+      const_set :ClassMethods, Module.new {
+        def hacked_on_also; end
+      }
+
+      # Doesn't overwrite existing ClassMethods module.
+      class_methods do
+        def nicer_dsl_also; end
+      end
+
+      # Doesn't overwrite previous class_methods definitions.
+      class_methods do
+        def doesnt_clobber_also; end
+      end
+    end
   end
 
   def test_using_class_methods_blocks_instead_of_ClassMethods_module
@@ -64,4 +103,15 @@ def test_using_class_methods_blocks_instead_of_ClassMethods_module
     assert Foo.const_defined?(:ClassMethods)
     assert Foo::ClassMethods.method_defined?(:will_be_orphaned)
   end
+
+  def test_using_class_methods_blocks_instead_of_ClassMethods_module_prepend
+    assert_not_respond_to Foo, :will_be_orphaned_also
+    assert_respond_to Foo, :hacked_on_also
+    assert_respond_to Foo, :nicer_dsl_also
+    assert_respond_to Foo, :doesnt_clobber_also
+
+    # Orphan in Foo::ClassMethods, not Bar::ClassMethods.
+    assert Foo.const_defined?(:ClassMethods)
+    assert Foo::ClassMethods.method_defined?(:will_be_orphaned_also)
+  end
 end

activesupport/test/fixtures/concern/some_concern.rb

@@ -8,4 +8,8 @@ module SomeConcern
   included do
     # shouldn't raise when module is loaded more than once
   end
+
+  prepended do
+    # shouldn't raise when module is loaded more than once
+  end
 end