pry 0.10.1 → 0.13.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (159) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +378 -11
  3. data/LICENSE +1 -1
  4. data/README.md +352 -306
  5. data/bin/pry +4 -7
  6. data/lib/pry/basic_object.rb +10 -0
  7. data/lib/pry/block_command.rb +22 -0
  8. data/lib/pry/class_command.rb +194 -0
  9. data/lib/pry/cli.rb +81 -74
  10. data/lib/pry/code/code_file.rb +37 -26
  11. data/lib/pry/code/code_range.rb +7 -5
  12. data/lib/pry/code/loc.rb +26 -13
  13. data/lib/pry/code.rb +49 -30
  14. data/lib/pry/code_object.rb +53 -28
  15. data/lib/pry/color_printer.rb +46 -35
  16. data/lib/pry/command.rb +197 -369
  17. data/lib/pry/command_set.rb +89 -114
  18. data/lib/pry/command_state.rb +31 -0
  19. data/lib/pry/commands/amend_line.rb +86 -82
  20. data/lib/pry/commands/bang.rb +18 -14
  21. data/lib/pry/commands/bang_pry.rb +15 -11
  22. data/lib/pry/commands/cat/abstract_formatter.rb +23 -18
  23. data/lib/pry/commands/cat/exception_formatter.rb +85 -72
  24. data/lib/pry/commands/cat/file_formatter.rb +56 -46
  25. data/lib/pry/commands/cat/input_expression_formatter.rb +35 -30
  26. data/lib/pry/commands/cat.rb +62 -54
  27. data/lib/pry/commands/cd.rb +40 -35
  28. data/lib/pry/commands/change_inspector.rb +29 -22
  29. data/lib/pry/commands/change_prompt.rb +48 -23
  30. data/lib/pry/commands/clear_screen.rb +20 -0
  31. data/lib/pry/commands/code_collector.rb +148 -131
  32. data/lib/pry/commands/disable_pry.rb +23 -19
  33. data/lib/pry/commands/easter_eggs.rb +23 -34
  34. data/lib/pry/commands/edit/exception_patcher.rb +21 -17
  35. data/lib/pry/commands/edit/file_and_line_locator.rb +34 -23
  36. data/lib/pry/commands/edit.rb +185 -157
  37. data/lib/pry/commands/exit.rb +40 -35
  38. data/lib/pry/commands/exit_all.rb +24 -20
  39. data/lib/pry/commands/exit_program.rb +20 -16
  40. data/lib/pry/commands/find_method.rb +168 -162
  41. data/lib/pry/commands/fix_indent.rb +16 -12
  42. data/lib/pry/commands/help.rb +140 -133
  43. data/lib/pry/commands/hist.rb +151 -149
  44. data/lib/pry/commands/import_set.rb +20 -15
  45. data/lib/pry/commands/jump_to.rb +25 -21
  46. data/lib/pry/commands/list_inspectors.rb +35 -28
  47. data/lib/pry/commands/ls/constants.rb +59 -31
  48. data/lib/pry/commands/ls/formatter.rb +42 -36
  49. data/lib/pry/commands/ls/globals.rb +38 -36
  50. data/lib/pry/commands/ls/grep.rb +17 -15
  51. data/lib/pry/commands/ls/instance_vars.rb +29 -28
  52. data/lib/pry/commands/ls/interrogatable.rb +18 -12
  53. data/lib/pry/commands/ls/jruby_hacks.rb +47 -41
  54. data/lib/pry/commands/ls/local_names.rb +26 -24
  55. data/lib/pry/commands/ls/local_vars.rb +38 -30
  56. data/lib/pry/commands/ls/ls_entity.rb +47 -52
  57. data/lib/pry/commands/ls/methods.rb +49 -51
  58. data/lib/pry/commands/ls/methods_helper.rb +46 -42
  59. data/lib/pry/commands/ls/self_methods.rb +23 -21
  60. data/lib/pry/commands/ls.rb +124 -103
  61. data/lib/pry/commands/nesting.rb +21 -17
  62. data/lib/pry/commands/play.rb +92 -82
  63. data/lib/pry/commands/pry_backtrace.rb +22 -17
  64. data/lib/pry/commands/pry_version.rb +15 -11
  65. data/lib/pry/commands/raise_up.rb +33 -27
  66. data/lib/pry/commands/reload_code.rb +60 -48
  67. data/lib/pry/commands/reset.rb +16 -12
  68. data/lib/pry/commands/ri.rb +57 -42
  69. data/lib/pry/commands/save_file.rb +45 -43
  70. data/lib/pry/commands/shell_command.rb +56 -29
  71. data/lib/pry/commands/shell_mode.rb +22 -18
  72. data/lib/pry/commands/show_doc.rb +81 -70
  73. data/lib/pry/commands/show_info.rb +194 -155
  74. data/lib/pry/commands/show_input.rb +16 -11
  75. data/lib/pry/commands/show_source.rb +109 -42
  76. data/lib/pry/commands/stat.rb +35 -31
  77. data/lib/pry/commands/switch_to.rb +21 -15
  78. data/lib/pry/commands/toggle_color.rb +20 -16
  79. data/lib/pry/commands/watch_expression/expression.rb +32 -27
  80. data/lib/pry/commands/watch_expression.rb +89 -84
  81. data/lib/pry/commands/whereami.rb +156 -141
  82. data/lib/pry/commands/wtf.rb +78 -40
  83. data/lib/pry/config/attributable.rb +22 -0
  84. data/lib/pry/config/lazy_value.rb +29 -0
  85. data/lib/pry/config/memoized_value.rb +34 -0
  86. data/lib/pry/config/value.rb +24 -0
  87. data/lib/pry/config.rb +317 -20
  88. data/lib/pry/control_d_handler.rb +28 -0
  89. data/lib/pry/core_extensions.rb +22 -9
  90. data/lib/pry/editor.rb +53 -33
  91. data/lib/pry/env.rb +18 -0
  92. data/lib/pry/exception_handler.rb +43 -0
  93. data/lib/pry/exceptions.rb +13 -17
  94. data/lib/pry/forwardable.rb +27 -0
  95. data/lib/pry/helpers/base_helpers.rb +20 -62
  96. data/lib/pry/helpers/command_helpers.rb +52 -62
  97. data/lib/pry/helpers/documentation_helpers.rb +20 -12
  98. data/lib/pry/helpers/options_helpers.rb +15 -8
  99. data/lib/pry/helpers/platform.rb +60 -0
  100. data/lib/pry/helpers/table.rb +44 -32
  101. data/lib/pry/helpers/text.rb +96 -85
  102. data/lib/pry/helpers.rb +3 -0
  103. data/lib/pry/history.rb +81 -55
  104. data/lib/pry/hooks.rb +60 -110
  105. data/lib/pry/indent.rb +72 -66
  106. data/lib/pry/input_completer.rb +199 -158
  107. data/lib/pry/input_lock.rb +7 -10
  108. data/lib/pry/inspector.rb +36 -24
  109. data/lib/pry/last_exception.rb +45 -45
  110. data/lib/pry/method/disowned.rb +19 -5
  111. data/lib/pry/method/patcher.rb +14 -8
  112. data/lib/pry/method/weird_method_locator.rb +79 -43
  113. data/lib/pry/method.rb +177 -124
  114. data/lib/pry/object_path.rb +37 -28
  115. data/lib/pry/output.rb +102 -16
  116. data/lib/pry/pager.rb +187 -174
  117. data/lib/pry/plugins.rb +49 -13
  118. data/lib/pry/prompt.rb +213 -25
  119. data/lib/pry/pry_class.rb +106 -93
  120. data/lib/pry/pry_instance.rb +261 -224
  121. data/lib/pry/repl.rb +82 -27
  122. data/lib/pry/repl_file_loader.rb +27 -22
  123. data/lib/pry/ring.rb +89 -0
  124. data/lib/pry/slop/LICENSE +20 -0
  125. data/lib/pry/slop/commands.rb +190 -0
  126. data/lib/pry/slop/option.rb +210 -0
  127. data/lib/pry/slop.rb +672 -0
  128. data/lib/pry/syntax_highlighter.rb +26 -0
  129. data/lib/pry/system_command_handler.rb +17 -0
  130. data/lib/pry/testable/evalable.rb +24 -0
  131. data/lib/pry/testable/mockable.rb +22 -0
  132. data/lib/pry/testable/pry_tester.rb +88 -0
  133. data/lib/pry/testable/utility.rb +34 -0
  134. data/lib/pry/testable/variables.rb +52 -0
  135. data/lib/pry/testable.rb +68 -0
  136. data/lib/pry/version.rb +3 -1
  137. data/lib/pry/warning.rb +27 -0
  138. data/lib/pry/{module_candidate.rb → wrapped_module/candidate.rb} +29 -27
  139. data/lib/pry/wrapped_module.rb +67 -57
  140. data/lib/pry.rb +134 -149
  141. metadata +49 -59
  142. data/lib/pry/commands/disabled_commands.rb +0 -2
  143. data/lib/pry/commands/gem_cd.rb +0 -26
  144. data/lib/pry/commands/gem_install.rb +0 -32
  145. data/lib/pry/commands/gem_list.rb +0 -33
  146. data/lib/pry/commands/gem_open.rb +0 -29
  147. data/lib/pry/commands/gist.rb +0 -101
  148. data/lib/pry/commands/install_command.rb +0 -53
  149. data/lib/pry/commands/list_prompts.rb +0 -35
  150. data/lib/pry/commands/simple_prompt.rb +0 -22
  151. data/lib/pry/commands.rb +0 -6
  152. data/lib/pry/config/behavior.rb +0 -139
  153. data/lib/pry/config/convenience.rb +0 -25
  154. data/lib/pry/config/default.rb +0 -161
  155. data/lib/pry/history_array.rb +0 -121
  156. data/lib/pry/rbx_path.rb +0 -22
  157. data/lib/pry/rubygem.rb +0 -82
  158. data/lib/pry/terminal.rb +0 -79
  159. data/lib/pry/test/helper.rb +0 -170
