pry 0.1.0 → 0.2.0

data/CHANGELOG

@@ -1,3 +1,7 @@
+9/12/2010 version 0.1.3
+* Got rid of rubygems dependency, refactored some code.
+8/12/2010 version 0.1.2
+* now rescuing SyntaxError as well as Racc::Parser error in valid_expression?
 8/12/2010 version 0.1.0
 * release!
 	

data/README.markdown

@@ -3,21 +3,23 @@ Pry
 
 (C) John Mair (banisterfiend) 2010
 
-_attach an irb-like session to any object_
+_attach an irb-like session to any object at runtime_
 
-Pry is a simple Ruby REPL that specializes in the interactive
+Pry is a simple Ruby REPL (Read-Eval-Print-Loop) that specializes in the interactive
 manipulation of objects during the running of a program.
 
+It is not based on the IRB codebase and is small, at around 260 LOC.
+
 * 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: prying on an object at runtime 
+example: Interacting with an object at runtime 
 ---------------------------------------
 
-With the `Pry.into()` method we can pry (open an irb-like session) on
+With the `Pry.start()` 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 program is halted for the duration of the session.
+an instance variable. The current thread is halted for the duration of the session.
 
     require 'pry'
     
@@ -25,7 +27,7 @@ an instance variable. The program is halted for the duration of the session.
       def self.hello() "hello world" end
     end
 
-    Pry.into(Test)
+    Pry.start(Test)
 
     # Pry session begins on stdin
     Beginning Pry session for Test
@@ -44,49 +46,85 @@ If we now inspect the `Test` object we can see our changes have had
 effect:
 
     Test.instance_variable_get(:@y) #=> 20
-    
 
+#### Alternative Syntax
+
+You can also use the `obj.pry` or `pry(obj)` syntax to start a pry session on
+`obj`. e.g
+
+    5.pry
+    Beginning Pry session for 5
+    pry(5)>
+
+OR
+
+    pry 6
+    beginning Pry session for 6
+    pry(6)>
+    
 example: Pry sessions can nest arbitrarily deep so we can pry on objects inside objects:
 ----------------------------------------------------------------------------------------
 
 Here we will begin Pry at top-level, then pry on a class and then on
 an instance variable inside that class:
 
-    # Pry.into() without parameters begins a Pry session on top-level (main)
-    Pry.into
+    # Pry.start() without parameters begins a Pry session on top-level (main)
+    Pry.start
     Beginning Pry session for main
     pry(main)> class Hello
     pry(main)*   @x = 20
     pry(main)* end
     => 20
-    pry(main)> Pry.into Hello
+    pry(main)> Pry.start Hello
     Beginning Pry session for Hello
-    pry(Hello)> instance_variables
+    pry(Hello):1> instance_variables
     => [:@x]
-    pry(Hello)> Pry.into @x
+    pry(Hello):1> Pry.start @x
     Beginning Pry session for 20
-    pry(20)> self + 10
+    pry(20:2)> self + 10
     => 30
-    pry(20)> exit
+    pry(20:2)> exit
     Ending Pry session for 20
-    pry(Hello)> exit
+    pry(Hello):1> exit
     Ending Pry session for Hello
     pry(main)> exit
     Ending Pry session for main
 
-    # program resumes here
+The number after the `:` in the pry prompt indicates the nesting
+level. To display more information about nesting, use the `nesting`
+command. E.g
+
+    pry("friend":3)> nesting
+    Nesting status:
+    0. main (Pry top level)
+    1. Hello
+    2. 100
+    3. "friend"
+    => nil
+    
+We can then jump back to any of the previous nesting levels by using
+the `jump_to` command:
 
+    pry("friend":3)> jump_to 1
+    Ending Pry session for "friend"
+    Ending Pry session for 100
+    => 100
+    pry(Hello):1>
 
-example: Spawn a separate thread so you can use `Pry` to manipulate an
-object without halting the program. 
----------------------------------------------------------------------------------------------------
+If we just want to go back one level of nesting we can of course 
+use the `quit` or `exit` or `back` commands.
 
-If we embed our `Pry.into` method inside its own thread we can examine
-and manipulate objects without halting the program.
+To break out of all levels of Pry nesting and return immediately to the
+calling process use `exit_all`:
 
