Letters was a fun project to work on. It was inspired by several debugging patterns I saw while consulting at Pivotal Labs. It generated a little bit of buzz and even made it to Hacker News and the Ruby5 podcast

Letters is a little alphabetical library that makes sophisticated debugging easy & fun.

For many of us, troubleshooting begins and ends with the puts statement. Others recruit the debugger, too. (Maybe you use puts statements to look at changes over time but the debugger to focus on a small bit of code.) These tools are good, but they are the lowest level of how we can debug in Ruby. Letters leverages puts, the debugger, control transfer, computer beeps, and other side-effects for more well-rounded visibility into code and state.

Debugging with letters

With Letters installed, you have a suite of methods available wherever you want them in your code – at the end of any expression, in the middle of any pipeline. Most of these methods will output some form of information, though there are more sophisticated ones that pass around control of the application.

There are almost 20 Letters methods so far.

Let’s use with the o method as an example. It is one of the most familiar methods. Calling it prints the receiver to STDOUT and returns the receiver:

{ foo: "bar" }.o
# => { foo: "bar" }
# prints { foo: "bar" }

That’s simple enough, but not really useful. Things get interesting when you’re in a pipeline:

  values_at(5, 10).
  join(", ")

If I want to know the state of your code after lines 3 and 5, all I have to do is add .o to each one:

  values_at(5, 10).
  join(", ")

Because the o method (and nearly every Letters method) returns the original object, introducing it is only ever for side effects – it won’t change the output of your code.

This is significantly easier than breaking apart the pipeline using variable assignment or a hefty tap block.

The o method takes options, too, so you can add a prefix message to the output or choose another output format – like YAML or Ruby’s pretty printer.

The methods

You can find all 20 letter methods in the documentation.