added Pry.sessions and Pry#parent, for more info on pry sessions. Also completed more documentation

README.markdown

@@ -54,13 +54,13 @@ effect:
 You can also use the `Pry.start(obj)` or `pry(obj)` syntax to start a pry session on
 `obj`. e.g
 
-    Pry.start 5
+    Pry.start(5)
     Beginning Pry session for 5
     pry(5)>
 
 OR
 
-    pry 6
+    pry(6)
     beginning Pry session for 6
     pry(6)>
 
@@ -262,8 +262,8 @@ are:
 
 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 also exist for a
-Pry instance.
+same accessors as described above for the `Pry` class exist for a
+Pry instance so that customization can occur during runtime.
 
 ### Input:
 
@@ -291,19 +291,26 @@ session will hang as it loops indefinitely awaiting new input.
 
 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:
+point the session is started, or within the session itself (at runtime):
 
-Here is the first case:
+##### 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
@@ -324,12 +331,12 @@ this output by default:
 
 As per Input, given above, we set the local output as follows:
 
-Here is the first case:
+##### At session start
 
     Pry.start(Object, :output => StringIO.new("@x = 10\nexit"))
     Object.instance_variable_get(:@x) #=> 10
 
-And to change output from within the session itself:
+##### At runtime
     
     _pry_.output = StringIO.new
 
@@ -337,7 +344,7 @@ And to change output from within the session itself:
 
 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, but these commands can be augmented or overriden by
+command set (`Pry::Commands`), but these commands can be augmented or overriden by
 user-specified ones.
 
 A valid Pry command object must inherit from
@@ -359,7 +366,7 @@ A valid Pry command object must inherit from
 
 Then inside a pry session:
 
-    (pry)> hello john
+    pry(main)> hello john
     hello john!
     => nil
 
@@ -367,11 +374,11 @@ Then inside a pry session:
 
 As in the case of `input` and `output`:
 
-At session start:
+##### At session start:
 
     Pry.start(self, :commands => MyCommands)
 
-From within the session:    
+##### At runtime:
 
     _pry_.commands = MyCommands
 
@@ -415,6 +422,49 @@ 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.
 
+### 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!" } }
     
     
 Contact

lib/pry/pry_class.rb

@@ -57,6 +57,7 @@ class Pry
     #   prompts by default by all Pry instances.
     attr_accessor :prompt
   end
+  
   # Start a Pry REPL.
   # @param [Object, Binding] target The receiver of the Pry session
   # @param [Hash] options
@@ -96,4 +97,11 @@ class Pry
   def @nesting.level
     last.is_a?(Array) ? last.first : nil
   end
+
+  # Return all active Pry sessions.
+  # @return [Array<Pry>] Active Pry sessions.
+  def self.sessions
+    # last element in nesting array is the pry instance
+    nesting.map(&:last)
+  end
 end

lib/pry/pry_instance.rb

@@ -45,6 +45,18 @@ class Pry
     self.class.nesting = v
   end
 
+  # Return parent of current Pry session.
+  # @return [Pry] The parent of the current Pry session.
+  def parent
+    idx = Pry.sessions.index(self)
+
+    if idx > 0
+      Pry.sessions[idx - 1]
+    else
+      nil
+    end
+  end
+
   # Execute the hook `hook_name`, if it is defined.
   # @param [Symbol] hook_name The hook to execute
   # @param [Array] args The arguments to pass to the hook.
@@ -75,7 +87,7 @@ class Pry
     target.eval("_ = Pry.last_result")
 
     break_level = catch(:breakout) do
-      nesting.push [nesting.size, target_self]
+      nesting.push [nesting.size, target_self, self]
       loop do
         rep(target)
       end