-    # Pry.into() without parameters opens up the top-level (main)
-    Thread.new { Pry.into }
+    pry("friend":3)> exit_all
+    Ending Pry session for "friend"
+    Ending Pry session for 100
+    Ending Pry session for Hello
+    Ending Pry session for main
+    => main
     
+    # program resumes here
 
 Features and limitations
 ------------------------
@@ -102,11 +140,15 @@ end.
 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'
+* Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
+* Use `_` to recover last result.
 * Pry has multi-line support built in.
+* Pry gives good control over nested sessions (important when exploring complicated runtime state)
+* Pry is not based on the IRB codebase.
+* Pry is small; around 260 LOC.
 * Pry implements all the methods in the REPL chain separately: `Pry.r`
 for reading; `Pry.re` for eval; `Pry.rep` for printing; and `Pry.repl`
-for the loop (`Pry.into` is simply an alias for `Pry.repl`). You can
+for the loop (`Pry.start` is simply an alias for `Pry.repl`). You can
 invoke any of these methods directly depending on exactly what aspect of the functionality you need.
 
 Limitations:
@@ -123,6 +165,53 @@ Limitations:
   hash literal syntax (this: syntax) or the 'stabby lambda' syntax
   (->).
  
+Commands
+-----------
+
+### The Pry API:
+
+* `Pry.start()` and `Pry.into()` and `Pry.repl()` are all aliases of
+oneanother. They all start a Read-Eval-Print-Loop on the object they
+receive as a parameter. In the case of no parameter they operate on
+top-level (main). They can receive any object or a `Binding`
+object as parameter.
+* `obj.pry` and `pry(obj)` may also be used as alternative syntax to `Pry.start(obj)`
+* If, for some reason you do not want to 'loop' then use `Pry.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()`
+* 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()`
+* Similarly `Pry.r()` only performs the Read section of the REPL, only
+returning the Ruby expression (as a string). It takes the same parameters as all the others.
+
+### Session commands
+
+Pry supports a few commands inside the session itself. These commands are
+not methods and must start at the beginning of a line, with no
+whitespace in between.
+
+If you want to access a method of the same name, prefix the invocation by whitespace.
+
+* Typing `!` on a line by itself will refresh the REPL - useful for
+  getting you out of a situation if the parsing process
+  goes wrong.
+* `status` shows status information about the current session.
+* `help` shows the list of session commands with brief explanations.
+* `exit` or `quit` or `back` will end the current Pry session and go
+  back to the calling process or back one level of nesting (if there
+  are nested sessions).
+* `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
+  -- as per the output of `nesting`
+* `exit_all` breaks out of all Pry nesting levels and returns to the
+  calling process.
+* You can type `Pry.start(obj)` or `obj.pry` to nest another Pry session within the
+  current one with `obj` as the receiver of the new session. Very useful
+  when exploring large or complicated runtime state.
 
 Contact
 -------

data/Rakefile

