pry 0.8.0pre9 → 0.8.0

data/README.markdown

@@ -1,34 +1,25 @@
-Pry
-=============
+![Alt text](http://dl.dropbox.com/u/26521875/pry_logo_shade.png)
 
 (C) John Mair (banisterfiend) 2011
 
-_Ruby voyeurism_
+_Get to the code_
 
 Pry is a powerful alternative to the standard IRB shell for Ruby. It is
 written from scratch to provide a number of advanced features, some of
 these include:
 
-* Runtime invocation
-* Syntax highlighting
-* Command shell integration
 * Source code browsing (including core C source with the pry-doc gem)
-* Documentation browsing 
+* Documentation browsing
+* Live help system
+* Syntax highlighting
+* Command shell integration (start editors, run git, and rake from within Pry)
+* Gist integration
+* 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
-* Gisting ability
-* Many convenience commands
-
-Pry is a Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
-manipulation of objects during the running of a program.
-
-In some sense it is the opposite of IRB in that you bring a REPL
-session to your code (with Pry) instead of bringing your code to a
-REPL session (as with IRB).
-
-It is not based on the IRB codebase, and implements some unique REPL
-commands such as `show-method`, `show-doc`, `ls` and `cd` (type `help`
-to get a full list).
+* Ability to view and replay history
+* Many convenience commands inspired by IPython and other advanced REPLs
 
 Pry is also fairly flexible and allows significant user
 [customization](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md). It
@@ -54,83 +45,43 @@ Pry, then:
 
 1. Install rubygems-test: `gem install rubygems-test`
 2. Run the test: `gem test pry`
-3. Finally choose 'Yes' to upload the results. 
-
-Example: Interacting with an object at runtime
----------------------------------------
-
-With the `Object#pry` method we can pry (open an irb-like session) on
-an object. In the example below we open a Pry session for the `Test` class and execute a method and add
-an instance variable. The current thread is taken over by the Pry REPL loop for the duration of the session.
-
-    require 'pry'
-
-    class Test
-      def self.hello() "hello world" end
-    end
-
-    Test.pry
-
-    # Pry session begins on stdin
-    Beginning Pry session for Test
-    pry(Test)> self
-    => Test
-    pry(Test)> hello
-    => "hello world"
-    pry(Test)> @y = 20
-    => 20
-    pry(Test)> exit
-    Ending Pry session for Test
-
-    # program resumes here
+3. Finally choose 'Yes' to upload the results.
 
-If we now inspect the `Test` object we can see our changes have had
-effect:
+### Commands
 
-    Test.instance_variable_get(:@y) #=> 20
+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'
 
-### Alternative Syntax
+    pry(YARD::Parser::SourceParser):5> ls -Mp --grep pa
+    [:parser_class, :parser_type=, :parser_type_for_filename]
 
-You can also use the `Pry.start(obj)` or `pry(obj)` syntax to start a pry session on
-`obj`. e.g
+### Navigating around state
 
-    Pry.start(5)
-    Beginning Pry session for 5
-    pry(5)>
+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)
 
-OR
-
-    pry(6)
-    beginning Pry session for 6
-    pry(6)>
-
-Example: Pry sessions can nest
------------------------------------------------
-
-Here we will begin Pry at top-level, then pry on a class and then on
+Here we will begin Pry at top-level, then Pry on a class and then on
 an instance variable inside that class:
 
-    # Pry.start() without parameters begins a Pry session on top-level (main)
-    Pry.start
-    Beginning Pry session for main
     pry(main)> class Hello
     pry(main)*   @x = 20
     pry(main)* end
     => 20
     pry(main)> cd Hello
-    Beginning Pry session for Hello
-    pry(Hello):1> instance_variables
+    pry(Hello):1> ls -i
     => [:@x]
     pry(Hello):1> cd @x
-    Beginning Pry session for 20
     pry(20:2)> self + 10
     => 30
     pry(20:2)> cd ..
-    Ending Pry session for 20
     pry(Hello):1> cd ..
-    Ending Pry session for Hello
     pry(main)> cd ..
-    Ending Pry session for main
 
 The number after the `:` in the pry prompt indicates the nesting
 level. To display more information about nesting, use the `nesting`
@@ -153,41 +104,337 @@ the `jump-to` command:
     => 100
     pry(Hello):1>
 
-If we just want to go back one level of nesting we can of course
-use the `quit` or `exit` or `back` commands.
+### Runtime invocation
 
