Prev chevron_right

Ruby Methods, Part 1

Sep 09, 2024 Greg Yut
tag Ruby Tech

Introduction

The Ruby programming language is a developer-friendly power tool that provides rich facilities to solve programming problems. In addition to its object-oriented representation, a key feature of Ruby is its flexible handling of methods–the actions an object can perform. Because the method patterns are so flexible, their full capabilities aren’t immediately obvious. Methods can, of course, be called on objects, but the possibilities for methods go way beyond that simple pattern.

This series on Ruby methods will dig below the surface to show how methods work and interesting ways to use them. It’s a practical guide more than a technical language analysis. The goal is to provide a mental model, a map, of how to define and use Ruby methods.

The series assumes familiarity with Ruby. This isn’t an introductory tutorial. Topics covered include the types of methods (singleton, instance, class), how to create methods statically and dynamically, how to organize methods (include, extend), and how to find and call methods.

Part 1 begins with a diagram of an example object model, followed by the Ruby code to create it, followed by the most interesting bits about Ruby methods, all while sharing snippets of Ruby code to demonstrate the ideas.

This material comes from time spent using Ruby, but it’s also influenced by the excellent explanation by Dave Thomas in Programming Ruby, Third Edition, specifically Chapter 24 on Metaprogramming. Also helpful is Vitalii Paprotskyi’s article on singletons and self.

Example Object Model

Below is a diagram of the object model created by the code in the next section. The object model is pretty simple, yet rich enough to explore many features of Ruby methods.

Notice that Ruby uses anonymous classes (the green boxes) to inject both modules and singleton methods into both the superclass and class hierarchies.

Ruby Methods

Figure 1: Ruby Methods

The diagram comes with a couple of caveats.

First, the diagram is not intended to accurately represent the internal Ruby implementation. The picture instead reflects the output when exploring the model by calling Ruby methods. For example, Ruby knows the order that modules were included (M1 before M2, for example). And it knows the difference between extending object o1 with M3 and adding direct singleton methods m01 and m04 to object o1, regardless of how Ruby represents this internally.

Second, the diagram shows three different types of singleton classes (the turquoise bubbles 1, 2, and 3), but they are all the same mechanism. For clarity, the diagram distinguishes the singleton classes based on the associated object type (instance object, Module, or Class), but the singleton behavior is the same for all three. The singleton class and associated singleton methods are a key feature of Ruby.

Example Code

Below is the example Ruby code that creates the classes, modules, objects, and methods shown in the object model in the previous section.

Here’s a quick tour of the model: Object o1 is an instance object of class C1. Class C2 in a superclass of class C1. Methods are added to objects and classes using modules M1 thru M4, along with Ruby’s include and extend features.

Singleton methods are added using three different, but equally-valid, patterns:

  • def self.m14
  • class << self
  • o1.define_singleton_method(:m01)

module M1
  def m07
    "M1 module method m07"
  end
  def self.m13
    "M1 module method m13"
  end
end

module M2
  def m09
    "M2 module method m09"
  end
end

module M3
  def m10
    "M3 module method m10"
  end
  def self.m12
    "M3 module method m12"
  end
end

module M4
  def m11
    "M4 module method m11"
  end
end

class C2
  def m06
    "C2 instance method m06"
  end
  def self.m14
    "C2 class method (singleton) m14"
  end
end

class C1 < C2
  include M1
  include M2
  extend M3
  extend M4

  def m02
    "C1 instance method m02"
  end

  def self.m08
    "C1 class method (singleton) m08"
  end

  class << self
    def m03
      "C1 class method (singleton) m03"
    end
  end

end

class Object
  def self.m15
    "Object m15"
  end
end

o1 = C1.new
class << o1
  def m04
    "o1 object singleton method m04"
  end
end
o1.define_singleton_method(:m01) {"o1 object singleton method m01"}
C1.define_singleton_method(:m05) {"C1 class method (singleton) m05"}
o1.extend(M3)

begin
  puts "Ruby Version: #{RUBY_VERSION}"
  puts "Server: #{Gem::Platform.local.os}"
end

Ruby Version: 3.3.3
Server: darwin

Class hierarchies and method calls

With both the object model and the code that created it in hand, questions about the methods can be answered. What are the different types of methods and where are they in the model? Which methods are callable by which objects and classes? Ruby has facilities to build, organize, and explore the object model and the methods.

Classes are objects

Methods are called on objects. The object receiving the method call can be given explicitly, like o1.m02, in which case o1 is the receiver of the method call m02, or implicitly, like m02, in which case the receiver is self (the current object).

“In Ruby, everything is an object.” Well, probably not exactly, but importantly, classes are objects. This seems unnatural at first but becomes more natural with exposure. Because classes are objects, the method search for a class like C1 is the same as for an instantiated object like o1.

Class hierarchy