data/README.md CHANGED
@@ -1,31 +1,62 @@
1
- [![Build Status](https://img.shields.io/travis/pry/pry.svg)](https://travis-ci.org/pry/pry)
2
- [![Code Climate](https://img.shields.io/codeclimate/github/pry/pry.svg)](https://codeclimate.com/github/pry/pry)
3
- [![Inline docs](http://inch-ci.org/github/pry/pry.svg)](http://inch-ci.org/github/pry/pry)
4
-
5
- <center>
6
- ![The Pry Logo](https://dl.dropbox.com/u/26521875/pry%20stuff/logo/pry_logo_350.png)
7
-
8
- © John Mair ([banisterfiend](https://twitter.com/banisterfiend)) 2013<br>
9
-
10
- **Please** [DONATE](http://www.pledgie.com/campaigns/15899) to the Pry project - Pry was a **huge** amount of work and every donation received is encouraging and supports Pry's continued development!
11
-
12
- **Sponsors**
13
-
14
- [Tealeaf Academy](http://www.gotealeaf.com)<br/>
15
- [Atomic Object](http://www.atomicobject.com/)<br/>
16
- [Hashrocket](http://hashrocket.com/)<br/>
17
- [Intridea](http://intridea.com/)<br/>
18
- [Gaslight](http://gaslight.co/home)<br/>
19
-
20
- **Other Resources**
21
-
22
- [Skip to the website (recommended)](http://pry.github.com) <br />
23
- [Skip to the wiki](https://github.com/pry/pry/wiki)
24
- </center>
25
-
26
- Pry is a powerful alternative to the standard IRB shell for Ruby. It is
27
- written from scratch to provide a number of advanced features,
28
- including:
1
+ Pry
2
+ ===
3
+
4
+ [![Circle Build Status](https://circleci.com/gh/pry/pry.svg?style=shield)](https://circleci.com/gh/pry/pry)
5
+ [![Code Climate](https://codeclimate.com/github/pry/pry.svg)](https://codeclimate.com/github/pry/pry)
6
+ [![Gem Version](https://badge.fury.io/rb/pry.svg)](https://badge.fury.io/rb/pry)
7
+ [![Documentation Status](https://inch-ci.org/github/pry/pry.svg?branch=master)](https://inch-ci.org/github/pry/pry)
8
+ [![Downloads](https://img.shields.io/gem/dt/pry.svg?style=flat)](https://rubygems.org/gems/pry)
9
+
10
+ ![Pry logo](https://www.dropbox.com/s/zp8o63kquby2rln/pry_logo_350.png?raw=1)
11
+
12
+ © John Mair ([banisterfiend](https://twitter.com/banisterfiend)) 2018<br> (Creator)
13
+
14
+ © Kyrylo Silin ([kyrylosilin](https://twitter.com/kyrylosilin)) 2018<br> (Maintainer)
15
+
16
+ **Alumni:**
17
+
18
+ * Conrad Irwin
19
+ * Ryan Fitzgerald
20
+ * Robert Gleeson
21
+
22
+ **Links:**
23
+
24
+ * https://pryrepl.org/
25
+ * [YARD API documentation](https://www.rubydoc.info/gems/pry)
26
+ * [Wiki](https://github.com/pry/pry/wiki)
27
+
28
+ Table of Contents
29
+ =================
30
+
31
+ * [Introduction](#introduction)
32
+ * [Key features](#key-features)
33
+ * [Installation](#installation)
34
+ * [Overview](#overview)
35
+ * [Commands](#commands)
36
+ * [Navigating around state](#navigating-around-state)
37
+ * [Runtime invocation](#runtime-invocation)
38
+ * [Command Shell Integration](#command-shell-integration)
39
+ * [Code Browsing](#code-browsing)
40
+ * [Documentation Browsing](#documentation-browsing)
41
+ * [Gist integration](#gist-integration)
42
+ * [Edit methods](#edit-methods)
43
+ * [Live Help System](#live-help-system)
44
+ * [Use Pry as your Rails Console](#use-pry-as-your-rails-console)
45
+ * [Syntax Highlighting](#syntax-highlighting)
46
+ * [Supported Rubies](#supported-rubies)
47
+ * [Contact](#contact)
48
+ * [License](#license)
49
+ * [Contributors](#contributors)
50
+
51
+ Introduction
52
+ ------------
53
+
54
+ Pry is a runtime developer console and IRB alternative with powerful
55
+ introspection capabilities. Pry aims to be more than an IRB replacement. It is
56
+ an attempt to bring REPL driven programming to the Ruby language.
57
+
58
+ Key features
59
+ ------------
29
60
 
30
61
  * Source code browsing (including core C source with the pry-doc gem)
31
62
  * Documentation browsing
@@ -37,370 +68,385 @@ including:
37
68
  * Navigation around state (`cd`, `ls` and friends)
38
69
  * Runtime invocation (use Pry as a developer console or debugger)
39
70
  * Exotic object support (BasicObject instances, IClasses, ...)
40
- * A Powerful and flexible command system
71
+ * A powerful and flexible command system
41
72
  * Ability to view and replay history
42
- * Many convenience commands inspired by IPython, Smalltalk and other advanced REPLs
43
- * A wide-range number of [plugins](https://github.com/pry/pry/wiki/Available-plugins) that provide remote sessions, full debugging functionality, and more.
44
-
45
- Pry also aims to be more than an IRB replacement; it is an
46
- attempt to bring REPL driven programming to the Ruby language. It is
47
- currently not as powerful as tools like [SLIME](http://en.wikipedia.org/wiki/SLIME) for lisp, but that is the
48
- general direction Pry is heading.
49
-
50
- Pry is also fairly flexible and allows significant user
51
- [customization](https://github.com/pry/pry/wiki/Customization-and-configuration)
52
- is trivial to set it to read from any object that has a `readline` method and write to any object that has a
53
- `puts` method - many other aspects of Pry are also configurable making
54
- it a good choice for implementing custom shells.
55
-
56
- Pry comes with an executable so it can be invoked at the command line.
57
- Just enter `pry` to start. A `.pryrc` file in the user's home directory will
58
- be loaded if it exists. Type `pry --help` at the command line for more
59
- information.
60
-
61
- Try `gem install pry-doc` for additional documentation on Ruby Core
62
- methods. The additional docs are accessed through the `show-doc` and
63
- `show-method` commands.
64
-
65
- * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
66
- * Browse the comprehensive [documentation at the official Pry wiki](https://github.com/pry/pry/wiki)
67
- * Read the [YARD API documentation](http://rdoc.info/github/pry/pry/master/file/README.markdown)
68
- * See the [source code](http://github.com/pry/pry)
73
+ * Many convenience commands inspired by IPython, Smalltalk and other advanced
74
+ REPLs
75
+ * A wide-range number of
76
+ [plugins](https://github.com/pry/pry/wiki/Available-plugins) that provide
77
+ remote sessions, full debugging functionality, and more.
78
+
79
+ Installation
80
+ ------------
81
+
82
+ ### Bundler
83
+
84
+ ```ruby
85
+ gem 'pry', '~> 0.12.2'
86
+ ```
87
+
88
+ ### Manual
89
+
90
+ ```sh
91
+ gem install pry
92
+ ```
93
+
94
+ Overview
95
+ --------
96
+
97
+ Pry is fairly flexible and allows significant user
98
+ [customization](https://github.com/pry/pry/wiki/Customization-and-configuration).
99
+ It is trivial to read from any object that has a `readline` method and
100
+ write to any object that has a `puts` method. Many other aspects of Pry are
101
+ also configurable, making it a good choice for implementing custom shells.
102
+
103
+ Pry comes with an executable so it can be invoked at the command line. Just
104
+ enter `pry` to start. A `pryrc` file in `$XDG_CONFIG_HOME/pry/` or the user's
105
+ home directory will be loaded if it exists. Type `pry --help` at the command
106
+ line for more information.
69
107
 
70
108
  ### Commands
71
109
 
72
- Nearly every piece of functionality in a Pry session is implemented as
73
- a command. Commands are not methods and must start at the beginning of a line, with no
74
- whitespace in between. Commands support a flexible syntax and allow
75
- 'options' in the same way as shell commands, for example the following
76
- Pry command will show a list of all private instance methods (in
77
- scope) that begin with 'pa'
110
+ Nearly every piece of functionality in a Pry session is implemented as a
111
+ command. Commands are not methods and must start at the beginning of a line,
112
+ with no whitespace in between. Commands support a flexible syntax and allow
113
+ 'options' in the same way as shell commands, for example the following Pry
114
+ command will show a list of all private instance methods (in scope) that begin
115
+ with 'pa'
78
116
 
79
- pry(YARD::Parser::SourceParser):5> ls -Mp --grep ^pa
80
- YARD::Parser::SourceParser#methods: parse parser_class parser_type parser_type= parser_type_for_filename
117
+ ```ruby
118
+ pry(YARD::Parser::SourceParser):5> ls -Mp --grep ^pa
119
+ YARD::Parser::SourceParser#methods: parse parser_class parser_type parser_type= parser_type_for_filename
120
+ ```
81
121
 
82
122
  ### Navigating around state
83
123
 
84
- Pry allows us to pop in and out of different scopes (objects) using
85
- the `cd` command. This enables us to explore the run-time view of a
86
- program or library. To view which variables and methods are available
87
- within a particular scope we use the versatile [ls command.](https://gist.github.com/c0fc686ef923c8b87715)
88
-
89
- Here we will begin Pry at top-level, then Pry on a class and then on
90
- an instance variable inside that class:
91
-
92
- pry(main)> class Hello
93
- pry(main)* @x = 20
94
- pry(main)* end
95
- => 20
96
- pry(main)> cd Hello
97
- pry(Hello):1> ls -i
98
- instance variables: @x
99
- pry(Hello):1> cd @x
100
- pry(20):2> self + 10
101
- => 30
102
- pry(20):2> cd ..
103
- pry(Hello):1> cd ..
104
- pry(main)> cd ..
105
-
106
- The number after the `:` in the pry prompt indicates the nesting
107
- level. To display more information about nesting, use the `nesting`
108
- command. E.g
109
-
110
- pry("friend"):3> nesting
111
- Nesting status:
112
- 0. main (Pry top level)
113
- 1. Hello
114
- 2. 100
115
- 3. "friend"
116
- => nil
117
-
118
- We can then jump back to any of the previous nesting levels by using
119
- the `jump-to` command:
120
-
121
- pry("friend"):3> jump-to 1
122
- => 100
123
- pry(Hello):1>
124
+ Pry allows us to pop in and out of different scopes (objects) using the `cd`
125
+ command. This enables us to explore the run-time view of a program or
126
+ library. To view which variables and methods are available within a particular
127
+ scope we use the versatile [ls
128
+ command.](https://gist.github.com/c0fc686ef923c8b87715)
129
+
130
+ Here we will begin Pry at top-level, then Pry on a class and then on an instance
131
+ variable inside that class:
132
+
133
+ ```ruby
134
+ pry(main)> class Hello
135
+ pry(main)* @x = 20
136
+ pry(main)* end
137
+ => 20
138
+ pry(main)> cd Hello
139
+ pry(Hello):1> ls -i
140
+ instance variables: @x
141
+ pry(Hello):1> cd @x
142
+ pry(20):2> self + 10
143
+ => 30
144
+ pry(20):2> cd ..
145
+ pry(Hello):1> cd ..
146
+ pry(main)> cd ..
147
+ ```
148
+
149
+ The number after the `:` in the pry prompt indicates the nesting level. To
150
+ display more information about nesting, use the `nesting` command. E.g
151
+
152
+ ```ruby
153
+ pry("friend"):3> nesting
154
+ Nesting status:
155
+ 0. main (Pry top level)
156
+ 1. Hello
157
+ 2. 100
158
+ 3. "friend"
159
+ => nil
160
+ ```
161
+
162
+ We can then jump back to any of the previous nesting levels by using the
163
+ `jump-to` command:
164
+
165
+ ```ruby
166
+ pry("friend"):3> jump-to 1
167
+ => 100
168
+ pry(Hello):1>
169
+ ```
124
170
 
125
171
  ### Runtime invocation
126
172
 
127
- Pry can be invoked in the middle of a running program. It opens a Pry
128
- session at the point it's called and makes all program state at that
129
- point available. It can be invoked on any object using the
130
- `my_object.pry` syntax or on the current binding (or any binding)
131
- using `binding.pry`. The Pry session will then begin within the scope
132
- of the object (or binding). When the session ends the program continues with any
133
- modifications you made to it.
173
+ Pry can be invoked in the middle of a running program. It opens a Pry session at
174
+ the point it's called and makes all program state at that point available. It
175
+ can be invoked on any object using the `my_object.pry` syntax or on the current
176
+ binding (or any binding) using `binding.pry`. The Pry session will then begin
177
+ within the scope of the object (or binding). When the session ends the program
178
+ continues with any modifications you made to it.
134
179
 
135
- This functionality can be used for such things as: debugging,
136
- implementing developer consoles and applying hot patches.
180
+ This functionality can be used for such things as: debugging, implementing
181
+ developer consoles and applying hot patches.
137
182
 
138
183
  code:
139
184
 
140
- # test.rb
141
- require 'pry'
185
+ ```ruby
186
+ # test.rb
187
+ require 'pry'
142
188
 
143
- class A
144
- def hello() puts "hello world!" end
145
- end
189
+ class A
190
+ def hello() puts "hello world!" end
191
+ end
146
192
 
147
- a = A.new
193
+ a = A.new
148
194
 
149
- # start a REPL session
150
- binding.pry
195
+ # start a REPL session
196
+ binding.pry
151
197
 
152
- # program resumes here (after pry session)
153
- puts "program resumes here."
198
+ # program resumes here (after pry session)
199
+ puts "program resumes here."
200
+ ```
154
201
 
155
202
  Pry session:
156
203
 
157
- pry(main)> a.hello
158
- hello world!
159
- => nil
160
- pry(main)> def a.goodbye
161
- pry(main)* puts "goodbye cruel world!"
162
- pry(main)* end
163
- => nil
164
- pry(main)> a.goodbye
165
- goodbye cruel world!
166
- => nil
167
- pry(main)> exit
168
-
169
- program resumes here.
204
+ ```ruby
205
+ pry(main)> a.hello
206
+ hello world!
207
+ => nil
208
+ pry(main)> def a.goodbye
209
+ pry(main)* puts "goodbye cruel world!"
210
+ pry(main)* end
211
+ => nil
212
+ pry(main)> a.goodbye
213
+ goodbye cruel world!
214
+ => nil
215
+ pry(main)> exit
216
+
217
+ program resumes here.
218
+ ```
170
219
 
171
220
  ### Command Shell Integration
172
221
 
173
- A line of input that begins with a '.' will be forwarded to the
174
- command shell. This enables us to navigate the file system, spawn
175
- editors, and run git and rake directly from within Pry.
222
+ A line of input that begins with a '.' will be forwarded to the command
223
+ shell. This enables us to navigate the file system, spawn editors, and run git
224
+ and rake directly from within Pry.
176
225
 
177
- Further, we can use the `shell-mode` command to incorporate the
178
- present working directory into the Pry prompt and bring in (limited at this stage, sorry) file name completion.
179
- We can also interpolate Ruby code directly into the shell by
226
+ Further, we can use the `shell-mode` command to incorporate the present working
227
+ directory into the Pry prompt and bring in (limited at this stage, sorry) file
228
+ name completion. We can also interpolate Ruby code directly into the shell by
180
229
  using the normal `#{}` string interpolation syntax.
181
230
 
182
- In the code below we're going to switch to `shell-mode` and edit the
183
- `.pryrc` file in the home directory. We'll then cat its contents and
184
- reload the file.
185
-
186
- pry(main)> shell-mode
187
- pry main:/home/john/ruby/projects/pry $ .cd ~
188
- pry main:/home/john $ .emacsclient .pryrc
189
- pry main:/home/john $ .cat .pryrc
190
- def hello_world
191
- puts "hello world!"
192
- end
193
- pry main:/home/john $ load ".pryrc"
194
- => true
195
- pry main:/home/john $ hello_world
196
- hello world!
197
-
198
- We can also interpolate Ruby code into the shell. In the
199
- example below we use the shell command `cat` on a random file from the
200
- current directory and count the number of lines in that file with
201
- `wc`:
202
-
203
- pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l
204
- 44
231
+ In the code below we're going to switch to `shell-mode` and edit the `pryrc`
232
+ file. We'll then cat its contents and reload the file.
233
+
234
+ ```ruby
235
+ pry(main)> shell-mode
236
+ pry main:/home/john/ruby/projects/pry $ .cd ~
237
+ pry main:/home/john $ .emacsclient .pryrc
238
+ pry main:/home/john $ .cat .pryrc
239
+ def hello_world
240
+ puts "hello world!"
241
+ end
242
+ pry main:/home/john $ load ".pryrc"
243
+ => true
244
+ pry main:/home/john $ hello_world
245
+ hello world!
246
+ ```
247
+
248
+ We can also interpolate Ruby code into the shell. In the example below we use
249
+ the shell command `cat` on a random file from the current directory and count
250
+ the number of lines in that file with `wc`:
251
+
252
+ ```ruby
253
+ pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l
254
+ 44
255
+ ```
205
256
 
206
257
  ### Code Browsing
207
258
 
208
- You can browse method source code with the `show-method` command. Nearly all Ruby methods (and some C methods, with the pry-doc
209
- gem) can have their source viewed. Code that is longer than a page is
210
- sent through a pager (such as less), and all code is properly syntax
211
- highlighted (even C code).
259
+ You can browse method source code with the `show-source` command. Nearly all
260
+ Ruby methods (and some C methods, with the pry-doc gem) can have their source
261
+ viewed. Code that is longer than a page is sent through a pager (such as less),
262
+ and all code is properly syntax highlighted (even C code).
212
263
 
213
- The `show-method` command accepts two syntaxes, the typical ri
214
- `Class#method` syntax and also simply the name of a method that's in
215
- scope. You can optionally pass the `-l` option to show-method to
216
- include line numbers in the output.
264
+ The `show-source` command accepts two syntaxes, the typical ri `Class#method`
265
+ syntax and also simply the name of a method that's in scope. You can optionally
266
+ pass the `-l` option to `show-source` to include line numbers in the output.
217
267
 
218
- In the following example we will enter the `Pry` class, list the
219
- instance methods beginning with 're' and display the source code for the `rep` method:
268
+ In the following example we will enter the `Pry` class, list the instance
269
+ methods beginning with 're' and display the source code for the `rep` method:
220
270
 
221
- pry(main)> cd Pry
222
- pry(Pry):1> ls -M --grep re
223
- Pry#methods: re readline refresh rep repl repl_epilogue repl_prologue retrieve_line
224
- pry(Pry):1> show-method rep -l
271
+ ```ruby
272
+ pry(main)> cd Pry
273
+ pry(Pry):1> ls -M --grep re
274
+ Pry#methods: re readline refresh rep repl repl_epilogue repl_prologue retrieve_line
275
+ pry(Pry):1> show-source rep -l
225
276
 
226
- From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb @ line 143:
227
- Number of lines: 6
277
+ From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb:143
278
+ Number of lines: 6
228
279
 
229
- 143: def rep(target=TOPLEVEL_BINDING)
230
- 144: target = Pry.binding_for(target)
231
- 145: result = re(target)
232
- 146:
233
- 147: show_result(result) if should_print?
234
- 148: end
280
+ 143: def rep(target=TOPLEVEL_BINDING)
281
+ 144: target = Pry.binding_for(target)
282
+ 145: result = re(target)
283
+ 146:
284
+ 147: show_result(result) if should_print?
285
+ 148: end
286
+ ```
235
287
 
236
288
  Note that we can also view C methods (from Ruby Core) using the
237
289
  `pry-doc` plugin; we also show off the alternate syntax for
238
- `show-method`:
290
+ `show-source`:
239
291
 
240
- pry(main)> show-method Array#select
292
+ ```ruby
293
+ pry(main)> show-source Array#select
241
294
 
242
- From: array.c in Ruby Core (C Method):
243
- Number of lines: 15
295
+ From: array.c in Ruby Core (C Method):
296
+ Number of lines: 15
244
297
 
245
- static VALUE
246
- rb_ary_select(VALUE ary)
247
- {
248
- VALUE result;
249
- long i;
298
+ static VALUE
299
+ rb_ary_select(VALUE ary)
300
+ {
301
+ VALUE result;
302
+ long i;
250
303
 
251
- RETURN_ENUMERATOR(ary, 0, 0);
252
- result = rb_ary_new2(RARRAY_LEN(ary));
253
- for (i = 0; i < RARRAY_LEN(ary); i++) {
254
- if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
255
- rb_ary_push(result, rb_ary_elt(ary, i));
256
- }
304
+ RETURN_ENUMERATOR(ary, 0, 0);
305
+ result = rb_ary_new2(RARRAY_LEN(ary));
306
+ for (i = 0; i < RARRAY_LEN(ary); i++) {
307
+ if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
308
+ rb_ary_push(result, rb_ary_elt(ary, i));
257
309
  }
258
- return result;
259
310
  }
311
+ return result;
312
+ }
313
+ ```
260
314
 
261
315
  ### Documentation Browsing
262
316
 
263
- One use-case for Pry is to explore a program at run-time by `cd`-ing
264
- in and out of objects and viewing and invoking methods. In the course
265
- of exploring it may be useful to read the documentation for a
266
- specific method that you come across. Like `show-method` the `show-doc` command supports
267
- two syntaxes - the normal `ri` syntax as well as accepting the name of
268
- any method that is currently in scope.
269
-
270
- The Pry documentation system does not rely on pre-generated `rdoc` or
271
- `ri`, instead it grabs the comments directly above the method on
272
- demand. This results in speedier documentation retrieval and allows
273
- the Pry system to retrieve documentation for methods that would not be
274
- picked up by `rdoc`. Pry also has a basic understanding of both the
275
- rdoc and yard formats and will attempt to syntax highlight the
276
- documentation appropriately.
277
-
278
- Nonetheless, the `ri` functionality is very good and
279
- has an advantage over Pry's system in that it allows documentation
280
- lookup for classes as well as methods. Pry therefore has good
281
- integration with `ri` through the `ri` command. The syntax
282
- for the command is exactly as it would be in command-line -
317
+ One use-case for Pry is to explore a program at run-time by `cd`-ing in and out
318
+ of objects and viewing and invoking methods. In the course of exploring it may
319
+ be useful to read the documentation for a specific method that you come
320
+ across. Like `show-source` the `show-doc` command supports two syntaxes - the
321
+ normal `ri` syntax as well as accepting the name of any method that is currently
322
+ in scope.
323
+
324
+ The Pry documentation system does not rely on pre-generated `rdoc` or `ri`,
325
+ instead it grabs the comments directly above the method on demand. This results
326
+ in speedier documentation retrieval and allows the Pry system to retrieve
327
+ documentation for methods that would not be picked up by `rdoc`. Pry also has a
328
+ basic understanding of both the rdoc and yard formats and will attempt to syntax
329
+ highlight the documentation appropriately.
330
+
331
+ Nonetheless, the `ri` functionality is very good and has an advantage over Pry's
332
+ system in that it allows documentation lookup for classes as well as
333
+ methods. Pry therefore has good integration with `ri` through the `ri`
334
+ command. The syntax for the command is exactly as it would be in command-line -
283
335
  so it is not necessary to quote strings.
284
336
 
285
- In our example we will enter the `Gem` class and view the
286
- documentation for the `try_activate` method:
337
+ In our example we will enter the `Gem` class and view the documentation for the
338
+ `try_activate` method:
287
339
 
288
- pry(main)> cd Gem
289
- pry(Gem):1> show-doc try_activate
340
+ ```ruby
341
+ pry(main)> cd Gem
342
+ pry(Gem):1> show-doc try_activate
290
343
 
291
- From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/site_ruby/1.9.1/rubygems.rb @ line 201:
292
- Number of lines: 3
344
+ From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/site_ruby/1.9.1/rubygems.rb:201
345
+ Number of lines: 3
293
346
 
294
- Try to activate a gem containing path. Returns true if
295
- activation succeeded or wasn't needed because it was already
296
- activated. Returns false if it can't find the path in a gem.
297
- pry(Gem):1>
347
+ Try to activate a gem containing path. Returns true if
348
+ activation succeeded or wasn't needed because it was already
349
+ activated. Returns false if it can't find the path in a gem.
350
+ pry(Gem):1>
351
+ ```
298
352
 
299
353
  We can also use `ri` in the normal way:
300
354
 
301
- pry(main) ri Array#each
302
- ----------------------------------------------------------- Array#each
303
- array.each {|item| block } -> array
304
- ------------------------------------------------------------------------
305
- Calls _block_ once for each element in _self_, passing that element
306
- as a parameter.
307
-
308
- a = [ "a", "b", "c" ]
309
- a.each {|x| print x, " -- " }
355
+ ```ruby
356
+ pry(main) ri Array#each
357
+ ----------------------------------------------------------- Array#each
358
+ array.each {|item| block } -> array
359
+ ------------------------------------------------------------------------
360
+ Calls _block_ once for each element in _self_, passing that element
361
+ as a parameter.
310
362
 
311
- produces:
363
+ a = [ "a", "b", "c" ]
364
+ a.each {|x| print x, " -- " }
312
365
 
313
- a -- b -- c --
366
+ produces:
314
367
 
315
- ### Gist integration
316
-
317
- If the `gist` gem is installed then method source or documentation can be gisted to github with the
318
- `gist` command. The `gist` command is capable of gisting [almost any REPL content](https://gist.github.com/cae143e4533416529726), including methods, documentation,
319
- input expressions, command source, and so on. In the example below we will gist the C source
320
- code for the `Symbol#to_proc` method to github:
321
-
322
- pry(main)> gist -m Symbol#to_proc
323
- Gist created at https://gist.github.com/5332c38afc46d902ce46 and added to clipboard.
324
- pry(main)>
325
-
326
- You can see the actual gist generated here: [https://gist.github.com/5332c38afc46d902ce46](https://gist.github.com/5332c38afc46d902ce46)
368
+ a -- b -- c --
369
+ ```
327
370
 
328
371
  ### Edit methods
329
372
 
330
- You can use `edit Class#method` or `edit my_method`
331
- (if the method is in scope) to open a method for editing directly in
332
- your favorite editor. Pry has knowledge of a few different editors and
333
- will attempt to open the file at the line the method is defined.
373
+ You can use `edit Class#method` or `edit my_method` (if the method is in scope)
374
+ to open a method for editing directly in your favorite editor. Pry has knowledge
375
+ of a few different editors and will attempt to open the file at the line the
376
+ method is defined.
334
377
 
335
378
  You can set the editor to use by assigning to the `Pry.editor`
336
- accessor. `Pry.editor` will default to `$EDITOR` or failing that will
337
- use `nano` as the backup default. The file that is edited will be
338
- automatically reloaded after exiting the editor - reloading can be
339
- suppressed by passing the `--no-reload` option to `edit`
379
+ accessor. `Pry.editor` will default to `$EDITOR` or failing that will use `nano`
380
+ as the backup default. The file that is edited will be automatically reloaded
381
+ after exiting the editor - reloading can be suppressed by passing the
382
+ `--no-reload` option to `edit`
340
383
 
341
- In the example below we will set our default editor to "emacsclient"
342
- and open the `Pry#repl` method for editing:
384
+ In the example below we will set our default editor to "emacsclient" and open
385
+ the `Pry#repl` method for editing:
343
386
 
344
- pry(main)> Pry.editor = "emacsclient"
345
- pry(main)> edit Pry#repl
387
+ ```ruby
388
+ pry(main)> Pry.editor = "emacsclient"
389
+ pry(main)> edit Pry#repl
390
+ ```
346
391
 
347
392
  ### Live Help System
348
393
 
349
- Many other commands are available in Pry; to see the full list type
350
- `help` at the prompt. A short description of each command is provided
351
- with basic instructions for use; some commands have a more extensive
352
- help that can be accessed via typing `command_name --help`. A command
353
- will typically say in its description if the `--help` option is
354
- avaiable.
394
+ Many other commands are available in Pry; to see the full list type `help` at
395
+ the prompt. A short description of each command is provided with basic
396
+ instructions for use; some commands have a more extensive help that can be
397
+ accessed via typing `command_name --help`. A command will typically say in its
398
+ description if the `--help` option is available.
355
399
 
356
400
  ### Use Pry as your Rails Console
357
401
 
358
- The recommended way to use Pry as your Rails console is to add
359
- [the `pry-rails` gem](https://github.com/rweng/pry-rails) to
360
- your Gemfile. This replaces the default console with Pry, in
361
- addition to loading the Rails console helpers and adding some
362
- useful Rails-specific commands.
402
+ The recommended way to use Pry as your Rails console is to add [the `pry-rails`
403
+ gem](https://github.com/rweng/pry-rails) to your Gemfile. This replaces the
404
+ default console with Pry, in addition to loading the Rails console helpers and
405
+ adding some useful Rails-specific commands.
363
406
 
364
- If you don't want to change your Gemfile, you can still run a Pry
365
- console in your app's environment using Pry's `-r` flag:
407
+ If you don't want to change your Gemfile, you can still run a Pry console in
408
+ your app's environment using Pry's `-r` flag:
366
409
 
367
- pry -r ./config/environment
410
+ ```sh
411
+ pry -r ./config/environment
412
+ ```
368
413
 
369
- Also check out the [wiki](https://github.com/pry/pry/wiki/Setting-up-Rails-or-Heroku-to-use-Pry)
414
+ Also check out the
415
+ [wiki](https://github.com/pry/pry/wiki/Setting-up-Rails-or-Heroku-to-use-Pry)
370
416
  for more information about integrating Pry with Rails.
371
417
 
372
- ### Limitations:
418
+ ### Syntax Highlighting
373
419
 
374
- * Tab completion is currently a bit broken/limited this will have a
375
- major overhaul in a future version.
420
+ Syntax highlighting is on by default in Pry. If you want to change the colors,
421
+ check out the [pry-theme](https://github.com/kyrylo/pry-theme) gem.
376
422
 
377
- ### Syntax Highlighting
423
+ You can toggle the syntax highlighting on and off in a session by using the
424
+ `toggle-color` command. Alternatively, you can turn it off permanently by
425
+ putting the line `Pry.color = false` in your `pryrc` file.
378
426
 
379
- Syntax highlighting is on by default in Pry. If you want to change
380
- the colors, check out the [pry-theme](https://github.com/kyrylo/pry-theme)
381
- gem.
427
+ Supported Rubies
428
+ ----------------
382
429
 
383
- You can toggle the syntax highlighting on and off in a session by
384
- using the `toggle-color` command. Alternatively, you can turn it off
385
- permanently by putting the line `Pry.color = false` in your `~/.pryrc`
386
- file.
430
+ * CRuby >= 1.9.3
431
+ * JRuby >= 1.7
387
432
 
388
- ### Future Directions
433
+ Contact
434
+ -------
389
435
 
390
- Many new features are planned such as:
436
+ In case you have a problem, question or a bug report, feel free to:
391
437
 
392
- * Increase modularity (rely more on plugin system)
393
- * Much improved documentation system, better support for YARD
394
- * Better support for code and method reloading and saving code
395
- * Extended and more sophisticated command system, allowing piping
396
- between commands and running commands in background
438
+ * ask a question on IRC (#pry on Freenode)
439
+ * [file an issue](https://github.com/pry/pry/issues)
440
+ * [tweet at us](https://twitter.com/pryruby)
397
441
 
398
- ### Contact
442
+ License
443
+ -------
399
444
 
400
- Problems or questions? file an issue at [github](https://github.com/pry/pry/issues)
445
+ The project uses the MIT License. See LICENSE.md for details.
401
446
 
402
- ### Contributors
447
+ Contributors
448
+ ------------
403
449
 
404
- Pry is primarily the work of [John Mair (banisterfiend)](http://github.com/banister), for full list
450
+ Pry is primarily the work of [John Mair (banisterfiend)](https://github.com/banister), for full list
405
451
  of contributors see the
406
- [CONTRIBUTORS](https://github.com/pry/pry/blob/master/CONTRIBUTORS) file.
452
+ [contributors graph](https://github.com/pry/pry/graphs/contributors).