Overview

Taking inspiration from the unix command shell, Pry provides commands to make navigating around your program's runtime state both familiar and natural.

Changing scope with cd

The cd command is used to move into a new object (or scope) inside a Pry session. When inside the new scope it becomes the self for the session and all commands and methods will operate on this new self.

As in unix shells you use cd .. to go back to the previous scope, cd / to return to the top-level scope for the Pry session (usually main but does not have to be) and cd - to switch between last two scopes.

The cd command also accepts complex syntax like cd ../@x/Const/@y
where the .. represents the context one level further up the
stack. The above example can be translated into English as the
following: "pop the current context off the
stack, look up @x in the prior context and push it onto the stack,
look up Const in the context of @x and push it onto the stack, look up
@y in the context of Const and push it onto the stack".

Learning about your context with the ls command

Note: This command has been significantly updated since Pry version 0.9.7. Some of the options below may work differently if you are using an earlier version; it is recommended you upgrade.

The ls command is essentially a unified wrapper to a number of Ruby's introspection mechanisms, including (but not limited to) the following methods: methods, instance_variables, constants, local_variables, instance_methods, class_variables and all the various permutations thereof.

By default typing ls shows you the local variables defined in the current context, and any public methods or instance variables defined on the current object.

Rapidly exploring with the find-method command

The find-method command allows you to easily find which method does what. It's very similar to grep, but instead of finding files and line-numbers, it finds ruby methods and source code. This is most useful when you're trying to get a feel for how a particular gem or application is structured, as it lets you answer questions such as "which method actually sends this to the client?", and "what's responsible for serialization".

To use it you just pass in the method name you'd like to find.

Example: find who's using yaml?

pry(main)> find-method to_yaml
Gem::Specification#to_yaml

Optionally you can also pass in a namespace to narrow down the search. This enables you to quickly find structure in large applications:

The final way to use find-method is with the -c flag. When this is present, find-method will grep the source code of each method. This can be used to help find methods that are calling other methods, or when searching for something you're sure you remember seeing once:

Switch to another context

Unlike the jump-to command (discussed above) which exits out of
nested contexts, the switch-to command does not exit contexts but starts a new Pry instance to
manage the session on the selected binding. Using switch-to you can
temporaily switch to a Binding further up the context stack, work on it, then
exit out, returning you to your exact position on the original binding
(even if you were mid-expression).

This functionality can be useful when you are writing a method in one
context, but need to quickly look up some information on another
context further up the context stack (and you do not wish to lose your current
work on the method as you would if you had used jump-to).

Exit a context with a value

Sometimes it can be useful to exit a context with a user-provided value. This is especially useful when Pry is invoked at runtime as the exit value of the Pry session can be used to determine program flow.

Note that using exit only goes back one nesting level, it doesn't exit Pry altogether. So exit is equivalent to cd .. except that it can return a user-provided a value.

Exit all nested contexts and return to the calling process

The exit-all command is normally used when Pry is invoked at runtime by a running program. Entering exit-all will break out of all nested contexts and return to the calling process, the program that invoked Pry will then continue its execution. Note that exit-all also accepts an optional value argument and will return with this value (as in the case of exit).

Exit the program completely

The exit-program command ends the current program, including the program that invoked the Pry session. This command is equivalent to running the Ruby exit method which raises the SystemExit exception; however history is saved before exit.