Ruby finds methods by looking “to the right and up.” That is, Ruby first finds the class of the receiver, then looks up the superclass hierarchy, which is shown in Figure 1 and explored in the code below. For instantiated object o1, Ruby searches for methods in the class hierarchy C1 → C2 → Object → Basic Object. For class C1, Ruby searches for methods in the class hierarchy Class → Module → Object → Basic Object.

Interestingly, the class of every class object, like C1 or C2, is Class. And the class of Class is Class. Notice also that the modules included in C1 (like M2 and M1) are considered ancestors of C1.

begin
  puts "o1.class: #{o1.class}"
  puts "o1.class.superclass: #{o1.class.superclass}"
  puts "o1.class.superclass.superclass: #{o1.class.superclass.superclass}"
  puts "o1.class.superclass.superclass.superclass: #{o1.class.superclass.superclass.superclass}"
  puts "C1.class: #{C1.class}"
  puts "C1.class.superclass: #{C1.class.superclass}"
  puts "C1.class.superclass.superclass: #{C1.class.superclass.superclass}"
  puts "C1.class.superclass.superclass.superclass: #{C1.class.superclass.superclass.superclass}"
  puts "C1.ancestors: #{C1.ancestors}"
end

o1.class: C1
o1.class.superclass: C2
o1.class.superclass.superclass: Object
o1.class.superclass.superclass.superclass: BasicObject
C1.class: Class
C1.class.superclass: Module
C1.class.superclass.superclass: Object
C1.class.superclass.superclass.superclass: BasicObject
C1.ancestors: [C1, M2, M1, C2, Object, PP::ObjectMixin, Kernel, BasicObject]

Method types

To get a list of the methods that object o1 will respond to, call o1.methods. Likewise, to get a list of the methods that class C1 will respond to, call C1.methods. In either case, an object’s methods include its singleton methods and the instance methods of its class.

methods = singleton methods + instance method of the class

Singleton methods

Every object, whether it’s an instance object or a class object, can have a singleton class. The singleton class is sometimes called an eigenclass. As seen in Figure 1, the singleton classes (the turquoise bubbles 1, 2, and 3) are the first classes in the class hierarchy. That is, the singleton class is injected between the object and its class. And singleton methods are methods defined on the singleton class.

Since Ruby looks for methods in the class hierarchy, the singleton methods will be found first, so singleton methods have the highest precedence. Figure 1 also shows that the singleton class and its methods fit neatly in the class hierarchy, without any special handling. So the method lookup process remains unchanged–no special handling is needed to find singleton methods.

The unique thing about singleton methods, as indicated by their name, is that they are defined only on that one object. For example, instance object o1 has a singleton method m04, and method m04 is only available for o1, not other instances of C1. Likewise, class C1 has singleton method m05, and method m05 is only available for class C1, not other instances of class Class.

Exploring singleton methods

Ruby provides the singleton_methods method to access an object’s singleton methods. As shown in the code below and confirmed in Figure 1, object o1 has three singleton methods [:m04, :m01, :m10]. Methods m01 and m04 are defined as singleton methods on o1 directly, while m10 is a singleton method of o1 because o1 was extended with module M3. Extending an object with a module adds the module methods as singleton methods on the object.

Class C1 has seven singleton methods, [:m08, :m03, :m05, :m11, :m10, :m14, :m15]. The first three are defined as singleton methods directly on C1. The next two, m11 and m10, are singleton methods because C1 is extended with modules M3 and M4. The last two, m14 and m15, are singleton methods of C1 because the singleton methods of a class include the singleton methods of its superclasses, C2 and Object in this case.

To see just the immediate singleton methods of an object, excluding extended modules and superclasses, use singleton_methods(false). C1 has three immediate singleton methods, [:m08, :m03, :m05].

Notice that the order of the methods returned from singleton_methods reflects the position of the methods in the object model. Method search begins at the bottom of the class hierarchy and moves up.

begin
  puts "o1.singleton_methods: #{o1.singleton_methods}"
  puts "C1.singleton_methods: #{C1.singleton_methods}"
  puts "C2.singleton_methods: #{C2.singleton_methods}"
  puts "Object.singleton_methods: #{Object.singleton_methods}"
  puts "C1.singleton_methods(false): #{C1.singleton_methods(false)}"
end

o1.singleton_methods: [:m04, :m01, :m10]
C1.singleton_methods: [:m08, :m03, :m05, :m11, :m10, :m14, :m15]
C2.singleton_methods: [:m14, :m15]
Object.singleton_methods: [:m15]
C1.singleton_methods(false): [:m08, :m03, :m05]

Instance methods

A class can have a list of method definitions. These instance methods can be called on the objects instantiated from the class, not on the class itself. And the instance methods for a class also include all of the instance methods up the class’s superclass hierarchy.

As mentioned earlier, an object’s methods include its singleton methods and the instance methods of its class. These are the instance methods of its class.

Exploring instance methods

Ruby provides the instance_methods method to access instance methods of a class. As shown in the code below, C1.instance_methods returns an array of the 60 instance methods of C1.

Modules can also have instance methods. M1 has just one instance method, m07.

