Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documented active_support/concern dependency handling

  • Loading branch information...
commit dcc9d38b8b92db57469b4cf6969a2ed3a1950ca0 1 parent e516378
@txus txus authored
Showing with 81 additions and 1 deletion.
  1. +81 −1 activesupport/lib/active_support/concern.rb
View
82 activesupport/lib/active_support/concern.rb
@@ -1,4 +1,4 @@
-# A typical module looks like this
+# A typical module looks like this:
#
# module M
# def self.included(base)
@@ -17,6 +17,8 @@
# end
#
# By using <tt>ActiveSupport::Concern</tt> the above module could instead be written as:
+#
+# require 'active_support/concern'
#
# module M
# extend ActiveSupport::Concern
@@ -33,6 +35,84 @@
# def im; puts 'I am an instance method'; end
# end
# end
+#
+# Moreover, it gracefully handles module dependencies. Given a Foo module and a Bar module which depends on the former, we would typically write the following:
+#
+# module Foo
+# def self.included(base)
+# # Define some :enhanced_method for Host class
+# base.class_eval do
+# def self.enhanced_method
+# # Do enhanced stuff
+# end
+# end
+# end
+# end
+#
+# module Bar
+# def self.included(base)
+# base.send(:enhanced_method)
+# end
+# end
+#
+# class Host
+# include Foo # We need to include this dependency for Bar
+# include Bar # Bar is the module that Host really needs
+# end
+#
+# But why should Host care about Bar's dependencies, namely Foo? We could try to hide these from Host directly including Foo in Bar:
+#
+# module Foo
+# def self.included(base)
+# # Define some :enhanced_method for Host class
+# base.class_eval do
+# def self.enhanced_method
+# # Do enhanced stuff
+# end
+# end
+# end
+# end
+#
+# module Bar
+# include Foo
+# def self.included(base)
+# base.send(:enhanced_method)
+# end
+# end
+#
+# class Host
+# include Bar
+# end
+#
+# Unfortunately this won't work, since when Foo is included, its <tt>base</tt> is Bar module, not Host class.
+# With <tt>ActiveSupport::Concern</tt>, module dependencies are properly resolved:
+#
+# require 'active_support/concern'
+#
+# module Foo
+# extend ActiveSupport::Concern
+# included do
+# class_eval do
+# def self.enhanced_method
+# # Do enhanced stuff
+# end
+# end
+# end
+# end
+#
+# module Bar
+# extend ActiveSupport::Concern
+# include Foo
+#
+# included do
+# self.send(:enhanced_method)
+# end
+# end
+#
+# class Host
+# include Bar # Host only needs to care about Bar without needing to know about its dependencies
+# end
+#
module ActiveSupport
module Concern
def self.extended(base)
Please sign in to comment.
Something went wrong with that request. Please try again.