A Ruby module can be used as a namespace, a container for code such as constants or methods with related functionality.

The Math module is an example of a built-in Ruby module used as a namespace. It defines the constants E and PI as well as many common trigonometric and transcendental methods. The double-colon operator (::) is used to access constants in Ruby. The following example accesses the constant PI in the Math module:

irb(main):006:0> Math::PI
 => 3.141592653589793

Methods defined in a module are accessed with a dot (.), just like methods in a class:

irb(main):007:0> Math.sin(0)
 => 0.0

A Ruby module can also be used as a mixin to provide additional functionality to a class. Ruby only supports single inheritance; that is, a class can only inherit from a single parent class. Modules allow you to implement something similar to multiple inheritance: a class can include several modules, adding each module’s methods to its own.

You can add a module’s methods to a class in three ways, using include, prepend, or extend. I discuss the effect of each of these keywords next.

   class Person
➊    include Comparable

➋    def <=>(other)
       name <=> other.name
     end
   end

irb(main):008:0> p1 = Person.new("Tony")
 => #<Person:0x007f91b40140a8 @name="Tony">
irb(main):009:0> p2 = Person.new("Matt")
 => #<Person:0x007f91b285fea8 @name="Matt">
irb(main):010:0> p3 = Person.new("Wyatt")
 => #<Person:0x007f91b401fb88 @name="Wyatt">
irb(main):011:0> p1 > p2
 => true

irb(main):012:0> p1.between? p2, p3
 => true

  class Fibonacci
    def calc(n)
      return n if n < 2
➊     return calc(n - 1) + calc(n - 2)
    end
  end

irb(main):013:0> f = Fibonacci.new
 => #<Fibonacci:0x007fd8d3269518>
irb(main):014:0> f.calc 10
 => 55
irb(main):015:0> f.calc 30
 => 832040

   module Memoize
     def calc(n)
➊      @@memo ||= {}
➋      @@memo[n] ||= super
     end
   end

{
  0 => 0,
  1 => 1,
  2 => 1,
  3 => 2
}

irb(main):016:0> class Fibonacci
irb(main):017:1> prepend Memoize
irb(main):018:1> end
 => Fibonacci
irb(main):019:0> f.calc 40
 => 102334155

class Library
  def initialize(books)
    @books = books
  end
end

1 require 'forwardable'
  class Library
2   extend Forwardable
3   def_delegators :@books, :size, :push

    def initialize(books)
      @books = books
    end
  end

irb(main):020:0> lib = Library.new ["Neuromancer", "Snow Crash"]
 => #<Library:0x007fe6c91854e0 @books=["Neuromancer", "Snow Crash"]>
irb(main):021:0> lib.size
 => 2
irb(main):022:0> lib.push "The Hobbit"
 => ["Neuromancer", "Snow Crash", "The Hobbit"]
irb(main):023:0> lib.size
 => 3

Continuing with the simple Person class defined previously, we can find out a lot about this class in IRB. First, let’s see which classes and modules define methods for the Person class:

irb(main):024:0> Person.ancestors
 => [Person, Distractable, Comparable, Object, Kernel, BasicObject]

The class method ancestors returns a list of classes that Person inherits from and the modules it includes. In this example, Person, Object, and BasicObject are classes, whereas Distractable, Comparable, and Kernel are modules. You can find out which of these are classes and which are modules by calling the class method as explained in the Class section below.

Object is the default root of all Ruby objects. Object inherits from BasicObject and mixes in the Kernel module. BasicObject is the parent class of all classes in Ruby. You can think of it as a blank class that all other classes build on. Kernel defines many of the Ruby methods that are called without a receiver, such as puts and exit. Every time you call puts, you’re actually calling the instance method puts in the Kernel module.

The order of this list indicates the order in which Ruby searches for a called method. Ruby first looks for a method definition in the class Person and then continues looking through the list until the method is found. If Ruby doesn’t find the method, it raises a NoMethodError exception.

You can see a list of the class methods and instance methods defined by a class by calling methods and instance_methods, respectively. These lists include methods defined by all parent classes by default. Pass the parameter false to leave out only these:

