Turning IRB on its head with Pry

IRB is a great tool and is perfect for experimenting with small code samples and testing out new ideas. It has some difficulty however when the code samples become a bit larger or you’d like to start an IRB session half-way through a method, for example.

Pry, in some sense, is IRB turned on its head. Instead of having to bring your code to a REPL session (as with IRB) you instead bring a REPL session to your code, see the following:

# test.rb
require 'pry'

class A
  def hello() puts "hello world!" end
end

a = A.new

# start a REPL session
binding.pry

# program resumes here (after pry session)
puts "program resumes here."

We then run ruby test.rb from the command line and the following REPL session begins:

Beginning Pry session for main
pry(main)> a.hello
hello world!
=> nil
pry(main)> def a.goodbye
pry(main)*   puts "goodbye cruel world!"
pry(main)* end
=> nil
pry(main)> a.goodbye
goodbye cruel world!
=> nil
pry(main)> exit
Ending Pry session for main
program resumes here.

There are a few things to note from above:

• The first is that local variables are available to a Pry session (locals are not available to an irb session when using `irb -r`).
• The second is that when you end a Pry session it returns to the running program; this makes Pry particularly useful for debugging.

Debugging

Pry sits somewhere between using `puts` statements to debug and using a bona fide debugger. It effectively opens up an IRB-like session at the place it’s called and makes all the program state at that point available.

In the example below, the code (sans the `binding.pry`) works as required in Ruby 1.8 but in 1.9 it returns the wrong result – notably check_array([]) displays "ary has content"; whereas we want it to output "ary is empty!" We start a Pry session right after the line b = *ary to try to determine the problem in Ruby 1.9:

def check_array(ary)
  b = *ary

  # invoking Pry here for debugging
  binding.pry

  if !b
    puts "ary is empty!"
  else
    puts "ary has content"
  end
end

check_array([])

When running the above code the following Pry session starts up:

Beginning Pry session for main
pry(main)> show-method
def check_array(ary)
  b = *ary

  binding.pry

  if !b
    puts "ary is empty!"
  else
    puts "ary has content"
  end
end
=> nil
pry(main)> b
=> []
pry(main)> test = *[]
=> []
pry(main)> b = !ary.empty?
=> false
pry(main)> exit
Ending Pry session for main
ary is empty!

From above the first thing we do is display the code for the method we’re debugging – Pry’s `show-method` command does this.

We next experiment and find that the behaviour of *[] has changed in 1.9 (in 1.8 it returned nil) and this must be the cause of our problems. We then come up with a new test b = !b.empty? and let the program continue (by typing `exit`) with this new value of b. It now outputs the expected result.

Note that any changes to state we make in a Pry session persist during the lifetime of the program. This fact also makes Pry useful for interactively modifying runtime state.

Interactively modifying runtime state

It may be convenient to open a Pry session in the middle of a running program. The example below is of a game where we are using Pry to increase the lunar lander’s fuel; we also do a bit of exploration of the runtime state to show off some features of Pry.

Beginning Pry session for #
pry(#)> ls
[:_, :_pry_,:@state, :@frame_counter, :@playgame]
=> nil
pry(#)> cd @playgame
Beginning Pry session for #
pry(#):1> ls
[:_, :_pry_, :@map, :@font,  :@wind, :@objects, :@lander]
=> nil
pry(#):1> cd @lander
Beginning Pry session for #
pry(#):2> @fuel = 300000
=> 300000
pry(#):2> nesting
Nesting status:
--
0. # (Pry top level)
1. #
2. #
=> nil
pry(#):2> cd ..
Ending Pry session for #
=> nil
pry(#):1> ls --methods
[:__binding_impl__, :draw, :initialize, :lander, :level, :map]
=> nil
pry(#):1> cd map
Beginning Pry session for #
pry(#):2> ls
[:_, :_pry_, :@nebula, :@nebula_theta, :@moonscape]
=> nil
pry(#):2> exit-all
Ending Pry session for #
Ending Pry session for #
Ending Pry session for #

From above, Pry makes it easy to navigate runtime state. You can pop in and out of objects, nesting sessions as deeply as you like. The `cd` and `ls` commands are provided to make this navigation seem familiar and natural.

Customizability

Pry is also easily customizable – you can trivially set the input for a Pry session to objects other than `Readline` and `$stdin`; and likewise set the output object to something other than `$stdout`.

Many other features of Pry can also be customized making Pry a perfect choice for implementing custom shells. See Customizing Pry for more information.

An IRB Alternative

Pry can be invoked from the command line using the `pry` executable. It can then be used as an alternative to IRB. Many of the IRB command line options are supported. Type `pry –help` at the command line for more information.

Conclusion

Pry is an IRB-alike that can be invoked at any time and anywhere in the program and on any receiver; it can also receive input from anywhere and send output to anywhere. The examples shown here illustrate just some of the functionality of Pry, read the Wiki for the full story.