added import_from, delete, run to command API. Also added examples, added more tests, and changed the way that commands work using split instead of regex captures. Also added output and trget methods to Pry::CommandBase

1 files changed, 67 insertions, 17 deletions

diff --git a/README.markdown b/README.markdown
index b4f02480..a92a5a3c 100644
--- a/README.markdown
+++ b/README.markdown
@@ -343,14 +343,19 @@ 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` and use the special command API:
 
 #### Example: Defining a command object and setting it globally
 
     class MyCommands < Pry::CommandBase
-      command "hello", "Output hello to the user." do |name|
-        opts[:output].puts "hello #{name}!"
+      command greet", "Greet the user." do |name|
+        output.puts "Hello #{name.capitalize}, how are you?"
       end
     end
 
@@ -358,8 +363,8 @@ A valid Pry command object must inherit from
 
 Then inside a pry session:
 
-    pry(main)> hello john
-    hello john!
+    pry(main)> greet john
+    hello John, how are you?
     => nil
 
 #### Example: Using a command object in a specific session
@@ -367,7 +372,7 @@ Then inside a pry session:
 As in the case of `input` and `output`:
 
 ##### At session start:
-nnnnn
+
     Pry.start(self, :commands => MyCommands)
 
 ##### At runtime:
@@ -377,9 +382,9 @@ nnnnn
 #### The command API
 
 The command API is defined by the `Pry::CommandBase` class (hence why
-all commands must inherit from it). The API works as follows:
+all commands must inherit from it or a subclass). The API works as follows:
 
-The `command` method defines a new command, its parameter is the
+* 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.
 
@@ -398,23 +403,64 @@ for the command name - all these strings will be valid names for the
 command.
 
     command ["ls", "dir"], "show a list of local vars" do
-      opts[:output].puts opts[:target].eval("local_variables")
+      output.puts target.eval("local_variables")
     end
 
+* 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
+
+* 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
+
+* 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:
 
-#### opts hash
+      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
 
-Note that in the example above we are using `opts[:output]` for output; this is the output
-object in use by the current pry session. Other hash values accessible
-within a `command` block include:
+    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 own commands:
 
-* `opts[:output]` - The session's output object.
 * `opts[:val]` - The line of input that invoked the command.
 * `opts[:eval_string]` - The cumulative lines of input for multi-line input.
-* `opts[:target]` - The object the Pry session is currently on.
-* `opts[:captures]` - The array of regex captures generated by the command (if any).
 * `opts[:nesting]` - Lowlevel session nesting information.
-* `opts[:command_info]` - Lowlevel information about all Pry commands.
+* `opts[:commands]` - Lowlevel data of all Pry commands.
 
 (see commands.rb for examples of how some of these options are used)
 
@@ -424,7 +470,11 @@ 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.
+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