2011-04-19 10:37:10 +00:00
|
|
|
|
![Alt text](http://dl.dropbox.com/u/26521875/pry_logo_shade.png)
|
2011-04-20 04:02:03 +00:00
|
|
|
|
|
2011-01-24 00:39:15 +00:00
|
|
|
|
(C) John Mair (banisterfiend) 2011
|
2010-12-08 07:30:38 +00:00
|
|
|
|
|
2011-04-18 04:50:19 +00:00
|
|
|
|
_Get to the code_
|
2010-12-08 07:30:38 +00:00
|
|
|
|
|
2011-04-13 11:49:45 +00:00
|
|
|
|
Pry is a powerful alternative to the standard IRB shell for Ruby. It is
|
|
|
|
|
written from scratch to provide a number of advanced features, some of
|
|
|
|
|
these include:
|
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
* Source code browsing (including core C source with the pry-doc gem)
|
|
|
|
|
* Documentation browsing
|
|
|
|
|
* Live help system
|
2011-04-18 05:56:17 +00:00
|
|
|
|
* Syntax highlighting
|
2011-04-23 12:22:51 +00:00
|
|
|
|
* Command shell integration (start editors, run git, and rake from within Pry)
|
|
|
|
|
* Gist integration
|
2011-04-18 04:50:19 +00:00
|
|
|
|
* Navigation around state (`cd`, `ls` and friends)
|
2011-04-18 06:43:47 +00:00
|
|
|
|
* Runtime invocation (use Pry as a developer console or debugger)
|
2011-04-13 11:49:45 +00:00
|
|
|
|
* Exotic object support (BasicObject instances, IClasses, ...)
|
|
|
|
|
* A Powerful and flexible command system
|
2011-04-18 04:50:19 +00:00
|
|
|
|
* Ability to view and replay history
|
2011-04-18 05:56:17 +00:00
|
|
|
|
* Many convenience commands inspired by IPython and other advanced REPLs
|
2010-12-08 07:30:38 +00:00
|
|
|
|
|
2011-01-22 14:02:10 +00:00
|
|
|
|
Pry is also fairly flexible and allows significant user
|
2011-01-30 13:50:18 +00: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-30 02:00:19 +00:00
|
|
|
|
`puts` method - many other aspects of Pry are also configurable making
|
|
|
|
|
it a good choice for implementing custom shells.
|
2011-01-22 14:02:10 +00:00
|
|
|
|
|
2011-03-15 03:31:40 +00:00
|
|
|
|
Pry comes with an executable so it can be invoked at the command line.
|
2011-02-20 16:54:18 +00:00
|
|
|
|
Just enter `pry` to start. A `.pryrc` file in the user's home directory will
|
2011-03-15 03:31:40 +00: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 16:54:18 +00:00
|
|
|
|
|
2010-12-08 11:39:06 +00: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 07:30:38 +00:00
|
|
|
|
|
2011-01-23 14:03:39 +00: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`
|
2011-04-23 10:43:56 +00:00
|
|
|
|
3. Finally choose 'Yes' to upload the results.
|
2011-01-23 14:03:39 +00:00
|
|
|
|
|
2011-04-23 10:43:56 +00:00
|
|
|
|
### Commands
|
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
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
|
2011-04-23 10:43:56 +00:00
|
|
|
|
whitespace in between. Commands support a flexible syntax and allow
|
2011-04-23 12:22:51 +00:00
|
|
|
|
'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
|
|
|
|
|
[:parser_class, :parser_type=, :parser_type_for_filename]
|
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
### Navigating around state
|
2010-12-08 07:30:38 +00:00
|
|
|
|
|
2011-04-18 05:56:17 +00:00
|
|
|
|
Pry allows us to pop in and out of different scopes (objects) using
|
2011-04-22 12:47:15 +00:00
|
|
|
|
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
|
2011-04-21 02:43:52 +00:00
|
|
|
|
within a particular scope we use the versatile [ls command.](https://gist.github.com/c0fc686ef923c8b87715)
|
2010-12-08 11:39:06 +00:00
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
Here we will begin Pry at top-level, then Pry on a class and then on
|
2010-12-08 11:39:06 +00:00
|
|
|
|
an instance variable inside that class:
|
|
|
|
|
|
|
|
|
|
pry(main)> class Hello
|
|
|
|
|
pry(main)* @x = 20
|
|
|
|
|
pry(main)* end
|
|
|
|
|
=> 20
|
2011-02-17 10:01:33 +00:00
|
|
|
|
pry(main)> cd Hello
|
2011-04-18 05:56:17 +00:00
|
|
|
|
pry(Hello):1> ls -i
|
2010-12-08 11:39:06 +00:00
|
|
|
|
=> [:@x]
|
2011-02-17 10:01:33 +00:00
|
|
|
|
pry(Hello):1> cd @x
|
2010-12-09 00:59:30 +00:00
|
|
|
|
pry(20:2)> self + 10
|
2010-12-08 11:39:06 +00:00
|
|
|
|
=> 30
|
2011-02-19 10:28:41 +00:00
|
|
|
|
pry(20:2)> cd ..
|
|
|
|
|
pry(Hello):1> cd ..
|
|
|
|
|
pry(main)> cd ..
|
2010-12-09 00:59:30 +00: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 14:35:46 +00:00
|
|
|
|
|
2010-12-09 00:59:30 +00:00
|
|
|
|
We can then jump back to any of the previous nesting levels by using
|
2011-02-16 21:22:59 +00:00
|
|
|
|
the `jump-to` command:
|
2010-12-09 00:59:30 +00:00
|
|
|
|
|
2011-02-16 21:22:59 +00:00
|
|
|
|
pry("friend":3)> jump-to 1
|
2010-12-09 00:59:30 +00:00
|
|
|
|
Ending Pry session for "friend"
|
|
|
|
|
Ending Pry session for 100
|
|
|
|
|
=> 100
|
|
|
|
|
pry(Hello):1>
|
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
### Runtime invocation
|
2011-04-18 06:43:47 +00:00
|
|
|
|
|
|
|
|
|
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
|
2011-04-18 08:08:14 +00:00
|
|
|
|
point available. When the session ends the program continues with any
|
2011-04-18 06:43:47 +00:00
|
|
|
|
modifications you made to it.
|
|
|
|
|
|
|
|
|
|
This functionality can be used for such things as: debugging,
|
2011-04-19 10:37:10 +00:00
|
|
|
|
implementing developer consoles and applying hot patches.
|
2011-04-18 06:43:47 +00:00
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
2011-04-18 08:08:14 +00:00
|
|
|
|
program resumes here.
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
### Command Shell Integration
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
|
|
|
|
A line of input that begins with a '.' will be forwarded to the
|
|
|
|
|
command shell. This enables us to navigate the file system, spawn
|
2011-04-21 02:43:52 +00:00
|
|
|
|
editors, and run git and rake directly from within Pry.
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
|
|
|
|
Further, we can use the `shell-mode` command to incorporate the
|
2011-04-21 02:43:52 +00:00
|
|
|
|
present working directory into the Pry prompt and bring in (limited at this stage, sorry) file name completion.
|
2011-04-19 10:37:10 +00:00
|
|
|
|
We can also interpolate Ruby code directly into the shell by
|
|
|
|
|
using the normal `#{}` string interpolation syntax.
|
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
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.
|
2011-04-20 04:02:03 +00:00
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
pry(main)> shell-mode
|
|
|
|
|
pry main:/home/john/ruby/projects/pry $ .cd ~
|
|
|
|
|
=> /home/john
|
|
|
|
|
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!
|
|
|
|
|
|
|
|
|
|
We can also interpolate Ruby code into the shell. In the
|
2011-04-20 04:02:03 +00:00
|
|
|
|
example below we use the shell command `cat` on a random file from the
|
|
|
|
|
current directory and count the number of lines in that file with
|
|
|
|
|
`wc`:
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l
|
|
|
|
|
44
|
|
|
|
|
|
|
|
|
|
### Code Browsing
|
|
|
|
|
|
2011-04-22 06:09:27 +00:00
|
|
|
|
#### show-method
|
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
You can browse method source code with the `show-method` command. Nearly all Ruby methods (and some C methods, with the pry-doc
|
|
|
|
|
gem) can have their source viewed. Code that is longer than a page is
|
|
|
|
|
sent through a pager (such as less), and all code is properly syntax
|
|
|
|
|
highlighted (even C code).
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
The `show-method` command accepts two syntaxes, the typical ri
|
|
|
|
|
`Class#method` syntax and also simply the name of a method that's in
|
|
|
|
|
scope. You can optionally pass the `-l` option to show-method to
|
|
|
|
|
include line numbers in the output.
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
2011-04-21 02:43:52 +00:00
|
|
|
|
In the following example we will enter the `Pry` class, list the
|
|
|
|
|
instance methods beginning with 're' and display the source code for the `rep` method:
|
|
|
|
|
|
|
|
|
|
pry(main)> cd Pry
|
|
|
|
|
pry(Pry):1> ls -M --grep ^re
|
|
|
|
|
[:re, :readline, :rep, :repl, :repl_epilogue, :repl_prologue, :retrieve_line]
|
|
|
|
|
pry(Pry):1> show-method rep -l
|
|
|
|
|
|
|
|
|
|
From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb @ line 143:
|
|
|
|
|
Number of lines: 6
|
|
|
|
|
|
|
|
|
|
143: def rep(target=TOPLEVEL_BINDING)
|
|
|
|
|
144: target = Pry.binding_for(target)
|
|
|
|
|
145: result = re(target)
|
|
|
|
|
146:
|
|
|
|
|
147: show_result(result) if should_print?
|
|
|
|
|
148: end
|
|
|
|
|
|
|
|
|
|
Note that we can also view C methods (from Ruby Core) using the
|
|
|
|
|
`pry-doc` gem; we also show off the alternate syntax for
|
|
|
|
|
`show-method`:
|
|
|
|
|
|
|
|
|
|
pry(main)> show-method Array#select
|
|
|
|
|
|
|
|
|
|
From: array.c in Ruby Core (C Method):
|
|
|
|
|
Number of lines: 15
|
|
|
|
|
|
|
|
|
|
static VALUE
|
|
|
|
|
rb_ary_select(VALUE ary)
|
|
|
|
|
{
|
|
|
|
|
VALUE result;
|
|
|
|
|
long i;
|
|
|
|
|
|
|
|
|
|
RETURN_ENUMERATOR(ary, 0, 0);
|
|
|
|
|
result = rb_ary_new2(RARRAY_LEN(ary));
|
|
|
|
|
for (i = 0; i < RARRAY_LEN(ary); i++) {
|
|
|
|
|
if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
|
|
|
|
|
rb_ary_push(result, rb_ary_elt(ary, i));
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
return result;
|
|
|
|
|
}
|
2011-04-19 10:37:10 +00:00
|
|
|
|
|
2011-04-22 06:09:27 +00:00
|
|
|
|
#### Special locals
|
|
|
|
|
|
2011-04-23 10:43:56 +00:00
|
|
|
|
Some commands such as `show-method`, `show-doc`, `show-command`, `stat`
|
2011-04-22 06:09:27 +00:00
|
|
|
|
and `cat` update the `_file_` and `_dir_` local variables after they
|
|
|
|
|
run. These locals contain the full path to the file involved in the
|
|
|
|
|
last command as well as the directory containing that file.
|
|
|
|
|
|
|
|
|
|
You can then use these special locals in conjunction with shell
|
|
|
|
|
commands to do such things as change directory into the directory
|
2011-04-22 12:47:15 +00:00
|
|
|
|
containing the file, open the file in an editor, display the file using `cat`, and so on.
|
2011-04-18 06:43:47 +00:00
|
|
|
|
|
2011-04-22 06:09:27 +00:00
|
|
|
|
In the following example we wil use Pry to fix a bug in a method:
|
|
|
|
|
|
|
|
|
|
pry(main)> greet "john"
|
|
|
|
|
hello johnhow are you?=> nil
|
|
|
|
|
pry(main)> show-method greet
|
|
|
|
|
|
|
|
|
|
From: /Users/john/ruby/play/bug.rb @ line 2:
|
|
|
|
|
Number of lines: 4
|
|
|
|
|
|
|
|
|
|
def greet(name)
|
|
|
|
|
print "hello #{name}"
|
|
|
|
|
print "how are you?"
|
|
|
|
|
end
|
|
|
|
|
pry(main)> .emacsclient #{_file_}
|
|
|
|
|
pry(main)> load _file_
|
|
|
|
|
pry(main)> greet "john"
|
|
|
|
|
hello john
|
|
|
|
|
how are you?
|
|
|
|
|
=> nil
|
|
|
|
|
pry(main)> show-method greet
|
|
|
|
|
|
|
|
|
|
From: /Users/john/ruby/play/bug.rb @ line 2:
|
|
|
|
|
Number of lines: 4
|
|
|
|
|
|
|
|
|
|
def greet(name)
|
|
|
|
|
puts "hello #{name}"
|
|
|
|
|
puts "how are you?"
|
|
|
|
|
end
|
2011-04-22 12:47:15 +00:00
|
|
|
|
|
|
|
|
|
|
2011-04-23 10:43:56 +00:00
|
|
|
|
### Documentation Browsing
|
2011-04-22 12:47:15 +00:00
|
|
|
|
|
|
|
|
|
One use-case for Pry is to explore a program at run-time by `cd`-ing
|
|
|
|
|
in and out of objects and viewing and invoking methods. In the course
|
|
|
|
|
of exploring it may be useful to read the documentation for a
|
|
|
|
|
specific method that you come across. Like `show-method` the `show-doc` command supports
|
|
|
|
|
two syntaxes - the normal `ri` syntax as well as accepting the name of
|
|
|
|
|
any method that is currently in scope.
|
|
|
|
|
|
|
|
|
|
The Pry documentation system does not rely on pre-generated `rdoc` or
|
|
|
|
|
`ri`, instead it grabs the comments directly above the method on
|
|
|
|
|
demand. This results in speedier documentation retrieval and allows
|
|
|
|
|
the Pry system to retrieve documentation for methods that would not be
|
|
|
|
|
picked up by `rdoc`. Pry also has a basic understanding of both the
|
|
|
|
|
rdoc and yard formats and will attempt to syntax highlight the
|
|
|
|
|
documentation appropriately.
|
|
|
|
|
|
2011-04-23 10:43:56 +00:00
|
|
|
|
Nonetheless The `ri` functionality is very good and
|
2011-04-22 12:47:15 +00:00
|
|
|
|
has an advantage over Pry's system in that it allows documentation
|
|
|
|
|
lookup for classes as well as methods. Pry therefore has good
|
|
|
|
|
integration with `ri` through the `ri` command. The syntax
|
|
|
|
|
for the command is exactly as it would be in command-line -
|
2011-04-23 10:43:56 +00:00
|
|
|
|
so it is not necessary to quote strings.
|
2011-04-22 12:47:15 +00:00
|
|
|
|
|
|
|
|
|
In our example we will enter the `Gem` class and view the
|
|
|
|
|
documentation for the `try_activate` method:
|
|
|
|
|
|
|
|
|
|
pry(main)> cd Gem
|
2011-04-23 10:43:56 +00:00
|
|
|
|
pry(Gem):1> show-doc try_activate
|
2011-04-22 12:47:15 +00:00
|
|
|
|
|
|
|
|
|
From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/site_ruby/1.9.1/rubygems.rb @ line 201:
|
|
|
|
|
Number of lines: 3
|
|
|
|
|
|
|
|
|
|
Try to activate a gem containing path. Returns true if
|
|
|
|
|
activation succeeded or wasn't needed because it was already
|
|
|
|
|
activated. Returns false if it can't find the path in a gem.
|
|
|
|
|
pry(Gem):1>
|
|
|
|
|
|
|
|
|
|
We can also use `ri` in the normal way:
|
|
|
|
|
|
|
|
|
|
pry(main) ri Array#each
|
|
|
|
|
----------------------------------------------------------- Array#each
|
|
|
|
|
array.each {|item| block } -> array
|
|
|
|
|
------------------------------------------------------------------------
|
|
|
|
|
Calls _block_ once for each element in _self_, passing that element
|
|
|
|
|
as a parameter.
|
2011-04-22 06:09:27 +00:00
|
|
|
|
|
2011-04-22 12:47:15 +00:00
|
|
|
|
a = [ "a", "b", "c" ]
|
|
|
|
|
a.each {|x| print x, " -- " }
|
|
|
|
|
|
|
|
|
|
produces:
|
|
|
|
|
|
|
|
|
|
a -- b -- c --
|
|
|
|
|
|
2011-04-23 10:43:56 +00:00
|
|
|
|
|
|
|
|
|
### History
|
|
|
|
|
|
|
|
|
|
Readline history can be viewed and replayed using the `hist`
|
|
|
|
|
command. When `hist` is invoked with no arguments it simply displays
|
|
|
|
|
the history (passing the output through a pager if necessary))
|
|
|
|
|
when the `--replay` option is used a line or a range of lines of
|
|
|
|
|
history can be replayed.
|
|
|
|
|
|
|
|
|
|
In the example below we will enter a few lines in a Pry session and
|
|
|
|
|
then view history; we will then replay one of those lines:
|
|
|
|
|
|
|
|
|
|
pry(main)> hist
|
|
|
|
|
0: hist -h
|
|
|
|
|
1: ls
|
|
|
|
|
2: ls
|
|
|
|
|
3: show-method puts
|
|
|
|
|
4: x = rand
|
|
|
|
|
5: hist
|
|
|
|
|
pry(main)> hist --replay 3
|
|
|
|
|
|
|
|
|
|
From: io.c in Ruby Core (C Method):
|
|
|
|
|
Number of lines: 8
|
|
|
|
|
|
|
|
|
|
static VALUE
|
|
|
|
|
rb_f_puts(int argc, VALUE *argv, VALUE recv)
|
|
|
|
|
{
|
|
|
|
|
if (recv == rb_stdout) {
|
|
|
|
|
return rb_io_puts(argc, argv, recv);
|
|
|
|
|
}
|
|
|
|
|
return rb_funcall2(rb_stdout, rb_intern("puts"), argc, argv);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
In the next example we will replay a range of lines in history. Note
|
|
|
|
|
that we replay to a point where a class definition is still open and so
|
|
|
|
|
we can continue to add instance methods to the class:
|
|
|
|
|
|
|
|
|
|
pry(main)> hist
|
|
|
|
|
0: class Hello
|
|
|
|
|
1: def hello_world
|
|
|
|
|
2: puts "hello world!"
|
|
|
|
|
3: end
|
|
|
|
|
4: end
|
|
|
|
|
5: hist
|
|
|
|
|
pry(main)> hist --replay 0..3
|
|
|
|
|
pry(main)* def goodbye_world
|
|
|
|
|
pry(main)* puts "goodbye world!"
|
|
|
|
|
pry(main)* end
|
|
|
|
|
pry(main)* end
|
|
|
|
|
=> nil
|
|
|
|
|
pry(main)> Hello.new.goodbye_world;
|
|
|
|
|
goodbye world!
|
|
|
|
|
pry(main)>
|
|
|
|
|
|
|
|
|
|
Also note that in the above the line `Hello.new.goodbye_world;` ends
|
|
|
|
|
with a semi-colon which causes expression evaluation output to be suppressed.
|
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
### Gist integration
|
|
|
|
|
|
|
|
|
|
If the `gist` gem installed then Method source or documentation can be gisted to github with the
|
|
|
|
|
`gist-method` command. The `gist-method` command accepts the same two
|
|
|
|
|
syntaxes as `show-method`. In the example below we will gist the C source
|
|
|
|
|
code for the `Symbol#to_proc` method to github:
|
|
|
|
|
|
|
|
|
|
pry(main)> gist-method Symbol#to_proc
|
|
|
|
|
https://gist.github.com/5332c38afc46d902ce46
|
|
|
|
|
pry(main)>
|
|
|
|
|
|
|
|
|
|
You can see the actual gist generated here: https://gist.github.com/5332c38afc46d902ce46
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Live Help System
|
2011-04-23 10:43:56 +00:00
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
Many other commands are available in Pry; to see the full list type
|
|
|
|
|
`help` at the prompt. A short description of each command is provided
|
|
|
|
|
with basic instructions for use; some commands have a more extensive
|
|
|
|
|
help that can be accessed via typeing `command_name --help`. A command
|
|
|
|
|
will typically say in its description if the `--help` option is
|
|
|
|
|
avaiable.
|
2010-12-08 11:39:06 +00:00
|
|
|
|
|
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
### Other Features and limitations
|
2010-12-08 11:39:06 +00:00
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
#### Features:
|
2010-12-08 12:06:49 +00:00
|
|
|
|
|
2011-04-23 12:22:51 +00:00
|
|
|
|
* Pry can be invoked both at the command-line and used as a more
|
|
|
|
|
powerful alternative to IRB or it can be invoked at runtime and used
|
|
|
|
|
as a developer consoler / debugger.
|
2011-03-15 03:31:40 +00:00
|
|
|
|
* Additional documentation and source code for Ruby Core methods are supported when the `pry-doc` gem is installed.
|
2010-12-09 00:59:30 +00:00
|
|
|
|
* Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
|
2011-03-06 06:46:44 +00:00
|
|
|
|
* Pry comes with syntax highlighting on by default just use the `toggle-color` command to turn it on and off.
|
2010-12-09 00:59:30 +00:00
|
|
|
|
* Use `_` to recover last result.
|
2011-01-09 11:51:45 +00:00
|
|
|
|
* Use `_pry_` to reference the Pry instance managing the current session.
|
2011-03-15 03:31:40 +00:00
|
|
|
|
* Use `_ex_` to recover the last exception.
|
2011-04-23 12:22:51 +00:00
|
|
|
|
* Use `_file_` and `_dir_` to refer to the associated file or
|
|
|
|
|
directory containing the definition for a method.
|
2011-01-12 13:03:45 +00:00
|
|
|
|
* Pry supports tab completion.
|
2010-12-08 11:39:06 +00:00
|
|
|
|
* Pry has multi-line support built in.
|
2011-02-17 10:04:20 +00:00
|
|
|
|
* Use `^d` (control-d) to quickly break out of a session.
|
2011-02-16 21:22:59 +00:00
|
|
|
|
* Pry has special commands not found in many other Ruby REPLs: `show-method`, `show-doc`
|
|
|
|
|
`jump-to`, `ls`, `cd`, `cat`
|
2010-12-11 05:22:17 +00:00
|
|
|
|
* Pry gives good control over nested sessions (important when exploring complicated runtime state)
|
2010-12-08 14:57:50 +00:00
|
|
|
|
* Pry is not based on the IRB codebase.
|
2011-01-15 08:57:50 +00:00
|
|
|
|
* Pry allows significant customizability.
|
2011-01-24 00:39:15 +00:00
|
|
|
|
* Pry uses the [method_source](https://github.com/banister/method_source) gem; so
|
|
|
|
|
this functionality is available to a Pry session.
|
2010-12-17 04:56:50 +00: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 12:06:49 +00:00
|
|
|
|
invoke any of these methods directly depending on exactly what aspect of the functionality you need.
|
|
|
|
|
|
2011-01-19 08:40:43 +00:00
|
|
|
|
###Limitations:
|
2010-12-08 12:06:49 +00:00
|
|
|
|
|
2011-02-27 16:18:34 +00:00
|
|
|
|
* Some Pry commands (e.g `show-command`) do not work in Ruby 1.8.
|
2011-03-01 13:14:38 +00:00
|
|
|
|
* `method_source` functionality does not work in JRuby.
|
2011-02-26 02:45:11 +00:00
|
|
|
|
* 1.9 support requires `Ripper` - some implementations may not support this.
|
2011-01-13 14:35:46 +00:00
|
|
|
|
|
2010-12-08 13:49:28 +00:00
|
|
|
|
Commands
|
|
|
|
|
-----------
|
|
|
|
|
|
2010-12-11 05:22:17 +00:00
|
|
|
|
### The Pry API:
|
2010-12-08 13:49:28 +00:00
|
|
|
|
|
2010-12-17 04:56:50 +00: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 11:51:45 +00: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-17 04:56:50 +00:00
|
|
|
|
* If, for some reason you do not want to 'loop' then use `Pry.new.rep()`; it
|
2010-12-08 13:49:28 +00: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 14:35:46 +00:00
|
|
|
|
`Pry#repl()`
|
2010-12-17 04:56:50 +00:00
|
|
|
|
* Likewise `Pry#re()` only performs the Read-Eval section of the REPL,
|
2010-12-08 15:06:25 +00:00
|
|
|
|
it returns the result of the evaluation or an Exception object in
|
2010-12-17 04:56:50 +00: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 15:06:25 +00:00
|
|
|
|
returning the Ruby expression (as a string). It takes the same parameters as all the others.
|
2011-02-18 17:01:21 +00: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 13:49:28 +00:00
|
|
|
|
|
2010-12-11 05:22:17 +00:00
|
|
|
|
### Session commands
|
|
|
|
|
|
|
|
|
|
Pry supports a few commands inside the session itself. These commands are
|
2010-12-09 00:59:30 +00: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 13:49:28 +00:00
|
|
|
|
|
2011-02-16 21:22:59 +00: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 09:01:47 +00:00
|
|
|
|
* `status` shows status information about the current session.
|
2011-03-26 10:33:08 +00:00
|
|
|
|
* `whereami AROUND` shows the code context of the session. Shows
|
|
|
|
|
AROUND lines either side of the current line.
|
2011-02-16 21:22:59 +00:00
|
|
|
|
* `version` Show Pry version information
|
2010-12-11 09:01:47 +00:00
|
|
|
|
* `help` shows the list of session commands with brief explanations.
|
2011-03-03 11:50:04 +00:00
|
|
|
|
* `toggle-color` turns on and off syntax highlighting.
|
|
|
|
|
* `simple-prompt` toggles the simple prompt mode.
|
2011-02-17 09:56:53 +00:00
|
|
|
|
* `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
|
2010-12-11 05:22:17 +00:00
|
|
|
|
back to the calling process or back one level of nesting (if there
|
|
|
|
|
are nested sessions).
|
2011-02-16 21:22:59 +00: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-24 00:39:15 +00:00
|
|
|
|
(use `cd ..` to go back).
|
2011-02-16 21:22:59 +00:00
|
|
|
|
* `show-method [OPTIONS] METH` Displays the sourcecode for the method
|
2011-02-17 10:26:19 +00:00
|
|
|
|
`METH`. e.g `show-method hello`. See `show-method --help` for more info.
|
2011-02-16 21:22:59 +00:00
|
|
|
|
* `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
|
|
|
|
|
--help` for more info.
|
2011-02-17 10:26:19 +00:00
|
|
|
|
* `show-command COMMAND` Displays the sourcecode for the given Pry
|
|
|
|
|
command. e.g: `show-command cd`
|
2011-02-16 21:22:59 +00: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-09 00:59:30 +00:00
|
|
|
|
calling process.
|
2010-12-08 12:06:49 +00:00
|
|
|
|
|
2011-03-05 14:17:54 +00: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 05:23:26 +00: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 06:09:21 +00:00
|
|
|
|
Example Programs
|
|
|
|
|
----------------
|
|
|
|
|
|
|
|
|
|
Pry comes bundled with a few example programs to illustrate some
|
|
|
|
|
features, see the `examples/` directory.
|
|
|
|
|
|
2011-02-05 03:14:28 +00:00
|
|
|
|
* `example_basic.rb` - Demonstrate basic Pry functionality
|
2011-01-21 09:17:12 +00: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-04-21 02:43:52 +00:00
|
|
|
|
### Customizing Pry
|
2011-01-09 11:51:45 +00:00
|
|
|
|
|
2011-01-22 14:02:10 +00:00
|
|
|
|
Pry allows a large degree of customization.
|
2011-01-09 11:51:45 +00:00
|
|
|
|
|
2011-01-22 02:50:19 +00:00
|
|
|
|
[Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
|
2011-01-22 01:40:24 +00:00
|
|
|
|
|
2010-12-08 07:30:38 +00:00
|
|
|
|
Contact
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
Problems or questions contact me at [github](http://github.com/banister)
|