Modules

Modules serve two purposes:

  • as namespaces for defining other types, methods and constants
  • as partial types that can be mixed in other types

An example of a module as a namespace:

  1. module Curses
  2.   class Window
  3.   end
  4. end
  6. Curses::Window.new

Library authors are advised to put their definitions inside a module to avoid name clashes. The standard library usually doesn’t have a namespace as its types and methods are very common, to avoid writing long names.

To use a module as a partial type you use include or extend.

An include makes a type include methods defined in that module as instance methods:

  1. module ItemsSize
  2.   def size
  3.     items.size
  4.   end
  5. end
  7. class Items
  8.   include ItemsSize
  10.   def items
  11.     [1, 2, 3]
  12.   end
  13. end
  15. items = Items.new
  16. items.size # => 3

In the above example, it is as if we pasted the size method from the module into the Items class. The way this really works is by making each type have a list of ancestors, or parents. By default this list starts with the superclass. As modules are included they are prepended to this list. When a method is not found in a type it is looked up in this list. When you invoke super, the first type in this ancestors list is used.

A module can include other modules, so when a method is not found in it it will be looked up in the included modules.

An extend makes a type include methods defined in that module as class methods:

  1. module SomeSize
  2.   def size
  3.     3
  4.   end
  5. end
  7. class Items
  8.   extend SomeSize
  9. end
  11. Items.size # => 3

Both include and extend make constants defined in the module available to the including/extending type.

Both of them can be used at the top level to avoid writing a namespace over and over (although the chances of name clashes increase):

  1. module SomeModule
  2.   class SomeType
  3.   end
  5.   def some_method
  6.     1
  7.   end
  8. end
  10. include SomeModule
  12. SomeType.new # OK, same as SomeModule::SomeType
  13. some_method  # OK, 1

extend self

A common pattern for modules is extend self:

  1. module Base64
  2.   extend self
  4.   def encode64(string)
  5.     # ...
  6.   end
  8.   def decode64(string)
  9.     # ...
  10.   end
  11. end

In this way a module can be used as a namespace:

  1. Base64.encode64 "hello" # => "aGVsbG8="

But also it can be included in the program and its methods can be invoked without a namespace:

  1. include Base64
  3. encode64 "hello" # => "aGVsbG8="

For this to be useful the method name should have some reference to the module, otherwise chances of name clashes are high.

A module cannot be instantiated:

  1. module Moo
  2. end
  4. Moo.new   # undefined method 'new' for Moo:Module

Module Type Checking

Modules can also be used for type checking.

If we define two modules with names A and B:

  1. module A; end
  2. module B; end

These can be included into classes:

  1. class One
  2.   include A
  3. end
  5. class Two
  6.   include B
  7. end
  9. class Three < Two
  10.   include A
  11. end

We can then type check against instances of these classes with not only their class, but the
included modules as well:

  1. one = One.new
  2. typeof(one)   # => One
  3. one.is_a?(A)  # => true
  4. one.is_a?(B)  # => false
  6. three = Three.new
  7. typeof(three)   # => Three
  8. three.is_a?(A)  # => true
  9. three.is_a?(B)  # => true

This allows you to define arrays and methods based on module type instead of class:

  2. one = One.new
  3. two = Two.new
  4. three = Three.new
  6. new_array = Array(A).new
  7. new_array << one    # Ok, One inherits module A
  8. new_array << three  # Ok, Three includes module A
  10. new_array << two    # Error, because Two does not inherit module A