Fork me on GitHub

Letters

A tiny debugging library for Ruby

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

For many of us, troubleshooting begins and ends with the print statement. Others recruit the debugger, too. (Maybe you use print 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 print, the debugger, control transfer, computer beeps, and other side-effects for more well-rounded visibility into code and state.

Installation

If you’re using RubyGems, install Letters with:

#!plain
          gem install letters
          

By default, requiring "letters" monkey-patches Object. It goes without saying that if you’re using Letters in an app that has environments, you probably only want to use it in development.

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.

Let’s start 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:

#!ruby
          { 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:

#!ruby
          words.grep(/interesting/).
            map(&:downcase).
            group_by(&:length).
            values_at(5, 10).
            slice(0..2).
            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:

#!ruby
          words.grep(/interesting/).
            map(&:downcase).
            group_by(&:length).o.
            values_at(5, 10).
            slice(0..2).o.
            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 pretty print.

The methods

Here are the methods, listed with any options that can be passed in to modify their behavior. Some options are available to all methods and are not listed in the table below:

  • :message (string): Print out the specified message as the method is being called.
  • :line_no (boolean): Print out the line number where a method is called as it is being called

You can easily set these for an entire project using global configuration if you wish (see below).

Letter Command Options Description
a Assert :error_class asserts in the context of its receiver or Letters::AssertionError
b Beep causes your terminal to beep
c Callstack prints the current callstack
d Debugger passes control to the debugger
d1/d2 Diff :format,:stream prints a diff between first and second receivers
e Empty raises a Letters::EmptyError if its receiver is empty
f File :format, :name writes its receiver into a file in a given format
j Jump (&block) executes its block in the context of its receiver
k Kill :on raises Letters::KillError at a specified number of calls
l Logger :format, :level logs its receivers on the available logger instance
m Mark as tainted (true|false) taints (or untaints) its receiver
n Nil raises a Letters::NilError if its receiver is nil
o Output :format, :stream prints its receiver to standard output
r Ri (method name as symbol) prints RI documentation of its receiver class
s Safety (level number) bumps the safety level (by one or as specified)
t Timestamp :time_format prints out the current timestamp

Configuration

For maximum productivity, you can tune and tweak each Letters method to fit your own tastes. Want to name put files somewhere else? No problem. Don’t like YAML? Default f to use Pretty Print instead! The world of defaults is your oyster.

Letters.config do
            f :format => "pp", :name => "my-special-file"
          end
          

You can also change options globally, for methods where the global option is appropriate. For example, if you want every Letters method to print out its line number when called, you can do this for all methods at once:

Letters.config do
            all :line_no => true
          end
          

Next steps

There is plenty more to do with this library – for example, arbitrary object diffs, user-defined methods and methods renaming. This core is just the beginning. For suggestions, feedback and questions, check out the resources page.