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/
Related
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
Why given a module like this:
module TestModule
module Configuration
# Return the configuration values set in this module
def options
puts "OPTIONS IS IN"
puts self.inspect
end
end
end
I get that the options method is in TestModule and not in Configuration?
EDIT: I add the gem that I am taking a look at, and the one that has given me this confusion:
Check this file: configuration.rb in line 37 the method options is defined.
In the class Client however, when options is called (line 11) is used doing Awesome instead of Configuration. Why is that? I don't see any class named Awesome where those modules are being mixed.
The gem in question does (in awesome.rb)
module Awesome
extend Configuration
end
So all of the methods on Awesome::Configuration (such as options) become singleton methods on the Awesome module
Technically, it's not part of either. It would have to be mixed in to a class to make it part of a class. To make it callable directly on the module, you need to prefix it with self. in the definition to make it a module method instead of an instance method:
def self.options
self #=> TestModule::Configuration
end
Here's a good tutorial on mixins which allows you to use the instance methods: http://rubylearning.com/satishtalim/modules_mixins.html
Let's say I have a bunch of related functions that have no persistent state, say various operations in a string differencing package. I can either define them in a class or module (using self) and they can be accessed the exact same way:
class Diff
def self.diff ...
def self.patch ...
end
or
module Diff
def self.diff ...
def self.patch ...
end
I can then do Diff.patch(...). Which is 'better' (or 'correct')?
The main reason I need to group them up is namespace issues, common function names are all used elsewhere.
Edit: Changed example from matrix to diff. Matrix is a terrible example as it does have state and everyone started explaining why it's better to write them as methods rather than answer the actual question. :(
In your two examples, you are not actually defining methods in a Class or a Module; you are defining singleton methods on an object which happens to be a Class or a Module, but could be just about any object. Here's an example with a String:
Diff = "Use me to access really cool methods"
def Diff.patch
# ...
end
You can do any of these and that will work, but the best way to group related methods is in a Module as normal instance methods (i.e. without self.):
module Diff
extend self # This makes the instance methods available to the Diff module itself
def diff ... # no self.
def patch ...
end
Now you can:
use this functionality from within any Class (with include Diff) or from any object (with extend Diff)
an example of this use is the extend self line which makes it possible to call Diff.patch.
even use these methods in the global namespace
For example, in irb:
class Foo
include Diff
end
Foo.new.patch # => calls the patch method
Diff.patch # => also calls Diff.patch
include Diff # => now you can call methods directly:
patch # => also calls the patch method
Note: the extend self will "modify" the Diff module object itself but it won't have any effect on inclusions of the module. Same thing happens for a def self.foo, the foo won't be available to any class including it. In short, only instance methods of Diff are imported with an include (or an extend), not the singleton methods. Only subclassing a class will provide inheritance of both instance and singleton methods.
When you actually want the inclusion of a module to provide both instance methods and singleton methods, it's not completely easy. You have to use the self.included hook:
module Foo
def some_instance_method; end
module ClassMethods
def some_singleton_method; end
end
def self.included(base)
base.send :extend, ClassMethods
end
def self.will_not_be_included_in_any_way; end
end
class Bar
include Foo
end
# Bar has now instance methods:
Bar.new.some_instance_method # => nil
# and singleton methods:
Bar.some_singleton_method # => nil
The main difference between modules and classes is that you can not instantiate a module; you can't do obj = MyModule.new. The assumption of your question is that you don't want to instantiate anything, so I recommend just using a module.
Still you should reconsider your approach: rather than using arrays of arrays or whatever you are doing to represent a Matrix, it would be more elegant to make your own class to represent a matrix, or find a good class that someone else has already written.
Ruby Modules are used to specify behaviour, pieces of related functionality.
Ruby Classes are used to specify both state and behaviour, a singular entity.
There is a maxim in software design that says that code is a liability, so use the less code possible. In the case of Ruby, the difference in code lines is cero. So you can use either way (if you don't need to save state)
If you want to be a purist, then use a Module, since you won't be using the State functionality. But I wouldn't say that using a class is wrong.
As a trivia info: In Ruby a Class is a kind of Module.
http://www.ruby-doc.org/core-1.9.3/Class.html
The following also works
Matrix = Object.new
def Matrix.add ...
def Matrix.equals ...
That's because so-called "class methods" are just methods added to a single object, and it doesn't really matter what that object class is.
As a matter of form, the Module is more correct. You can still create instances of the class, even if it has only class methods. You can think of a module here as a static class of C# or Java. Classes also always have the instance related methods (new, allocate, etc.). Use the Module. Class methods usually have something to do with objects (creating them, manipulating them).
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