pry 0.8.3-i386-mswin32 → 0.8.4pre1-i386-mswin32

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,397 @@
1
+ Customizing Pry
2
+ ---------------
3
+
4
+ Pry supports customization of the input, the output, the commands,
5
+ the hooks, the prompt, and the 'print' object (the "P" in REPL).
6
+
7
+ Global customization, which applies to all Pry sessions, is done
8
+ through invoking class accessors on the `Pry` class, the accessors
9
+ are:
10
+
11
+ * `Pry.input=`
12
+ * `Pry.output=`
13
+ * `Pry.commands=`
14
+ * `Pry.hooks=`
15
+ * `Pry.prompt=`
16
+ * `Pry.print=`
17
+
18
+ Local customization (applied to a single Pry session) is done by
19
+ passing config hash options to `Pry.start()` or to `Pry.new()`; also the
20
+ same accessors as described above for the `Pry` class exist for a
21
+ Pry instance so that customization can occur at runtime.
22
+
23
+ ### Input
24
+
25
+ For input Pry accepts any object that implements the `readline` method. This
26
+ includes `IO` objects, `StringIO`, `Readline`, `File` and custom objects. Pry
27
+ initially defaults to using `Readline` for input.
28
+
29
+ #### Example: Setting global input
30
+
31
+ Setting Pry's global input causes all subsequent Pry instances to use
32
+ this input by default:
33
+
34
+ Pry.input = StringIO.new("@x = 10\nexit")
35
+ Object.pry
36
+
37
+ Object.instance_variable_get(:@x) #=> 10
38
+
39
+ The above will execute the code in the `StringIO`
40
+ non-interactively. It gets all the input it needs from the `StringIO`
41
+ and then exits the Pry session. Note it is important to end the
42
+ session with 'exit' if you are running non-interactively or the Pry
43
+ session will hang as it loops indefinitely awaiting new input.
44
+
45
+ #### Example: Setting input for a specific session
46
+
47
+ The settings for a specific session override the global settings
48
+ (discussed above). There are two ways to set input for a specific pry session: At the
49
+ point the session is started, or within the session itself (at runtime):
50
+
51
+ ##### At session start
52
+
53
+ Pry.start(Object, :input => StringIO.new("@x = 10\nexit"))
54
+ Object.instance_variable_get(:@x) #=> 10
55
+
56
+ ##### At runtime
57
+
58
+ If you want to set the input object within the session itself you use
59
+ the special `_pry_` local variable which represents the Pry instance
60
+ managing the current session; inside the session we type:
61
+
62
+ _pry_.input = StringIO.new("@x = 10\nexit")
63
+
64
+ Note we can also set the input object for the parent Pry session (if
65
+ the current session is nested) like so:
66
+
67
+ _pry_.parent.input = StringIO.new("@x = 10\nexit")
68
+
69
+ ### Output
70
+
71
+ For output Pry accepts any object that implements the `puts` method. This
72
+ includes `IO` objects, `StringIO`, `File` and custom objects. Pry initially
73
+ defaults to using `$stdout` for output.
74
+
75
+ #### Example: Setting global output
76
+
77
+ Setting Pry's global output causes all subsequent Pry instances to use
78
+ this output by default:
79
+
80
+ Pry.output = StringIO.new
81
+
82
+ #### Example: Setting output for a specific session
83
+
84
+ As per Input, given above, we set the local output as follows:
85
+
86
+ ##### At session start
87
+
88
+ Pry.start(Object, :output => StringIO.new("@x = 10\nexit"))
89
+
90
+ ##### At runtime
91
+
92
+ _pry_.output = StringIO.new
93
+
94
+ ### Commands
95
+
96
+ Pry commands are not methods; they are commands that are intercepted
97
+ and executed before a Ruby eval takes place. Pry comes with a default
98
+ command set (`Pry::Commands`), but these commands can be augmented or overriden by
99
+ user-specified ones.
100
+
101
+ The Pry command API is quite sophisticated supporting features such as:
102
+ command set inheritance, importing of specific commands from another
103
+ command set, deletion of commands, calling of commands within other
104
+ commands, and so on.
105
+
106
+ A valid Pry command object must inherit from
107
+ `Pry::CommandBase` (or one of its subclasses) and use the special command API:
108
+
109
+ #### Example: Defining a command object and setting it globally
110
+
111
+ class MyCommands < Pry::CommandBase
112
+ command "greet", "Greet the user." do |name, age|
113
+ output.puts "Hello #{name.capitalize}, how does it feel being #{age}?"
114
+ end
115
+ end
116
+
117
+ Pry.commands = MyCommands
118
+
119
+ Then inside a pry session:
120
+
121
+ pry(main)> greet john 9
122
+ Hello John, how does it feel being 9?
123
+ => nil
124
+
125
+ #### Example: Using a command object in a specific session
126
+
127
+ As in the case of `input` and `output`:
128
+
129
+ ##### At session start:
130
+
131
+ Pry.start(self, :commands => MyCommands)
132
+
133
+ ##### At runtime:
134
+
135
+ _pry_.commands = MyCommands
136
+
137
+ #### The command API
138
+
139
+ The command API is defined by the `Pry::CommandBase` class (hence why
140
+ all commands must inherit from it or a subclass). The API works as follows:
141
+
142
+ ##### `command` method
143
+
144
+ The `command` method defines a new command, its parameter is the
145
+ name of the command and an optional second parameter is a description of
146
+ the command.
147
+
148
+ The associated block defines the action to be performed. The number of
149
+ parameters in the block determine the number of parameters that will
150
+ be sent to the command (from the Pry prompt) when it is invoked. Note
151
+ that all parameters that are received will be strings; if a parameter
152
+ is not received it will be set to `nil`.
153
+
154
+ command "hello" do |x, y, z|
155
+ puts "hello there #{x}, #{y}, and #{z}!"
156
+ end
157
+
158
+ Command aliases can also be defined - simply use an array of strings
159
+ for the command name - all these strings will be valid names for the
160
+ command.
161
+
162
+ command ["ls", "dir"], "show a list of local vars" do
163
+ output.puts target.eval("local_variables")
164
+ end
165
+
166
+ ##### `delete` method
167
+
168
+ The `delete` method deletes a command or a group of commands. It
169
+ can be useful when inheriting from another command set and you wish
170
+ to keep only a portion of the inherited commands.
171
+
172
+ class MyCommands < Pry::Commands
173
+ delete "show_method", "show_imethod"
174
+ end
175
+
176
+ ##### `import_from` method
177
+
178
+ The `import_from` method enables you to specifically select which
179
+ commands will be copied across from another command set, useful when
180
+ you only want a small number of commands and so inheriting and then
181
+ deleting would be inefficient. The first parameter to `import_from`
182
+ is the class to import from and the other paramters are the names of
183
+ the commands to import:
184
+
185
+ class MyCommands < Pry::CommandBase
186
+ import_from Pry::Commands, "ls", "status", "!"
187
+ end
188
+
189
+ ##### `run` method
190
+
191
+ The `run` command invokes one command from within another.
192
+ The first parameter is the name of the command to invoke
193
+ and the remainder of the parameters will be passed on to the command
194
+ being invoked:
195
+
196
+ class MyCommands < Pry::Commands
197
+ command "ls_with_hello" do
198
+ output.puts "hello!"
199
+ run "ls"
200
+ end
201
+ end
202
+
203
+ ##### `alias_command` method
204
+
205
+ The `alias_command` method creates an alias of a command. The first
206
+ parameter is the name of the new command, the second parameter is the
207
+ name of the command to be aliased; an optional third parameter is the
208
+ description to use for the alias. If no description is provided then
209
+ the description of the original command is used.
210
+
211
+ class MyCommands < Pry::Commands
212
+ alias_command "help2", "help", "An alias of help"
213
+ end
214
+
215
+ ##### `desc` method
216
+
217
+ The `desc` method is used to give a command a new description. The
218
+ first parameter is the name of the command, the second parameter is
219
+ the description.
220
+
221
+ class MyCommands < Pry::Commands
222
+ desc "ls", "a new description"
223
+ end
224
+
225
+ #### Utility methods for commands
226
+
227
+ All commands can access the special `output` and `target` methods. The
228
+ `output` method returns the `output` object for the active pry session.
229
+ Ensuring that your commands invoke `puts` on this rather than using
230
+ the top-level `puts` will ensure that all your session output goes to
231
+ the same place.
232
+
233
+ The `target` method returns the `Binding` object the Pry session is currently
234
+ active on - useful when your commands need to manipulate or examine
235
+ the state of the object. E.g, the "ls" command is implemented as follows
236
+
237
+ command "ls" do
238
+ output.puts target.eval("local_variables + instance_variables").inspect
239
+ end
240
+
241
+ #### The opts hash
242
+
243
+ These are miscellaneous variables that may be useful to your commands:
244
+
245
+ * `opts[:val]` - The line of input that invoked the command.
246
+ * `opts[:eval_string]` - The cumulative lines of input for multi-line input.
247
+ * `opts[:nesting]` - Lowlevel session nesting information.
248
+ * `opts[:commands]` - Lowlevel data of all Pry commands.
249
+
250
+ (see commands.rb for examples of how some of these options are used)
251
+
252
+ #### The `help` command
253
+
254
+ The `Pry::CommandBase` class automatically defines a `help` command
255
+ for you. Typing `help` in a Pry session will show a list of commands
256
+ to the user followed by their descriptions. Passing a parameter to
257
+ `help` with the command name will just return the description of that
258
+ specific command. If a description is left out it will automatically
259
+ be given the description "No description.".
260
+
261
+ If the description is explicitly set to `""` then this command will
262
+ not be displayed in `help`.
263
+
264
+ ### Hooks
265
+
266
+ Currently Pry supports just two hooks: `before_session` and
267
+ `after_session`. These hooks are invoked before a Pry session starts
268
+ and after a session ends respectively. The default hooks used are
269
+ stored in the `Pry::DEFAULT_HOOKS` and just output the text `"Beginning
270
+ Pry session for <obj>"` and `"Ending Pry session for <obj>"`.
271
+
272
+ #### Example: Setting global hooks
273
+
274
+ All subsequent Pry instances will use these hooks as default:
275
+
276
+ Pry.hooks = {
277
+ :before_session => proc { |out, obj| out.puts "Opened #{obj}" },
278
+ :after_session => proc { |out, obj| out.puts "Closed #{obj}" }
279
+ }
280
+
281
+ 5.pry
282
+
283
+ Inside the session:
284
+
285
+ Opened 5
286
+ pry(5)> exit
287
+ Closed 5
288
+
289
+ Note that the `before_session` and `after_session` procs receive the
290
+ current session's output object and session receiver as parameters.
291
+
292
+ #### Example: Setting hooks for a specific session
293
+
294
+ Like all the other customization options, the global default (as
295
+ explained above) can be overriden for a specific session, either at
296
+ session start or during runtime.
297
+
298
+ ##### At session start
299
+
300
+ Pry.start(self, :hooks => { :before_session => proc { puts "hello world!" },
301
+ :after_session => proc { puts "goodbye world!" }
302
+ })
303
+
304
+ ##### At runtime
305
+
306
+ _pry_.hooks = { :before_session => proc { puts "puts "hello world!" } }
307
+
308
+ ### Prompts
309
+
310
+ The Pry prompt is used by `Readline` and other input objects that
311
+ accept a prompt. Pry can accept two prompt-types for every prompt; the
312
+ 'main prompt' and the 'wait prompt'. The main prompt is always used
313
+ for the first line of input; the wait prompt is used in multi-line
314
+ input to indicate that the current expression is incomplete and more lines of
315
+ input are required. The default Prompt used by Pry is stored in the
316
+ `Pry::DEFAULT_PROMPT` constant.
317
+
318
+ A valid Pry prompt is either a single `Proc` object or a two element
319
+ array of `Proc` objects. When an array is used the first element is
320
+ the 'main prompt' and the last element is the 'wait prompt'. When a
321
+ single `Proc` object is used it will be used for both the main prompt
322
+ and the wait prompt.
323
+
324
+ #### Example: Setting global prompt
325
+
326
+ The prompt `Proc` objects are passed the receiver of the Pry session
327
+ and the nesting level of that session as parameters (they can simply
328
+ ignore these if they do not need them).
329
+
330
+ # Using one proc for both main and wait prompts
331
+ Pry.prompt = proc { |obj, nest_level| "#{obj}:#{nest_level}> " }
332
+
333
+ # Alternatively, provide two procs; one for main and one for wait
334
+ Pry.prompt = [ proc { "ENTER INPUT> " }, proc { "MORE INPUT REQUIRED!* " }]
335
+
336
+ #### Example: Setting the prompt for a specific session
337
+
338
+ ##### At session start
339
+
340
+ Pry.start(self, :prompt => [proc { "ENTER INPUT> " },
341
+ proc { "MORE INPUT REQUIRED!* " }])
342
+
343
+ ##### At runtime
344
+
345
+ _pry_.prompt = [proc { "ENTER INPUT> " },
346
+ proc { "MORE INPUT REQUIRED!* " }]
347
+
348
+ ### Print
349
+
350
+ The Print phase of Pry's READ-EVAL-PRINT-LOOP can be customized. The
351
+ default action is stored in the `Pry::DEFAULT_PRINT` constant and it
352
+ simply outputs the value of the current expression preceded by a `=>` (or the first
353
+ line of the backtrace if the value is an `Exception` object.)
354
+
355
+ The print object should be a `Proc` and the parameters passed to the
356
+ `Proc` are the output object for the current session and the 'value'
357
+ returned by the current expression.
358
+
359
+ #### Example: Setting global print object
360
+
361
+ Let's define a print object that displays the full backtrace of any
362
+ exception and precedes the output of a value by the text `"Output is: "`:
363
+
364
+ Pry.print = proc do |output, value|
365
+ case value
366
+ when Exception
367
+ output.puts value.backtrace
368
+ else
369
+ output.puts "Output is: #{value}"
370
+ end
371
+ end
372
+
373
+ #### Example: Setting the print object for a specific session
374
+
375
+ ##### At session start
376
+
377
+ Pry.start(self, :print => proc do |output, value|
378
+ case value
379
+ when Exception
380
+ output.puts value.backtrace
381
+ else
382
+ output.puts "Output is: #{value.inspect}"
383
+ end
384
+ end)
385
+
386
+ ##### At runtime
387
+
388
+ _pry_.print = proc do |output, value|
389
+ case value
390
+ when Exception
391
+ output.puts value.backtrace
392
+ else
393
+ output.puts "Output is: #{value.inspect}"
394
+ end
395
+ end
396
+
397
+ [Back to front page of documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
@@ -0,0 +1,4 @@
1
+ Further documentation on Pry can be found here:
2
+
3
+ * [Customizing Pry](https://github.com/banister/pry/wiki/Customizing-pry)
4
+ * [Blog post: Turning IRB on its head with Pry](http://banisterfiend.wordpress.com/2011/01/27/turning-irb-on-its-head-with-pry/)
metadata CHANGED
@@ -1,8 +1,8 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: pry
3
3
  version: !ruby/object:Gem::Version
4
- prerelease:
5
- version: 0.8.3
4
+ prerelease: 5
5
+ version: 0.8.4pre1
6
6
  platform: i386-mswin32
7
7
  authors:
8
8
  - John Mair (banisterfiend)
@@ -10,8 +10,7 @@ autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
12
 
13
- date: 2011-04-26 00:00:00 +12:00
14
- default_executable:
13
+ date: 2011-05-05 00:00:00 Z
15
14
  dependencies:
16
15
  - !ruby/object:Gem::Dependency
17
16
  name: ruby_parser
@@ -32,7 +31,7 @@ dependencies:
32
31
  requirements:
33
32
  - - ">="
34
33
  - !ruby/object:Gem::Version
35
- version: 0.9.7
34
+ version: 0.9.8
36
35
  type: :runtime
37
36
  version_requirements: *id002
38
37
  - !ruby/object:Gem::Dependency
@@ -47,26 +46,26 @@ dependencies:
47
46
  type: :runtime
48
47
  version_requirements: *id003
49
48
  - !ruby/object:Gem::Dependency
50
- name: bacon
49
+ name: method_source
51
50
  prerelease: false
52
51
  requirement: &id004 !ruby/object:Gem::Requirement
53
52
  none: false
54
53
  requirements:
55
54
  - - ">="
56
55
  - !ruby/object:Gem::Version
57
- version: 1.1.0
58
- type: :development
56
+ version: 0.4.0
57
+ type: :runtime
59
58
  version_requirements: *id004
60
59
  - !ruby/object:Gem::Dependency
61
- name: method_source
60
+ name: bacon
62
61
  prerelease: false
63
62
  requirement: &id005 !ruby/object:Gem::Requirement
64
63
  none: false
65
64
  requirements:
66
65
  - - ">="
67
66
  - !ruby/object:Gem::Version
68
- version: 0.4.0
69
- type: :runtime
67
+ version: 1.1.0
68
+ type: :development
70
69
  version_requirements: *id005
71
70
  - !ruby/object:Gem::Dependency
72
71
  name: win32console
@@ -79,7 +78,7 @@ dependencies:
79
78
  version: 1.3.0
80
79
  type: :runtime
81
80
  version_requirements: *id006
82
- description: attach an irb-like session to any object at runtime
81
+ description: an IRB alternative and runtime developer console
83
82
  email: jrmair@gmail.com
84
83
  executables:
85
84
  - pry
@@ -88,41 +87,58 @@ extensions: []
88
87
  extra_rdoc_files: []
89
88
 
90
89
  files:
91
- - lib/pry/command_base.rb
92
- - lib/pry/command_base_helpers.rb
93
- - lib/pry/command_helpers.rb
90
+ - .document
91
+ - .gemtest
92
+ - .gitignore
93
+ - .yardopts
94
+ - CHANGELOG
95
+ - LICENSE
96
+ - README.markdown
97
+ - Rakefile
98
+ - TODO
99
+ - bin/pry
100
+ - examples/example_basic.rb
101
+ - examples/example_command_override.rb
102
+ - examples/example_commands.rb
103
+ - examples/example_hooks.rb
104
+ - examples/example_image_edit.rb
105
+ - examples/example_input.rb
106
+ - examples/example_input2.rb
107
+ - examples/example_output.rb
108
+ - examples/example_print.rb
109
+ - examples/example_prompt.rb
110
+ - lib/pry.rb
111
+ - lib/pry/command_context.rb
94
112
  - lib/pry/command_processor.rb
113
+ - lib/pry/command_set.rb
95
114
  - lib/pry/commands.rb
96
115
  - lib/pry/completion.rb
97
116
  - lib/pry/core_extensions.rb
98
117
  - lib/pry/custom_completions.rb
118
+ - lib/pry/default_commands/context.rb
119
+ - lib/pry/default_commands/documentation.rb
120
+ - lib/pry/default_commands/easter_eggs.rb
121
+ - lib/pry/default_commands/gems.rb
122
+ - lib/pry/default_commands/input.rb
123
+ - lib/pry/default_commands/introspection.rb
124
+ - lib/pry/default_commands/ls.rb
125
+ - lib/pry/default_commands/shell.rb
126
+ - lib/pry/helpers.rb
127
+ - lib/pry/helpers/base_helpers.rb
128
+ - lib/pry/helpers/command_helpers.rb
99
129
  - lib/pry/hooks.rb
100
130
  - lib/pry/print.rb
101
131
  - lib/pry/prompts.rb
102
132
  - lib/pry/pry_class.rb
103
133
  - lib/pry/pry_instance.rb
104
134
  - lib/pry/version.rb
105
- - lib/pry.rb
106
- - examples/example_basic.rb
107
- - examples/example_command_override.rb
108
- - examples/example_commands.rb
109
- - examples/example_hooks.rb
110
- - examples/example_image_edit.rb
111
- - examples/example_input.rb
112
- - examples/example_input2.rb
113
- - examples/example_output.rb
114
- - examples/example_print.rb
115
- - examples/example_prompt.rb
116
- - test/test.rb
117
- - test/test_helper.rb
135
+ - test/helper.rb
136
+ - test/test_command_helpers.rb
137
+ - test/test_commandset.rb
138
+ - test/test_pry.rb
118
139
  - test/testrc
119
- - CHANGELOG
120
- - LICENSE
121
- - README.markdown
122
- - Rakefile
123
- - .gemtest
124
- - bin/pry
125
- has_rdoc: true
140
+ - wiki/Customizing-pry.md
141
+ - wiki/Home.md
126
142
  homepage: http://banisterfiend.wordpress.com
127
143
  licenses: []
128
144
 
@@ -140,15 +156,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
140
156
  required_rubygems_version: !ruby/object:Gem::Requirement
141
157
  none: false
142
158
  requirements:
143
- - - ">="
159
+ - - ">"
144
160
  - !ruby/object:Gem::Version
145
- version: "0"
161
+ version: 1.3.1
146
162
  requirements: []
147
163
 
148
164
  rubyforge_project:
149
- rubygems_version: 1.6.2
165
+ rubygems_version: 1.7.2
150
166
  signing_key:
151
167
  specification_version: 3
152
- summary: attach an irb-like session to any object at runtime
153
- test_files: []
154
-
168
+ summary: an IRB alternative and runtime developer console
169
+ test_files:
170
+ - test/helper.rb
171
+ - test/test_command_helpers.rb
172
+ - test/test_commandset.rb
173
+ - test/test_pry.rb
174
+ - test/testrc