-To break out of all levels of Pry nesting and return immediately to the
-calling process use `exit-all`:
+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. When the session ends the program continues with any
+modifications you made to it.
 
-    pry("friend":3)> exit-all
-    Ending Pry session for "friend"
-    Ending Pry session for 100
-    Ending Pry session for Hello
-    Ending Pry session for main
-    => main
+This functionality can be used for such things as: debugging,
+implementing developer consoles and applying hot patches.
+
+code:
+
+    # test.rb
+    require 'pry'
+    
+    class A
+      def hello() puts "hello world!" end
+    end
+    
+    a = A.new
+    
+    # start a REPL session
+    binding.pry
+    
+    # program resumes here (after pry session)
+    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.
+
+### 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.
+
+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 in the home directory. 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
+    
+### Code Browsing
+
+#### show-method
+
+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).
+
+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.
+
+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:
+    
+    pry(main)> cd Pry
+    pry(Pry):1> ls -M --grep ^re
+    [:re, :readline, :rep, :repl, :repl_epilogue, :repl_prologue, :retrieve_line]
+    pry(Pry):1> show-method rep -l
+    
+    From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb @ line 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` gem; 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;
+    
+        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;
+    }
+
+#### Special locals
+
+Some commands such as `show-method`, `show-doc`, `show-command`, `stat`
+and `cat` update the `_file_` and `_dir_` local variables after they
+run. These locals contain the full path to the file involved in the
+last command as well as the directory containing that file.
+
+You can then use these special locals in conjunction with shell
+commands to do such things as change directory into the directory
+containing the file, open the file in an editor, display the file using `cat`, and so on.
+
+In the following example we wil use Pry to fix a bug in a method:
+    
+    pry(main)> greet "john"
+    hello johnhow are you?=> nil
+    pry(main)> show-method greet
+    
+    From: /Users/john/ruby/play/bug.rb @ line 2:
+    Number of lines: 4
+    
+    def greet(name)
+      print "hello #{name}"
+      print "how are you?"
+    end
+    pry(main)> .emacsclient #{_file_}
+    pry(main)> load _file_
+    pry(main)> greet "john"
+    hello john
+    how are you?
+    => nil
+    pry(main)> show-method greet
+    
+    From: /Users/john/ruby/play/bug.rb @ line 2:
+    Number of lines: 4
+    
+    def greet(name)
+      puts "hello #{name}"
+      puts "how are you?"
+    end
+
+
+### 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 -
+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:
+
+    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 @ line 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>
+
+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.
+    
+            a = [ "a", "b", "c" ]
+            a.each {|x| print x, " -- " }
+    
+         produces:
+    
+            a -- b -- c --
+    
+
+### History
+
+Readline history can be viewed and replayed using the `hist`
+command. When `hist` is invoked with no arguments it simply displays
+the history (passing the output through a pager if necessary))
+when the `--replay` option is used a line or a range of lines of
+history can be replayed.
+
+In the example below we will enter a few lines in a Pry session and
+then view history; we will then replay one of those lines:
+    
+    pry(main)> hist
+    0: hist -h
+    1: ls
+    2: ls
+    3: show-method puts
+    4: x = rand
+    5: hist
+    pry(main)> hist --replay 3
+    
+    From: io.c in Ruby Core (C Method):
+    Number of lines: 8
+    
+    static VALUE
+    rb_f_puts(int argc, VALUE *argv, VALUE recv)
+    {
+        if (recv == rb_stdout) {
+        return rb_io_puts(argc, argv, recv);
+        }
+        return rb_funcall2(rb_stdout, rb_intern("puts"), argc, argv);
+    }
+    
+In the next example we will replay a range of lines in history. Note
+that we replay to a point where a class definition is still open and so
+we can continue to add instance methods to the class:
+
+    pry(main)> hist
+    0: class Hello
+    1:   def hello_world
+    2:     puts "hello world!"
+    3:   end
+    4: end
+    5: hist
+    pry(main)> hist --replay 0..3
+    pry(main)* def goodbye_world
+    pry(main)*   puts "goodbye world!"
+    pry(main)* end
+    pry(main)* end
+    => nil
+    pry(main)> Hello.new.goodbye_world;
+    goodbye world!
+    pry(main)>
+
+Also note that in the above the line `Hello.new.goodbye_world;` ends
+with a semi-colon which causes expression evaluation output to be suppressed.    
 
-    # program resumes here
+### Gist integration
 
-Features and limitations
-------------------------
+If the `gist` gem is installed then method source or documentation can be gisted to github with the
+`gist-method` command. The `gist-method` command accepts the same two
+syntaxes as `show-method`. In the example below we will gist the C source
+code for the `Symbol#to_proc` method to github:
+    
+    pry(main)> gist-method Symbol#to_proc
+    https://gist.github.com/5332c38afc46d902ce46
+    pry(main)> 
+    
+You can see the actual gist generated here: https://gist.github.com/5332c38afc46d902ce46
 
