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

README.markdown

@@ -16,7 +16,7 @@ commands such as `show_method` and `jump_to`
 * 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 `Object#pry` method we can pry (open an irb-like session) on
@@ -24,7 +24,7 @@ an object. In the example below we open a Pry session for the `Test` class and e
 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
@@ -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)>
 
@@ -103,7 +103,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:
 
@@ -113,7 +113,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
@@ -125,7 +125,7 @@ calling process use `exit_all`:
     Ending Pry session for Hello
     Ending Pry session for main
     => main
-    
+
     # program resumes here
 
 Features and limitations
@@ -167,7 +167,7 @@ invoke any of these methods directly depending on exactly what aspect of the fun
   see [ripl](https://github.com/cldwalker/ripl)
 * Pry's `show_method` and `show_doc` commands do not work
   in Ruby 1.8.
- 
+
 Commands
 -----------
 
@@ -196,7 +196,7 @@ 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()`
@@ -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
+same accessors as described above for the `Pry` class exist for a
-Pry instance.
+Pry instance so that customization can occur during runtime.
 
 ### Input:
 
@@ -278,7 +278,7 @@ 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`
@@ -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
@@ -317,27 +324,27 @@ this output by default:
 
     Pry.output = StringIO.new
     Object.pry
-    
+
     Object.instance_variable_get(:@x) #=> 10
 
 #### Example: Setting output for a specific session
 
 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
 
 ### 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, 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,12 +374,12 @@ 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
 
 #### The command API
@@ -415,8 +422,51 @@ 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

@@ -20,7 +20,7 @@ class Pry
     # This method should not need to be accessed directly.
     # @return [Pry] The active Pry instance.
     attr_accessor :active_instance
-    
+
     # Get/Set the object to use for input by default by all Pry instances.
     # @return [#readline] The object to use for input by default by all
     #   Pry instances.
@@ -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

@@ -12,7 +12,7 @@ class Pry
   # @param [Hash] options The optional configuration parameters.
   # @option options [#readline] :input The object to use for input. (see input.rb)
   # @option options [#puts] :output The object to use for output. (see output.rb)
-  # @option options [Pry::CommandBase] :commands The object to use for 
+  # @option options [Pry::CommandBase] :commands The object to use for
   #   commands. (see commands.rb)
   # @option options [Hash] :hooks The defined hook Procs (see hooks.rb)
   # @option options [Array<Proc>] :default_prompt The array of Procs
@@ -45,13 +45,25 @@ 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.
   def exec_hook(hook_name, *args, &block)
     hooks[hook_name].call(*args, &block) if hooks[hook_name]
   end
-  
+
   # Start a read-eval-print-loop.
   # If no parameter is given, default to top-level (main).
   # @param [Object, Binding] target The receiver of the Pry session
@@ -63,7 +75,7 @@ class Pry
     target_self = target.eval('self')
 
     exec_hook :before_session, output, target_self
-    
+
     # cannot rely on nesting.level as
     # nesting.level changes with new sessions
     nesting_level = nesting.size
@@ -73,26 +85,26 @@ class Pry
     # Make sure special locals exist
     target.eval("_pry_ = Pry.active_instance")
     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) 
+        rep(target)
       end
     end
 
     nesting.pop
-    
+
     exec_hook :after_session, output, target_self
 
     # keep throwing until we reach the desired nesting level
     if nesting_level != break_level
-      throw :breakout, break_level 
+      throw :breakout, break_level
     end
-    
+
     target_self
   end
-  
+
   # Perform a read-eval-print.
   # If no parameter is given, default to top-level (main).
   # @param [Object, Binding] target The receiver of the read-eval-print
@@ -152,11 +164,11 @@ class Pry
 
       process_commands(val, eval_string, target)
       eval_string << "#{val}\n"
-      
+
       break eval_string if valid_expression?(eval_string)
     end
   end
-  
+
   # Process Pry commands. Pry commands are not Ruby methods and are evaluated
   # prior to Ruby expressions.
   # Commands can be modified/configured by the user: see `Pry::Commands`
@@ -174,7 +186,7 @@ class Pry
 
     if pattern
       last_match = Regexp.last_match
-      
+
       options = {
         :captures => last_match ? last_match.captures : nil,
         :eval_string => eval_string,
@@ -208,7 +220,7 @@ class Pry
         input.readline
       end
     end
-  end    
+  end
 
   # Returns the appropriate prompt to use.
   # This method should not need to be invoked directly.
@@ -217,7 +229,7 @@ class Pry
   # @param [Object] target_self The receiver of the Pry session.
   # @return [String] The prompt.
   def select_prompt(first_line, target_self)
-    
+
     if first_line
       Array(prompt).first.call(target_self, nesting.level)
     else
@@ -238,10 +250,10 @@ class Pry
     def valid_expression?(code)
       !!Ripper::SexpBuilder.new(code).parse
     end
-    
+
   else
     require 'ruby_parser'
-    
+
     # Determine if a string of code is a valid Ruby expression.
     # Ruby 1.9 uses Ripper, Ruby 1.8 uses RubyParser.
     # @param [String] code The code to validate.
@@ -257,7 +269,7 @@ class Pry
       true
     end
   end
-  
+
   # Return a `Binding` object for `target` or return `target` if it is
   # already a `Binding`.
   # In the case where `target` is top-level then return `TOPLEVEL_BINDING`