Ruby Source Code – A Full Description

by Minero AOKI

Translated into English as

The Ruby Hacker's Guide

Contributors: Clifford Escobar CAOILE, Robert GRAVINA, Vincent ISAMBART, C.E. THORNTON


Edwin W. Meyer

The Ruby language was created by Yukihiro Matsumoto ("Matz"), a Japanese computer language enthusiast, who released the first public version in 1995. For many years a little known niche language, it has surged in popularity since the first release of the Ruby on Rails web development framework in 2004. Ruby remains in continuous development under the guidance of its originator Matz.

As of June, 2010 there are now two branches of Ruby. The latest (and probably last) release of Ruby using the original MRI interpreter (Matz's Ruby Interpreter) is 1.8.7. A new version of Ruby, using the faster YARV (Yet Another Ruby Virtual machine) is available in Ruby development release 1.9.1.

YARV is a bytecode interpreter created by Koichi Sasada that converts the syntax tree – an internal representation of a Ruby program – into an intermediate bytecode target, which is then executed by the "virtual machine". YARV is considerably faster than Matz's original MRI, which directly interprets the internal syntax tree, but the implementation is substantially different. Both are written in the C language.

Note: While Rails 2.3.8 (released May 25, 2010) works with Ruby 1.8.7 and some earlier versions, the new version (as of June, 2010) Rails 3.0 beta requires Ruby 1.8.7 or the not yet officially released Ruby 1.9.2.

Although there is a continuing flood of books on various aspects of the Ruby on Rails web framework, there are a scant half-dozen or so fairly recent English-language introductions to Ruby, and there is absolutely nothing in print that describes the structure of the interpreter, which forms the foundation of the Ruby language. I find this unfathomable, since the best way to understand the idiosyncrasies of Ruby's behavior is to understand key aspects of its interpreter.

The one source is an online book written in 2004 by Minero Aoki -- however it is in Japanese.

There have been two successive attempts to translate this book for English readers.

The first, in 2006, by Vincent Isambart and others is published as the Ruby Hacking Guide (RHG) at (RHG RubyForge project page). However of the 20+ segments, only chapters 2 through 4 and chapter 6 are translated. No further updates since May, 2006 have occurred.

In 2008 a semi-retired computer consultant C. E. Thornton of Houston, Texas released a revised and more extensive translation as the Integrated Ruby Hacker's Guide (IHRG) on his Hawthorne Press website. He has provided translations of the prefatory sections plus chapters 1 through 11 and chapter 18. Furthermore, he provides machine-translated versions (barely readable but better than nothing) of the original untranslated Japanese chapters. Hence the prefix "Integrated".

A brief comparison of the two versions indicates that Thornton's translation is more colloquial the that of Isambart, et. al. on RubyForge, which seems to mimic the phrasing of the Japanese original. He also has interpolated useful material that the RubyForge version lacks. Thornton also has not made any updates since his original September, 2008 version.

Thornton's website provides IRHG only in a not readily readable ".tgz" archive file format. As of this date, one other website ( provides the html files, but its home page does not link to it.

The Integrated Ruby Hacker's Guide suffers from several serious faults:

Still, even with its faults, the Integrated Ruby Hacker's Guide remains a valuable resource that deserves much wider exposure. Not only will the 1.8 versions of Ruby remain in wide use for some time until 1.9 matures (and is released as 2.0), but the structure of 1.9's YARV interpreter, while different in detail, must basically mimic that of 1.8 in order to be compatible with it.

While the implementation language the Ruby interpreter is C, the document's major focus is on the architecture and internal data structures, which are readily understandable even by one without a C background. Little or no executable C code is presented.

The unmodified C. E. Thornton version of this essential work is available on Edwin Meyer's professional website as The Integrated Ruby Hacker's Guide

An annotated table of contents indicating what chapter versions are available follows.

Table of contents

1st Section – "Objects"

2nd Section – "Syntax Analysis"

3rd Section – "Appraisal"

4th Section – "Around"

The original work is Copyright © 2002 - 2004 Minero Aoki
Original English translation by Vincent Isambart and others
Further Translations and Additions by C.E. Thornton
This introduction by Edwin W. Meyer
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike2.5 License.