Metaprogramming in Ruby: It’s All About the Self

After writing my last post on Rails plugin idioms, I realized that Ruby metaprogramming, at its core, is actually quite simple.

It comes down to the fact that all Ruby code is executed code–there is no separate compile or runtime phase. In Ruby, every line of code is executed against a particular self . Consider the following five snippets:

class

 Person
  def

 self

.species


    "Homo Sapien"


  end


end


 
class

 Person
  class

 <<

 self


    def

 species
      "Homo Sapien"


    end


  end


end


 
class

 <<

 Person
  def

 species
    "Homo Sapien"


  end


end


 
Person.instance_eval

 do


  def
   species
    "Homo Sapien"


  end


end


 
def

 Person.species


  "Homo Sapien"


end

All five of these snippets define a Person.species that returns Homo Sapien . Now consider another set of snippets:

class

 Person
  def

 name
    "Matz"


  end


end


 
Person.class_eval

 do


  def

 name
    "Matz"


  end


end

These snippets all define a method called name on the Person class. So Person.new.name will return “Matz”. For those familiar with Ruby, this isn’t news. When learning about metaprogramming, each of these snippets is presented in isolation: another mechanism for getting methods where they “belong”. In fact, however, there is a single unified reason that all of these snippets work the way they do.

First, it is important to understand how Ruby’s metaclass works. When you first learn Ruby, you learn about the concept of the class, and that each object in Ruby has one:

class

 Person
end


 
Person.class

 #=> Class


 
class

 Class


  def

 loud_name
    "#{name.upcase}!"


  end


end


 
Person.loud_name

 #=> "PERSON!"

Person is an instance of Class , so any methods added to Class are available on Person as well. What they don’t tell you, however, is that each object in Ruby also has its own metaclass , a Class that can have methods, but is only attached to the object itself.

matz = Object

.new


def

 matz.speak


  "Place your burden to machine's shoulders"


end

What’s going on here is that we’re adding the speak method to matz ’s metaclass , and the matz object inherits from its metaclass and then Object . The reason this is somewhat less clear than ideal is that the metaclass is invisible in Ruby:

matz = Object

.new


def

 matz.speak


  "Place your burden to machine's shoulders"


end


 
matz.class

 #=> Object

In fact, matz ’s “class” is its invisible metaclass. We can even get access to the metaclass:

metaclass = class

 <<

 matz; self

; end


metaclass.instance_methods

.grep

(

/

speak/

)

 #=> ["speak"]

At this point in other articles on this topic, you’re probably struggling to keep all of the details in your head; it seems as though there are so many rules. And what’s this class << matz thing anyway?

It turns out that all of these weird rules collapse down into a single concept: control over the self in a given part of the code. Let’s go back and take a look at some of the snippets we looked at earlier:

class

 Person
  def

 name
    "Matz"


  end


 
  self

.name

 #=> "Person"


end

Here, we are adding the name method to the Person class. Once we say class Person , the self until the end of the block is the Person class itself.

Person.class_eval

 do


  def

 name
    "Matz"


  end


 
  self

.name

 #=> "Person"


end

Here, we’re doing exactly the same thing: adding the name method to instances of the Person class. In this case, class_eval is setting the self to Person until the end of the block. This is all perfectly straight forward when dealing with classes, but it’s equally straight forward when dealing with metaclasses:

def

 Person.species


  "Homo Sapien"


end


 
Person.name

 #=> "Person"

As in the matz example earlier, we are defining the species method on Person ’s metaclass. We have not manipulated self , but you can see using def with an object attaches the method to the object’s metaclass.

class

 Person
  def

 self

.species


    "Homo Sapien"


  end


 
  self

.name

 #=> "Person"


end

Here, we have opened the Person class, setting the self to Person for the duration of the block, as in the example above. However, we are defining a method on Person ’s metaclass here, since we’re defining the method on an object (self ). Also, you can see that self.name while inside the person class is identical to Person.name while outside it.

class

 <<

 Person
  def

 species
    "Homo Sapien"


  end


 
  self

.name

 #=> ""


end

Ruby provides a syntax for accessing an object’s metaclass directly. By doing class << Person , we are setting self to Person ’s metaclass for the duration of the block. As a result, the species method is added to Person ’s metaclass, rather than the class itself.

class

 Person
  class

 <<

 self


    def

 species
      "Homo Sapien"


    end


 
    self

.name

 #=> ""


  end


end

Here, we combine several of the techniques. First, we open Person , making self equal to the Person class. Next, we do class << self , making self equal to Person ’s metaclass. When we then define the species method, it is defined on Person ’s metaclass.

Person.instance_eval

 do


  def

 species
    "Homo Sapien"


  end


 
  self

.name

 #=> "Person"


end

The last case, instance_eval , actually does something interesting. It breaks apart the self into the self that is used to execute methods and the self that is used when new methods are defined. When instance_eval is used, new methods are defined on the metaclass , but the self is the object itself.

In some of these cases, the multiple ways to achieve the same thing arise naturally out of Ruby’s semantics. After this explanation, it should be clear that def Person.species , class << Person; def species , and class Person; class << self; def species aren’t three ways to achieve the same thing by design , but that they arise out of Ruby’s flexibility with regard to specifying what self is at any given point in your program.

On the other hand, class_eval is slightly different. Because it take a block, rather than act as a keyword, it captures the local variables surrounding it. This can provide powerful DSL capabilities, in addition to controlling the self used in a code block. But other than that, they are exactly identical to the other constructs used here.

Finally, instance_eval breaks apart the self into two parts, while also giving you access to local variables defined outside of it.

In the following table, defines a new scope means that code inside the block does not have access to local variables outside of the block.

mechanism	method resolution	method definition	new scope?
class Person	Person	same	yes
class << Person	Person’s metaclass	same	yes
Person.class_eval	Person	same	no
Person.instance_eval	Person	Person’s metaclass	no

Also note that class_eval is only available to Modules (note that Class inherits from Module) and is an alias for module_eval . Additionally, instance_exec , which was added to Ruby in 1.8.7, works exactly like instance_eval , except that it also allows you to send variables into the block.

UPDATE: Thank you to Yugui of the Ruby core team for correcting the original post , which ignored the fact that self is broken into two in the case of instance_eval .