2010-12-08 02:30:38 -05:00
|
|
|
Pry
|
|
|
|
=============
|
|
|
|
|
2011-01-23 19:39:15 -05:00
|
|
|
(C) John Mair (banisterfiend) 2011
|
2010-12-08 02:30:38 -05:00
|
|
|
|
2010-12-08 08:49:28 -05:00
|
|
|
_attach an irb-like session to any object at runtime_
|
2010-12-08 02:30:38 -05:00
|
|
|
|
2010-12-08 09:06:52 -05:00
|
|
|
Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
|
2011-01-22 09:02:10 -05:00
|
|
|
manipulation of objects during the running of a program.
|
|
|
|
|
|
|
|
In some sense it is the opposite of IRB in that you bring a REPL
|
|
|
|
session to your code (with Pry) instead of bringing your code to a
|
|
|
|
REPL session (as with IRB).
|
2010-12-08 02:30:38 -05:00
|
|
|
|
2010-12-16 23:56:50 -05:00
|
|
|
It is not based on the IRB codebase, and implements some unique REPL
|
2011-02-21 22:49:53 -05:00
|
|
|
commands such as `show-method`, `show-doc`, `ls` and `cd` (type `help`
|
|
|
|
to get a full list).
|
2010-12-08 11:18:01 -05:00
|
|
|
|
2011-01-22 09:02:10 -05:00
|
|
|
Pry is also fairly flexible and allows significant user
|
2011-01-30 08:50:18 -05:00
|
|
|
[customization](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md). It
|
|
|
|
is trivial to set it to read from any object that has a `readline` method and write to any object that has a
|
2011-01-29 21:00:19 -05:00
|
|
|
`puts` method - many other aspects of Pry are also configurable making
|
|
|
|
it a good choice for implementing custom shells.
|
2011-01-22 09:02:10 -05:00
|
|
|
|
2011-03-14 23:31:40 -04:00
|
|
|
Pry comes with an executable so it can be invoked at the command line.
|
2011-02-20 11:54:18 -05:00
|
|
|
Just enter `pry` to start. A `.pryrc` file in the user's home directory will
|
2011-03-14 23:31:40 -04:00
|
|
|
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.
|
2011-02-20 11:54:18 -05:00
|
|
|
|
2010-12-08 06:39:06 -05:00
|
|
|
* Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
|
|
|
|
* Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
|
|
|
|
* See the [source code](http://github.com/banister/pry)
|
2010-12-08 02:30:38 -05:00
|
|
|
|
2011-01-23 09:03:39 -05:00
|
|
|
Pry also has `rubygems-test` support; to participate, first install
|
|
|
|
Pry, then:
|
|
|
|
|
|
|
|
1. Install rubygems-test: `gem install rubygems-test`
|
|
|
|
2. Run the test: `gem test pry`
|
|
|
|
3. Finally choose 'Yes' to upload the results.
|
|
|
|
|
2011-01-13 09:35:46 -05:00
|
|
|
Example: Interacting with an object at runtime
|
2010-12-08 06:39:06 -05:00
|
|
|
---------------------------------------
|
2010-12-08 02:30:38 -05:00
|
|
|
|
2011-01-09 06:51:45 -05:00
|
|
|
With the `Object#pry` method we can pry (open an irb-like session) on
|
2010-12-08 06:39:06 -05:00
|
|
|
an object. In the example below we open a Pry session for the `Test` class and execute a method and add
|
2011-03-05 09:17:54 -05:00
|
|
|
an instance variable. The current thread is taken over by the Pry REPL loop for the duration of the session.
|
2010-12-08 02:30:38 -05:00
|
|
|
|
2010-12-08 06:39:06 -05:00
|
|
|
require 'pry'
|
2011-01-13 09:35:46 -05:00
|
|
|
|
2010-12-08 06:39:06 -05:00
|
|
|
class Test
|
|
|
|
def self.hello() "hello world" end
|
2010-12-08 02:30:38 -05:00
|
|
|
end
|
|
|
|
|
2011-01-09 06:51:45 -05:00
|
|
|
Test.pry
|
2010-12-08 06:39:06 -05:00
|
|
|
|
|
|
|
# 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
|
|
|
|
effect:
|
|
|
|
|
|
|
|
Test.instance_variable_get(:@y) #=> 20
|
|
|
|
|
2011-01-19 03:40:43 -05:00
|
|
|
### Alternative Syntax
|
2010-12-11 00:22:17 -05:00
|
|
|
|
2011-01-09 06:51:45 -05:00
|
|
|
You can also use the `Pry.start(obj)` or `pry(obj)` syntax to start a pry session on
|
2010-12-08 19:59:30 -05:00
|
|
|
`obj`. e.g
|
|
|
|
|
2011-01-13 09:35:46 -05:00
|
|
|
Pry.start(5)
|
2010-12-08 19:59:30 -05:00
|
|
|
Beginning Pry session for 5
|
|
|
|
pry(5)>
|
2010-12-11 04:01:47 -05:00
|
|
|
|
|
|
|
OR
|
|
|
|
|
2011-01-13 09:35:46 -05:00
|
|
|
pry(6)
|
2010-12-11 04:01:47 -05:00
|
|
|
beginning Pry session for 6
|
|
|
|
pry(6)>
|
2011-01-09 06:51:45 -05:00
|
|
|
|
2011-01-20 21:46:56 -05:00
|
|
|
Example: Pry sessions can nest
|
2011-01-19 03:40:43 -05:00
|
|
|
-----------------------------------------------
|
2010-12-08 06:39:06 -05:00
|
|
|
|
|
|
|
Here we will begin Pry at top-level, then pry on a class and then on
|
|
|
|
an instance variable inside that class:
|
|
|
|
|
2010-12-08 19:59:30 -05:00
|
|
|
# Pry.start() without parameters begins a Pry session on top-level (main)
|
|
|
|
Pry.start
|
2010-12-08 06:39:06 -05:00
|
|
|
Beginning Pry session for main
|
|
|
|
pry(main)> class Hello
|
|
|
|
pry(main)* @x = 20
|
|
|
|
pry(main)* end
|
|
|
|
=> 20
|
2011-02-17 05:01:33 -05:00
|
|
|
pry(main)> cd Hello
|
2010-12-08 06:39:06 -05:00
|
|
|
Beginning Pry session for Hello
|
2010-12-08 19:59:30 -05:00
|
|
|
pry(Hello):1> instance_variables
|
2010-12-08 06:39:06 -05:00
|
|
|
=> [:@x]
|
2011-02-17 05:01:33 -05:00
|
|
|
pry(Hello):1> cd @x
|
2010-12-08 06:39:06 -05:00
|
|
|
Beginning Pry session for 20
|
2010-12-08 19:59:30 -05:00
|
|
|
pry(20:2)> self + 10
|
2010-12-08 06:39:06 -05:00
|
|
|
=> 30
|
2011-02-19 05:28:41 -05:00
|
|
|
pry(20:2)> cd ..
|
2010-12-08 06:39:06 -05:00
|
|
|
Ending Pry session for 20
|
2011-02-19 05:28:41 -05:00
|
|
|
pry(Hello):1> cd ..
|
2010-12-08 06:39:06 -05:00
|
|
|
Ending Pry session for Hello
|
2011-02-19 05:28:41 -05:00
|
|
|
pry(main)> cd ..
|
2010-12-08 06:39:06 -05:00
|
|
|
Ending Pry session for main
|
2010-12-08 19:59:30 -05:00
|
|
|
|
|
|
|
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
|
2011-01-13 09:35:46 -05:00
|
|
|
|
2010-12-08 19:59:30 -05:00
|
|
|
We can then jump back to any of the previous nesting levels by using
|
2011-02-16 16:22:59 -05:00
|
|
|
the `jump-to` command:
|
2010-12-08 19:59:30 -05:00
|
|
|
|
2011-02-16 16:22:59 -05:00
|
|
|
pry("friend":3)> jump-to 1
|
2010-12-08 19:59:30 -05:00
|
|
|
Ending Pry session for "friend"
|
|
|
|
Ending Pry session for 100
|
|
|
|
=> 100
|
|
|
|
pry(Hello):1>
|
|
|
|
|
2011-01-13 09:35:46 -05:00
|
|
|
If we just want to go back one level of nesting we can of course
|
2010-12-08 19:59:30 -05:00
|
|
|
use the `quit` or `exit` or `back` commands.
|
|
|
|
|
2010-12-11 00:22:17 -05:00
|
|
|
To break out of all levels of Pry nesting and return immediately to the
|
2011-02-16 16:22:59 -05:00
|
|
|
calling process use `exit-all`:
|
2010-12-08 19:59:30 -05:00
|
|
|
|
2011-02-16 16:22:59 -05:00
|
|
|
pry("friend":3)> exit-all
|
2010-12-08 19:59:30 -05:00
|
|
|
Ending Pry session for "friend"
|
|
|
|
Ending Pry session for 100
|
|
|
|
Ending Pry session for Hello
|
|
|
|
Ending Pry session for main
|
|
|
|
=> main
|
2011-01-13 09:35:46 -05:00
|
|
|
|
2010-12-08 19:59:30 -05:00
|
|
|
# program resumes here
|
2010-12-08 07:06:49 -05:00
|
|
|
|
2010-12-08 06:39:06 -05:00
|
|
|
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.
|
|
|
|
|
2011-01-19 03:40:43 -05:00
|
|
|
###Features:
|
2010-12-08 07:06:49 -05:00
|
|
|
|
2010-12-08 06:39:06 -05:00
|
|
|
* Pry can be invoked at any time and on any object in the running program.
|
2011-03-14 23:31:40 -04:00
|
|
|
* Additional documentation and source code for Ruby Core methods are supported when the `pry-doc` gem is installed.
|
2010-12-08 19:59:30 -05:00
|
|
|
* Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
|
2011-03-06 01:46:44 -05:00
|
|
|
* Pry comes with syntax highlighting on by default just use the `toggle-color` command to turn it on and off.
|
2010-12-08 19:59:30 -05:00
|
|
|
* Use `_` to recover last result.
|
2011-01-09 06:51:45 -05:00
|
|
|
* Use `_pry_` to reference the Pry instance managing the current session.
|
2011-03-14 23:31:40 -04:00
|
|
|
* Use `_ex_` to recover the last exception.
|
2011-01-12 08:03:45 -05:00
|
|
|
* Pry supports tab completion.
|
2010-12-08 06:39:06 -05:00
|
|
|
* Pry has multi-line support built in.
|
2011-02-17 05:04:20 -05:00
|
|
|
* Use `^d` (control-d) to quickly break out of a session.
|
2011-02-16 16:22:59 -05:00
|
|
|
* Pry has special commands not found in many other Ruby REPLs: `show-method`, `show-doc`
|
|
|
|
`jump-to`, `ls`, `cd`, `cat`
|
2010-12-11 00:22:17 -05:00
|
|
|
* Pry gives good control over nested sessions (important when exploring complicated runtime state)
|
2010-12-08 09:57:50 -05:00
|
|
|
* Pry is not based on the IRB codebase.
|
2011-01-15 03:57:50 -05:00
|
|
|
* Pry allows significant customizability.
|
2011-01-23 19:39:15 -05:00
|
|
|
* Pry uses the [method_source](https://github.com/banister/method_source) gem; so
|
|
|
|
this functionality is available to a Pry session.
|
2010-12-16 23:56:50 -05:00
|
|
|
* Pry uses [RubyParser](https://github.com/seattlerb/ruby_parser) to
|
|
|
|
validate expressions in 1.8, and [Ripper](http://rdoc.info/docs/ruby-core/1.9.2/Ripper) for 1.9.
|
|
|
|
* Pry implements all the methods in the REPL chain separately: `Pry#r`
|
|
|
|
for reading; `Pry#re` for eval; `Pry#rep` for printing; and `Pry#repl`
|
|
|
|
for the loop (`Pry.start` simply wraps `Pry.new.repl`). You can
|
2010-12-08 07:06:49 -05:00
|
|
|
invoke any of these methods directly depending on exactly what aspect of the functionality you need.
|
|
|
|
|
2011-01-19 03:40:43 -05:00
|
|
|
###Limitations:
|
2010-12-08 07:06:49 -05:00
|
|
|
|
2011-02-27 11:18:34 -05:00
|
|
|
* Some Pry commands (e.g `show-command`) do not work in Ruby 1.8.
|
2011-03-01 08:14:38 -05:00
|
|
|
* `method_source` functionality does not work in JRuby.
|
2011-02-25 21:45:11 -05:00
|
|
|
* 1.9 support requires `Ripper` - some implementations may not support this.
|
2011-01-13 09:35:46 -05:00
|
|
|
|
2010-12-08 08:49:28 -05:00
|
|
|
Commands
|
|
|
|
-----------
|
|
|
|
|
2010-12-11 00:22:17 -05:00
|
|
|
### The Pry API:
|
2010-12-08 08:49:28 -05:00
|
|
|
|
2010-12-16 23:56:50 -05:00
|
|
|
* `Pry.start()` Starts a Read-Eval-Print-Loop on the object it
|
|
|
|
receives as a parameter. In the case of no parameter it operates on
|
|
|
|
top-level (main). It can receive any object or a `Binding`
|
|
|
|
object as parameter. `Pry.start()` is implemented as `Pry.new.repl()`
|
2011-01-09 06:51:45 -05:00
|
|
|
* `obj.pry` and `pry(obj)` may also be used as alternative syntax to
|
|
|
|
`Pry.start(obj)`.
|
|
|
|
|
|
|
|
However there are some differences. `obj.pry` opens
|
|
|
|
a Pry session on the receiver whereas `Pry.start` (with no parameter)
|
|
|
|
will start a Pry session on top-level. The other form of the `pry`
|
|
|
|
method: `pry(obj)` will also start a Pry session on its parameter.
|
|
|
|
|
|
|
|
The `pry` method invoked by itself, with no explict receiver and no
|
|
|
|
parameter will start a Pry session on the implied receiver. It is
|
|
|
|
perhaps more useful to invoke it in this form `pry(binding)` or
|
|
|
|
`binding.pry` so as to get access to locals in the current context.
|
|
|
|
|
|
|
|
Another difference is that `Pry.start()` accepts a second parameter
|
|
|
|
that is a hash of configuration options (discussed further, below).
|
|
|
|
|
2010-12-16 23:56:50 -05:00
|
|
|
* If, for some reason you do not want to 'loop' then use `Pry.new.rep()`; it
|
2010-12-08 08:49:28 -05:00
|
|
|
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
|
2011-01-13 09:35:46 -05:00
|
|
|
`Pry#repl()`
|
2010-12-16 23:56:50 -05:00
|
|
|
* Likewise `Pry#re()` only performs the Read-Eval section of the REPL,
|
2010-12-08 10:06:25 -05:00
|
|
|
it returns the result of the evaluation or an Exception object in
|
2010-12-16 23:56:50 -05:00
|
|
|
case of error. It also takes the same parameters as `Pry#repl()`
|
|
|
|
* Similarly `Pry#r()` only performs the Read section of the REPL, only
|
2010-12-08 10:06:25 -05:00
|
|
|
returning the Ruby expression (as a string). It takes the same parameters as all the others.
|
2011-02-18 12:01:21 -05:00
|
|
|
* `Pry.run_command COMMAND` enables you to invoke Pry commands outside
|
|
|
|
of a session, e.g `Pry.run_command "ls -m", :context => MyObject`. See
|
|
|
|
docs for more info.
|
2010-12-08 08:49:28 -05:00
|
|
|
|
2010-12-11 00:22:17 -05:00
|
|
|
### Session commands
|
|
|
|
|
|
|
|
Pry supports a few commands inside the session itself. These commands are
|
2010-12-08 19:59:30 -05:00
|
|
|
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.
|
2010-12-08 08:49:28 -05:00
|
|
|
|
2011-02-16 16:22:59 -05:00
|
|
|
* Typing `!` on a line by itself will clear the input buffer - useful for
|
|
|
|
getting you out of a situation where the parsing process
|
|
|
|
goes wrong and you get stuck in an endless read loop.
|
2010-12-11 04:01:47 -05:00
|
|
|
* `status` shows status information about the current session.
|
2011-03-05 09:17:54 -05:00
|
|
|
* `whereami` shows the code context of the session.
|
2011-02-16 16:22:59 -05:00
|
|
|
* `version` Show Pry version information
|
2010-12-11 04:01:47 -05:00
|
|
|
* `help` shows the list of session commands with brief explanations.
|
2011-03-03 06:50:04 -05:00
|
|
|
* `toggle-color` turns on and off syntax highlighting.
|
|
|
|
* `simple-prompt` toggles the simple prompt mode.
|
2011-02-17 04:56:53 -05:00
|
|
|
* `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
|
2010-12-11 00:22:17 -05:00
|
|
|
back to the calling process or back one level of nesting (if there
|
|
|
|
are nested sessions).
|
2011-02-16 16:22:59 -05:00
|
|
|
* `ls [OPTIONS] [VAR]` returns a list of local variables, instance variables, and
|
|
|
|
methods, etc. Highly flexible. See `ls --help` for more info.
|
|
|
|
* `cat VAR` Calls `inspect` on `VAR`
|
|
|
|
* `cd VAR` Starts a `Pry` session on the variable VAR. E.g `cd @x`
|
2011-01-23 19:39:15 -05:00
|
|
|
(use `cd ..` to go back).
|
2011-02-16 16:22:59 -05:00
|
|
|
* `show-method [OPTIONS] METH` Displays the sourcecode for the method
|
2011-02-17 05:26:19 -05:00
|
|
|
`METH`. e.g `show-method hello`. See `show-method --help` for more info.
|
2011-02-16 16:22:59 -05:00
|
|
|
* `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
|
|
|
|
--help` for more info.
|
2011-02-17 05:26:19 -05:00
|
|
|
* `show-command COMMAND` Displays the sourcecode for the given Pry
|
|
|
|
command. e.g: `show-command cd`
|
2011-02-16 16:22:59 -05:00
|
|
|
* `jump-to NEST_LEVEL` Unwinds the Pry stack (nesting level) until the appropriate nesting level is reached.
|
|
|
|
* `exit-all` breaks out of all Pry nesting levels and returns to the
|
2010-12-08 19:59:30 -05:00
|
|
|
calling process.
|
2010-12-08 07:06:49 -05:00
|
|
|
|
2011-03-05 09:17:54 -05:00
|
|
|
Syntax Highlighting
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
Syntax highlighting is on by default in Pry. You can toggle it on and
|
|
|
|
off in a session by using the `toggle-color` command. Alternatively,
|
|
|
|
you can turn it off permanently by putting the line `Pry.color =
|
|
|
|
false` in your `~/.pryrc` file.
|
|
|
|
|
2011-01-29 00:23:26 -05:00
|
|
|
Bindings and objects
|
|
|
|
--------------------
|
|
|
|
|
|
|
|
Pry ultimately operates on `Binding` objects. If you invoke Pry with a
|
|
|
|
Binding object it uses that Binding. If you invoke Pry with anything
|
|
|
|
other than a `Binding`, Pry will generate a Binding for that
|
|
|
|
object and use that.
|
|
|
|
|
|
|
|
If you want to open a Pry session on the current context and capture
|
|
|
|
the locals you should use: `binding.pry`. If you do not care about
|
|
|
|
capturing the locals you can simply use `pry` (which will generate a
|
|
|
|
fresh `Binding` for the receiver).
|
|
|
|
|
|
|
|
Top-level is a special case; you can start a Pry session on top-level
|
|
|
|
*and* capture locals by simply using: `pry`. This is because Pry
|
|
|
|
automatically uses `TOPLEVEL_BINDING` for the top-level object (main).
|
|
|
|
|
2011-01-21 01:09:21 -05:00
|
|
|
Example Programs
|
|
|
|
----------------
|
|
|
|
|
|
|
|
Pry comes bundled with a few example programs to illustrate some
|
|
|
|
features, see the `examples/` directory.
|
|
|
|
|
2011-02-04 22:14:28 -05:00
|
|
|
* `example_basic.rb` - Demonstrate basic Pry functionality
|
2011-01-21 04:17:12 -05:00
|
|
|
* `example_input.rb` - Demonstrates how to set the `input` object.
|
|
|
|
* `example_output.rb` - Demonstrates how to set the `output` object.
|
|
|
|
* `example_hooks.rb` - Demonstrates how to set the `hooks` hash.
|
|
|
|
* `example_print.rb` - Demonstrates how to set the `print` object.
|
|
|
|
* `example_prompt.rb` - Demonstrates how to set the `prompt`.
|
|
|
|
* `example_input2.rb` - An advanced `input` example.
|
|
|
|
* `example_commands.rb` - Implementing a mathematical command set.
|
|
|
|
* `example_commands_override.rb` - An advanced `commands` example.
|
|
|
|
* `example_image_edit.rb` - A simple image editor using a Pry REPL (requires `Gosu` and `TexPlay` gems).
|
|
|
|
|
2011-01-09 06:51:45 -05:00
|
|
|
Customizing Pry
|
|
|
|
---------------
|
|
|
|
|
2011-01-22 09:02:10 -05:00
|
|
|
Pry allows a large degree of customization.
|
2011-01-09 06:51:45 -05:00
|
|
|
|
2011-01-21 21:50:19 -05:00
|
|
|
[Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
|
2011-01-21 20:40:24 -05:00
|
|
|
|
2010-12-08 02:30:38 -05:00
|
|
|
Contact
|
|
|
|
-------
|
|
|
|
|
|
|
|
Problems or questions contact me at [github](http://github.com/banister)
|