pry 0.6.7pre4-i386-mingw32 → 0.6.8-i386-mingw32

Sign up to get free protection for your applications and to get access to all the features.
data/CHANGELOG CHANGED
@@ -1,75 +1,88 @@
1
- 28/2/2011 version 0.6.3
2
- * Using MethodSource 0.3.4 so 1.8 show-method support provided
3
- * `Set` class added to list of classes that are inspected
4
-
5
- 26/2/2011 version 0.6.1
6
- * !@ command alias for exit_all
7
- * `cd /` for breaking out to pry top level (jump-to 0)
8
- * made `-e` option work in a more effective way for `pry` command line invocation
9
- * exit and exit-all commands now accept a parameter, this parameter becomes the return value of repl()
10
- * `command` method from CommandBase now accepts a :keep_retval arg that determines if command value is returned to pry session or just `nil` (`nil` was old behaviour)
11
- * tests for new :keep_retval and exit-all/exit behaviour; :keep_retval will remain undocumented.
12
-
13
- 22/2/2011 version 0.5.8
14
- * Added -c (context) option to show-doc, show-methods and eval-file
15
- * Fixed up ordering issue of -c and -r parameters to command line pry
16
-
17
- 21/2/2011 version 0.5.7
18
- * Added pry executable, auto-loads .pryrc in user's home directory, if it
19
- exists.
20
-
21
- 19/2/2011 version 0.5.5
22
- * Added Pry.run_command
23
- * More useful error messages
24
- * Easter eggs (game and cohen-poem)
25
-
26
- 17/2/2011 version 0.5.0
27
- * Use clipped version of Pry.view() for large objects
28
- * Exit Pry session on ^d
29
- * Use Shellwords for breaking up parameters to pry commands
30
- * Use OptionParser to parse options for default pry commands
31
- * Add version command
32
- * Refactor 'status' command: add current method info
33
- * Add meth_name_from_binding utility lambda to commands.rb
34
- * Add -M, -m, -v(erbose), -a(ll), -s(uper), -l(ocals), -i(ivars), -k(klass
35
- vars), etc options to ls
36
- * add -M(instance method) options to show-method and show-doc
37
- * add --help option to most commands
38
- * Get rid of ls_method and ls_imethods (subsumed by more powerful ls)
39
- * Get rid of show_idoc and show_imethod
40
- * Add special eval-file command that evals target file in current context
41
-
42
- 27/1/2011 version 0.4.5
43
- * fixed show_method (though fragile as it references __binding_impl__
44
- directly, making a name change to that method difficult
45
- 27/1/2011 version 0.4.4
46
- * oops, added examples/ directory
47
- 26/1/2011 version 0.4.3
48
- * added alias_command and desc methods to Pry::CommandBase
49
- * changed behaviour of ls_methods and ls_imethods to return sorted lists
50
- of methods
51
- 23/1/2011 version 0.4.1
52
- * made it so a 'def meth;end' in an object Pry session defines singleton
53
- methods, not methods on the class (except in the case of
54
- immediates)
55
- * reorganized documentation, moving customization to a separate wiki file
56
- * storing wiki in a nested git repo, as github wiki pages have their own
57
- repo
58
- * added more tests for new method definition behaviour
59
- 21/1/2011 version 0.4.0
60
- * added command API
61
- * added many new commands, i.e ls_methods and friends
62
- * modified other commands
63
- * now accepts greater customization, can modify: input, output, hooks,
64
- prompt, print object
65
- * added tab completion (even completes commands)
66
- * added extensive tests
67
- * added examples
68
- * many more changes
69
- 9/12/2010 version 0.1.3
70
- * Got rid of rubygems dependency, refactored some code.
71
- 8/12/2010 version 0.1.2
72
- * now rescuing SyntaxError as well as Racc::Parser error in valid_expression?
73
- 8/12/2010 version 0.1.0
74
- * release!
75
-
1
+ 6/3/2011 version 0.6.8
2
+ * add whereami command, a la the `ir_b` gem
3
+ * make whereami run at the start of every session
4
+ * make .pryrc be loaded by run-time pry sessions
5
+
6
+ 4/3/2011 version 0.6.7
7
+ * color support
8
+ * --simple-prompt for pry commandline
9
+ * -I mode for pry commandline
10
+ * --color mode for pry commandline
11
+ * clean up requires (put them all in one place)
12
+ * simple-prompt command and toggle-color commandd.
13
+
14
+ 28/2/2011 version 0.6.3
15
+ * Using MethodSource 0.3.4 so 1.8 show-method support provided
16
+ * `Set` class added to list of classes that are inspected
17
+
18
+ 26/2/2011 version 0.6.1
19
+ * !@ command alias for exit_all
20
+ * `cd /` for breaking out to pry top level (jump-to 0)
21
+ * made `-e` option work in a more effective way for `pry` command line invocation
22
+ * exit and exit-all commands now accept a parameter, this parameter becomes the return value of repl()
23
+ * `command` method from CommandBase now accepts a :keep_retval arg that determines if command value is returned to pry session or just `nil` (`nil` was old behaviour)
24
+ * tests for new :keep_retval and exit-all/exit behaviour; :keep_retval will remain undocumented.
25
+
26
+ 22/2/2011 version 0.5.8
27
+ * Added -c (context) option to show-doc, show-methods and eval-file
28
+ * Fixed up ordering issue of -c and -r parameters to command line pry
29
+
30
+ 21/2/2011 version 0.5.7
31
+ * Added pry executable, auto-loads .pryrc in user's home directory, if it
32
+ exists.
33
+
34
+ 19/2/2011 version 0.5.5
35
+ * Added Pry.run_command
36
+ * More useful error messages
37
+ * Easter eggs (game and cohen-poem)
38
+
39
+ 17/2/2011 version 0.5.0
40
+ * Use clipped version of Pry.view() for large objects
41
+ * Exit Pry session on ^d
42
+ * Use Shellwords for breaking up parameters to pry commands
43
+ * Use OptionParser to parse options for default pry commands
44
+ * Add version command
45
+ * Refactor 'status' command: add current method info
46
+ * Add meth_name_from_binding utility lambda to commands.rb
47
+ * Add -M, -m, -v(erbose), -a(ll), -s(uper), -l(ocals), -i(ivars), -k(klass
48
+ vars), etc options to ls
49
+ * add -M(instance method) options to show-method and show-doc
50
+ * add --help option to most commands
51
+ * Get rid of ls_method and ls_imethods (subsumed by more powerful ls)
52
+ * Get rid of show_idoc and show_imethod
53
+ * Add special eval-file command that evals target file in current context
54
+
55
+ 27/1/2011 version 0.4.5
56
+ * fixed show_method (though fragile as it references __binding_impl__
57
+ directly, making a name change to that method difficult
58
+ 27/1/2011 version 0.4.4
59
+ * oops, added examples/ directory
60
+ 26/1/2011 version 0.4.3
61
+ * added alias_command and desc methods to Pry::CommandBase
62
+ * changed behaviour of ls_methods and ls_imethods to return sorted lists
63
+ of methods
64
+ 23/1/2011 version 0.4.1
65
+ * made it so a 'def meth;end' in an object Pry session defines singleton
66
+ methods, not methods on the class (except in the case of
67
+ immediates)
68
+ * reorganized documentation, moving customization to a separate wiki file
69
+ * storing wiki in a nested git repo, as github wiki pages have their own
70
+ repo
71
+ * added more tests for new method definition behaviour
72
+ 21/1/2011 version 0.4.0
73
+ * added command API
74
+ * added many new commands, i.e ls_methods and friends
75
+ * modified other commands
76
+ * now accepts greater customization, can modify: input, output, hooks,
77
+ prompt, print object
78
+ * added tab completion (even completes commands)
79
+ * added extensive tests
80
+ * added examples
81
+ * many more changes
82
+ 9/12/2010 version 0.1.3
83
+ * Got rid of rubygems dependency, refactored some code.
84
+ 8/12/2010 version 0.1.2
85
+ * now rescuing SyntaxError as well as Racc::Parser error in valid_expression?
86
+ 8/12/2010 version 0.1.0
87
+ * release!
88
+
data/LICENSE CHANGED
@@ -1,25 +1,25 @@
1
- License
2
- -------
3
-
4
- (The MIT License)
5
-
6
- Copyright (c) 2011 John Mair (banisterfiend)
7
-
8
- Permission is hereby granted, free of charge, to any person obtaining
9
- a copy of this software and associated documentation files (the
10
- 'Software'), to deal in the Software without restriction, including
11
- without limitation the rights to use, copy, modify, merge, publish,
12
- distribute, sublicense, and/or sell copies of the Software, and to
13
- permit persons to whom the Software is furnished to do so, subject to
14
- the following conditions:
15
-
16
- The above copyright notice and this permission notice shall be
17
- included in all copies or substantial portions of the Software.
18
-
19
- THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
20
- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21
- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
22
- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
23
- CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
24
- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
25
- SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1
+ License
2
+ -------
3
+
4
+ (The MIT License)
5
+
6
+ Copyright (c) 2011 John Mair (banisterfiend)
7
+
8
+ Permission is hereby granted, free of charge, to any person obtaining
9
+ a copy of this software and associated documentation files (the
10
+ 'Software'), to deal in the Software without restriction, including
11
+ without limitation the rights to use, copy, modify, merge, publish,
12
+ distribute, sublicense, and/or sell copies of the Software, and to
13
+ permit persons to whom the Software is furnished to do so, subject to
14
+ the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be
17
+ included in all copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
20
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
22
+ IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
23
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
24
+ TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
25
+ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
data/README.markdown CHANGED
@@ -1,309 +1,321 @@
1
- Pry
2
- =============
3
-
4
- (C) John Mair (banisterfiend) 2011
5
-
6
- _attach an irb-like session to any object at runtime_
7
-
8
- Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
9
- manipulation of objects during the running of a program.
10
-
11
- In some sense it is the opposite of IRB in that you bring a REPL
12
- session to your code (with Pry) instead of bringing your code to a
13
- REPL session (as with IRB).
14
-
15
- It is not based on the IRB codebase, and implements some unique REPL
16
- commands such as `show-method`, `show-doc`, `ls` and `cd` (type `help`
17
- to get a full list).
18
-
19
- Pry is also fairly flexible and allows significant user
20
- [customization](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md). It
21
- is trivial to set it to read from any object that has a `readline` method and write to any object that has a
22
- `puts` method - many other aspects of Pry are also configurable making
23
- it a good choice for implementing custom shells.
24
-
25
- Pry now comes with an executable so it can be invoked at the command line.
26
- Just enter `pry` to start. A `.pryrc` file in the user's home directory will
27
- be loaded if it exists. Type `pry --help` at the command line for more information.
28
-
29
- * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
30
- * Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
31
- * See the [source code](http://github.com/banister/pry)
32
-
33
- Pry also has `rubygems-test` support; to participate, first install
34
- Pry, then:
35
-
36
- 1. Install rubygems-test: `gem install rubygems-test`
37
- 2. Run the test: `gem test pry`
38
- 3. Finally choose 'Yes' to upload the results.
39
-
40
- Example: Interacting with an object at runtime
41
- ---------------------------------------
42
-
43
- With the `Object#pry` method we can pry (open an irb-like session) on
44
- an object. In the example below we open a Pry session for the `Test` class and execute a method and add
45
- an instance variable. The current thread is halted for the duration of the session.
46
-
47
- require 'pry'
48
-
49
- class Test
50
- def self.hello() "hello world" end
51
- end
52
-
53
- Test.pry
54
-
55
- # Pry session begins on stdin
56
- Beginning Pry session for Test
57
- pry(Test)> self
58
- => Test
59
- pry(Test)> hello
60
- => "hello world"
61
- pry(Test)> @y = 20
62
- => 20
63
- pry(Test)> exit
64
- Ending Pry session for Test
65
-
66
- # program resumes here
67
-
68
- If we now inspect the `Test` object we can see our changes have had
69
- effect:
70
-
71
- Test.instance_variable_get(:@y) #=> 20
72
-
73
- ### Alternative Syntax
74
-
75
- You can also use the `Pry.start(obj)` or `pry(obj)` syntax to start a pry session on
76
- `obj`. e.g
77
-
78
- Pry.start(5)
79
- Beginning Pry session for 5
80
- pry(5)>
81
-
82
- OR
83
-
84
- pry(6)
85
- beginning Pry session for 6
86
- pry(6)>
87
-
88
- Example: Pry sessions can nest
89
- -----------------------------------------------
90
-
91
- Here we will begin Pry at top-level, then pry on a class and then on
92
- an instance variable inside that class:
93
-
94
- # Pry.start() without parameters begins a Pry session on top-level (main)
95
- Pry.start
96
- Beginning Pry session for main
97
- pry(main)> class Hello
98
- pry(main)* @x = 20
99
- pry(main)* end
100
- => 20
101
- pry(main)> cd Hello
102
- Beginning Pry session for Hello
103
- pry(Hello):1> instance_variables
104
- => [:@x]
105
- pry(Hello):1> cd @x
106
- Beginning Pry session for 20
107
- pry(20:2)> self + 10
108
- => 30
109
- pry(20:2)> cd ..
110
- Ending Pry session for 20
111
- pry(Hello):1> cd ..
112
- Ending Pry session for Hello
113
- pry(main)> cd ..
114
- Ending Pry session for main
115
-
116
- The number after the `:` in the pry prompt indicates the nesting
117
- level. To display more information about nesting, use the `nesting`
118
- command. E.g
119
-
120
- pry("friend":3)> nesting
121
- Nesting status:
122
- 0. main (Pry top level)
123
- 1. Hello
124
- 2. 100
125
- 3. "friend"
126
- => nil
127
-
128
- We can then jump back to any of the previous nesting levels by using
129
- the `jump-to` command:
130
-
131
- pry("friend":3)> jump-to 1
132
- Ending Pry session for "friend"
133
- Ending Pry session for 100
134
- => 100
135
- pry(Hello):1>
136
-
137
- If we just want to go back one level of nesting we can of course
138
- use the `quit` or `exit` or `back` commands.
139
-
140
- To break out of all levels of Pry nesting and return immediately to the
141
- calling process use `exit-all`:
142
-
143
- pry("friend":3)> exit-all
144
- Ending Pry session for "friend"
145
- Ending Pry session for 100
146
- Ending Pry session for Hello
147
- Ending Pry session for main
148
- => main
149
-
150
- # program resumes here
151
-
152
- Features and limitations
153
- ------------------------
154
-
155
- Pry is an irb-like clone with an emphasis on interactively examining
156
- and manipulating objects during the running of a program.
157
-
158
- Its primary utility is probably in debugging, though it may have other
159
- uses (such as implementing a quake-like console for games, for example). Here is a
160
- list of Pry's features along with some of its limitations given at the
161
- end.
162
-
163
- ###Features:
164
-
165
- * Pry can be invoked at any time and on any object in the running program.
166
- * Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
167
- * Use `_` to recover last result.
168
- * Use `_pry_` to reference the Pry instance managing the current session.
169
- * Pry supports tab completion.
170
- * Pry has multi-line support built in.
171
- * Use `^d` (control-d) to quickly break out of a session.
172
- * Pry has special commands not found in many other Ruby REPLs: `show-method`, `show-doc`
173
- `jump-to`, `ls`, `cd`, `cat`
174
- * Pry gives good control over nested sessions (important when exploring complicated runtime state)
175
- * Pry is not based on the IRB codebase.
176
- * Pry allows significant customizability.
177
- * Pry uses the [method_source](https://github.com/banister/method_source) gem; so
178
- this functionality is available to a Pry session.
179
- * Pry uses [RubyParser](https://github.com/seattlerb/ruby_parser) to
180
- validate expressions in 1.8, and [Ripper](http://rdoc.info/docs/ruby-core/1.9.2/Ripper) for 1.9.
181
- * Pry implements all the methods in the REPL chain separately: `Pry#r`
182
- for reading; `Pry#re` for eval; `Pry#rep` for printing; and `Pry#repl`
183
- for the loop (`Pry.start` simply wraps `Pry.new.repl`). You can
184
- invoke any of these methods directly depending on exactly what aspect of the functionality you need.
185
-
186
- ###Limitations:
187
-
188
- * Some Pry commands (e.g `show-command`) do not work in Ruby 1.8.
189
- * `method_source` functionality does not work in JRuby.
190
- * 1.9 support requires `Ripper` - some implementations may not support this.
191
-
192
- Commands
193
- -----------
194
-
195
- ### The Pry API:
196
-
197
- * `Pry.start()` Starts a Read-Eval-Print-Loop on the object it
198
- receives as a parameter. In the case of no parameter it operates on
199
- top-level (main). It can receive any object or a `Binding`
200
- object as parameter. `Pry.start()` is implemented as `Pry.new.repl()`
201
- * `obj.pry` and `pry(obj)` may also be used as alternative syntax to
202
- `Pry.start(obj)`.
203
-
204
- However there are some differences. `obj.pry` opens
205
- a Pry session on the receiver whereas `Pry.start` (with no parameter)
206
- will start a Pry session on top-level. The other form of the `pry`
207
- method: `pry(obj)` will also start a Pry session on its parameter.
208
-
209
- The `pry` method invoked by itself, with no explict receiver and no
210
- parameter will start a Pry session on the implied receiver. It is
211
- perhaps more useful to invoke it in this form `pry(binding)` or
212
- `binding.pry` so as to get access to locals in the current context.
213
-
214
- Another difference is that `Pry.start()` accepts a second parameter
215
- that is a hash of configuration options (discussed further, below).
216
-
217
- * If, for some reason you do not want to 'loop' then use `Pry.new.rep()`; it
218
- only performs the Read-Eval-Print section of the REPL - it ends the
219
- session after just one line of input. It takes the same parameters as
220
- `Pry#repl()`
221
- * Likewise `Pry#re()` only performs the Read-Eval section of the REPL,
222
- it returns the result of the evaluation or an Exception object in
223
- case of error. It also takes the same parameters as `Pry#repl()`
224
- * Similarly `Pry#r()` only performs the Read section of the REPL, only
225
- returning the Ruby expression (as a string). It takes the same parameters as all the others.
226
- * `Pry.run_command COMMAND` enables you to invoke Pry commands outside
227
- of a session, e.g `Pry.run_command "ls -m", :context => MyObject`. See
228
- docs for more info.
229
-
230
- ### Session commands
231
-
232
- Pry supports a few commands inside the session itself. These commands are
233
- not methods and must start at the beginning of a line, with no
234
- whitespace in between.
235
-
236
- If you want to access a method of the same name, prefix the invocation by whitespace.
237
-
238
- * Typing `!` on a line by itself will clear the input buffer - useful for
239
- getting you out of a situation where the parsing process
240
- goes wrong and you get stuck in an endless read loop.
241
- * `status` shows status information about the current session.
242
- * `version` Show Pry version information
243
- * `help` shows the list of session commands with brief explanations.
244
- * `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
245
- back to the calling process or back one level of nesting (if there
246
- are nested sessions).
247
- * `ls [OPTIONS] [VAR]` returns a list of local variables, instance variables, and
248
- methods, etc. Highly flexible. See `ls --help` for more info.
249
- * `cat VAR` Calls `inspect` on `VAR`
250
- * `cd VAR` Starts a `Pry` session on the variable VAR. E.g `cd @x`
251
- (use `cd ..` to go back).
252
- * `show-method [OPTIONS] METH` Displays the sourcecode for the method
253
- `METH`. e.g `show-method hello`. See `show-method --help` for more info.
254
- * `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
255
- --help` for more info.
256
- * `show-command COMMAND` Displays the sourcecode for the given Pry
257
- command. e.g: `show-command cd`
258
- * `jump-to NEST_LEVEL` Unwinds the Pry stack (nesting level) until the appropriate nesting level is reached.
259
- * `exit-all` breaks out of all Pry nesting levels and returns to the
260
- calling process.
261
- * You can type `Pry.start(obj)` or `obj.pry` to nest another Pry session within the
262
- current one with `obj` as the receiver of the new session. Very useful
263
- when exploring large or complicated runtime state.
264
-
265
- Bindings and objects
266
- --------------------
267
-
268
- Pry ultimately operates on `Binding` objects. If you invoke Pry with a
269
- Binding object it uses that Binding. If you invoke Pry with anything
270
- other than a `Binding`, Pry will generate a Binding for that
271
- object and use that.
272
-
273
- If you want to open a Pry session on the current context and capture
274
- the locals you should use: `binding.pry`. If you do not care about
275
- capturing the locals you can simply use `pry` (which will generate a
276
- fresh `Binding` for the receiver).
277
-
278
- Top-level is a special case; you can start a Pry session on top-level
279
- *and* capture locals by simply using: `pry`. This is because Pry
280
- automatically uses `TOPLEVEL_BINDING` for the top-level object (main).
281
-
282
- Example Programs
283
- ----------------
284
-
285
- Pry comes bundled with a few example programs to illustrate some
286
- features, see the `examples/` directory.
287
-
288
- * `example_basic.rb` - Demonstrate basic Pry functionality
289
- * `example_input.rb` - Demonstrates how to set the `input` object.
290
- * `example_output.rb` - Demonstrates how to set the `output` object.
291
- * `example_hooks.rb` - Demonstrates how to set the `hooks` hash.
292
- * `example_print.rb` - Demonstrates how to set the `print` object.
293
- * `example_prompt.rb` - Demonstrates how to set the `prompt`.
294
- * `example_input2.rb` - An advanced `input` example.
295
- * `example_commands.rb` - Implementing a mathematical command set.
296
- * `example_commands_override.rb` - An advanced `commands` example.
297
- * `example_image_edit.rb` - A simple image editor using a Pry REPL (requires `Gosu` and `TexPlay` gems).
298
-
299
- Customizing Pry
300
- ---------------
301
-
302
- Pry allows a large degree of customization.
303
-
304
- [Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
305
-
306
- Contact
307
- -------
308
-
309
- Problems or questions contact me at [github](http://github.com/banister)
1
+ Pry
2
+ =============
3
+
4
+ (C) John Mair (banisterfiend) 2011
5
+
6
+ _attach an irb-like session to any object at runtime_
7
+
8
+ Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
9
+ manipulation of objects during the running of a program.
10
+
11
+ In some sense it is the opposite of IRB in that you bring a REPL
12
+ session to your code (with Pry) instead of bringing your code to a
13
+ REPL session (as with IRB).
14
+
15
+ It is not based on the IRB codebase, and implements some unique REPL
16
+ commands such as `show-method`, `show-doc`, `ls` and `cd` (type `help`
17
+ to get a full list).
18
+
19
+ Pry is also fairly flexible and allows significant user
20
+ [customization](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md). It
21
+ is trivial to set it to read from any object that has a `readline` method and write to any object that has a
22
+ `puts` method - many other aspects of Pry are also configurable making
23
+ it a good choice for implementing custom shells.
24
+
25
+ Pry now comes with an executable so it can be invoked at the command line.
26
+ Just enter `pry` to start. A `.pryrc` file in the user's home directory will
27
+ be loaded if it exists. Type `pry --help` at the command line for more information.
28
+
29
+ * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
30
+ * Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
31
+ * See the [source code](http://github.com/banister/pry)
32
+
33
+ Pry also has `rubygems-test` support; to participate, first install
34
+ Pry, then:
35
+
36
+ 1. Install rubygems-test: `gem install rubygems-test`
37
+ 2. Run the test: `gem test pry`
38
+ 3. Finally choose 'Yes' to upload the results.
39
+
40
+ Example: Interacting with an object at runtime
41
+ ---------------------------------------
42
+
43
+ With the `Object#pry` method we can pry (open an irb-like session) on
44
+ an object. In the example below we open a Pry session for the `Test` class and execute a method and add
45
+ an instance variable. The current thread is taken over by the Pry REPL loop for the duration of the session.
46
+
47
+ require 'pry'
48
+
49
+ class Test
50
+ def self.hello() "hello world" end
51
+ end
52
+
53
+ Test.pry
54
+
55
+ # Pry session begins on stdin
56
+ Beginning Pry session for Test
57
+ pry(Test)> self
58
+ => Test
59
+ pry(Test)> hello
60
+ => "hello world"
61
+ pry(Test)> @y = 20
62
+ => 20
63
+ pry(Test)> exit
64
+ Ending Pry session for Test
65
+
66
+ # program resumes here
67
+
68
+ If we now inspect the `Test` object we can see our changes have had
69
+ effect:
70
+
71
+ Test.instance_variable_get(:@y) #=> 20
72
+
73
+ ### Alternative Syntax
74
+
75
+ You can also use the `Pry.start(obj)` or `pry(obj)` syntax to start a pry session on
76
+ `obj`. e.g
77
+
78
+ Pry.start(5)
79
+ Beginning Pry session for 5
80
+ pry(5)>
81
+
82
+ OR
83
+
84
+ pry(6)
85
+ beginning Pry session for 6
86
+ pry(6)>
87
+
88
+ Example: Pry sessions can nest
89
+ -----------------------------------------------
90
+
91
+ Here we will begin Pry at top-level, then pry on a class and then on
92
+ an instance variable inside that class:
93
+
94
+ # Pry.start() without parameters begins a Pry session on top-level (main)
95
+ Pry.start
96
+ Beginning Pry session for main
97
+ pry(main)> class Hello
98
+ pry(main)* @x = 20
99
+ pry(main)* end
100
+ => 20
101
+ pry(main)> cd Hello
102
+ Beginning Pry session for Hello
103
+ pry(Hello):1> instance_variables
104
+ => [:@x]
105
+ pry(Hello):1> cd @x
106
+ Beginning Pry session for 20
107
+ pry(20:2)> self + 10
108
+ => 30
109
+ pry(20:2)> cd ..
110
+ Ending Pry session for 20
111
+ pry(Hello):1> cd ..
112
+ Ending Pry session for Hello
113
+ pry(main)> cd ..
114
+ Ending Pry session for main
115
+
116
+ The number after the `:` in the pry prompt indicates the nesting
117
+ level. To display more information about nesting, use the `nesting`
118
+ command. E.g
119
+
120
+ pry("friend":3)> nesting
121
+ Nesting status:
122
+ 0. main (Pry top level)
123
+ 1. Hello
124
+ 2. 100
125
+ 3. "friend"
126
+ => nil
127
+
128
+ We can then jump back to any of the previous nesting levels by using
129
+ the `jump-to` command:
130
+
131
+ pry("friend":3)> jump-to 1
132
+ Ending Pry session for "friend"
133
+ Ending Pry session for 100
134
+ => 100
135
+ pry(Hello):1>
136
+
137
+ If we just want to go back one level of nesting we can of course
138
+ use the `quit` or `exit` or `back` commands.
139
+
140
+ To break out of all levels of Pry nesting and return immediately to the
141
+ calling process use `exit-all`:
142
+
143
+ pry("friend":3)> exit-all
144
+ Ending Pry session for "friend"
145
+ Ending Pry session for 100
146
+ Ending Pry session for Hello
147
+ Ending Pry session for main
148
+ => main
149
+
150
+ # program resumes here
151
+
152
+ Features and limitations
153
+ ------------------------
154
+
155
+ Pry is an irb-like clone with an emphasis on interactively examining
156
+ and manipulating objects during the running of a program.
157
+
158
+ Its primary utility is probably in debugging, though it may have other
159
+ uses (such as implementing a quake-like console for games, for example). Here is a
160
+ list of Pry's features along with some of its limitations given at the
161
+ end.
162
+
163
+ ###Features:
164
+
165
+ * Pry can be invoked at any time and on any object in the running program.
166
+ * Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
167
+ * Pry comes with syntax highlighting on by default just use the `toggle-color` command to use it.
168
+ * Use `_` to recover last result.
169
+ * Use `_pry_` to reference the Pry instance managing the current session.
170
+ * Pry supports tab completion.
171
+ * Pry has multi-line support built in.
172
+ * Use `^d` (control-d) to quickly break out of a session.
173
+ * Pry has special commands not found in many other Ruby REPLs: `show-method`, `show-doc`
174
+ `jump-to`, `ls`, `cd`, `cat`
175
+ * Pry gives good control over nested sessions (important when exploring complicated runtime state)
176
+ * Pry is not based on the IRB codebase.
177
+ * Pry allows significant customizability.
178
+ * Pry uses the [method_source](https://github.com/banister/method_source) gem; so
179
+ this functionality is available to a Pry session.
180
+ * Pry uses [RubyParser](https://github.com/seattlerb/ruby_parser) to
181
+ validate expressions in 1.8, and [Ripper](http://rdoc.info/docs/ruby-core/1.9.2/Ripper) for 1.9.
182
+ * Pry implements all the methods in the REPL chain separately: `Pry#r`
183
+ for reading; `Pry#re` for eval; `Pry#rep` for printing; and `Pry#repl`
184
+ for the loop (`Pry.start` simply wraps `Pry.new.repl`). You can
185
+ invoke any of these methods directly depending on exactly what aspect of the functionality you need.
186
+
187
+ ###Limitations:
188
+
189
+ * Some Pry commands (e.g `show-command`) do not work in Ruby 1.8.
190
+ * `method_source` functionality does not work in JRuby.
191
+ * 1.9 support requires `Ripper` - some implementations may not support this.
192
+
193
+ Commands
194
+ -----------
195
+
196
+ ### The Pry API:
197
+
198
+ * `Pry.start()` Starts a Read-Eval-Print-Loop on the object it
199
+ receives as a parameter. In the case of no parameter it operates on
200
+ top-level (main). It can receive any object or a `Binding`
201
+ object as parameter. `Pry.start()` is implemented as `Pry.new.repl()`
202
+ * `obj.pry` and `pry(obj)` may also be used as alternative syntax to
203
+ `Pry.start(obj)`.
204
+
205
+ However there are some differences. `obj.pry` opens
206
+ a Pry session on the receiver whereas `Pry.start` (with no parameter)
207
+ will start a Pry session on top-level. The other form of the `pry`
208
+ method: `pry(obj)` will also start a Pry session on its parameter.
209
+
210
+ The `pry` method invoked by itself, with no explict receiver and no
211
+ parameter will start a Pry session on the implied receiver. It is
212
+ perhaps more useful to invoke it in this form `pry(binding)` or
213
+ `binding.pry` so as to get access to locals in the current context.
214
+
215
+ Another difference is that `Pry.start()` accepts a second parameter
216
+ that is a hash of configuration options (discussed further, below).
217
+
218
+ * If, for some reason you do not want to 'loop' then use `Pry.new.rep()`; it
219
+ only performs the Read-Eval-Print section of the REPL - it ends the
220
+ session after just one line of input. It takes the same parameters as
221
+ `Pry#repl()`
222
+ * Likewise `Pry#re()` only performs the Read-Eval section of the REPL,
223
+ it returns the result of the evaluation or an Exception object in
224
+ case of error. It also takes the same parameters as `Pry#repl()`
225
+ * Similarly `Pry#r()` only performs the Read section of the REPL, only
226
+ returning the Ruby expression (as a string). It takes the same parameters as all the others.
227
+ * `Pry.run_command COMMAND` enables you to invoke Pry commands outside
228
+ of a session, e.g `Pry.run_command "ls -m", :context => MyObject`. See
229
+ docs for more info.
230
+
231
+ ### Session commands
232
+
233
+ Pry supports a few commands inside the session itself. These commands are
234
+ not methods and must start at the beginning of a line, with no
235
+ whitespace in between.
236
+
237
+ If you want to access a method of the same name, prefix the invocation by whitespace.
238
+
239
+ * Typing `!` on a line by itself will clear the input buffer - useful for
240
+ getting you out of a situation where the parsing process
241
+ goes wrong and you get stuck in an endless read loop.
242
+ * `status` shows status information about the current session.
243
+ * `whereami` shows the code context of the session.
244
+ * `version` Show Pry version information
245
+ * `help` shows the list of session commands with brief explanations.
246
+ * `toggle-color` turns on and off syntax highlighting.
247
+ * `simple-prompt` toggles the simple prompt mode.
248
+ * `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
249
+ back to the calling process or back one level of nesting (if there
250
+ are nested sessions).
251
+ * `ls [OPTIONS] [VAR]` returns a list of local variables, instance variables, and
252
+ methods, etc. Highly flexible. See `ls --help` for more info.
253
+ * `cat VAR` Calls `inspect` on `VAR`
254
+ * `cd VAR` Starts a `Pry` session on the variable VAR. E.g `cd @x`
255
+ (use `cd ..` to go back).
256
+ * `show-method [OPTIONS] METH` Displays the sourcecode for the method
257
+ `METH`. e.g `show-method hello`. See `show-method --help` for more info.
258
+ * `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
259
+ --help` for more info.
260
+ * `show-command COMMAND` Displays the sourcecode for the given Pry
261
+ command. e.g: `show-command cd`
262
+ * `jump-to NEST_LEVEL` Unwinds the Pry stack (nesting level) until the appropriate nesting level is reached.
263
+ * `exit-all` breaks out of all Pry nesting levels and returns to the
264
+ calling process.
265
+ * You can type `Pry.start(obj)` or `obj.pry` to nest another Pry session within the
266
+ current one with `obj` as the receiver of the new session. Very useful
267
+ when exploring large or complicated runtime state.
268
+
269
+ Syntax Highlighting
270
+ --------------------
271
+
272
+ Syntax highlighting is on by default in Pry. You can toggle it on and
273
+ off in a session by using the `toggle-color` command. Alternatively,
274
+ you can turn it off permanently by putting the line `Pry.color =
275
+ false` in your `~/.pryrc` file.
276
+
277
+ Bindings and objects
278
+ --------------------
279
+
280
+ Pry ultimately operates on `Binding` objects. If you invoke Pry with a
281
+ Binding object it uses that Binding. If you invoke Pry with anything
282
+ other than a `Binding`, Pry will generate a Binding for that
283
+ object and use that.
284
+
285
+ If you want to open a Pry session on the current context and capture
286
+ the locals you should use: `binding.pry`. If you do not care about
287
+ capturing the locals you can simply use `pry` (which will generate a
288
+ fresh `Binding` for the receiver).
289
+
290
+ Top-level is a special case; you can start a Pry session on top-level
291
+ *and* capture locals by simply using: `pry`. This is because Pry
292
+ automatically uses `TOPLEVEL_BINDING` for the top-level object (main).
293
+
294
+ Example Programs
295
+ ----------------
296
+
297
+ Pry comes bundled with a few example programs to illustrate some
298
+ features, see the `examples/` directory.
299
+
300
+ * `example_basic.rb` - Demonstrate basic Pry functionality
301
+ * `example_input.rb` - Demonstrates how to set the `input` object.
302
+ * `example_output.rb` - Demonstrates how to set the `output` object.
303
+ * `example_hooks.rb` - Demonstrates how to set the `hooks` hash.
304
+ * `example_print.rb` - Demonstrates how to set the `print` object.
305
+ * `example_prompt.rb` - Demonstrates how to set the `prompt`.
306
+ * `example_input2.rb` - An advanced `input` example.
307
+ * `example_commands.rb` - Implementing a mathematical command set.
308
+ * `example_commands_override.rb` - An advanced `commands` example.
309
+ * `example_image_edit.rb` - A simple image editor using a Pry REPL (requires `Gosu` and `TexPlay` gems).
310
+
311
+ Customizing Pry
312
+ ---------------
313
+
314
+ Pry allows a large degree of customization.
315
+
316
+ [Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
317
+
318
+ Contact
319
+ -------
320
+
321
+ Problems or questions contact me at [github](http://github.com/banister)