Watch Ruby as it parses your code

In this post we'll use a little-known command line flag to spy on Ruby as it parses our code.

I thought it would be fun to take a break from practical, useful content to show you a neat Ruby party trick.

Before Ruby runs your program it has to parse it. The parser is a kind of a state machine. And there is a little-known command line flag that you can use to make Ruby log everything the state machine does.

Take the following example:

a = 1 + 2

If I run this using the -y flag, I get the following output:

$ ruby -y sample.rb
Starting parse
Entering state 0
Reducing stack by rule 1 (line 903):
-> $$ = nterm $@1 ()
Stack now 0
Entering state 2
Reading a token: Next token is token tIDENTIFIER ()
Shifting token tIDENTIFIER ()
Entering state 35
Reading a token: Next token is token '=' ()
Reducing stack by rule 509 (line 4417):
   $1 = token tIDENTIFIER ()
-> $$ = nterm user_variable ()
Stack now 0 2
Entering state 113
Next token is token '=' ()
Reducing stack by rule 100 (line 1764):
   $1 = nterm user_variable ()
-> $$ = nterm lhs ()
Stack now 0 2
140 more lines

What we're seeing here is the Ruby parser cycling through each token in the file and performing the following operations:

  • Add the token to a stack
  • Compare the stack to a list of rules
    • If the token matches a rule, do a state transition
    • If no match, add another token to the stack and try again.

All of the states and rules are defined in parse.y a file that is processed by the bison parser generator to generate the actual parser which is in C.

What to do next:
  1. Try Honeybadger for FREE
    Honeybadger helps you find and fix errors before your users can even report them. Get set up in minutes and check monitoring off your to-do list.
    Start free trial
    Easy 5-minute setup — No credit card required
  2. Get the Honeybadger newsletter
    Each month we share news, best practices, and stories from the DevOps & monitoring community—exclusively for developers like you.
    author photo

    Starr Horne

    Starr Horne is a Rubyist and Chief JavaScripter at When she's not neck-deep in other people's bugs, she enjoys making furniture with traditional hand-tools, reading history and brewing beer in her garage in Seattle.

    More articles by Starr Horne