© John Mair (banisterfiend) 2016
Please DONATE to the Pry project - Pry was a huge amount of work and every donation received is encouraging and supports Pry's continued development!
Sponsors
Launch School
Atomic Object
Hashrocket
Intridea
Gaslight
Other Resources
Skip to the website (recommended)
Skip to the wiki
Pry is a powerful alternative to the standard IRB shell for Ruby. It is written from scratch to provide a number of advanced features, including:
- Source code browsing (including core C source with the pry-doc gem)
- Documentation browsing
- Live help system
- Open methods in editors (
edit Class#method) - Syntax highlighting
- Command shell integration (start editors, run git, and rake from within Pry)
- Gist integration
- Navigation around state (
cd,lsand friends) - Runtime invocation (use Pry as a developer console or debugger)
- Exotic object support (BasicObject instances, IClasses, ...)
- A Powerful and flexible command system
- Ability to view and replay history
- Many convenience commands inspired by IPython, Smalltalk and other advanced REPLs
- A wide-range number of plugins that provide remote sessions, full debugging functionality, and more.
Pry also aims to be more than an IRB replacement; it is an attempt to bring REPL driven programming to the Ruby language. It is currently not as powerful as tools like SLIME for lisp, but that is the general direction Pry is heading.
Pry is also fairly flexible and allows significant user
customization
is trivial to set it to read from any object that has a readline method and write to any object that has a
puts method - many other aspects of Pry are also configurable making
it a good choice for implementing custom shells.
Pry comes with an executable so it can be invoked at the command line.
Just enter pry to start. A .pryrc file in the user's home directory will
be loaded if it exists. Type pry --help at the command line for more
information.
Try gem install pry-doc for additional documentation on Ruby Core
methods. The additional docs are accessed through the show-doc and
show-method commands.
- Install the gem:
gem install pry - Browse the comprehensive documentation at the official Pry wiki
- Read the YARD API documentation
- See the source code
Nearly every piece of functionality in a Pry session is implemented as a command. Commands are not methods and must start at the beginning of a line, with no whitespace in between. Commands support a flexible syntax and allow 'options' in the same way as shell commands, for example the following Pry command will show a list of all private instance methods (in scope) that begin with 'pa'
pry(YARD::Parser::SourceParser):5> ls -Mp --grep ^pa
YARD::Parser::SourceParser#methods: parse parser_class parser_type parser_type= parser_type_for_filename
Pry allows us to pop in and out of different scopes (objects) using
the cd command. This enables us to explore the run-time view of a
program or library. To view which variables and methods are available
within a particular scope we use the versatile ls command.
Here we will begin Pry at top-level, then Pry on a class and then on an instance variable inside that class:
pry(main)> class Hello
pry(main)* @x = 20
pry(main)* end
=> 20
pry(main)> cd Hello
pry(Hello):1> ls -i
instance variables: @x
pry(Hello):1> cd @x
pry(20):2> self + 10
=> 30
pry(20):2> cd ..
pry(Hello):1> cd ..
pry(main)> cd ..
The number after the : in the pry prompt indicates the nesting
level. To display more information about nesting, use the nesting
command. E.g
pry("friend"):3> nesting
Nesting status:
0. main (Pry top level)
1. Hello
2. 100
3. "friend"
=> nil
We can then jump back to any of the previous nesting levels by using
the jump-to command:
pry("friend"):3> jump-to 1
=> 100
pry(Hello):1>
Pry can be invoked in the middle of a running program. It opens a Pry
session at the point it's called and makes all program state at that
point available. It can be invoked on any object using the
my_object.pry syntax or on the current binding (or any binding)
using binding.pry. The Pry session will then begin within the scope
of the object (or binding). When the session ends the program continues with any
modifications you made to it.
This functionality can be used for such things as: debugging, implementing developer consoles and applying hot patches.
code:
# 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."Pry session:
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
program resumes here.
A line of input that begins with a '.' will be forwarded to the command shell. This enables us to navigate the file system, spawn editors, and run git and rake directly from within Pry.
Further, we can use the shell-mode command to incorporate the
present working directory into the Pry prompt and bring in (limited at this stage, sorry) file name completion.
We can also interpolate Ruby code directly into the shell by
using the normal #{} string interpolation syntax.
In the code below we're going to switch to shell-mode and edit the
.pryrc file in the home directory. We'll then cat its contents and
reload the file.
pry(main)> shell-mode
pry main:/home/john/ruby/projects/pry $ .cd ~
pry main:/home/john $ .emacsclient .pryrc
pry main:/home/john $ .cat .pryrc
def hello_world
puts "hello world!"
end
pry main:/home/john $ load ".pryrc"
=> true
pry main:/home/john $ hello_world
hello world!