irb(main):025:0> Person.methods
 => [:allocate, :new, :superclass, :freeze, :===, :==, ... ]
irb(main):026:0> Person.methods(false)
 => []
irb(main):027:0> Person.instance_methods(false)
 => [:name, :name=, :<=>]

The Person class contains almost 100 different class methods from its ancestors, but it defines none of its own, so the call to methods(false) returns an empty array. The call to instance_methods returns the name and name= methods defined by attr_accessor and the <=> method that we defined in the body of the class.

The last piece of the object model concerns the Person class itself. Everything in Ruby is an object, that is, an instance of a class. Therefore, the Person class must be an instance of some class.

irb(main):028:0> Person.class
 => Class

All Ruby classes are instances of the class Class. Defining a class, such as Person, creates an instance of the class Class and assigns it to a global constant, in this case Person. The most important method in Class is new, which is responsible for allocating memory for a new object and calling the initialize method.

Class has its own set of ancestors:

irb(main):029:0> Class.ancestors
 => [Class, Module, Object, Kernel, BasicObject]

Class inherits from the class Module, which inherits from Object as before. The Module class contains definitions of several of the methods used in this section such as ancestors and instance_methods.

Let’s say we have an application with a list of features that can be enabled for users. The User class stores these features in a hash named @features. If a user has access to a feature, the corresponding hash value will be true.

We want to add methods of the form can_ feature! and can_ feature? to enable a feature and check if a feature is enabled, respectively. Rather than write several mostly identical methods, we can iterate over the list of available features and use define_method, as shown here, to define the individual methods:

  class User
➊   FEATURES = ['create', 'update', 'delete']

    FEATURES.each do |f|
➋     define_method "can_#{f}!" do
        @features[f] = true
      end

➌     define_method "can_#{f}?" do
➍        !!@features[f]
       end
     end
     def initialize
       @features = {}
     end
   end

The User class first creates a constant array ➊ of available features named FEATURES. It then iterates over FEATURES using each and calls define_method to create a method of the form can_ feature! ➋ to allow a user access to a feature. Still inside the each block, the class also defines a method of the form can_ feature? ➌ that determines whether a user has access to the feature. This method converts the value @features[f] to either true or false by using two NOT operators ➍.

Now let’s create a new User and try the dynamically defined methods:

irb(main):001:0> user = User.new
 => #<User:0x007fc01b95abe0 @features={}>
irb(main):002:0> user.can_create!
 => true
irb(main):003:0> user.can_create?
 => true
irb(main):004:0> user.can_update?
 => false
irb(main):005:0> user.can_delete?
 => false

If you want more practice with define_method, see if you can add methods of the form cannot_feature!, which disables a feature for the user. More details are provided in Exercise 3 at the end of this chapter.

The class_eval method evaluates a string of code as if it were typed directly into the class definition. Using class_eval is an easy way to add instance methods to a class at runtime.

When I discussed attr_accessor in Chapter 1, you learned that it defines getter and setter methods for instance variables in a class, but I didn’t discuss exactly how those methods were defined. The attr_accessor method is built in to Ruby. You don’t need to define it yourself, but you can learn about class_eval by implementing your own version of attr_accessor.

➊ class Accessor
➋   def self.accessor(attr)
      class_eval "
➌       def #{attr}
          @#{attr}
          end

➍         def #{attr}=(val)
            @#{attr} = val
          end
         "
       end
     end

Here, you define a class named Accessor ➊ with a single class method named accessor ➋. This method works like the built-in attr_accessor. It accepts a single parameter representing the attribute for which you’re creating getter and setter methods. Pass the string to class_eval, which uses string interpolation to insert the value of attr as needed to define two methods. The first method has the same name as the attribute and returns the value of the attribute ➌. The second method is the attribute name followed by an equal sign. It sets the attribute to a specified value val ➍.

For example, if attr is :name, then accessor defines the methods name and name= by replacing attr with name in the specified places. This is a little hard to follow without an example. The following code uses the accessor method in a class:

➊ class Element < Accessor
➋   accessor :name

    def initialize(name)
      @name = name
    end
  end

