module - What is the difference between include and extend in Ruby?

Question

Just getting my head around Ruby metaprogramming. The mixin/modules always manage to confuse me.

• include: mixes in specified module methods as instance methods in the target class
• extend: mixes in specified module methods as class methods in the target class

So is the major difference just this or is a bigger dragon lurking? e.g.

module ReusableModule
  def module_method
    puts "Module Method: Hi there!"
  end
end

class ClassThatIncludes
  include ReusableModule
end
class ClassThatExtends
  extend ReusableModule
end

puts "Include"
ClassThatIncludes.new.module_method       # "Module Method: Hi there!"
puts "Extend"
ClassThatExtends.module_method            # "Module Method: Hi there!"

Answer 1

extend - adds the specified module's methods and constants to the target's metaclass (i.e. the singleton class) e.g.

• if you call Klazz.extend(Mod), now Klazz has Mod's methods (as class methods)
• if you call obj.extend(Mod), now obj has Mod's methods (as instance methods), but no other instance of of obj.class has those methods added.
• extend is a public method

include - By default, it mixes in the specified module's methods as instance methods in the target module/class. e.g.

• if you call class Klazz; include Mod; end;, now all instances of Klazz have access to Mod's methods (as instance methods)
• include is a private method, because it's intended to be called from within the container class/module.

However, modules very often override include's behavior by monkey-patching the included method. This is very prominent in legacy Rails code. more details from Yehuda Katz.

Further details about include, with its default behavior, assuming you've run the following code

class Klazz
  include Mod
end

• If Mod is already included in Klazz, or one of its ancestors, the include statement has no effect
• It also includes Mod's constants in Klazz, as long as they don't clash
• It gives Klazz access to Mod's module variables, e.g. @@foo or @@bar
• raises ArgumentError if there are cyclic includes
• Attaches the module as the caller's immediate ancestor (i.e. It adds Mod to Klazz.ancestors, but Mod is not added to the chain of Klazz.superclass.superclass.superclass. So, calling super in Klazz#foo will check for Mod#foo before checking to Klazz's real superclass's foo method. See the RubySpec for details.).

Of course, the ruby core documentation is always the best place to go for these things. The RubySpec project was also a fantastic resource, because they documented the functionality precisely.

• #include RubySpec rubydoc
• #included RubySpec rubydoc
• #extend RubySpec rubydoc
• #extended RubySpec rubydoc
• #extend_object RubySpec rubydoc
• #append_features RubySpec rubydoc