1
0
Fork 0
mirror of https://github.com/pry/pry.git synced 2022-11-09 12:35:05 -05:00
pry--pry/README.markdown

397 lines
15 KiB
Markdown
Raw Normal View History

![Alt text](http://dl.dropbox.com/u/26521875/pry_logo_shade.png)
(C) John Mair (banisterfiend) 2011
2010-12-08 02:30:38 -05:00
_Get to the code_
2010-12-08 02:30:38 -05:00
added highlighting to disabled commands in GNU bash, version 4.1.5(1)-release (i486-pc-linux-gnu) These shell commands are defined internally. Type `help' to see this list. Type `help name' to find out more about the function `name'. Use `info bash' to find out more about the shell in general. Use `man -k' or `info' to find out more about commands not in this list. A star (*) next to a name means that the command is disabled. job_spec [&] history [-c] [-d offset] [n] or history -anrw [filename] o> (( expression )) if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMANDS> . filename [arguments] jobs [-lnprs] [jobspec ...] or jobs -x command [args] : kill [-s sigspec | -n signum | -sigspec] pid | jobspec ...> [ arg... ] let arg [arg ...] [[ expression ]] local [option] name[=value] ... alias [-p] [name[=value] ... ] logout [n] bg [job_spec ...] mapfile [-n count] [-O origin] [-s count] [-t] [-u fd] [-C> bind [-lpvsPVS] [-m keymap] [-f filename] [-q name] [-u nam> popd [-n] [+N | -N] break [n] printf [-v var] format [arguments] builtin [shell-builtin [arg ...]] pushd [-n] [+N | -N | dir] caller [expr] pwd [-LP] case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac read [-ers] [-a array] [-d delim] [-i text] [-n nchars] [-> cd [-L|-P] [dir] readarray [-n count] [-O origin] [-s count] [-t] [-u fd] [> command [-pVv] command [arg ...] readonly [-af] [name[=value] ...] or readonly -p compgen [-abcdefgjksuv] [-o option] [-A action] [-G globpa> return [n] complete [-abcdefgjksuv] [-pr] [-DE] [-o option] [-A action> select NAME [in WORDS ... ;] do COMMANDS; done compopt [-o|+o option] [-DE] [name ...] set [--abefhkmnptuvxBCHP] [-o option-name] [arg ...] continue [n] shift [n] coproc [NAME] command [redirections] shopt [-pqsu] [-o] [optname ...] declare [-aAfFilrtux] [-p] [name[=value] ...] source filename [arguments] dirs [-clpv] [+N] [-N] suspend [-f] disown [-h] [-ar] [jobspec ...] test [expr] echo [-neE] [arg ...] time [-p] pipeline enable [-a] [-dnps] [-f filename] [name ...] times eval [arg ...] trap [-lp] [[arg] signal_spec ...] exec [-cl] [-a name] [command [arguments ...]] [redirection> true exit [n] type [-afptP] name [name ...] export [-fn] [name[=value] ...] or export -p typeset [-aAfFilrtux] [-p] name[=value] ... false ulimit [-SHacdefilmnpqrstuvx] [limit] fc [-e ename] [-lnr] [first] [last] or fc -s [pat=rep] [com> umask [-p] [-S] [mode] fg [job_spec] unalias [-a] name [name ...] for NAME [in WORDS ... ] ; do COMMANDS; done unset [-f] [-v] [name ...] for (( exp1; exp2; exp3 )); do COMMANDS; done until COMMANDS; do COMMANDS; done function name { COMMANDS ; } or name () { COMMANDS ; } variables - Names and meanings of some shell variables getopts optstring name [arg] wait [id] hash [-lr] [-p pathname] [-dt] [name ...] while COMMANDS; do COMMANDS; done help [-dms] [pattern ...] { COMMANDS ; }
2011-04-13 07:49:45 -04: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-18 01:56:17 -04:00
* Syntax highlighting
* Navigation around state (`cd`, `ls` and friends)
* Runtime invocation (use Pry as a developer console or debugger)
added highlighting to disabled commands in GNU bash, version 4.1.5(1)-release (i486-pc-linux-gnu) These shell commands are defined internally. Type `help' to see this list. Type `help name' to find out more about the function `name'. Use `info bash' to find out more about the shell in general. Use `man -k' or `info' to find out more about commands not in this list. A star (*) next to a name means that the command is disabled. job_spec [&] history [-c] [-d offset] [n] or history -anrw [filename] o> (( expression )) if COMMANDS; then COMMANDS; [ elif COMMANDS; then COMMANDS> . filename [arguments] jobs [-lnprs] [jobspec ...] or jobs -x command [args] : kill [-s sigspec | -n signum | -sigspec] pid | jobspec ...> [ arg... ] let arg [arg ...] [[ expression ]] local [option] name[=value] ... alias [-p] [name[=value] ... ] logout [n] bg [job_spec ...] mapfile [-n count] [-O origin] [-s count] [-t] [-u fd] [-C> bind [-lpvsPVS] [-m keymap] [-f filename] [-q name] [-u nam> popd [-n] [+N | -N] break [n] printf [-v var] format [arguments] builtin [shell-builtin [arg ...]] pushd [-n] [+N | -N | dir] caller [expr] pwd [-LP] case WORD in [PATTERN [| PATTERN]...) COMMANDS ;;]... esac read [-ers] [-a array] [-d delim] [-i text] [-n nchars] [-> cd [-L|-P] [dir] readarray [-n count] [-O origin] [-s count] [-t] [-u fd] [> command [-pVv] command [arg ...] readonly [-af] [name[=value] ...] or readonly -p compgen [-abcdefgjksuv] [-o option] [-A action] [-G globpa> return [n] complete [-abcdefgjksuv] [-pr] [-DE] [-o option] [-A action> select NAME [in WORDS ... ;] do COMMANDS; done compopt [-o|+o option] [-DE] [name ...] set [--abefhkmnptuvxBCHP] [-o option-name] [arg ...] continue [n] shift [n] coproc [NAME] command [redirections] shopt [-pqsu] [-o] [optname ...] declare [-aAfFilrtux] [-p] [name[=value] ...] source filename [arguments] dirs [-clpv] [+N] [-N] suspend [-f] disown [-h] [-ar] [jobspec ...] test [expr] echo [-neE] [arg ...] time [-p] pipeline enable [-a] [-dnps] [-f filename] [name ...] times eval [arg ...] trap [-lp] [[arg] signal_spec ...] exec [-cl] [-a name] [command [arguments ...]] [redirection> true exit [n] type [-afptP] name [name ...] export [-fn] [name[=value] ...] or export -p typeset [-aAfFilrtux] [-p] name[=value] ... false ulimit [-SHacdefilmnpqrstuvx] [limit] fc [-e ename] [-lnr] [first] [last] or fc -s [pat=rep] [com> umask [-p] [-S] [mode] fg [job_spec] unalias [-a] name [name ...] for NAME [in WORDS ... ] ; do COMMANDS; done unset [-f] [-v] [name ...] for (( exp1; exp2; exp3 )); do COMMANDS; done until COMMANDS; do COMMANDS; done function name { COMMANDS ; } or name () { COMMANDS ; } variables - Names and meanings of some shell variables getopts optstring name [arg] wait [id] hash [-lr] [-p pathname] [-dt] [name ...] while COMMANDS; do COMMANDS; done help [-dms] [pattern ...] { COMMANDS ; }
2011-04-13 07:49:45 -04:00
* Command shell integration
* Source code browsing (including core C source with the pry-doc gem)
* Documentation browsing
* Exotic object support (BasicObject instances, IClasses, ...)
* A Powerful and flexible command system
* Ability to view and replay history
2011-04-18 01:56:17 -04:00
* Many convenience commands inspired by IPython and other advanced REPLs
2010-12-08 02:30:38 -05:00
2010-12-08 11:18:01 -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.
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.
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
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-04-20 22:43:52 -04:00
### Navigating around state
2010-12-08 02:30:38 -05:00
2011-04-18 01:56:17 -04:00
Pry allows us to pop in and out of different scopes (objects) using
the `cd` command. To view which variables and methods are available
2011-04-20 22:43:52 -04:00
within a particular scope we use the versatile [ls command.](https://gist.github.com/c0fc686ef923c8b87715)
2010-12-08 06:39:06 -05:00
2011-04-20 22:43:52 -04:00
Here we will begin Pry at top-level, then Pry on a class and then on
2010-12-08 06:39:06 -05:00
an instance variable inside that class:
pry(main)> class Hello
pry(main)* @x = 20
pry(main)* end
=> 20
2011-02-17 05:01:33 -05:00
pry(main)> cd Hello
2011-04-18 01:56:17 -04:00
pry(Hello):1> ls -i
2010-12-08 06:39:06 -05:00
=> [:@x]
2011-02-17 05:01:33 -05:00
pry(Hello):1> cd @x
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 ..
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
Ending Pry session for "friend"
Ending Pry session for 100
=> 100
pry(Hello):1>
2011-04-20 22:43:52 -04:00
### Runtime invocation
Pry can be invoked in the middle of a running program. It opens a Pry
session at the point its called and makes all program state at that
2011-04-18 04:08:14 -04:00
point available. 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
2011-04-18 04:08:14 -04:00
program resumes here.
2011-04-20 22:43:52 -04:00
### Command Shell Integration
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-20 22:43:52 -04:00
editors, and run git and rake directly from within Pry.
Further, we can use the `shell-mode` command to incorporate the
2011-04-20 22:43:52 -04:00
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.
2011-04-20 22:43:52 -04: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 22:43:52 -04: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
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-20 22:43:52 -04:00
pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l
44
### Code Browsing
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-20 22:43:52 -04: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-20 22:43:52 -04: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;
}
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.
###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.
* Additional documentation and source code for Ruby Core methods are supported when the `pry-doc` gem is installed.
* Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
* Pry comes with syntax highlighting on by default just use the `toggle-color` command to turn it on and off.
* Use `_` to recover last result.
2011-01-09 06:51:45 -05:00
* Use `_pry_` to reference the Pry instance managing the current session.
* Use `_ex_` to recover the last exception.
* 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.
* Pry has special commands not found in many other Ruby REPLs: `show-method`, `show-doc`
`jump-to`, `ls`, `cd`, `cat`
* 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.
* Pry allows significant customizability.
* Pry uses the [method_source](https://github.com/banister/method_source) gem; so
this functionality is available to a Pry session.
* 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.
###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.
* `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.
Commands
-----------
### The Pry API:
* `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).
* If, for some reason you do not want to 'loop' then use `Pry.new.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#repl()`
* 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
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.
* `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.
### Session commands
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.
* 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.
* `status` shows status information about the current session.
2011-03-26 06:33:08 -04:00
* `whereami AROUND` shows the code context of the session. Shows
AROUND lines either side of the current line.
* `version` Show Pry version information
* `help` shows the list of session commands with brief explanations.
* `toggle-color` turns on and off syntax highlighting.
* `simple-prompt` toggles the simple prompt mode.
* `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
back to the calling process or back one level of nesting (if there
are nested sessions).
* `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`
(use `cd ..` to go back).
* `show-method [OPTIONS] METH` Displays the sourcecode for the method
`METH`. e.g `show-method hello`. See `show-method --help` for more info.
* `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
--help` for more info.
* `show-command COMMAND` Displays the sourcecode for the given Pry
command. e.g: `show-command cd`
* `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
calling process.
2010-12-08 07:06:49 -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.
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).
Example Programs
----------------
Pry comes bundled with a few example programs to illustrate some
features, see the `examples/` directory.
* `example_basic.rb` - Demonstrate basic Pry functionality
* `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-20 22:43:52 -04:00
### Customizing Pry
2011-01-09 06:51:45 -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)
2010-12-08 02:30:38 -05:00
Contact
-------
Problems or questions contact me at [github](http://github.com/banister)