(C) John Mair (banisterfiend) 2010
attach an irb-like session to any object at runtime
Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive manipulation of objects during the running of a program.
It is not based on the IRB codebase and is small, at around 260 LOC.
example: Interacting with an object at runtime
Pry.start() method we can pry (open an irb-like session) on
an object. In the example below we open a Pry session for the
Test class and execute a method and add
an instance variable. The current thread is halted for the duration of the session.
require 'pry' class Test def self.hello() "hello world" end end Pry.start(Test) # Pry session begins on stdin Beginning Pry session for Test pry(Test)> self => Test pry(Test)> hello => "hello world" pry(Test)> @y = 20 => 20 pry(Test)> exit Ending Pry session for Test # program resumes here
If we now inspect the
Test object we can see our changes have had
Test.instance_variable_get(:@y) #=> 20
You can also use the
pry(obj) syntax to start a pry session on
5.pry Beginning Pry session for 5 pry(5)>
pry 6 beginning Pry session for 6 pry(6)>
example: Pry sessions can nest arbitrarily deep so we can pry on objects inside objects:
Here we will begin Pry at top-level, then pry on a class and then on an instance variable inside that class:
# Pry.start() without parameters begins a Pry session on top-level (main) Pry.start Beginning Pry session for main pry(main)> class Hello pry(main)* @x = 20 pry(main)* end => 20 pry(main)> Pry.start Hello Beginning Pry session for Hello pry(Hello):1> instance_variables => [:@x] pry(Hello):1> Pry.start @x Beginning Pry session for 20 pry(20:2)> self + 10 => 30 pry(20:2)> exit Ending Pry session for 20 pry(Hello):1> exit Ending Pry session for Hello pry(main)> exit Ending Pry session for main
The number after the
: in the pry prompt indicates the nesting
level. To display more information about nesting, use the
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
pry("friend":3)> jump_to 1 Ending Pry session for "friend" Ending Pry session for 100 => 100 pry(Hello):1>
If we just want to go back one level of nesting we can of course
To break out of all levels of Pry nesting and return immediately to the
calling process use
pry("friend":3)> exit_all Ending Pry session for "friend" Ending Pry session for 100 Ending Pry session for Hello Ending Pry session for main => main # program resumes here
Features and limitations
Pry is an irb-like clone with an emphasis on interactively examining and manipulating objects during the running of a program.
Its primary utility is probably in debugging, though it may have other uses (such as implementing a quake-like console for games, for example). Here is a list of Pry's features along with some of its limitations given at the end.
- Pry can be invoked at any time and on any object in the running program.
- Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
_to recover last result.
- Pry has multi-line support built in.
- Pry gives good control over nested sessions (important when exploring complicated runtime state)
- Pry is not based on the IRB codebase.
- Pry is small; around 260 LOC.
- Pry implements all the methods in the REPL chain separately:
Pry.repfor printing; and
Pry.replfor the loop (
Pry.startis simply an alias for
Pry.repl). You can invoke any of these methods directly depending on exactly what aspect of the functionality you need.
- Pry does not pretend to be a replacement for
irb, and so does not have an executable. It is designed to be used by other programs, not on its own. For a full-featured
irbreplacement see ripl
- Although Pry works fine in Ruby 1.9, only Ruby 1.8 syntax is supported. This is because Pry uses the RubyParser gem internally to validate expressions, and RubyParser, as yet, only parses Ruby 1.8 code. In practice this usually just means you cannot use the new hash literal syntax (this: syntax) or the 'stabby lambda' syntax (->).
The Pry API:
Pry.repl()are all aliases of oneanother. They all start a Read-Eval-Print-Loop on the object they receive as a parameter. In the case of no parameter they operate on top-level (main). They can receive any object or a
Bindingobject as parameter.
pry(obj)may also be used as alternative syntax to
- If, for some reason you do not want to 'loop' then use
Pry.rep(); it only performs the Read-Eval-Print section of the REPL - it ends the session after just one line of input. It takes the same parameters as
Pry.re()only performs the Read-Eval section of the REPL, it returns the result of the evaluation or an Exception object in case of error. It also takes the same parameters as
Pry.r()only performs the Read section of the REPL, only returning the Ruby expression (as a string). It takes the same parameters as all the others.
Pry supports a few commands inside the session itself. These commands are not methods and must start at the beginning of a line, with no whitespace in between.
If you want to access a method of the same name, prefix the invocation by whitespace.
!on a line by itself will refresh the REPL - useful for getting you out of a situation if the parsing process goes wrong.
statusshows status information about the current session.
helpshows the list of session commands with brief explanations.
backwill end the current Pry session and go back to the calling process or back one level of nesting (if there are nested sessions).
quit_programwill end the currently running program.
nestingshows Pry nesting information.
jump_to <nest_level>unwinds the Pry stack (nesting level) until the appropriate nesting level is reached -- as per the output of
exit_allbreaks out of all Pry nesting levels and returns to the calling process.
- You can type
obj.pryto nest another Pry session within the current one with
objas the receiver of the new session. Very useful when exploring large or complicated runtime state.
Problems or questions contact me at github