On May 16, 2007, at 10:02 PM, Dave Hoefler wrote:

> Hi there,
>
> I see the following code chunk in a lot of Rails plugins:
>
>  def self.included(base)
>    base.extend(ClassMethods)
>  end
>
>  module ClassMethods
>     def method_one
>     end
>
>     def method_two
>     end
>  end
>
>
> I'm most curious about "self.included". I checked out the docs on  
> 'included'
> (http://www.ruby-doc.org/core/classes/Module.html#M001661). They  
> pointed to
> 'Module.append_features' (
> http://www.ruby-doc.org/core/classes/Module.html#M001659). Even after
> reading the docs, I'm still a little lost. Could someone break it  
> down a
> little more than the docs? ...or point me at some other resource.  
> I'd like
> to know "why" this is done.

If a module implements self.included the interpreter calls that  
method whenever the module is included in another module or class,  
which is passed as its single argument.

Object#extend on the other hand adds the instance methods of the  
module or modules passed as arguments to the target object (as  
singleton methods). If the object is a class, that means you are  
making module instance methods available as class methods in that  
class, and that's what base is when a module is being included in a  
class.

In short, plugins put methods that will end up being class methods  
(acts_as_something, say) in their own nested module, conventionally  
called ClassMethods, and then include them in init.rb. For instance

   ActiveRecord::Base.send(:include, MyModule)

That triggers inclusion when Rails boots, so your code is able to  
call those class methods as if they belonged to the original API of  
ActiveRecord::Base (in the example).

-- fxn