Get the Lowdown on Ruby Modules

Modules are wonderfully flexible language constructs which can be applied to a wide variety of use cases, such as namespacing, inheritance, and decorating. However, some developers are still confused about how modules work and how they interact with their own code. This article aims to shed some light on Modules and their usage.

The Ruby Object Model (ROM)

As with most things Ruby, modules are very easy to use, once we understand how they fit into the Ruby Object Model (ROM). The ROM is populated by objects that are classes (class-objects, a.k.a. Classes) and objects that are instances of classes (instance-objects). Oh, and Modules too! Let’s create a couple of classes:

class Car
  def drive
    "driving"
  end
end

class Trabant < Car
end

If we visualize the ROM on a 2D plain, then the object hierarchy looks like this:

The class-objects our class is derived from live above our class. The class-objects deriving from our class live below it. To the right of our class, lives its eigenclass (a.k.a singleton class or meta-class). Eigenclasses are class-objects, too, and as such, they have superclasses, usually the eigenclass of our class’s superclass or, in the case of instance objects, the class of the object itself. A full description of eigenclasses is beyond the scope of this article and deserves an article in itself. For now, don’t worry too much about them, just know that they are there and that they have a purpose.

So, what happens when we instantiate an object based on our class?

my_car = Car.new

Ruby will create our object’s eigenclass directly under our Car class. It will place our new instance (my_car) to the left of its eigenclass and outside the object hierarchy.

We can actually verify all this in Ruby’s irb:

  my_car.class
        => Car 
> my_car.singleton_class
        => #<Class:#<Car:0x0000000165e568>> 
> my_car.singleton_class.class
        => Class 
> my_car.singleton_class.superclass
        => Car

Method Lookup

Let’s call a method on our object?

my_car.drive

The object we call a method on (my_car) is called the receiver object. Ruby has a very simple algorithm for looking up methods:

receiver –> look to the right –> look up

When we call the drive method on my_car, Ruby will first look to the right in my_car‘s eigenclass object. It won’t find the method definition there, so it will look up to the Car objects, where it will find the definition of drive. Knowing this makes understanding how to use modules easy.

Modules in Their Environment

There are three things we can do with a module:

1. Include it in our class-objects
2. Prepend it to our class-objects
3. Extend our class objects or instance objects with it

The Helicopter Rule

Ruby slots Modules into the ROM by following what I call the Helicopter rule. I call it that because in my warped imagination the diagram looks like a helicopter, as shown in the above image. The Helicopter Rule means:

Let’s verify this in code:

  module A; end
  module B; end
  module C; end

  class MyClass
    include A
    prepend B
    extend C
          end

   MyClass.ancestors
   => [B, MyClass, A, Object, Kernel, BasicObject] 
   MyClass.singleton_class.ancestors
   => [#<Class:MyClass>, C, #<Class:Object>, #<Class:BasicObject>, Class, Module, Object, Kernel, BasicObject]

We observe that module A is placed directly above MyClass (included), module B is placed directly below MyClass (prepended) and module C is placed directly above MyClass‘s eigenclass (extended)

NOTE: Calling the superclass method on a class object will give us the next higher class in the ancestor chain above our class. However, as Modules aren’t technically Classes, superclass won’t show us any modules directly above our class. For that, we need to use the ancestors method.

Including

Let’s open our Car class and include a Module:

module V12Engine
  def start; "...roar!"; end
end

class Car
  include V12Engine
end

When we include a module in our class, Ruby places it directly above our class. This means that when we call a method on our instance object, Ruby will find it in the object hierarchy and run it:

my_car.start 
=>  ...roar!"

This is the usual way to implement multiple inheritance in Ruby, as we can include many modules in our class, thereby giving it a lot of extra functionality. Modules used to that effect are known as “mixins”.

Note: It also means that if we define a method with the same name in our Car class, Ruby will find and run this instead and our Module method will never be called.

Prepending

When we prepend a module to our class, Ruby places it directly below our class. The means that, during method lookup, Ruby will encounter the methods defined in the Module before the methods defined in our Class. As a result, any module methods will effectively override any class methods with the same name. Let’s try this:

module ElectricEngine
  def drive; "eco-driving!"; end
end

class Car
  prepend ElectricEngine
end

my_car = Car.new

my_car.drive
=> eco-driving!

Observe that if we now call the drive method on my_car, we’re getting the prepended module’s implementation of the method, instead of the Car class implementation. Prepending modules can be very useful when we want to scope our method logic according to various external conditions. Say, for example, we want to measure our methods’ performance when running in a test environment. Instead of polluting our methods with if statements and instrumentation code, we can put our specialized methods in a separate module and prepend the module to our class only if we’re in a test environment:

module Instrumentable
  require 'objspace'
  def drive
    puts ObjectSpace.count_objects[:FREE]
    super
    puts ObjectSpace.count_objects[:FREE]
  end
end

class Car
  prepend Instrumentable if ENV['RACK_ENV'] = 'test'
end

my_car = Car.new.drive
=> 711
=> driving
=> 678

Including and Prepending with Instances

As instance objects are placed outside the ROM hierarchy, there is no ‘above’ or ‘below’ them where we can place modules (see the Method Lookup diagram). This means that we cannot include or prepend modules to instance objects.

Extending Classes

When we extend our class object with a module, Ruby places it directly above our object’s eigenclass:

module SuperCar
  def fly; "flying!"; end
end


class Car
  extend SuperCar
end

Our Car instances can’t access the fly method, as the method lookup will start at the car instance, my_car, move right to the eigenclass my_car and then up to the Car class and its ancestors. The fly method will never be found in that path:

my_car.fly
=> NoMethodError: undefined method `fly' for #<Car:0x000000019ae8d0>

But what if we call the method on our class object instead?

Car.fly
=> flying

Our receiver object is now the Car class itself. Ruby will first look to the right (Car) and then up to SuperCar module where, lo and behold, it will find the fly method. So, extending a Class with a Module, effectively gives our Class new class methods.

Extending Instances

We can extend a specific instance of our Class, like so:

my_car.extend(SuperCar)

This will place the SuperCar module above our object’s eigen-class.

We can now call fly on our car:

my_car.fly
=> flying

But not on any other car:

another_car.fly
=> NoMethodError: undefined method `fly' for #<Car:0x000000012ae868>

Extending an instance object with a Module is a great way to dynamically decorate specific Class instances. I use it all the time in Rails applications to easily and quickly implement the Presenter pattern (i.e. model objects that I want to show in my views)

<%=  my_article.extend(Presentable).title %>

Epilogue

There’s much more to Modules than can be covered in a single article. Understanding how Modules fit into the Ruby Object Model is essential in order to use them fully and creatively. Let us know how Modules fit into your designs and all the cool things you do with them!

Frequently Asked Questions about Ruby Modules