-Pry is an irb-like clone with an emphasis on interactively examining
-and manipulating objects during the running of a program.
 
-Its primary utility is probably in debugging, though it may have other
-uses (such as implementing a quake-like console for games, for example). Here is a
-list of Pry's features along with some of its limitations given at the
-end.
+### Live Help System
 
-###Features:
+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
+avaiable.
 
-* Pry can be invoked at any time and on any object in the running program.
+
+### Other Features and limitations
+
+#### Other Features:
+
+* Pry can be invoked both at the command-line and used as a more
+powerful alternative to IRB or it can be invoked at runtime and used
+as a developer consoler / debugger.
 * Additional documentation and source code for Ruby Core methods are supported when the `pry-doc` gem is installed.
 * Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
 * Pry comes with syntax highlighting on by default just use the `toggle-color` command to turn it on and off.
 * Use `_` to recover last result.
 * Use `_pry_` to reference the Pry instance managing the current session.
 * Use `_ex_` to recover the last exception.
+* Use `_file_` and `_dir_` to refer to the associated file or
+  directory containing the definition for a method.
+* A trailing `;` on an entered expression suppresses the display of
+  the evaluation output.
+* Typing `!` on a line by itself will clear the input buffer - useful for
+  getting you out of a situation where the parsing process
+  goes wrong and you get stuck in an endless read loop.
 * Pry supports tab completion.
 * Pry has multi-line support built in.
 * Use `^d` (control-d) to quickly break out of a session.
@@ -205,113 +452,26 @@ for reading; `Pry#re` for eval; `Pry#rep` for printing; and `Pry#repl`
 for the loop (`Pry.start` simply wraps `Pry.new.repl`). You can
 invoke any of these methods directly depending on exactly what aspect of the functionality you need.
 
-###Limitations:
+#### Limitations:
 
 * Some Pry commands (e.g `show-command`) do not work in Ruby 1.8.
