pry 0.8.0pre9-i386-mingw32 → 0.8.1-i386-mingw32
Sign up to get free protection for your applications and to get access to all the features.
- data/README.markdown +385 -201
- data/Rakefile +2 -1
- data/bin/pry +24 -39
- data/lib/pry.rb +7 -1
- data/lib/pry/command_base.rb +14 -15
- data/lib/pry/command_base_helpers.rb +149 -18
- data/lib/pry/command_helpers.rb +37 -13
- data/lib/pry/command_processor.rb +20 -10
- data/lib/pry/commands.rb +285 -199
- data/lib/pry/completion.rb +1 -1
- data/lib/pry/hooks.rb +2 -6
- data/lib/pry/print.rb +10 -13
- data/lib/pry/prompts.rb +3 -3
- data/lib/pry/pry_class.rb +23 -18
- data/lib/pry/pry_instance.rb +44 -29
- data/lib/pry/version.rb +1 -1
- data/test/test.rb +114 -47
- metadata +113 -103
- data/lib/pry/TAGS +0 -62
data/README.markdown
CHANGED
@@ -1,34 +1,25 @@
|
|
1
|
-
|
2
|
-
=============
|
1
|
+
![Alt text](http://dl.dropbox.com/u/26521875/pry_logo_shade.png)
|
3
2
|
|
4
3
|
(C) John Mair (banisterfiend) 2011
|
5
4
|
|
6
|
-
|
5
|
+
_Get to the code_
|
7
6
|
|
8
7
|
Pry is a powerful alternative to the standard IRB shell for Ruby. It is
|
9
8
|
written from scratch to provide a number of advanced features, some of
|
10
9
|
these include:
|
11
10
|
|
12
|
-
* Runtime invocation
|
13
|
-
* Syntax highlighting
|
14
|
-
* Command shell integration
|
15
11
|
* Source code browsing (including core C source with the pry-doc gem)
|
16
|
-
* Documentation browsing
|
12
|
+
* Documentation browsing
|
13
|
+
* Live help system
|
14
|
+
* Syntax highlighting
|
15
|
+
* Command shell integration (start editors, run git, and rake from within Pry)
|
16
|
+
* Gist integration
|
17
|
+
* Navigation around state (`cd`, `ls` and friends)
|
18
|
+
* Runtime invocation (use Pry as a developer console or debugger)
|
17
19
|
* Exotic object support (BasicObject instances, IClasses, ...)
|
18
20
|
* A Powerful and flexible command system
|
19
|
-
*
|
20
|
-
* Many convenience commands
|
21
|
-
|
22
|
-
Pry is a Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
|
23
|
-
manipulation of objects during the running of a program.
|
24
|
-
|
25
|
-
In some sense it is the opposite of IRB in that you bring a REPL
|
26
|
-
session to your code (with Pry) instead of bringing your code to a
|
27
|
-
REPL session (as with IRB).
|
28
|
-
|
29
|
-
It is not based on the IRB codebase, and implements some unique REPL
|
30
|
-
commands such as `show-method`, `show-doc`, `ls` and `cd` (type `help`
|
31
|
-
to get a full list).
|
21
|
+
* Ability to view and replay history
|
22
|
+
* Many convenience commands inspired by IPython and other advanced REPLs
|
32
23
|
|
33
24
|
Pry is also fairly flexible and allows significant user
|
34
25
|
[customization](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md). It
|
@@ -54,83 +45,43 @@ Pry, then:
|
|
54
45
|
|
55
46
|
1. Install rubygems-test: `gem install rubygems-test`
|
56
47
|
2. Run the test: `gem test pry`
|
57
|
-
3. Finally choose 'Yes' to upload the results.
|
58
|
-
|
59
|
-
Example: Interacting with an object at runtime
|
60
|
-
---------------------------------------
|
61
|
-
|
62
|
-
With the `Object#pry` method we can pry (open an irb-like session) on
|
63
|
-
an object. In the example below we open a Pry session for the `Test` class and execute a method and add
|
64
|
-
an instance variable. The current thread is taken over by the Pry REPL loop for the duration of the session.
|
65
|
-
|
66
|
-
require 'pry'
|
67
|
-
|
68
|
-
class Test
|
69
|
-
def self.hello() "hello world" end
|
70
|
-
end
|
71
|
-
|
72
|
-
Test.pry
|
73
|
-
|
74
|
-
# Pry session begins on stdin
|
75
|
-
Beginning Pry session for Test
|
76
|
-
pry(Test)> self
|
77
|
-
=> Test
|
78
|
-
pry(Test)> hello
|
79
|
-
=> "hello world"
|
80
|
-
pry(Test)> @y = 20
|
81
|
-
=> 20
|
82
|
-
pry(Test)> exit
|
83
|
-
Ending Pry session for Test
|
84
|
-
|
85
|
-
# program resumes here
|
48
|
+
3. Finally choose 'Yes' to upload the results.
|
86
49
|
|
87
|
-
|
88
|
-
effect:
|
50
|
+
### Commands
|
89
51
|
|
90
|
-
|
52
|
+
Nearly every piece of functionality in a Pry session is implemented as
|
53
|
+
a command. Commands are not methods and must start at the beginning of a line, with no
|
54
|
+
whitespace in between. Commands support a flexible syntax and allow
|
55
|
+
'options' in the same way as shell commands, for example the following
|
56
|
+
Pry command will show a list of all private instance methods (in
|
57
|
+
scope) that begin with 'pa'
|
91
58
|
|
92
|
-
|
59
|
+
pry(YARD::Parser::SourceParser):5> ls -Mp --grep pa
|
60
|
+
[:parser_class, :parser_type=, :parser_type_for_filename]
|
93
61
|
|
94
|
-
|
95
|
-
`obj`. e.g
|
62
|
+
### Navigating around state
|
96
63
|
|
97
|
-
|
98
|
-
|
99
|
-
|
64
|
+
Pry allows us to pop in and out of different scopes (objects) using
|
65
|
+
the `cd` command. This enables us to explore the run-time view of a
|
66
|
+
program or library. To view which variables and methods are available
|
67
|
+
within a particular scope we use the versatile [ls command.](https://gist.github.com/c0fc686ef923c8b87715)
|
100
68
|
|
101
|
-
|
102
|
-
|
103
|
-
pry(6)
|
104
|
-
beginning Pry session for 6
|
105
|
-
pry(6)>
|
106
|
-
|
107
|
-
Example: Pry sessions can nest
|
108
|
-
-----------------------------------------------
|
109
|
-
|
110
|
-
Here we will begin Pry at top-level, then pry on a class and then on
|
69
|
+
Here we will begin Pry at top-level, then Pry on a class and then on
|
111
70
|
an instance variable inside that class:
|
112
71
|
|
113
|
-
# Pry.start() without parameters begins a Pry session on top-level (main)
|
114
|
-
Pry.start
|
115
|
-
Beginning Pry session for main
|
116
72
|
pry(main)> class Hello
|
117
73
|
pry(main)* @x = 20
|
118
74
|
pry(main)* end
|
119
75
|
=> 20
|
120
76
|
pry(main)> cd Hello
|
121
|
-
|
122
|
-
pry(Hello):1> instance_variables
|
77
|
+
pry(Hello):1> ls -i
|
123
78
|
=> [:@x]
|
124
79
|
pry(Hello):1> cd @x
|
125
|
-
Beginning Pry session for 20
|
126
80
|
pry(20:2)> self + 10
|
127
81
|
=> 30
|
128
82
|
pry(20:2)> cd ..
|
129
|
-
Ending Pry session for 20
|
130
83
|
pry(Hello):1> cd ..
|
131
|
-
Ending Pry session for Hello
|
132
84
|
pry(main)> cd ..
|
133
|
-
Ending Pry session for main
|
134
85
|
|
135
86
|
The number after the `:` in the pry prompt indicates the nesting
|
136
87
|
level. To display more information about nesting, use the `nesting`
|
@@ -153,41 +104,337 @@ the `jump-to` command:
|
|
153
104
|
=> 100
|
154
105
|
pry(Hello):1>
|
155
106
|
|
156
|
-
|
157
|
-
use the `quit` or `exit` or `back` commands.
|
107
|
+
### Runtime invocation
|
158
108
|
|
159
|
-
|
160
|
-
|
109
|
+
Pry can be invoked in the middle of a running program. It opens a Pry
|
110
|
+
session at the point it's called and makes all program state at that
|
111
|
+
point available. When the session ends the program continues with any
|
112
|
+
modifications you made to it.
|
161
113
|
|
162
|
-
|
163
|
-
|
164
|
-
|
165
|
-
|
166
|
-
|
167
|
-
|
114
|
+
This functionality can be used for such things as: debugging,
|
115
|
+
implementing developer consoles and applying hot patches.
|
116
|
+
|
117
|
+
code:
|
118
|
+
|
119
|
+
# test.rb
|
120
|
+
require 'pry'
|
121
|
+
|
122
|
+
class A
|
123
|
+
def hello() puts "hello world!" end
|
124
|
+
end
|
125
|
+
|
126
|
+
a = A.new
|
127
|
+
|
128
|
+
# start a REPL session
|
129
|
+
binding.pry
|
130
|
+
|
131
|
+
# program resumes here (after pry session)
|
132
|
+
puts "program resumes here."
|
133
|
+
|
134
|
+
Pry session:
|
135
|
+
|
136
|
+
pry(main)> a.hello
|
137
|
+
hello world!
|
138
|
+
=> nil
|
139
|
+
pry(main)> def a.goodbye
|
140
|
+
pry(main)* puts "goodbye cruel world!"
|
141
|
+
pry(main)* end
|
142
|
+
=> nil
|
143
|
+
pry(main)> a.goodbye
|
144
|
+
goodbye cruel world!
|
145
|
+
=> nil
|
146
|
+
pry(main)> exit
|
147
|
+
|
148
|
+
program resumes here.
|
149
|
+
|
150
|
+
### Command Shell Integration
|
151
|
+
|
152
|
+
A line of input that begins with a '.' will be forwarded to the
|
153
|
+
command shell. This enables us to navigate the file system, spawn
|
154
|
+
editors, and run git and rake directly from within Pry.
|
155
|
+
|
156
|
+
Further, we can use the `shell-mode` command to incorporate the
|
157
|
+
present working directory into the Pry prompt and bring in (limited at this stage, sorry) file name completion.
|
158
|
+
We can also interpolate Ruby code directly into the shell by
|
159
|
+
using the normal `#{}` string interpolation syntax.
|
160
|
+
|
161
|
+
In the code below we're going to switch to `shell-mode` and edit the
|
162
|
+
`.pryrc` file in the home directory. We'll then cat its contents and
|
163
|
+
reload the file.
|
164
|
+
|
165
|
+
pry(main)> shell-mode
|
166
|
+
pry main:/home/john/ruby/projects/pry $ .cd ~
|
167
|
+
pry main:/home/john $ .emacsclient .pryrc
|
168
|
+
pry main:/home/john $ .cat .pryrc
|
169
|
+
def hello_world
|
170
|
+
puts "hello world!"
|
171
|
+
end
|
172
|
+
pry main:/home/john $ load ".pryrc"
|
173
|
+
=> true
|
174
|
+
pry main:/home/john $ hello_world
|
175
|
+
hello world!
|
176
|
+
|
177
|
+
We can also interpolate Ruby code into the shell. In the
|
178
|
+
example below we use the shell command `cat` on a random file from the
|
179
|
+
current directory and count the number of lines in that file with
|
180
|
+
`wc`:
|
181
|
+
|
182
|
+
pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l
|
183
|
+
44
|
184
|
+
|
185
|
+
### Code Browsing
|
186
|
+
|
187
|
+
#### show-method
|
188
|
+
|
189
|
+
You can browse method source code with the `show-method` command. Nearly all Ruby methods (and some C methods, with the pry-doc
|
190
|
+
gem) can have their source viewed. Code that is longer than a page is
|
191
|
+
sent through a pager (such as less), and all code is properly syntax
|
192
|
+
highlighted (even C code).
|
193
|
+
|
194
|
+
The `show-method` command accepts two syntaxes, the typical ri
|
195
|
+
`Class#method` syntax and also simply the name of a method that's in
|
196
|
+
scope. You can optionally pass the `-l` option to show-method to
|
197
|
+
include line numbers in the output.
|
198
|
+
|
199
|
+
In the following example we will enter the `Pry` class, list the
|
200
|
+
instance methods beginning with 're' and display the source code for the `rep` method:
|
201
|
+
|
202
|
+
pry(main)> cd Pry
|
203
|
+
pry(Pry):1> ls -M --grep ^re
|
204
|
+
[:re, :readline, :rep, :repl, :repl_epilogue, :repl_prologue, :retrieve_line]
|
205
|
+
pry(Pry):1> show-method rep -l
|
206
|
+
|
207
|
+
From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb @ line 143:
|
208
|
+
Number of lines: 6
|
209
|
+
|
210
|
+
143: def rep(target=TOPLEVEL_BINDING)
|
211
|
+
144: target = Pry.binding_for(target)
|
212
|
+
145: result = re(target)
|
213
|
+
146:
|
214
|
+
147: show_result(result) if should_print?
|
215
|
+
148: end
|
216
|
+
|
217
|
+
Note that we can also view C methods (from Ruby Core) using the
|
218
|
+
`pry-doc` gem; we also show off the alternate syntax for
|
219
|
+
`show-method`:
|
220
|
+
|
221
|
+
pry(main)> show-method Array#select
|
222
|
+
|
223
|
+
From: array.c in Ruby Core (C Method):
|
224
|
+
Number of lines: 15
|
225
|
+
|
226
|
+
static VALUE
|
227
|
+
rb_ary_select(VALUE ary)
|
228
|
+
{
|
229
|
+
VALUE result;
|
230
|
+
long i;
|
231
|
+
|
232
|
+
RETURN_ENUMERATOR(ary, 0, 0);
|
233
|
+
result = rb_ary_new2(RARRAY_LEN(ary));
|
234
|
+
for (i = 0; i < RARRAY_LEN(ary); i++) {
|
235
|
+
if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
|
236
|
+
rb_ary_push(result, rb_ary_elt(ary, i));
|
237
|
+
}
|
238
|
+
}
|
239
|
+
return result;
|
240
|
+
}
|
241
|
+
|
242
|
+
#### Special locals
|
243
|
+
|
244
|
+
Some commands such as `show-method`, `show-doc`, `show-command`, `stat`
|
245
|
+
and `cat` update the `_file_` and `_dir_` local variables after they
|
246
|
+
run. These locals contain the full path to the file involved in the
|
247
|
+
last command as well as the directory containing that file.
|
248
|
+
|
249
|
+
You can then use these special locals in conjunction with shell
|
250
|
+
commands to do such things as change directory into the directory
|
251
|
+
containing the file, open the file in an editor, display the file using `cat`, and so on.
|
252
|
+
|
253
|
+
In the following example we wil use Pry to fix a bug in a method:
|
254
|
+
|
255
|
+
pry(main)> greet "john"
|
256
|
+
hello johnhow are you?=> nil
|
257
|
+
pry(main)> show-method greet
|
258
|
+
|
259
|
+
From: /Users/john/ruby/play/bug.rb @ line 2:
|
260
|
+
Number of lines: 4
|
261
|
+
|
262
|
+
def greet(name)
|
263
|
+
print "hello #{name}"
|
264
|
+
print "how are you?"
|
265
|
+
end
|
266
|
+
pry(main)> .emacsclient #{_file_}
|
267
|
+
pry(main)> load _file_
|
268
|
+
pry(main)> greet "john"
|
269
|
+
hello john
|
270
|
+
how are you?
|
271
|
+
=> nil
|
272
|
+
pry(main)> show-method greet
|
273
|
+
|
274
|
+
From: /Users/john/ruby/play/bug.rb @ line 2:
|
275
|
+
Number of lines: 4
|
276
|
+
|
277
|
+
def greet(name)
|
278
|
+
puts "hello #{name}"
|
279
|
+
puts "how are you?"
|
280
|
+
end
|
281
|
+
|
282
|
+
|
283
|
+
### Documentation Browsing
|
284
|
+
|
285
|
+
One use-case for Pry is to explore a program at run-time by `cd`-ing
|
286
|
+
in and out of objects and viewing and invoking methods. In the course
|
287
|
+
of exploring it may be useful to read the documentation for a
|
288
|
+
specific method that you come across. Like `show-method` the `show-doc` command supports
|
289
|
+
two syntaxes - the normal `ri` syntax as well as accepting the name of
|
290
|
+
any method that is currently in scope.
|
291
|
+
|
292
|
+
The Pry documentation system does not rely on pre-generated `rdoc` or
|
293
|
+
`ri`, instead it grabs the comments directly above the method on
|
294
|
+
demand. This results in speedier documentation retrieval and allows
|
295
|
+
the Pry system to retrieve documentation for methods that would not be
|
296
|
+
picked up by `rdoc`. Pry also has a basic understanding of both the
|
297
|
+
rdoc and yard formats and will attempt to syntax highlight the
|
298
|
+
documentation appropriately.
|
299
|
+
|
300
|
+
Nonetheless The `ri` functionality is very good and
|
301
|
+
has an advantage over Pry's system in that it allows documentation
|
302
|
+
lookup for classes as well as methods. Pry therefore has good
|
303
|
+
integration with `ri` through the `ri` command. The syntax
|
304
|
+
for the command is exactly as it would be in command-line -
|
305
|
+
so it is not necessary to quote strings.
|
306
|
+
|
307
|
+
In our example we will enter the `Gem` class and view the
|
308
|
+
documentation for the `try_activate` method:
|
309
|
+
|
310
|
+
pry(main)> cd Gem
|
311
|
+
pry(Gem):1> show-doc try_activate
|
312
|
+
|
313
|
+
From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/site_ruby/1.9.1/rubygems.rb @ line 201:
|
314
|
+
Number of lines: 3
|
315
|
+
|
316
|
+
Try to activate a gem containing path. Returns true if
|
317
|
+
activation succeeded or wasn't needed because it was already
|
318
|
+
activated. Returns false if it can't find the path in a gem.
|
319
|
+
pry(Gem):1>
|
320
|
+
|
321
|
+
We can also use `ri` in the normal way:
|
322
|
+
|
323
|
+
pry(main) ri Array#each
|
324
|
+
----------------------------------------------------------- Array#each
|
325
|
+
array.each {|item| block } -> array
|
326
|
+
------------------------------------------------------------------------
|
327
|
+
Calls _block_ once for each element in _self_, passing that element
|
328
|
+
as a parameter.
|
329
|
+
|
330
|
+
a = [ "a", "b", "c" ]
|
331
|
+
a.each {|x| print x, " -- " }
|
332
|
+
|
333
|
+
produces:
|
334
|
+
|
335
|
+
a -- b -- c --
|
336
|
+
|
337
|
+
|
338
|
+
### History
|
339
|
+
|
340
|
+
Readline history can be viewed and replayed using the `hist`
|
341
|
+
command. When `hist` is invoked with no arguments it simply displays
|
342
|
+
the history (passing the output through a pager if necessary))
|
343
|
+
when the `--replay` option is used a line or a range of lines of
|
344
|
+
history can be replayed.
|
345
|
+
|
346
|
+
In the example below we will enter a few lines in a Pry session and
|
347
|
+
then view history; we will then replay one of those lines:
|
348
|
+
|
349
|
+
pry(main)> hist
|
350
|
+
0: hist -h
|
351
|
+
1: ls
|
352
|
+
2: ls
|
353
|
+
3: show-method puts
|
354
|
+
4: x = rand
|
355
|
+
5: hist
|
356
|
+
pry(main)> hist --replay 3
|
357
|
+
|
358
|
+
From: io.c in Ruby Core (C Method):
|
359
|
+
Number of lines: 8
|
360
|
+
|
361
|
+
static VALUE
|
362
|
+
rb_f_puts(int argc, VALUE *argv, VALUE recv)
|
363
|
+
{
|
364
|
+
if (recv == rb_stdout) {
|
365
|
+
return rb_io_puts(argc, argv, recv);
|
366
|
+
}
|
367
|
+
return rb_funcall2(rb_stdout, rb_intern("puts"), argc, argv);
|
368
|
+
}
|
369
|
+
|
370
|
+
In the next example we will replay a range of lines in history. Note
|
371
|
+
that we replay to a point where a class definition is still open and so
|
372
|
+
we can continue to add instance methods to the class:
|
373
|
+
|
374
|
+
pry(main)> hist
|
375
|
+
0: class Hello
|
376
|
+
1: def hello_world
|
377
|
+
2: puts "hello world!"
|
378
|
+
3: end
|
379
|
+
4: end
|
380
|
+
5: hist
|
381
|
+
pry(main)> hist --replay 0..3
|
382
|
+
pry(main)* def goodbye_world
|
383
|
+
pry(main)* puts "goodbye world!"
|
384
|
+
pry(main)* end
|
385
|
+
pry(main)* end
|
386
|
+
=> nil
|
387
|
+
pry(main)> Hello.new.goodbye_world;
|
388
|
+
goodbye world!
|
389
|
+
pry(main)>
|
390
|
+
|
391
|
+
Also note that in the above the line `Hello.new.goodbye_world;` ends
|
392
|
+
with a semi-colon which causes expression evaluation output to be suppressed.
|
168
393
|
|
169
|
-
|
394
|
+
### Gist integration
|
170
395
|
|
171
|
-
|
172
|
-
|
396
|
+
If the `gist` gem is installed then method source or documentation can be gisted to github with the
|
397
|
+
`gist-method` command. The `gist-method` command accepts the same two
|
398
|
+
syntaxes as `show-method`. In the example below we will gist the C source
|
399
|
+
code for the `Symbol#to_proc` method to github:
|
400
|
+
|
401
|
+
pry(main)> gist-method Symbol#to_proc
|
402
|
+
https://gist.github.com/5332c38afc46d902ce46
|
403
|
+
pry(main)>
|
404
|
+
|
405
|
+
You can see the actual gist generated here: https://gist.github.com/5332c38afc46d902ce46
|
173
406
|
|
174
|
-
Pry is an irb-like clone with an emphasis on interactively examining
|
175
|
-
and manipulating objects during the running of a program.
|
176
407
|
|
177
|
-
|
178
|
-
uses (such as implementing a quake-like console for games, for example). Here is a
|
179
|
-
list of Pry's features along with some of its limitations given at the
|
180
|
-
end.
|
408
|
+
### Live Help System
|
181
409
|
|
182
|
-
|
410
|
+
Many other commands are available in Pry; to see the full list type
|
411
|
+
`help` at the prompt. A short description of each command is provided
|
412
|
+
with basic instructions for use; some commands have a more extensive
|
413
|
+
help that can be accessed via typing `command_name --help`. A command
|
414
|
+
will typically say in its description if the `--help` option is
|
415
|
+
avaiable.
|
183
416
|
|
184
|
-
|
417
|
+
|
418
|
+
### Other Features and limitations
|
419
|
+
|
420
|
+
#### Other Features:
|
421
|
+
|
422
|
+
* Pry can be invoked both at the command-line and used as a more
|
423
|
+
powerful alternative to IRB or it can be invoked at runtime and used
|
424
|
+
as a developer consoler / debugger.
|
185
425
|
* Additional documentation and source code for Ruby Core methods are supported when the `pry-doc` gem is installed.
|
186
426
|
* Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
|
187
427
|
* Pry comes with syntax highlighting on by default just use the `toggle-color` command to turn it on and off.
|
188
428
|
* Use `_` to recover last result.
|
189
429
|
* Use `_pry_` to reference the Pry instance managing the current session.
|
190
430
|
* Use `_ex_` to recover the last exception.
|
431
|
+
* Use `_file_` and `_dir_` to refer to the associated file or
|
432
|
+
directory containing the definition for a method.
|
433
|
+
* A trailing `;` on an entered expression suppresses the display of
|
434
|
+
the evaluation output.
|
435
|
+
* Typing `!` on a line by itself will clear the input buffer - useful for
|
436
|
+
getting you out of a situation where the parsing process
|
437
|
+
goes wrong and you get stuck in an endless read loop.
|
191
438
|
* Pry supports tab completion.
|
192
439
|
* Pry has multi-line support built in.
|
193
440
|
* Use `^d` (control-d) to quickly break out of a session.
|
@@ -205,113 +452,26 @@ for reading; `Pry#re` for eval; `Pry#rep` for printing; and `Pry#repl`
|
|
205
452
|
for the loop (`Pry.start` simply wraps `Pry.new.repl`). You can
|
206
453
|
invoke any of these methods directly depending on exactly what aspect of the functionality you need.
|
207
454
|
|
208
|
-
|
455
|
+
#### Limitations:
|
209
456
|
|
210
457
|
* Some Pry commands (e.g `show-command`) do not work in Ruby 1.8.
|
211
|
-
*
|
212
|
-
|
213
|
-
|
214
|
-
|
215
|
-
|
216
|
-
|
217
|
-
|
218
|
-
|
219
|
-
|
220
|
-
|
221
|
-
top-level (main). It can receive any object or a `Binding`
|
222
|
-
object as parameter. `Pry.start()` is implemented as `Pry.new.repl()`
|
223
|
-
* `obj.pry` and `pry(obj)` may also be used as alternative syntax to
|
224
|
-
`Pry.start(obj)`.
|
225
|
-
|
226
|
-
However there are some differences. `obj.pry` opens
|
227
|
-
a Pry session on the receiver whereas `Pry.start` (with no parameter)
|
228
|
-
will start a Pry session on top-level. The other form of the `pry`
|
229
|
-
method: `pry(obj)` will also start a Pry session on its parameter.
|
230
|
-
|
231
|
-
The `pry` method invoked by itself, with no explict receiver and no
|
232
|
-
parameter will start a Pry session on the implied receiver. It is
|
233
|
-
perhaps more useful to invoke it in this form `pry(binding)` or
|
234
|
-
`binding.pry` so as to get access to locals in the current context.
|
235
|
-
|
236
|
-
Another difference is that `Pry.start()` accepts a second parameter
|
237
|
-
that is a hash of configuration options (discussed further, below).
|
238
|
-
|
239
|
-
* If, for some reason you do not want to 'loop' then use `Pry.new.rep()`; it
|
240
|
-
only performs the Read-Eval-Print section of the REPL - it ends the
|
241
|
-
session after just one line of input. It takes the same parameters as
|
242
|
-
`Pry#repl()`
|
243
|
-
* Likewise `Pry#re()` only performs the Read-Eval section of the REPL,
|
244
|
-
it returns the result of the evaluation or an Exception object in
|
245
|
-
case of error. It also takes the same parameters as `Pry#repl()`
|
246
|
-
* Similarly `Pry#r()` only performs the Read section of the REPL, only
|
247
|
-
returning the Ruby expression (as a string). It takes the same parameters as all the others.
|
248
|
-
* `Pry.run_command COMMAND` enables you to invoke Pry commands outside
|
249
|
-
of a session, e.g `Pry.run_command "ls -m", :context => MyObject`. See
|
250
|
-
docs for more info.
|
251
|
-
|
252
|
-
### Session commands
|
253
|
-
|
254
|
-
Pry supports a few commands inside the session itself. These commands are
|
255
|
-
not methods and must start at the beginning of a line, with no
|
256
|
-
whitespace in between.
|
257
|
-
|
258
|
-
If you want to access a method of the same name, prefix the invocation by whitespace.
|
259
|
-
|
260
|
-
* Typing `!` on a line by itself will clear the input buffer - useful for
|
261
|
-
getting you out of a situation where the parsing process
|
262
|
-
goes wrong and you get stuck in an endless read loop.
|
263
|
-
* `status` shows status information about the current session.
|
264
|
-
* `whereami AROUND` shows the code context of the session. Shows
|
265
|
-
AROUND lines either side of the current line.
|
266
|
-
* `version` Show Pry version information
|
267
|
-
* `help` shows the list of session commands with brief explanations.
|
268
|
-
* `toggle-color` turns on and off syntax highlighting.
|
269
|
-
* `simple-prompt` toggles the simple prompt mode.
|
270
|
-
* `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
|
271
|
-
back to the calling process or back one level of nesting (if there
|
272
|
-
are nested sessions).
|
273
|
-
* `ls [OPTIONS] [VAR]` returns a list of local variables, instance variables, and
|
274
|
-
methods, etc. Highly flexible. See `ls --help` for more info.
|
275
|
-
* `cat VAR` Calls `inspect` on `VAR`
|
276
|
-
* `cd VAR` Starts a `Pry` session on the variable VAR. E.g `cd @x`
|
277
|
-
(use `cd ..` to go back).
|
278
|
-
* `show-method [OPTIONS] METH` Displays the sourcecode for the method
|
279
|
-
`METH`. e.g `show-method hello`. See `show-method --help` for more info.
|
280
|
-
* `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
|
281
|
-
--help` for more info.
|
282
|
-
* `show-command COMMAND` Displays the sourcecode for the given Pry
|
283
|
-
command. e.g: `show-command cd`
|
284
|
-
* `jump-to NEST_LEVEL` Unwinds the Pry stack (nesting level) until the appropriate nesting level is reached.
|
285
|
-
* `exit-all` breaks out of all Pry nesting levels and returns to the
|
286
|
-
calling process.
|
287
|
-
|
288
|
-
Syntax Highlighting
|
289
|
-
--------------------
|
458
|
+
* JRuby not officially supported due to currently too many quirks and
|
459
|
+
strange behaviour. Nonetheless most functionality should still work
|
460
|
+
OK in JRuby. Full JRuby support coming in a future version.
|
461
|
+
* `method_source` functionality does not work in JRuby with Ruby 1.8
|
462
|
+
* Color support does not work in JRuby with Ruby 1.9 (due to a
|
463
|
+
limitation in JRuby's regex).
|
464
|
+
* Tab completion is currently a bit broken/limited this will have a
|
465
|
+
major overhaul in a future version.
|
466
|
+
|
467
|
+
### Syntax Highlighting
|
290
468
|
|
291
469
|
Syntax highlighting is on by default in Pry. You can toggle it on and
|
292
470
|
off in a session by using the `toggle-color` command. Alternatively,
|
293
471
|
you can turn it off permanently by putting the line `Pry.color =
|
294
472
|
false` in your `~/.pryrc` file.
|
295
473
|
|
296
|
-
|
297
|
-
--------------------
|
298
|
-
|
299
|
-
Pry ultimately operates on `Binding` objects. If you invoke Pry with a
|
300
|
-
Binding object it uses that Binding. If you invoke Pry with anything
|
301
|
-
other than a `Binding`, Pry will generate a Binding for that
|
302
|
-
object and use that.
|
303
|
-
|
304
|
-
If you want to open a Pry session on the current context and capture
|
305
|
-
the locals you should use: `binding.pry`. If you do not care about
|
306
|
-
capturing the locals you can simply use `pry` (which will generate a
|
307
|
-
fresh `Binding` for the receiver).
|
308
|
-
|
309
|
-
Top-level is a special case; you can start a Pry session on top-level
|
310
|
-
*and* capture locals by simply using: `pry`. This is because Pry
|
311
|
-
automatically uses `TOPLEVEL_BINDING` for the top-level object (main).
|
312
|
-
|
313
|
-
Example Programs
|
314
|
-
----------------
|
474
|
+
### Example Programs
|
315
475
|
|
316
476
|
Pry comes bundled with a few example programs to illustrate some
|
317
477
|
features, see the `examples/` directory.
|
@@ -327,14 +487,38 @@ features, see the `examples/` directory.
|
|
327
487
|
* `example_commands_override.rb` - An advanced `commands` example.
|
328
488
|
* `example_image_edit.rb` - A simple image editor using a Pry REPL (requires `Gosu` and `TexPlay` gems).
|
329
489
|
|
330
|
-
Customizing Pry
|
331
|
-
---------------
|
490
|
+
### Customizing Pry
|
332
491
|
|
333
492
|
Pry allows a large degree of customization.
|
334
493
|
|
335
494
|
[Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
|
336
495
|
|
337
|
-
|
338
|
-
|
496
|
+
### Future Directions
|
497
|
+
|
498
|
+
Many new features are planned such as:
|
499
|
+
|
500
|
+
* Much improved tab completion (using [Bond](http://github.com/cldwalker/bond))
|
501
|
+
* Improved JRuby support
|
502
|
+
* Support for viewing source-code of binary gems and C stdlib
|
503
|
+
* git integration
|
504
|
+
* Much improved documentation system, better support for YARD
|
505
|
+
* A proper plugin system
|
506
|
+
* Get rid of `.` prefix for shell commands in `shell-mode`
|
507
|
+
* Better support for code and method reloading
|
508
|
+
* Extended and more sophisticated command system, allowing piping
|
509
|
+
between commands and running commands in background
|
510
|
+
|
511
|
+
### Contact
|
339
512
|
|
340
513
|
Problems or questions contact me at [github](http://github.com/banister)
|
514
|
+
|
515
|
+
### Contributors
|
516
|
+
|
517
|
+
The Pry team consists of:
|
518
|
+
|
519
|
+
* [banisterfiend](http://github.com/banister)
|
520
|
+
* [epitron](http://github.com/epitron)
|
521
|
+
* [injekt](http://github.com/injekt)
|
522
|
+
* [Mon_Ouie](http://github.com/mon-ouie)
|
523
|
+
|
524
|
+
|