An instantiated object like o1, on the other hand, is neither a class nor a module and therefore does not have instance methods. So o1.instance_methods is not defined. Instead, it’s the instance methods of the object’s class that can be called on the object.

Also notice that the instance methods of C1 include the instance methods of its superclass C2.

begin
  puts "C1.instance_methods.count: #{C1.instance_methods.count}"
  puts "M1.instance_methods: #{M1.instance_methods}"
  puts "defined?(o1.instance_methods): #{defined?(o1.instance_methods) ? "true" : "false"}"
  puts "o1.class.instance_methods.count: #{o1.class.instance_methods.count}"
  puts "C1.instance_methods.first(5): #{C1.instance_methods.first(5)}"
  puts "C2.instance_methods.first(2): #{C2.instance_methods.first(2)}"
end

C1.instance_methods.count: 60
M1.instance_methods: [:m07]
defined?(o1.instance_methods): false
o1.class.instance_methods.count: 60
C1.instance_methods.first(5): [:m02, :m09, :m07, :m06, :pretty_print]
C2.instance_methods.first(2): [:m06, :pretty_print]

Class methods

In Ruby, it’s not uncommon to talk about class methods. These are methods that can be called on a class object, like C1 or C2. But technically, Ruby does not have class methods. Consequently, Ruby does not have a class_methods method.

Since classes are objects, the methods that can be called on a class are its singleton methods plus the instance methods of its class (just like any other object). The singleton methods of the class are defined as mentioned earlier in the section on singleton methods. And since the class of a class is Class, the instance methods come from Class and its superclass hierarchy.

Exploring class methods

The snippet below shows that the methods of C1 (sometimes called class methods) are found just like for any other object, using C1.methods, and C1 has a long list of methods. Looking at just the first ten of these shows that the first seven (m08 thru m15) are singleton methods defined on C1 and its superclass hierarchy. The remaining methods are instance methods on Class and its superclass hierarchy.

begin
  puts "C1.methods.count: #{C1.methods.count}"
  puts "C1.methods.first(10): #{C1.methods.first(10)}"
  puts "C1.singleton_methods: #{C1.singleton_methods}"
  puts "C1.class: #{C1.class}"
  puts "C1.class.instance_methods.first(3): #{C1.class.instance_methods.first(3)}"
end

C1.methods.count: 122
C1.methods.first(10): [:m08, :m03, :m05, :m11, :m10, :m14, :m15, :allocate, :attached_object, :superclass]
C1.singleton_methods: [:m08, :m03, :m05, :m11, :m10, :m14, :m15]
C1.class: Class
C1.class.instance_methods.first(3): [:allocate, :attached_object, :superclass]

Methods

Returning now to Ruby’s methods method, this method returns both the singleton methods of the object and the instance methods of the object’s class, which is the full list of methods that can be called on the object.

Exploring methods

Similar to calling C1.methods above, o1.methods returns an array of all the methods that can be called on object o1. And the code below demonstrates that this list of methods is exactly the same list as the singleton methods of o1 plus the instance methods of the class of o1.

begin
  puts "o1.methods.count: #{o1.methods.count}"
  puts "(o1.singleton_methods + o1.class.instance_methods).count: #{(o1.singleton_methods + o1.class.instance_methods).count}"
  puts "o1.methods == o1.singleton_methods + o1.class.instance_methods: #{o1.methods == o1.singleton_methods + o1.class.instance_methods}"
  puts "o1.methods.first(8): #{o1.methods.first(8)}"
  puts "o1.singleton_methods: #{o1.singleton_methods}"
  puts "o1.class.instance_methods.first(5): #{o1.class.instance_methods.first(5)}"
end

o1.methods.count: 63
(o1.singleton_methods + o1.class.instance_methods).count: 63
o1.methods == o1.singleton_methods + o1.class.instance_methods: true
o1.methods.first(8): [:m04, :m01, :m10, :m02, :m09, :m07, :m06, :pretty_print]
o1.singleton_methods: [:m04, :m01, :m10]
o1.class.instance_methods.first(5): [:m02, :m09, :m07, :m06, :pretty_print]

Summary

This post presents a practical guide to Ruby’s object model, with a focus on Ruby methods. It uses Ruby’s facilities to build, organize, and explore an example object model, and it includes a diagram that helps explain how Ruby searches for methods.

Key points from the post include:

  • An object’s methods include its singleton methods plus the instance methods of its class.
  • Any object can have a singleton class. Methods defined on the singleton class are singleton methods.
  • The singleton class is the first class in the class hierarchy, so singleton methods will be found first in the method search.
  • Because the singleton class and singleton methods are injected into the standard Ruby object model, the method search for singleton methods is the same as for any other method.
  • Class methods are really singleton methods defined on a class object, like C1 and C2.
  • Classes and modules have instance methods. Instantiated objects, like o1, do not.
  • A singleton method defined on an object is only callable on that one object, while an instance method defined on a class is callable on any instance of the class.