@@ -12,7 +12,7 @@ CLEAN.include("ext/**/*.#{dlext}", "ext/**/*.log", "ext/**/*.o",
 
 def apply_spec_defaults(s)
   s.name = "pry"
-  s.summary = "attach an irb-like session to any object"
+  s.summary = "attach an irb-like session to any object at runtime"
   s.version = Pry::VERSION
   s.date = Time.now.strftime '%Y-%m-%d'
   s.author = "John Mair (banisterfiend)"

data/lib/pry/input.rb

@@ -0,0 +1,9 @@
+require 'readline'
+
+module Pry
+  class Input
+    def read(prompt)
+      Readline.readline(prompt, true)
+    end
+  end
+end

data/lib/pry/output.rb

@@ -0,0 +1,67 @@
+module Pry
+  class Output
+    def refresh
+      puts "Refreshed REPL"
+    end
+
+    def session_start(obj)
+      puts "Beginning Pry session for #{obj.inspect}"
+    end
+
+    def session_end(obj)
+      puts "Ending Pry session for #{obj.inspect}"
+    end
+
+    # the print component of READ-EVAL-PRINT-LOOP
+    def print(value)
+      case value
+      when Exception
+        puts "#{value.class}: #{value.message}"
+      else
+        puts "=> #{value.inspect}"
+      end
+    end
+
+    def show_help
+      puts "Command list:"
+      puts "--"
+      puts "help                             This menu"
+      puts "status                           Show status information"
+      puts "!                                Refresh the REPL"
+      puts "nesting                          Show nesting information"
+      puts "exit/quit/back                   End the current Pry session"
+      puts "exit_all                         End all nested Pry sessions"
+      puts "exit_program/quit_program        End the current program"
+      puts "jump_to <level>                  Jump to a Pry session further up the stack, exiting all sessions below"
+    end
+
+    def show_nesting(nesting)
+      puts "Nesting status:"
+      puts "--"
+      nesting.each do |level, obj|
+        if level == 0
+          puts "#{level}. #{obj.inspect} (Pry top level)"
+        else
+          puts "#{level}. #{obj.inspect}"
+        end
+      end
+    end
+
+    def show_status(nesting, target)
+      puts "Status:"
+      puts "--"
+      puts "Receiver: #{target.eval('self').inspect}"
+      puts "Nesting level: #{nesting.level}"
+      puts "Local variables: #{target.eval("local_variables").inspect}"
+      puts "Last result: #{Pry.last_result.inspect}"
+    end
+
+    def error_invalid_nest_level(nest_level, max_nest_level)
+      puts "Invalid nest level. Must be between 0 and #{max_nest_level}. Got #{nest_level}."
+    end
+
+    def exit() end
+    def jump_to(nesting_level_breakout) end
+    def exit_program() end
+  end
+end

data/lib/pry/version.rb

@@ -1,3 +1,3 @@
 module Pry
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/pry.rb

@@ -1,35 +1,79 @@
-require 'rubygems'
-require 'readline'
+# (C) John Mair (banisterfiend) 2010
+# MIT License
+
+direc = File.dirname(__FILE__)
+
 require 'ruby_parser'
+require "#{direc}/pry/version"
+require "#{direc}/pry/input"
+require "#{direc}/pry/output"
 
 module Pry
+  
+  # class accessors
   class << self
-    attr_accessor :default_prompt, :wait_prompt,
-    :session_start_msg, :session_end_msg
+    attr_reader :nesting
+    attr_reader :last_result
+    attr_accessor :default_prompt
+    attr_accessor :wait_prompt
+    attr_accessor :input
+    attr_accessor :output
+  end
+  
+  @default_prompt = lambda do |v, nest|
+    if nest == 0
+      "pry(#{v.inspect})> "
+    else
+      "pry(#{v.inspect}):#{nest.inspect}> "
+    end
+  end
+  
+  @wait_prompt = lambda do |v, nest|
+    if nest == 0
+      "pry(#{v.inspect})* "
+    else
+      "pry(#{v.inspect}):#{nest.inspect}* "
+    end
   end
   
-  @default_prompt = proc { |v| "pry(#{v})> " }
-  @wait_prompt = proc { |v| "pry(#{v})* " }
-  @session_start_msg = proc { |v| "Beginning Pry session for #{v}" }
-  @session_end_msg = proc { |v| "Ending Pry session for #{v}" }
+  @output = Output.new
+  @input = Input.new
+  
+  @nesting = []
+
+  def @nesting.level
+    last.is_a?(Array) ? last.first : nil
+  end
   
   # loop
   def self.repl(target=TOPLEVEL_BINDING)
-    if !target.is_a?(Binding)
-      target = target.instance_eval { binding }
-    end
-    
-    puts session_start_msg.call(target.eval('self'))
+    target = binding_for(target)
+    target_self = target.eval('self')
+    output.session_start(target_self)
 
-    loop do
-      if catch(:pop) { rep(target) } == :return
-        break target.eval('self')
+    nesting_level = @nesting.size
+
+    # Make sure _ exists
+    target.eval("_ = Pry.last_result")
+    
+    nesting_level_breakout = catch(:breakout) do
+      @nesting << [@nesting.size, target_self]
+      loop do
+         rep(target) 
       end
     end
 
-    puts session_end_msg.call(target.eval('self'))
-  end
+    @nesting.pop
+    output.session_end(target_self)
 
+    # we only enter here if :breakout has been thrown
+    if nesting_level_breakout
+      throw :breakout, nesting_level_breakout if nesting_level != nesting_level_breakout
+    end
+    
+    target_self
+  end
+  
   class << self
     alias_method :into, :repl
     alias_method :start, :repl
@@ -37,31 +81,25 @@ module Pry
   
   # print
   def self.rep(target=TOPLEVEL_BINDING)
-    if !target.is_a?(Binding)
-      target = target.instance_eval { binding }
-    end
-
-    value = re(target)
-    case value
-    when Exception
-      puts "#{value.class}: #{value.message}"
-    else
-      puts "=> #{value.inspect}"
-    end
+    target = binding_for(target)
+    output.print re(target)
   end
 
   # eval
   def self.re(target=TOPLEVEL_BINDING)
-    target.eval r(target)
+    target = binding_for(target)
+    @last_result = target.eval r(target)
+    target.eval("_ = Pry.last_result")
   rescue StandardError => e
     e
   end
 
   # read
   def self.r(target=TOPLEVEL_BINDING)
+    target = binding_for(target)
     eval_string = ""
     loop do
-      val = Readline.readline(prompt(eval_string, target), true)
+      val = input.read(prompt(eval_string, target, nesting.level))
       eval_string += "#{val}\n"
       process_commands(val, eval_string, target)
       
@@ -70,32 +108,79 @@ module Pry
   end
   
   def self.process_commands(val, eval_string, target)
+    def eval_string.clear() replace("") end
+    
     case val
-    when "#exit", "#quit"
+    when "exit_program", "quit_program"
+      output.exit_program
       exit
     when "!"
-      eval_string.replace("")
-      puts "Refreshed REPL."
-    when "exit", "quit"
-      throw(:pop, :return)
+      output.refresh
+      eval_string.clear
+    when "help"
+      output.show_help
+      eval_string.clear
+    when "nesting"
+      output.show_nesting(nesting)
+      eval_string.clear
+    when "status"
+      output.show_status(nesting, target)
+      eval_string.clear
+    when "exit_all"
+      throw(:breakout, 0)
+    when "exit", "quit", "back"
+      output.exit
+      throw(:breakout, nesting.level)
+    when /jump_to\s*(\d*)/
+      nesting_level_breakout = ($~.captures).first.to_i
+      output.jump_to(nesting_level_breakout)
+      
+      if nesting_level_breakout < 0 || nesting_level_breakout >= nesting.level
+        output.error_invalid_nest_level(nesting_level_breakout, nesting.level - 1)
+        eval_string.clear
+      else
+        throw(:breakout, nesting_level_breakout + 1)
+      end
     end
   end
 
-  def self.prompt(eval_string, target)
-    context = target.eval('self')
+  def self.prompt(eval_string, target, nest)
+    target_self = target.eval('self')
     
     if eval_string.empty?
-      default_prompt.call(context)
+      default_prompt.call(target_self, nest)
     else
-      wait_prompt.call(context)
+      wait_prompt.call(target_self, nest)
     end
   end
 
   def self.valid_expression?(code)
     RubyParser.new.parse(code)
-  rescue Racc::ParseError
+  rescue Racc::ParseError, SyntaxError
     false
   else
     true
   end
+
+  def self.binding_for(target)
+    if target.is_a?(Binding)
+      target
+    else
+      if target == TOPLEVEL_BINDING.eval('self')
+        TOPLEVEL_BINDING
+      else
+        target.instance_eval { binding }
+      end
+    end
+  end
+
+  module ObjectExtensions
+    def pry(target=self)
+      Pry.start(Pry.binding_for(target))
+    end
+  end
+end
+
+class Object
+  include Pry::ObjectExtensions
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: pry
 version: !ruby/object:Gem::Version 
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -14,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-09 00:00:00 +13:00
+date: 2010-12-11 00:00:00 +13:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -25,6 +26,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 5
         segments: 
         - 2
         - 0
@@ -32,7 +34,7 @@ dependencies:
         version: 2.0.5
   type: :runtime
   version_requirements: *id001
-description: attach an irb-like session to any object
+description: attach an irb-like session to any object at runtime
 email: jrmair@gmail.com
 executables: []
 
@@ -41,6 +43,8 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/pry/input.rb
+- lib/pry/output.rb
 - lib/pry/version.rb
 - lib/pry.rb
 - CHANGELOG
@@ -60,6 +64,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -68,6 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -77,6 +83,6 @@ rubyforge_project:
 rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
-summary: attach an irb-like session to any object
+summary: attach an irb-like session to any object at runtime
 test_files: []