-* `method_source` functionality does not work in JRuby.
-* 1.9 support requires `Ripper` - some implementations may not support this.
-
-Commands
------------
-
-### The Pry API:
-
-* `Pry.start()` Starts a Read-Eval-Print-Loop on the object it
-receives as a parameter. In the case of no parameter it operates on
-top-level (main). It can receive any object or a `Binding`
-object as parameter. `Pry.start()` is implemented as `Pry.new.repl()`
-* `obj.pry` and `pry(obj)` may also be used as alternative syntax to
-`Pry.start(obj)`.
-
-  However there are some differences. `obj.pry` opens
-a Pry session on the receiver whereas `Pry.start` (with no parameter)
-will start a Pry session on top-level. The other form of the `pry`
-method: `pry(obj)` will also start a Pry session on its parameter.
-
-  The `pry` method invoked by itself, with no explict receiver and no
-parameter will start a Pry session on the implied receiver. It is
-perhaps more useful to invoke it in this form `pry(binding)` or
-`binding.pry` so as to get access to locals in the current context.
-
-  Another difference is that `Pry.start()` accepts a second parameter
-that is a hash of configuration options (discussed further, below).
-
-* If, for some reason you do not want to 'loop' then use `Pry.new.rep()`; it
-only performs the Read-Eval-Print section of the REPL - it ends the
-session after just one line of input. It takes the same parameters as
-`Pry#repl()`
-* Likewise `Pry#re()` only performs the Read-Eval section of the REPL,
-it returns the result of the evaluation or an Exception object in
-case of error. It also takes the same parameters as `Pry#repl()`
-* Similarly `Pry#r()` only performs the Read section of the REPL, only
-returning the Ruby expression (as a string). It takes the same parameters as all the others.
-* `Pry.run_command COMMAND` enables you to invoke Pry commands outside
-of a session, e.g `Pry.run_command "ls -m", :context => MyObject`. See
-docs for more info.
-
-### Session commands
-
-Pry supports a few commands inside the session itself. These commands are
-not methods and must start at the beginning of a line, with no
-whitespace in between.
-
-If you want to access a method of the same name, prefix the invocation by whitespace.
-
-* Typing `!` on a line by itself will clear the input buffer - useful for
-  getting you out of a situation where the parsing process
-  goes wrong and you get stuck in an endless read loop.
-* `status` shows status information about the current session.
-* `whereami AROUND` shows the code context of the session. Shows
-  AROUND lines either side of the current line.
-* `version` Show Pry version information
-* `help` shows the list of session commands with brief explanations.
-* `toggle-color` turns on and off syntax highlighting.
-* `simple-prompt` toggles the simple prompt mode.
-* `exit` or `quit` or `back` or `^d` (control-d) will end the current Pry session and go
-  back to the calling process or back one level of nesting (if there
-  are nested sessions).
-* `ls [OPTIONS] [VAR]` returns a list of local variables, instance variables, and
-  methods, etc. Highly flexible. See `ls --help` for more info.
-* `cat VAR` Calls `inspect` on `VAR`
-* `cd VAR` Starts a `Pry` session on the variable VAR. E.g `cd @x`
-(use `cd ..` to go back).
-* `show-method [OPTIONS] METH` Displays the sourcecode for the method
-  `METH`. e.g `show-method hello`. See `show-method --help` for more info.
-* `show-doc [OPTIONS] METH` Displays comments for `METH`. See `show-doc
-  --help` for more info.
-* `show-command COMMAND` Displays the sourcecode for the given Pry
-  command. e.g: `show-command cd`
-* `jump-to NEST_LEVEL`  Unwinds the Pry stack (nesting level) until the appropriate nesting level is reached.
-* `exit-all` breaks out of all Pry nesting levels and returns to the
-  calling process.
-
-Syntax Highlighting
---------------------
+* JRuby not officially supported due to currently too many quirks and
+ strange behaviour. Nonetheless most functionality should still work
+ OK in JRuby. Full JRuby support coming in a future version.
+* `method_source` functionality does not work in JRuby with Ruby 1.8
+* Color support does not work in JRuby with Ruby 1.9 (due to a
+  limitation in JRuby's regex).
+* Tab completion is currently a bit broken/limited this will have a
+   major overhaul in a future version.
+   
+### Syntax Highlighting
 
 Syntax highlighting is on by default in Pry. You can toggle it 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.
 
-Bindings and objects
---------------------
-
-Pry ultimately operates on `Binding` objects. If you invoke Pry with a
-Binding object it uses that Binding. If you invoke Pry with anything
-other than a `Binding`, Pry will generate a Binding for that
-object and use that.
-
-If you want to open a Pry session on the current context and capture
-the locals you should use: `binding.pry`. If you do not care about
-capturing the locals you can simply use `pry` (which will generate a
-fresh `Binding` for the receiver).
-
-Top-level is a special case; you can start a Pry session on top-level
-*and* capture locals by simply using: `pry`. This is because Pry
-automatically uses `TOPLEVEL_BINDING` for the top-level object (main).
-
-Example Programs
-----------------
+### Example Programs
 
 Pry comes bundled with a few example programs to illustrate some
 features, see the `examples/` directory.
@@ -327,14 +487,38 @@ features, see the `examples/` directory.
 * `example_commands_override.rb` - An advanced `commands` example.
 * `example_image_edit.rb`        - A simple image editor using a Pry REPL (requires `Gosu` and `TexPlay` gems).
 
-Customizing Pry
----------------
+### Customizing Pry
 
 Pry allows a large degree of customization. 
 
 [Read how to customize Pry here.](http://rdoc.info/github/banister/pry/master/file/wiki/Customizing-pry.md)
 
-Contact
--------
+### Future Directions
+
+Many new features are planned such as:
+
+* Much improved tab completion (using [Bond](http://github.com/cldwalker/bond))
+* Improved JRuby support
+* Support for viewing source-code of binary gems and C stdlib
+* git integration
+* Much improved documentation system, better support for YARD
+* A proper plugin system
+* Get rid of `.` prefix for shell commands in `shell-mode`
+* Better support for code and method reloading
+* Extended and more sophisticated command system, allowing piping
+between commands and running commands in background
+
+### Contact
 
 Problems or questions contact me at [github](http://github.com/banister)
+
+### Contributors
+
+The Pry team consists of:
+
+* [banisterfiend](http://github.com/banister)
+* [epitron](http://github.com/epitron)
+* [injekt](http://github.com/injekt)
+* [Mon_Ouie](http://github.com/mon-ouie)
+
+