I am reading this explanation of module methods for Ruby and how they are different from instance methods for classes. Here is the explanation I am reading:
Remember that unlike an instance method, a module method needs to be
defined on the module itself. How do you access the module? Recall
that inside a module definition, self refers to the module being
defined. So you'll need to define the method using the form self.xxx.
I don't totally get it. When we defined methods inside Classes, we didn't have to define it on the class itself. We merely called it on the instantiated objects of the classes.
Why do we need to define module methods on the module itself using the term "self"? What's the purpose of this? Why can't we just define module methods without using the term self? Here is how my module skeleton looks:
module GameTurn
def self.take_turn(player)
end
There's two kinds of module methods:
Those that are intended to be mixed in to other modules or classes: "Mixins"
Those that are intended to be used directly: "Exposed Methods"
For example:
module Example
def self.exposed_method
# This method is called as Example.exposed_Method
end
def mixin_method
# This method must be imported somewhere else with include or extend
# or it cannot be used.
end
end
You have two on a class as well:
Those that are called only on instances of the class: "Instance methods"
Those that are called directly on the class: "Class methods"
These are also called "static methods" in other languages.
Example:
class ExampleClass
def self.class_method
# This can be called as ExampleClass.class_method
end
def instance_method
# This can only be called on an instance: ExampleClass.new.instance_method
end
end
Related
I have a class Brand that includes a module SimpleURLSanitizer. The module has a class method defined as below:
class Brand
include SimpleURLSanitizer
end
module SimpleURLSanitizer
def self.included base
base.send :extend, self
end
end
Since we are including the module, it will only have access to the module's instance methods. But the class method included will be called when the module is included in the class. The base is the Brand class. What is this included method doing? Is the self inside this method referring to the module or the Brand class? How does it work?
As you're including SimpleURLSanitizer in a class, all the methods of SimpleURLSanitizer will be accessible as instance method. This is the default behavior.
The included part is also making sure that, you can access those methods as class methods.
The base and self refer to Brand and SimpleURLSanitizer, respectively. The command will be expanded as:
Brand.send(:extend, SimpleURLSanitizer)
which can be rewritten as:
class Brand
extend SimpleURLSanitizer
end
and means that the instance methods of SimpleURLSanitizer will also become class methods of Brand.
The methods in Math can be invoked like a class method:
Math.cos(0)
but also can be include-d like instance method:
include Math
cos(0)
In contrast, the following modules can be invoked in one way but not the other:
module Foo
def bar
end
end
Foo.bar() # NoMethodError for this call
include Foo
bar() # but this call is fine
Singleton method:
module Foo
def self.bar
end
end
Foo.bar() # this call is fine
include Foo
bar() # but not this one
Any idea how to write a module like Math?
There're a few ways to get singleton methods, so I'm going to go over those first. We'll get to the part that lets the include Math work in a minute. So, first, if you're in a module or class body, you can define a singleton method as a method of self, like so:
module Foo
# Define bar as a method on self (the Foo module), thereby making
# it a singleton method.
def self.bar
"baz"
end
end
Alternatively, you can define them as methods on a module or class's singleton class:
module Foo
# Opens the singleton class of self (the Foo module). This makes
# bar a singleton method (see Module#define_singleton_method for
# some more on that).
class <<self
def bar
"baz"
end
end
end
include Math, Having Your Methods, and Eating Them Too
Thirdly, if you want methods as both instance and singleton methods, you can use extend. This allows you to include the module somewhere and call its methods without qualification or at least with differing qualification, depending on where you include the module (sort of -- that's beyond the scope of this, though). You can also extend self or extend using another module (containing instance methods) to add them as singleton methods when in a module or class body. This might sound more complicated than it probably looks:
module Foo
def bar
"baz"
end
# Extending self will add the instance methods of self as
# methods on the object self -- which happens to be a module,
# so you basically get class methods from the instance methods.
extend self
end
This last case allows you to also include the module in another module or class and gain bar as an instance method as well, so what you do depends on what you need. In general, I prefer the first route if I'm just defining a singleton method and it's all I'll need. The second option is more or less equivalent, but also allows you to use alias_method and so on. Qualified access is next to godliness, as far as I'm concerned.
The third option, however, — using extend self — is good for doing what you're asking about with include Math, where you want to be able to both call a function as a singleton method (Math.cos(0)) and include the module to access and call the methods without qualifying them with the module name (cos(0)). If you want that, you can do one of the following:
Define the method twice, both as a singleton method and as an instance method. This is not preferrable.
Define them in another module and both include and extend using that module. This is handy if you want to use the module in multiple places.
extend self. Extending using self is probably the best choice here, since it's simple, reduces duplicate code, and it's sufficient for the purpose of the question.
So there you go, instance methods and singleton methods living side-by-side in harmony, just like Holan and Hamlet.
That's what Module#module_function is for.
module A
end
class Klass
include A
end
How does this include influence Klass? Does it simply put Klass into module A or do something more?
Short Answer: If you have some methods inside your module and you use include in a class, those methods can be used in the class.
Module A
def shout
puts "HEY THERE!!!!"
end
end
class Klass
include A
end
# Create instance of Klass
instance = Klass.new
# Produces "HEY THERE!!!!"
instance.shout
The include method takes all the methods from another module and
includes them into the current module. This is a language-level thing
as opposed to a file-level thing as with require. The include method
is the primary way to "extend" classes with other modules (usually
referred to as mix-ins). For example, if your class defines the method
"each", you can include the mixin module Enumerable and it can act as
a collection. This can be confusing as the include verb is used very
differently in other languages.
from here: What is the difference between include and require in Ruby?
also take a look at this page: http://www.ruby-doc.org/docs/ProgrammingRuby/html/tut_modules.html it has a verbose explanation about how include works.
include is one of the ways to include methods of a Module in another Module or Class.
Please read my article on how that affects method calls in Ruby/
It looks like const_missing is an instance method of Object. If so, why doesn't this code work?
module Extensions
def const_missing(c)
puts c
end
end
class Object
include Extensions
end
NonExistent.new
In order to get it to function correctly, I have to change def const_missing to def Object.const_missing. Why?
This is just a consequence of the way method calls are resolved in Ruby.
First, singleton methods are checked. Then instance methods of the class, followed by the ancestors (which will be the included modules, then superclasses with their included modules).
So you could define Object.const_missing directly, or include your Module in the singleton class of Object:
class << Object
include Extensions
end
NonExistent # => prints "NonExistent"
You could also monkeypatch Module#const_missing.
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!"
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
What you have said is correct. However, there is more to it than that.
If you have a class Klazz and module Mod, including Mod in Klazz gives instances of Klazz access to Mod's methods. Or you can extend Klazz with Mod giving the class Klazz access to Mod's methods. But you can also extend an arbitrary object with o.extend Mod. In this case the individual object gets Mod's methods even though all other objects with the same class as o do not.
That's correct.
Behind the scenes, include is actually an alias for append_features, which (from the docs):
Ruby's default implementation is to
add the constants, methods, and module
variables of this module to aModule if
this module has not already been added
to aModule or one of its ancestors.
When you include a module into a class, the module methods are imported as instance methods.
However, when you extend a module into a class, the module methods are imported as class methods.
For example, if we have a module Module_test defined as follows:
module Module_test
def func
puts "M - in module"
end
end
Now, for include module. If we define the class A as follows:
class A
include Module_test
end
a = A.new
a.func
The output will be: M - in module.
If we replace the line include Module_test with extend Module_test and run the code again, we receive the following error: undefined method 'func' for #<A:instance_num> (NoMethodError).
Changing the method call a.func to A.func, the output changes to: M - in module.
From the above code execution, it is clear that when we include a module, its methods become instance methods and when we extend a module, its methods become class methods.
All the other answers are good, including the tip to dig through RubySpecs:
https://github.com/rubyspec/rubyspec/blob/master/core/module/include_spec.rb
https://github.com/rubyspec/rubyspec/blob/master/core/module/extend_object_spec.rb
As for use cases:
If you include module ReusableModule in class ClassThatIncludes, the methods, constants, classes, submodules, and other declarations gets referenced.
If you extend class ClassThatExtends with module ReusableModule, then the methods and constants gets copied. Obviously, if you are not careful, you can waste a lot of memory by dynamically duplicating definitions.
If you use ActiveSupport::Concern, the .included() functionality lets you rewrite the including class directly. module ClassMethods inside a Concern gets extended (copied) into the including class.
I would also like to explain the mechanism as it works. If I am not right please correct.
When we use include we are adding a linkage from our class to a module which contains some methods.
class A
include MyMOd
end
a = A.new
a.some_method
Objects don't have methods, only clases and modules do.
So when a receives mesage some_method it begin search method some_method in a's eigen class, then in A class and then in linked to A class modules if there are some (in reverse order, last included wins).
When we use extend we are adding linkage to a module in object's eigen class.
So if we use A.new.extend(MyMod) we are adding linkage to our module to A's instance eigen class or a' class.
And if we use A.extend(MyMod) we are adding linkage to A(object's, classes are also objects) eigenclass A'.
so method lookup path for a is as follows:
a => a' => linked modules to a' class => A.
also there is a prepend method which changes lookup path:
a => a' => prepended modulesto A => A => included module to A
sorry for my bad english.
I came across a very useful article that compares include, extend and prepend methods used inside a class:
include adds module methods as instance methods to the class, whereas extend adds module methods as class methods. The module being included or extended must be defined accordingly