Updated more docs and formatting.

Changed tests to remove opts[:output] and then removed opts[:output]; replaced with output method, changed prompt in example_commands.rb to have a math* wait prompt. Added bullet points to examples in README.markdown. Added more info on TexPlay and Gosu for example_image_edit

README.markdown

@@ -248,6 +248,16 @@ 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
 ---------------
 
@@ -354,7 +364,7 @@ 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:
+`Pry::CommandBase` (or one of its subclasses) and use the special command API:
 
 #### Example: Defining a command object and setting it globally
 
@@ -389,7 +399,9 @@ As in the case of `input` and `output`:
 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:
 
-* The `command` method defines a new command, its parameter is the
+##### `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.
 
@@ -411,36 +423,42 @@ command.
       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.
+##### `delete` method
 
-      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:
-
-      class MyCommands < Pry::Commands
-        command "ls_with_hello" do
-          output.puts "hello!"
-          run "ls"
-        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
+
+##### `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
 

examples/example_command_override.rb

@@ -3,8 +3,9 @@ direc = File.dirname(__FILE__)
 require 'rubygems'
 require "#{direc}/../lib/pry"
 
-# inherit standard command set, but tweak them by deleting some and
-# overriding others
+# Inherit standard command set, but tweak them by importing some and
+# overriding others.
+# Illustrates use of `command`, `run`, and `import_from` commands.
 class MyCommands < Pry::CommandBase
 
   # Override ls command

examples/example_commands.rb

@@ -21,11 +21,14 @@ class MathCommands < Pry::CommandBase
   command "exit", "" do
     throw :breakout, 0
   end
+
+  # Bring in the "!" method from Pry::Commands
+  import_from Pry::Commands, "!"
 end
 
 # Since we provide math commands, let's have mathematical
 # before_session and after_session hooks, and a mathematical prompt
-math_prompt = proc { "math> " }
+math_prompt = [proc { "math> " }, proc { "math* " }]
 math_hooks = {
   :before_session => proc { |output, *| output.puts "Welcome! Let's do some math! Type 'help' for a list of commands." },
   :after_session => proc { |output, *| output.puts "Goodbye!" }

examples/example_input2.rb

@@ -15,10 +15,12 @@ _pry_.parent.input = Readline
 back
 exit_all
 CMDS
+
+# create our StringIO object
 str_input = StringIO.new(cmds)
 
-# Start a Pry session on the Fixnum 5 using the input data in
-# str_input
+# set global input to str_input, this means that all pry sessions
+# adopt this object as their input object.
 Pry.input = str_input
 
 # Start the session reading from str_input.
@@ -27,5 +29,4 @@ Pry.input = str_input
 # for non-interactive, except for `pry(1)` which starts off
 # non-interactive but is set to be interactive by pry(2) (using
 # _pry_.parent.input = Readline)
-
 0.pry

lib/pry/pry_instance.rb

@@ -196,7 +196,6 @@ class Pry
         :val => val,
         :eval_string => eval_string,
         :nesting => nesting,
-        :output => output,
         :commands => commands.commands
       }
 

test/test.rb

@@ -264,8 +264,7 @@ describe Pry do
           it 'should set the commands default, and the default should be overridable' do
             class Command0 < Pry::CommandBase
               command "hello" do
-                opts[:output].puts "hello world"
-                opts[:val].clear 
+                output.puts "hello world"
               end
             end
 
@@ -277,8 +276,7 @@ describe Pry do
 
             class Command1 < Pry::CommandBase
               command "goodbye", "" do
-                opts[:output].puts "goodbye world"
-                opts[:val].clear 
+                output.puts "goodbye world"
               end
             end
 

test/test_helper.rb

@@ -29,12 +29,10 @@ end
 class CommandTester < Pry::CommandBase
 
   command "command1", "command 1 test" do
-    opts[:output].puts "command1"
-    opts[:val].clear 
+    output.puts "command1"
   end
 
   command "command2", "command 2 test" do |arg|
-    opts[:output].puts arg
-    opts[:val].clear
+    output.puts arg
   end
 end