diff options
-rw-r--r-- | README.md | 545 |
1 files changed, 290 insertions, 255 deletions
@@ -16,8 +16,12 @@ Pry Introduction ------------ -Pry is a powerful runtime developer console and IRB alternative for Ruby. It -provides a number of advanced features, including: +Pry is a runtime developer console and IRB alternative with powerful +introspection capabilities. Pry aims to be more than an IRB replacement. It is +an attempt to bring REPL driven programming to the Ruby language. + +Key features +------------ * Source code browsing (including core C source with the pry-doc gem) * Documentation browsing @@ -29,103 +33,117 @@ provides a number of advanced features, including: * Navigation around state (`cd`, `ls` and friends) * Runtime invocation (use Pry as a developer console or debugger) * Exotic object support (BasicObject instances, IClasses, ...) -* A Powerful and flexible command system +* A powerful and flexible command system * Ability to view and replay history -* Many convenience commands inspired by IPython, Smalltalk and other advanced REPLs -* A wide-range number of [plugins](https://github.com/pry/pry/wiki/Available-plugins) that provide remote sessions, full debugging functionality, and more. +* Many convenience commands inspired by IPython, Smalltalk and other advanced + REPLs +* A wide-range number of + [plugins](https://github.com/pry/pry/wiki/Available-plugins) that provide + remote sessions, full debugging functionality, and more. + +Installation +------------ + +### Bundler + +```ruby +gem 'pry', '~> 0.12.2' +``` + +### Manual + +```sh +gem install pry +``` -Pry also aims to be more than an IRB replacement; it is an -attempt to bring REPL driven programming to the Ruby language. It is -currently not as powerful as tools like [SLIME](https://en.wikipedia.org/wiki/SLIME) for lisp, but that is the -general direction Pry is heading. +Overview +-------- -Pry is also fairly flexible and allows significant user +Pry is fairly flexible and allows significant user [customization](https://github.com/pry/pry/wiki/Customization-and-configuration) -is trivial to set it to read from any object that has a `readline` method and write to any object that has a -`puts` method - many other aspects of Pry are also configurable making -it a good choice for implementing custom shells. +is trivial to set it to read from any object that has a `readline` method and +write to any object that has a `puts` method - many other aspects of Pry are +also configurable making it a good choice for implementing custom shells. -Pry comes with an executable so it can be invoked at the command line. Just +Pry comes with an executable so it can be invoked at the command line. Just enter `pry` to start. A `pryrc` file in `$XDG_CONFIG_HOME/pry/` or the user's home directory will be loaded if it exists. Type `pry --help` at the command line for more information. -Try `gem install pry-doc` for additional documentation on Ruby Core -methods. The additional docs are accessed through the `show-doc` and -`show-method` commands. - -* Install the [gem](https://rubygems.org/gems/pry): `gem install pry` -* Browse the comprehensive [documentation at the official Pry wiki](https://github.com/pry/pry/wiki) -* Read the [YARD API documentation](http://www.rubydoc.info/github/pry/pry/) -* See the [source code](https://github.com/pry/pry) - ### Commands -Nearly every piece of functionality in a Pry session is implemented as -a command. Commands are not methods and must start at the beginning of a line, with no -whitespace in between. Commands support a flexible syntax and allow -'options' in the same way as shell commands, for example the following -Pry command will show a list of all private instance methods (in -scope) that begin with 'pa' +Nearly every piece of functionality in a Pry session is implemented as a +command. Commands are not methods and must start at the beginning of a line, +with no whitespace in between. Commands support a flexible syntax and allow +'options' in the same way as shell commands, for example the following Pry +command will show a list of all private instance methods (in scope) that begin +with 'pa' - pry(YARD::Parser::SourceParser):5> ls -Mp --grep ^pa - YARD::Parser::SourceParser#methods: parse parser_class parser_type parser_type= parser_type_for_filename +```ruby +pry(YARD::Parser::SourceParser):5> ls -Mp --grep ^pa +YARD::Parser::SourceParser#methods: parse parser_class parser_type parser_type= parser_type_for_filename +``` ### Navigating around state -Pry allows us to pop in and out of different scopes (objects) using -the `cd` command. This enables us to explore the run-time view of a -program or library. To view which variables and methods are available -within a particular scope we use the versatile [ls command.](https://gist.github.com/c0fc686ef923c8b87715) - -Here we will begin Pry at top-level, then Pry on a class and then on -an instance variable inside that class: - - pry(main)> class Hello - pry(main)* @x = 20 - pry(main)* end - => 20 - pry(main)> cd Hello - pry(Hello):1> ls -i - instance variables: @x - pry(Hello):1> cd @x - pry(20):2> self + 10 - => 30 - pry(20):2> cd .. - pry(Hello):1> cd .. - pry(main)> cd .. - -The number after the `:` in the pry prompt indicates the nesting -level. To display more information about nesting, use the `nesting` -command. E.g - - pry("friend"):3> nesting - Nesting status: - 0. main (Pry top level) - 1. Hello - 2. 100 - 3. "friend" - => nil - -We can then jump back to any of the previous nesting levels by using -the `jump-to` command: - - pry("friend"):3> jump-to 1 - => 100 - pry(Hello):1> +Pry allows us to pop in and out of different scopes (objects) using the `cd` +command. This enables us to explore the run-time view of a program or +library. To view which variables and methods are available within a particular +scope we use the versatile [ls +command.](https://gist.github.com/c0fc686ef923c8b87715) + +Here we will begin Pry at top-level, then Pry on a class and then on an instance +variable inside that class: + +```ruby +pry(main)> class Hello +pry(main)* @x = 20 +pry(main)* end +=> 20 +pry(main)> cd Hello +pry(Hello):1> ls -i +instance variables: @x +pry(Hello):1> cd @x +pry(20):2> self + 10 +=> 30 +pry(20):2> cd .. +pry(Hello):1> cd .. +pry(main)> cd .. +``` + +The number after the `:` in the pry prompt indicates the nesting level. To +display more information about nesting, use the `nesting` command. E.g + +```ruby +pry("friend"):3> nesting +Nesting status: +0. main (Pry top level) +1. Hello +2. 100 +3. "friend" +=> nil +``` + +We can then jump back to any of the previous nesting levels by using the +`jump-to` command: + +```ruby +pry("friend"):3> jump-to 1 +=> 100 +pry(Hello):1> +``` ### Runtime invocation -Pry can be invoked in the middle of a running program. It opens a Pry -session at the point it's called and makes all program state at that -point available. It can be invoked on any object using the -`my_object.pry` syntax or on the current binding (or any binding) -using `binding.pry`. The Pry session will then begin within the scope -of the object (or binding). When the session ends the program continues with any -modifications you made to it. +Pry can be invoked in the middle of a running program. It opens a Pry session at +the point it's called and makes all program state at that point available. It +can be invoked on any object using the `my_object.pry` syntax or on the current +binding (or any binding) using `binding.pry`. The Pry session will then begin +within the scope of the object (or binding). When the session ends the program +continues with any modifications you made to it. -This functionality can be used for such things as: debugging, -implementing developer consoles and applying hot patches. +This functionality can be used for such things as: debugging, implementing +developer consoles and applying hot patches. code: @@ -148,246 +166,263 @@ puts "program resumes here." Pry session: - pry(main)> a.hello - hello world! - => nil - pry(main)> def a.goodbye - pry(main)* puts "goodbye cruel world!" - pry(main)* end - => nil - pry(main)> a.goodbye - goodbye cruel world! - => nil - pry(main)> exit - - program resumes here. +```ruby +pry(main)> a.hello +hello world! +=> nil +pry(main)> def a.goodbye +pry(main)* puts "goodbye cruel world!" +pry(main)* end +=> nil +pry(main)> a.goodbye +goodbye cruel world! +=> nil +pry(main)> exit + +program resumes here. +``` ### Command Shell Integration -A line of input that begins with a '.' will be forwarded to the -command shell. This enables us to navigate the file system, spawn -editors, and run git and rake directly from within Pry. +A line of input that begins with a '.' will be forwarded to the command +shell. This enables us to navigate the file system, spawn editors, and run git +and rake directly from within Pry. -Further, we can use the `shell-mode` command to incorporate the -present working directory into the Pry prompt and bring in (limited at this stage, sorry) file name completion. -We can also interpolate Ruby code directly into the shell by +Further, we can use the `shell-mode` command to incorporate the present working +directory into the Pry prompt and bring in (limited at this stage, sorry) file +name completion. We can also interpolate Ruby code directly into the shell by using the normal `#{}` string interpolation syntax. In the code below we're going to switch to `shell-mode` and edit the `pryrc` file. We'll then cat its contents and reload the file. - pry(main)> shell-mode - pry main:/home/john/ruby/projects/pry $ .cd ~ - pry main:/home/john $ .emacsclient .pryrc - pry main:/home/john $ .cat .pryrc - def hello_world - puts "hello world!" - end - pry main:/home/john $ load ".pryrc" - => true - pry main:/home/john $ hello_world - hello world! - -We can also interpolate Ruby code into the shell. In the -example below we use the shell command `cat` on a random file from the -current directory and count the number of lines in that file with -`wc`: - - pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l - 44 +```ruby +pry(main)> shell-mode +pry main:/home/john/ruby/projects/pry $ .cd ~ +pry main:/home/john $ .emacsclient .pryrc +pry main:/home/john $ .cat .pryrc +def hello_world + puts "hello world!" +end +pry main:/home/john $ load ".pryrc" +=> true +pry main:/home/john $ hello_world +hello world! +``` -### Code Browsing +We can also interpolate Ruby code into the shell. In the example below we use +the shell command `cat` on a random file from the current directory and count +the number of lines in that file with `wc`: -You can browse method source code with the `show-method` command. Nearly all Ruby methods (and some C methods, with the pry-doc -gem) can have their source viewed. Code that is longer than a page is -sent through a pager (such as less), and all code is properly syntax -highlighted (even C code). +```ruby +pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l +44 +``` -The `show-method` command accepts two syntaxes, the typical ri -`Class#method` syntax and also simply the name of a method that's in -scope. You can optionally pass the `-l` option to show-method to -include line numbers in the output. +### Code Browsing -In the following example we will enter the `Pry` class, list the -instance methods beginning with 're' and display the source code for the `rep` method: +You can browse method source code with the `show-source` command. Nearly all +Ruby methods (and some C methods, with the pry-doc gem) can have their source +viewed. Code that is longer than a page is sent through a pager (such as less), +and all code is properly syntax highlighted (even C code). - pry(main)> cd Pry - pry(Pry):1> ls -M --grep re - Pry#methods: re readline refresh rep repl repl_epilogue repl_prologue retrieve_line - pry(Pry):1> show-method rep -l +The `show-source` command accepts two syntaxes, the typical ri `Class#method` +syntax and also simply the name of a method that's in scope. You can optionally +pass the `-l` option to `show-source` to include line numbers in the output. - From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb:143 - Number of lines: 6 +In the following example we will enter the `Pry` class, list the instance +methods beginning with 're' and display the source code for the `rep` method: - 143: def rep(target=TOPLEVEL_BINDING) - 144: target = Pry.binding_for(target) - 145: result = re(target) - 146: - 147: show_result(result) if should_print? - 148: end +```ruby +pry(main)> cd Pry +pry(Pry):1> ls -M --grep re +Pry#methods: re readline refresh rep repl repl_epilogue repl_prologue retrieve_line +pry(Pry):1> show-source rep -l + +From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb:143 +Number of lines: 6 + +143: def rep(target=TOPLEVEL_BINDING) +144: target = Pry.binding_for(target) +145: result = re(target) +146: +147: show_result(result) if should_print? +148: end +``` Note that we can also view C methods (from Ruby Core) using the `pry-doc` plugin; we also show off the alternate syntax for -`show-method`: - - pry(main)> show-method Array#select - - From: array.c in Ruby Core (C Method): - Number of lines: 15 - - static VALUE - rb_ary_select(VALUE ary) - { - VALUE result; - long i; +`show-source`: - RETURN_ENUMERATOR(ary, 0, 0); - result = rb_ary_new2(RARRAY_LEN(ary)); - for (i = 0; i < RARRAY_LEN(ary); i++) { - if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) { - rb_ary_push(result, rb_ary_elt(ary, i)); - } +```ruby +pry(main)> show-source Array#select + +From: array.c in Ruby Core (C Method): +Number of lines: 15 + +static VALUE +rb_ary_select(VALUE ary) +{ + VALUE result; + long i; + + RETURN_ENUMERATOR(ary, 0, 0); + result = rb_ary_new2(RARRAY_LEN(ary)); + for (i = 0; i < RARRAY_LEN(ary); i++) { + if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) { + rb_ary_push(result, rb_ary_elt(ary, i)); } - return result; } + return result; +} +``` ### Documentation Browsing -One use-case for Pry is to explore a program at run-time by `cd`-ing -in and out of objects and viewing and invoking methods. In the course -of exploring it may be useful to read the documentation for a -specific method that you come across. Like `show-method` the `show-doc` command supports -two syntaxes - the normal `ri` syntax as well as accepting the name of -any method that is currently in scope. - -The Pry documentation system does not rely on pre-generated `rdoc` or -`ri`, instead it grabs the comments directly above the method on -demand. This results in speedier documentation retrieval and allows -the Pry system to retrieve documentation for methods that would not be -picked up by `rdoc`. Pry also has a basic understanding of both the -rdoc and yard formats and will attempt to syntax highlight the -documentation appropriately. - -Nonetheless, the `ri` functionality is very good and -has an advantage over Pry's system in that it allows documentation -lookup for classes as well as methods. Pry therefore has good -integration with `ri` through the `ri` command. The syntax -for the command is exactly as it would be in command-line - +One use-case for Pry is to explore a program at run-time by `cd`-ing in and out +of objects and viewing and invoking methods. In the course of exploring it may +be useful to read the documentation for a specific method that you come +across. Like `show-source` the `show-doc` command supports two syntaxes - the +normal `ri` syntax as well as accepting the name of any method that is currently +in scope. + +The Pry documentation system does not rely on pre-generated `rdoc` or `ri`, +instead it grabs the comments directly above the method on demand. This results +in speedier documentation retrieval and allows the Pry system to retrieve +documentation for methods that would not be picked up by `rdoc`. Pry also has a +basic understanding of both the rdoc and yard formats and will attempt to syntax +highlight the documentation appropriately. + +Nonetheless, the `ri` functionality is very good and has an advantage over Pry's +system in that it allows documentation lookup for classes as well as +methods. Pry therefore has good integration with `ri` through the `ri` +command. The syntax for the command is exactly as it would be in command-line - so it is not necessary to quote strings. -In our example we will enter the `Gem` class and view the -documentation for the `try_activate` method: +In our example we will enter the `Gem` class and view the documentation for the +`try_activate` method: - pry(main)> cd Gem - pry(Gem):1> show-doc try_activate +```ruby +pry(main)> cd Gem +pry(Gem):1> show-doc try_activate - From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/site_ruby/1.9.1/rubygems.rb:201 - Number of lines: 3 +From: /Users/john/.rvm/rubies/ruby-1.9.2-p180/lib/ruby/site_ruby/1.9.1/rubygems.rb:201 +Number of lines: 3 - Try to activate a gem containing path. Returns true if - activation succeeded or wasn't needed because it was already - activated. Returns false if it can't find the path in a gem. - pry(Gem):1> +Try to activate a gem containing path. Returns true if +activation succeeded or wasn't needed because it was already +activated. Returns false if it can't find the path in a gem. +pry(Gem):1> +``` We can also use `ri` in the normal way: - pry(main) ri Array#each - ----------------------------------------------------------- Array#each - array.each {|item| block } -> array - ------------------------------------------------------------------------ - Calls _block_ once for each element in _self_, passing that element - as a parameter. +```ruby +pry(main) ri Array#each +----------------------------------------------------------- Array#each + array.each {|item| block } -> array +------------------------------------------------------------------------ + Calls _block_ once for each element in _self_, passing that element + as a parameter. - a = [ "a", "b", "c" ] - a.each {|x| print x, " -- " } + a = [ "a", "b", "c" ] + a.each {|x| print x, " -- " } - produces: + produces: - a -- b -- c -- + a -- b -- c -- +``` ### Gist integration -If the `gist` gem is installed then method source or documentation can be gisted to GitHub with the -`gist` command. The `gist` command is capable of gisting [almost any REPL content](https://gist.github.com/cae143e4533416529726), including methods, documentation, -input expressions, command source, and so on. In the example below we will gist the C source -code for the `Symbol#to_proc` method to GitHub: +If the `gist` gem is installed then method source or documentation can be gisted +to GitHub with the `gist` command. The `gist` command is capable of gisting +[almost any REPL content](https://gist.github.com/cae143e4533416529726), +including methods, documentation, input expressions, command source, and so +on. In the example below we will gist the C source code for the `Symbol#to_proc` +method to GitHub: - pry(main)> gist -m Symbol#to_proc - Gist created at https://gist.github.com/5332c38afc46d902ce46 and added to clipboard. - pry(main)> +```ruby +pry(main)> gist -m Symbol#to_proc +Gist created at https://gist.github.com/5332c38afc46d902ce46 and added to clipboard. +pry(main)> +``` -You can see the actual gist generated here: [https://gist.github.com/5332c38afc46d902ce46](https://gist.github.com/5332c38afc46d902ce46) +You can see the actual gist generated here: +[https://gist.github.com/5332c38afc46d902ce46](https://gist.github.com/5332c38afc46d902ce46) ### Edit methods -You can use `edit Class#method` or `edit my_method` -(if the method is in scope) to open a method for editing directly in -your favorite editor. Pry has knowledge of a few different editors and -will attempt to open the file at the line the method is defined. +You can use `edit Class#method` or `edit my_method` (if the method is in scope) +to open a method for editing directly in your favorite editor. Pry has knowledge +of a few different editors and will attempt to open the file at the line the +method is defined. You can set the editor to use by assigning to the `Pry.editor` -accessor. `Pry.editor` will default to `$EDITOR` or failing that will -use `nano` as the backup default. The file that is edited will be -automatically reloaded after exiting the editor - reloading can be -suppressed by passing the `--no-reload` option to `edit` +accessor. `Pry.editor` will default to `$EDITOR` or failing that will use `nano` +as the backup default. The file that is edited will be automatically reloaded +after exiting the editor - reloading can be suppressed by passing the +`--no-reload` option to `edit` -In the example below we will set our default editor to "emacsclient" -and open the `Pry#repl` method for editing: +In the example below we will set our default editor to "emacsclient" and open +the `Pry#repl` method for editing: - pry(main)> Pry.editor = "emacsclient" - pry(main)> edit Pry#repl +```ruby +pry(main)> Pry.editor = "emacsclient" +pry(main)> edit Pry#repl +``` ### Live Help System -Many other commands are available in Pry; to see the full list type -`help` at the prompt. A short description of each command is provided -with basic instructions for use; some commands have a more extensive -help that can be accessed via typing `command_name --help`. A command -will typically say in its description if the `--help` option is -available. +Many other commands are available in Pry; to see the full list type `help` at +the prompt. A short description of each command is provided with basic +instructions for use; some commands have a more extensive help that can be +accessed via typing `command_name --help`. A command will typically say in its +description if the `--help` option is available. ### Use Pry as your Rails Console -The recommended way to use Pry as your Rails console is to add -[the `pry-rails` gem](https://github.com/rweng/pry-rails) to -your Gemfile. This replaces the default console with Pry, in -addition to loading the Rails console helpers and adding some -useful Rails-specific commands. +The recommended way to use Pry as your Rails console is to add [the `pry-rails` +gem](https://github.com/rweng/pry-rails) to your Gemfile. This replaces the +default console with Pry, in addition to loading the Rails console helpers and +adding some useful Rails-specific commands. -If you don't want to change your Gemfile, you can still run a Pry -console in your app's environment using Pry's `-r` flag: +If you don't want to change your Gemfile, you can still run a Pry console in +your app's environment using Pry's `-r` flag: - pry -r ./config/environment +```sh +pry -r ./config/environment +``` -Also check out the [wiki](https://github.com/pry/pry/wiki/Setting-up-Rails-or-Heroku-to-use-Pry) +Also check out the +[wiki](https://github.com/pry/pry/wiki/Setting-up-Rails-or-Heroku-to-use-Pry) for more information about integrating Pry with Rails. -### Limitations: +### Syntax Highlighting -* Tab completion is currently a bit broken/limited this will have a - major overhaul in a future version. +Syntax highlighting is on by default in Pry. If you want to change the colors, +check out the [pry-theme](https://github.com/kyrylo/pry-theme) gem. -### Syntax Highlighting +You can toggle the syntax highlighting on and off in a session by using the +`toggle-color` command. Alternatively, you can turn it off permanently by +putting the line `Pry.color = false` in your `pryrc` file. -Syntax highlighting is on by default in Pry. If you want to change -the colors, check out the [pry-theme](https://github.com/kyrylo/pry-theme) -gem. +Supported Rubies +---------------- -You can toggle the syntax highlighting on and off in a session by -using the `toggle-color` command. Alternatively, you can turn it off -permanently by putting the line `Pry.color = false` in your `pryrc` -file. +* CRuby >= 1.9.3 +* JRuby >= 1.7 -### Future Directions +Contact +------- -Many new features are planned such as: +In case you have a problem, question or a bug report, feel free to: -* Increase modularity (rely more on plugin system) -* Much improved documentation system, better support for YARD -* Better support for code and method reloading and saving code -* Extended and more sophisticated command system, allowing piping -between commands and running commands in background +* ask a question on IRC (#pry on Freenode) +* [file an issue](https://github.com/pry/pry/issues) +* [tweet at us](https://twitter.com/pryruby) -### Contact +License +------- -Problems or questions? File an issue at [GitHub](https://github.com/pry/pry/issues). +The project uses the MIT License. See LICENSE.md for details. |