pry 0.3.0 → 0.4.0pre1

data/CHANGELOG

@@ -1,3 +1,13 @@
+21/1/2010 version 0.4.0
+* added command API
+* added many new commands, i.e ls_methods and friends
+* modified other commands
+* now accepts greater customization, can modify: input, output, hooks,
+	prompt, print object
+* added tab completion (even completes commands)
+* added extensive tests
+* added examples
+* many more changes
 9/12/2010 version 0.1.3
 * Got rid of rubygems dependency, refactored some code.
 8/12/2010 version 0.1.2

data/README.markdown

@@ -6,29 +6,29 @@ Pry
 _attach an irb-like session to any object at runtime_
 
 Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
-manipulation of objects during the running of a program.
+manipulation of objects during the running of a program. 
 
 It is not based on the IRB codebase, and implements some unique REPL
-commands such as `show_method` and `jump_to`
+commands such as `show_method` and `show_doc`
 
 * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
 * Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
 * See the [source code](http://github.com/banister/pry)
 
-Example: Interacting with an object at runtime 
+Example: Interacting with an object at runtime
 ---------------------------------------
 
-With the `Pry.start()` method we can pry (open an irb-like session) on
+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 halted for the duration of the session.
 
     require 'pry'
-    
+
     class Test
       def self.hello() "hello world" end
     end
 
-    Pry.start(Test)
+    Test.pry
 
     # Pry session begins on stdin
     Beginning Pry session for Test
@@ -48,23 +48,23 @@ effect:
 
     Test.instance_variable_get(:@y) #=> 20
 
-#### Alternative Syntax
+### Alternative Syntax
 
-You can also use the `obj.pry` or `pry(obj)` syntax to start a pry session on
+You can also use the `Pry.start(obj)` or `pry(obj)` syntax to start a pry session on
 `obj`. e.g
 
-    5.pry
+    Pry.start(5)
     Beginning Pry session for 5
     pry(5)>
 
 OR
 
-    pry 6
+    pry(6)
     beginning Pry session for 6
     pry(6)>
-    
-Example: Pry sessions can nest arbitrarily deep so we can pry on objects inside objects:
-----------------------------------------------------------------------------------------
+
+Example: Pry sessions can nest
+-----------------------------------------------
 
 Here we will begin Pry at top-level, then pry on a class and then on
 an instance variable inside that class:
@@ -76,11 +76,11 @@ an instance variable inside that class:
     pry(main)*   @x = 20
     pry(main)* end
     => 20
-    pry(main)> Pry.start Hello
+    pry(main)> Hello.pry
     Beginning Pry session for Hello
     pry(Hello):1> instance_variables
     => [:@x]
-    pry(Hello):1> Pry.start @x
+    pry(Hello):1> @x.pry
     Beginning Pry session for 20
     pry(20:2)> self + 10
     => 30
@@ -102,7 +102,7 @@ command. E.g
     2. 100
     3. "friend"
     => nil
-    
+
 We can then jump back to any of the previous nesting levels by using
 the `jump_to` command:
 
@@ -112,7 +112,7 @@ the `jump_to` command:
     => 100
     pry(Hello):1>
 
-If we just want to go back one level of nesting we can of course 
+If we just want to go back one level of nesting we can of course
 use the `quit` or `exit` or `back` commands.
 
 To break out of all levels of Pry nesting and return immediately to the
@@ -124,7 +124,7 @@ calling process use `exit_all`:
     Ending Pry session for Hello
     Ending Pry session for main
     => main
-    
+
     # program resumes here
 
 Features and limitations
@@ -138,16 +138,19 @@ uses (such as implementing a quake-like console for games, for example). Here is
 list of Pry's features along with some of its limitations given at the
 end.
 
-####Features:
+###Features:
 
 * Pry can be invoked at any time and on any object in the running program.
 * Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
 * Use `_` to recover last result.
+* Use `_pry_` to reference the Pry instance managing the current session.
+* Pry supports tab completion.
 * Pry has multi-line support built in.
-* Pry has unique commands not found in any other REPL: `show_method`, `show_doc`
+* Pry has special commands not found in many other Ruby REPLs: `show_method`, `show_doc`
 `jump_to`, `ls`, `cd`, `cat`
 * Pry gives good control over nested sessions (important when exploring complicated runtime state)
 * Pry is not based on the IRB codebase.
+* Pry allows significant customizability.
 * Pry uses [RubyParser](https://github.com/seattlerb/ruby_parser) to
 validate expressions in 1.8, and [Ripper](http://rdoc.info/docs/ruby-core/1.9.2/Ripper) for 1.9.
 * Pry implements all the methods in the REPL chain separately: `Pry#r`
@@ -155,15 +158,15 @@ 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:
 
 * Pry does not pretend to be a replacement for `irb`,
   and so does not have an executable. It is designed to be used by
   other programs, not on its own. For a full-featured `irb` replacement
   see [ripl](https://github.com/cldwalker/ripl)
-* Pry's `show_method` and `show_instance_method` commands do not work
+* Pry's `show_method` and `show_doc` commands do not work
   in Ruby 1.8.
- 
+
 Commands
 -----------
 
@@ -173,11 +176,26 @@ Commands
 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)`
+* `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()` 
+`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()`
@@ -202,8 +220,10 @@ If you want to access a method of the same name, prefix the invocation by whites
   are nested sessions).
 * `ls` returns a list of local variables and instance variables in the
   current scope
-* `cat <var>` calls `inspect` on `<var>`
-* `cd <var>` starts a `Pry` session on the variable <var>. E.g `cd @x`
+* `ls_methods` List all methods defined on immediate class of receiver.
+* `ls_imethods` List all instance methods defined on receiver.
+* `cat <var>` Calls `inspect` on `<var>`
+* `cd <var>` Starts a `Pry` session on the variable <var>. E.g `cd @x`
 * `show_method <methname>` Displays the sourcecode for the method
   <methname>. E.g `show_method hello`
 * `show_imethod <methname>` Displays the sourcecode for the
@@ -213,8 +233,10 @@ If you want to access a method of the same name, prefix the invocation by whites
   method `<methname>`
 * `exit_program` or `quit_program` will end the currently running
   program.
-* `nesting` shows Pry nesting information.
-* `jump_to <nest_level>`  unwinds the Pry stack (nesting level) until the appropriate nesting level is reached
+* `nesting` Shows Pry nesting information.
+* `!pry` Starts a Pry session on the implied receiver; this can be
+  used in the middle of an expression in multi-line input.
+* `jump_to <nest_level>`  Unwinds the Pry stack (nesting level) until the appropriate nesting level is reached
   -- as per the output of `nesting`
 * `exit_all` breaks out of all Pry nesting levels and returns to the
   calling process.
@@ -222,6 +244,396 @@ If you want to access a method of the same name, prefix the invocation by whites
   current one with `obj` as the receiver of the new session. Very useful
   when exploring large or complicated runtime state.
 
+Example Programs
+----------------
+
+Pry comes bundled with a few example programs to illustrate some
+features, see the `examples/` directory.
+
+* `example_input.rb`             - Demonstrates how to set the `input` object.
+* `example_output.rb`            - Demonstrates how to set the `output` object.
+* `example_hooks.rb`             - Demonstrates how to set the `hooks` hash.
+* `example_print.rb`             - Demonstrates how to set the `print` object.
+* `example_prompt.rb`            - Demonstrates how to set the `prompt`.
+* `example_input2.rb`            - An advanced `input` example.
+* `example_commands.rb`          - Implementing a mathematical command set.
+* `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
+---------------
+
+Pry supports customization of the input, the output, the commands,
+the hooks, the prompt, and 'print' (the "P" in REPL).
+
+Global customization, which applies to all Pry sessions, is done
+through invoking class accessors on the `Pry` class, the accessors
+are:
+
+* `Pry.input=`
+* `Pry.output=`
+* `Pry.commands=`
+* `Pry.hooks=`
+* `Pry.prompt=`
+* `Pry.print=`
+
+Local customization (applied to a single Pry session) is done by
+passing config hash options to `Pry.start()` or to `Pry.new()`; also the
+same accessors as described above for the `Pry` class exist for a
+Pry instance so that customization can occur during runtime.
+
+### Input
+
+For input Pry accepts any object that implements the `readline` method. This
+includes `IO` objects, `StringIO`, `Readline` and custom objects. Pry
+initially defaults to using `Readline` for input.
+
+#### Example: Setting global input
+
+Setting Pry's global input causes all subsequent Pry instances to use
+this input by default:
+
+    Pry.input = StringIO.new("@x = 10\nexit")
+    Object.pry
+
+    Object.instance_variable_get(:@x) #=> 10
+
+The above will execute the code in the `StringIO`
+non-interactively. It gets all the input it needs from the `StringIO`
+and then exits the Pry session. Note it is important to end the
+session with 'exit' if you are running non-interactively or the Pry
+session will hang as it loops indefinitely awaiting new input.
+
+#### Example: Setting input for a specific session
+
+The settings for a specific session override the global settings
+(discussed above). There are two ways to set input for a specific pry session: At the
+point the session is started, or within the session itself (at runtime):
+
+##### At session start
+
+    Pry.start(Object, :input => StringIO.new("@x = 10\nexit"))
+    Object.instance_variable_get(:@x) #=> 10
+
+##### At runtime
+
+If you want to set the input object within the session itself you use
+the special `_pry_` local variable which represents the Pry instance
+managing the current session; inside the session we type:
+
+    _pry_.input = StringIO.new("@x = 10\nexit")
+
+Note we can also set the input object for the parent Pry session (if
+the current session is nested) like so:
+
+    _pry_.parent.input = StringIO.new("@x = 10\nexit")
+
+### Output
+
+For output Pry accepts any object that implements the `puts` method. This
+includes `IO` objects, `StringIO` and custom objects. Pry initially
+defaults to using `$stdout` for output.
+
+#### Example: Setting global output
+
+Setting Pry's global output causes all subsequent Pry instances to use
+this output by default:
+
+    Pry.output = StringIO.new
+
+#### Example: Setting output for a specific session
+
+As per Input, given above, we set the local output as follows:
+
+##### At session start
+
+    Pry.start(Object, :output => StringIO.new("@x = 10\nexit"))
+
+##### At runtime
+    
+    _pry_.output = StringIO.new
+
+### Commands
+
+Pry commands are not methods; they are commands that are intercepted
+and executed before a Ruby eval takes place. Pry comes with a default
+command set (`Pry::Commands`), but these commands can be augmented or overriden by
+user-specified ones.
+
+The Pry command API is quite sophisticated supporting features such as:
+command set inheritance, importing of specific commands from another
+command set, deletion of commands, calling of commands within other
+commands, and so on.
+
+A valid Pry command object must inherit from
+`Pry::CommandBase` (or one of its subclasses) and use the special command API:
+
+#### Example: Defining a command object and setting it globally
+
+    class MyCommands < Pry::CommandBase
+      command "greet", "Greet the user." do |name|
+        output.puts "Hello #{name.capitalize}, how are you?"
+      end
+    end
+
+    Pry.commands = MyCommands
+
+Then inside a pry session:
+
+    pry(main)> greet john
+    hello John, how are you?
+    => nil
+
+#### Example: Using a command object in a specific session
+
+As in the case of `input` and `output`:
+
+##### At session start:
+
+    Pry.start(self, :commands => MyCommands)
+
+##### At runtime:
+
+    _pry_.commands = MyCommands
+
+#### The command API
+
+The command API is defined by the `Pry::CommandBase` class (hence why
+all commands must inherit from it or a subclass). The API works as follows:
+
+##### `command` method
+
+The `command` method defines a new command, its parameter is the
+name of the command and an optional second parameter is a description of
+the command.
+
+The associated block defines the action to be performed. The number of
+parameters in the block determine the number of parameters that will
+be sent to the command (from the Pry prompt) when it is invoked. Note
+that all parameters that are received will be strings; if a parameter
+is not received it will be set to `nil`.
+
+    command "hello" do |x, y, z|
+      puts "hello there #{x}, #{y}, and #{z}!"
+    end
+
+Command aliases can also be defined - simply use an array of strings
+for the command name - all these strings will be valid names for the
+command.
+
+    command ["ls", "dir"], "show a list of local vars" do
+      output.puts target.eval("local_variables")
+    end
+
+##### `delete` method
+
+The `delete` method deletes a command or a group of a commands; it
+can be useful when inheriting from another command set when you decide
+to keep only a portion of inherited commands.
+
+    class MyCommands < Pry::Commands
+      delete "show_method", "show_imethod"
+    end
+
+##### `import_from` method
+
+The `import_from` method enables you to specifically select which
+commands will be copied across from another command set, useful when
+you only want a small number of commands and so inheriting and then
+deleting would be inefficient. The first parameter to `import_from`
+is the class to import from and the other paramters are the names of
+the commands to import:
+
+    class MyCommands < Pry::CommandBase
+      import_from Pry::Commands, "ls", "status", "!"
+    end
+
+##### `run` method
+
+The `run` command invokes one command from within another.
+The first parameter is the name of the command to invoke
+and the remainder of the parameters will be passed on to the command
+being invoked:
+
+    class MyCommands < Pry::Commands
+      command "ls_with_hello" do
+        output.puts "hello!"
+        run "ls"
+      end
+    end
+
+#### Utility methods for commands
+
+All commands can access the special `output` and `target` methods. The
+`output` method returns the `output` object for the active pry session.
+Ensuring that your commands invoke `puts` on this rather than using
+the top-level `puts` will ensure that all your session output goes to
+the same place.
+
+The `target` method returns the `Binding` object the Pry session is currently
+active on - useful when your commands need to manipulate or examine
+the state of the object. E.g, the "ls" command is implemented as follows
+
+    command "ls" do
+      output.puts target.eval("local_variables + instance_variables").inspect
+    end
+
+#### The opts hash
+
+These are miscellaneous variables that may be useful to your commands:
+
+* `opts[:val]` - The line of input that invoked the command.
+* `opts[:eval_string]` - The cumulative lines of input for multi-line input.
+* `opts[:nesting]` - Lowlevel session nesting information.
+* `opts[:commands]` - Lowlevel data of all Pry commands.
+
+(see commands.rb for examples of how some of these options are used)
+
+#### The `help` command
+
+The `Pry::CommandBase` class automatically defines a `help` command
+for you. Typing `help` in a Pry session will show a list of commands
+to the user followed by their descriptions. Passing a parameter to
+`help` with the command name will just return the description of that
+specific command. If a description is left out it will automatically
+be given the description "No description.".
+
+If the description is explicitly set to `""` then this command will
+not be displayed in `help`.
+
+### Hooks
+
+Currently Pry supports just two hooks: `before_session` and
+`after_session`. These hooks are invoked before a Pry session starts
+and after a session ends respectively. The default hooks used are
+stored in the `Pry::DEFAULT_HOOKS` and just output the text `"Beginning
+Pry session for <obj>"` and `"Ending Pry session for <obj>"`.
+
+#### Example: Setting global hooks
+
+All subsequent Pry instances will use these hooks as default:
+
+    Pry.hooks = {
+      :before_session => proc { |out, obj| out.puts "Opened #{obj}" },
+      :after_session => proc { |out, obj| out.puts "Closed #{obj}" }
+    }
+
+    5.pry
+
+Inside the session:
+
+    Opened 5
+    pry(5)> exit
+    Closed 5
+
+Note that the `before_session` and `after_session` procs receive the
+current session's output object and session receiver as parameters.
+
+#### Example: Setting hooks for a specific session
+
+Like all the other customization options, the global default (as
+explained above) can be overriden for a specific session, either at
+session start or during runtime.
+
+##### At session start
+
+    Pry.start(self, :hooks => { :before_session => proc { puts "hello world!" },
+                                :after_session => proc { puts "goodbye world!" }
+                              })
+
+##### At runtime
+
+    _pry_.hooks = { :before_session => proc { puts "puts "hello world!" } }
+
+### Prompts
+
+The Pry prompt is used by `Readline` and other input objects that
+accept a prompt. Pry can accept two prompt-types for every prompt; the
+'main prompt' and the 'wait prompt'. The main prompt is always used
+for the first line of input; the wait prompt is used in multi-line
+input to indicate that the current expression is incomplete and more lines of
+input are required. The default Prompt used by Pry is stored in the
+`Pry::DEFAULT_PROMPT` constant.
+
+A valid Pry prompt is either a single `Proc` object or a two element
+array of `Proc` objects. When an array is used the first element is
+the 'main prompt' and the last element is the 'wait prompt'. When a
+single `Proc` object is used it will be used for both the main prompt
+and the wait prompt.
+
+#### Example: Setting global prompt
+
+The prompt `Proc` objects are passed the receiver of the Pry session
+and the nesting level of that session as parameters (they can simply
+ignore these if they do not need them).
+
+    # Using one proc for both main and wait prompts
+    Pry.prompt = proc { |obj, nest_level| "#{obj}:#{nest_level}> " }
+
+    # Alternatively, provide two procs; one for main and one for wait
+    Pry.prompt = [ proc { "ENTER INPUT> " }, proc { "MORE INPUT REQUIRED!* " }]
+
+#### Example: Setting the prompt for a specific session
+
+##### At session start
+
+    Pry.start(self, :prompt => [proc { "ENTER INPUT> " },
+                                proc { "MORE INPUT REQUIRED!* " }])
+
+##### At runtime
+
+    _pry_.prompt = [proc { "ENTER INPUT> " },
+                    proc { "MORE INPUT REQUIRED!* " }]
+
+### Print
+
+The Print phase of Pry's READ-EVAL-PRINT-LOOP can be customized. The
+default action is stored in the `Pry::DEFAULT_PRINT` constant and it
+simply outputs the value of the current expression preceded by a `=>` (or the first
+line of the backtrace if the value is an `Exception` object.)
+
+The print object should be a `Proc` and the parameters passed to the
+`Proc` are the output object for the current session and the 'value'
+returned by the current expression.
+
+#### Example: Setting global print object
+
+Let's define a print object that displays the full backtrace of any
+exception and precedes the output of a value by the text `"Output is: "`:
+
+    Pry.print = proc do |output, value|
+                  case value
+                  when Exception
+                    output.puts value.backtrace
+                  else
+                    output.puts "Output is: #{value}"
+                  end
+                end
+
+#### Example: Setting the print object for a specific session
+
+##### At session start
+
+    Pry.start(self, :print => proc do |output, value|
+                                case value
+                                when Exception
+                                  output.puts value.backtrace
+                                else
+                                  output.puts "Output is: #{value.inspect}"
+                                end
+                              end)
+
+##### At runtime
+
+    _pry_.print =  proc do |output, value|
+                     case value
+                     when Exception
+                       output.puts value.backtrace
+                     else
+                       output.puts "Output is: #{value.inspect}"
+                     end
+                   end
+    
 Contact
 -------
 
@@ -229,3 +641,4 @@ Problems or questions contact me at [github](http://github.com/banister)
 
 
 
+