From dcc9d38b8b92db57469b4cf6969a2ed3a1950ca0 Mon Sep 17 00:00:00 2001 From: "Josep M. Bach" Date: Sat, 14 Aug 2010 16:28:30 +0200 Subject: [PATCH] Documented active_support/concern dependency handling --- activesupport/lib/active_support/concern.rb | 82 ++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/activesupport/lib/active_support/concern.rb b/activesupport/lib/active_support/concern.rb index 2d87e8d0e5e31..6781082786e53 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 ActiveSupport::Concern 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 base is Bar module, not Host class. +# With ActiveSupport::Concern, 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)