First, you have the Element class inherit from the Accessor class ➊ so the accessor method is available. Then, you pass the name of the instance variable to accessor ➋. Here, you pass the symbol :name. When the program runs, the call to class_eval automatically generates this code inside the Element class:

➊ def name
    @name
  end

➋ def name=(val)
    @name = val
  end

The name method returns the current value of the instance variable @name ➊. The name= method accepts a value and assigns it to @name ➋. Test this by creating an instance of the Element class and trying to get and set the value of name:

➊ irb(main):001:0> e = Element.new "lead"
   => #<Element:0x007fc01b840110 @name="lead">
➋ irb(main):002:0> e.name = "gold"
   => "gold"
➌ irb(main):003:0> puts e.name
  gold
   => nil

First, create a new Element and initialize its name with "lead" ➊. Next, use the name= method to assign the new name "gold" ➋. Finally, use the name method to display the value of @name ➌. There you have it. With a bit of metaprogramming magic, you turned lead into gold.

Whenever Ruby can’t find a method, it calls method_missing on the receiver. This method receives the original method name as a symbol, an array of arguments, and any block passed to the method call.

By default, method_missing calls super, which passes the method up the ancestor chain until it finds an ancestor class containing the method. If the method reaches the BasicObject class, it raises a NoMethodError exception. You can override method_missing by defining your own implementation in a class to intercept these method calls and add your own behavior.

Let’s start with a simple example so you can see how it works. This class echoes any unknown method calls back to you three times:

class Echo
  def method_missing(name, *args, &block)
    word = name
    puts "#{word}, #{word}, #{word}"
  end
end

Now that method_missing is overridden, if you try to call a nonexistent method on an instance of this class, you’ll just see that method’s “echo” in the terminal:

irb(main):001:0> echo = Echo.new
 => #<Echo:0x007fa8131c9590>
irb(main):002:0> echo.hello
 => hello, hello, hello

A real-world use for method_missing is the Rails dynamic finder. Using dynamic finders, you can write Active Record queries like Post.find_by_title("First Post") instead of Post.where(title: "First Post").first.

Dynamic finders can be implemented using method_missing. Let’s define our own version of dynamic finders. Instead of method names like find_by_attribute, we’ll use query_by_attribute so we can avoid conflicts with the built-in methods.

Open the Post model at app/models/post.rb in your blog directory to follow along with this example:

  class Post < ActiveRecord::Base
    validates :title, :presence => true
    has_many :comments

➊   def self.method_missing(name, *args, &block)
➋     if name =~ /Aquery_by_(.+)z/
➌       where($1 => args[0]).first
      else
➍       super
      end
    end
 end

First, define the method_missing class method ➊ because our query_by_attribute method will be called on the Post class. Next, test the name against a regular expression ➋.

Finally, call the built-in where method ➌ using the string captured by the regular expression and the first argument passed to the method. Be sure to call super ➍ if the string doesn’t match; this ensures that unknown methods will be sent to the parent class.

The real dynamic finders also check to make sure the captured string matches an attribute of the model. If you try to call our query_by_attribute method with nonexistent column, it raises a SQLException.

irb(main):001:0> Post.query_by_title "First Post"
 => #<Post id: 1, ...>

Our implementation of query_by_attribute has one more problem:

irb(main):002:0> Post.respond_to? :query_by_title
 => false

Because we’re overriding method_missing to call this method, Ruby doesn’t know that the Post class can respond to it. To fix this, we need to also override the respond_to_missing? method in the Post model at app/models/post.rb.

   class Post < ActiveRecord::Base
     --snip--

     def self.respond_to_missing?(name, include_all=false)
➊      name.to_s.start_with?("query_by_") || super
    end
  end

Instead of the regular expression used in method_missing, we just check if the method name starts with "query_by_" ➊. If it does, this method returns true. Otherwise, super is called. Now restart the Rails console and try again:

irb(main):001:0> Post.respond_to? :query_by_title
 => true

With this change in place, respond_to? returns true as expected. Remember to always override respond_to_missing? when using method_missing. Otherwise, users of your class have no way of knowing which methods it accepts, and the duck typing techniques covered earlier will fail.