aboutsummaryrefslogtreecommitdiffstats
path: root/activesupport/lib/active_support
diff options
context:
space:
mode:
authorJosep M. Bach <josep.m.bach@gmail.com>2010-08-14 16:28:30 +0200
committerJosep M. Bach <josep.m.bach@gmail.com>2010-08-14 16:28:30 +0200
commitdcc9d38b8b92db57469b4cf6969a2ed3a1950ca0 (patch)
tree017385002f49b8252a1a542ed2a56cdf2a7b41da /activesupport/lib/active_support
parente5163784102e3ce97b99dd50b35b18868dc3c3b5 (diff)
downloadrails-dcc9d38b8b92db57469b4cf6969a2ed3a1950ca0.tar.gz
rails-dcc9d38b8b92db57469b4cf6969a2ed3a1950ca0.tar.bz2
rails-dcc9d38b8b92db57469b4cf6969a2ed3a1950ca0.zip
Documented active_support/concern dependency handling
Diffstat (limited to 'activesupport/lib/active_support')
-rw-r--r--activesupport/lib/active_support/concern.rb82
1 files changed, 81 insertions, 1 deletions
diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb
index 2d87e8d0e5..6781082786 100644
--- a/activesupport/lib/active_support/concern.rb
+++ b/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)