pry 0.6.9pre1-i386-mingw32 → 0.7.0-i386-mingw32

data/CHANGELOG

@@ -1,3 +1,8 @@
+15/3/2011 version 0.7.0
+* add pry-doc support with syntax highlighting for docs
+* add 'mj' option to ls (restrict to singleton methods)
+* add _ex_ local to hold last exception raised in an exception
+
 6/3/2011 version 0.6.8
 * add whereami command, a la the `ir_b` gem
 * make whereami run at the start of every session

data/README.markdown

@@ -22,9 +22,14 @@ is trivial to set it to read from any object that has a `readline` method and wr
 `puts` method - many other aspects of Pry are also configurable making
 it a good choice for implementing custom shells.
 
-Pry now comes with an executable so it can be invoked at the command line.
+Pry comes with an executable so it can be invoked at the command line.
 Just enter `pry` to start. A `.pryrc` file in the user's home directory will
-be loaded if it exists. Type `pry --help` at the command line for more information.
+be loaded if it exists. Type `pry --help` at the command line for more
+information.
+
+Try `gem install pry-doc` for additional documentation on Ruby Core
+methods. The additional docs are accessed through the `show-doc` and
+`show-method` commands.
 
 * Install the [gem](https://rubygems.org/gems/pry): `gem install pry`
 * Read the [documentation](http://rdoc.info/github/banister/pry/master/file/README.markdown)
@@ -163,10 +168,12 @@ end.
 ###Features:
 
 * Pry can be invoked at any time and on any object in the running program.
+* Additional documentation and source code for Ruby Core methods are supported when the `pry-doc` gem is installed.
 * Pry sessions can nest arbitrarily deeply -- to go back one level of nesting type 'exit' or 'quit' or 'back'
 * Pry comes with syntax highlighting on by default just use the `toggle-color` command to turn it on and off.
 * Use `_` to recover last result.
 * Use `_pry_` to reference the Pry instance managing the current session.
+* Use `_ex_` to recover the last exception.
 * Pry supports tab completion.
 * Pry has multi-line support built in.
 * Use `^d` (control-d) to quickly break out of a session.

data/Rakefile

@@ -21,13 +21,12 @@ def apply_spec_defaults(s)
   s.require_path = 'lib'
   s.add_dependency("ruby_parser",">=2.0.5")
   s.add_dependency("coderay",">=0.9.7")
-  s.add_dependency("yard",">=0.6.4")
   s.add_development_dependency("bacon",">=1.1.0")
   s.homepage = "http://banisterfiend.wordpress.com"
   s.has_rdoc = 'yard'
   s.executables = ["pry"]
   s.files = Dir["ext/**/extconf.rb", "ext/**/*.h", "ext/**/*.c", "lib/**/*", "examples/**/*.rb",
-                     "test/*.rb", "test/testrc", "CHANGELOG", "LICENSE", "README.markdown", "Rakefile", ".gemtest"]
+                "test/*.rb", "test/testrc", "CHANGELOG", "LICENSE", "README.markdown", "Rakefile", ".gemtest"]
 end
 
 task :test do

data/lib/pry.rb

@@ -4,6 +4,7 @@
 direc = File.dirname(__FILE__)
 
 $LOAD_PATH << File.expand_path(direc)
+$LOAD_PATH << "."
 
 require "method_source"
 require 'shellwords'

data/lib/pry/commands.rb

@@ -3,6 +3,11 @@ require "method_source"
 require "pry/command_base"
 require "pry/pry_instance"
 
+begin
+  require "pry-doc"
+rescue LoadError
+end
+
 class Pry
 
   # Default commands used by Pry.
@@ -30,6 +35,29 @@ class Pry
       text.split.drop(1).join(' ')
     end
 
+    get_method_object = lambda do |meth_name, target, options|
+      if options[:M]
+        target.eval("instance_method(:#{meth_name})")
+      elsif options[:m]
+        target.eval("method(:#{meth_name})")
+      else
+        begin
+          target.eval("instance_method(:#{meth_name})")
+        rescue
+          target.eval("method(:#{meth_name})")
+        end
+      end
+    end
+
+    make_header = lambda do |file, line, code_type|
+      header = case code_type
+               when :ruby
+                 "--\nFrom #{file} @ line #{line}:\n--"
+               else
+                 "--\nFrom Ruby Core (C Method):\n--"
+               end
+    end
+
     command "!", "Clear the input buffer. Useful if the parsing process goes wrong and you get stuck in the read loop." do
       output.puts "Input buffer cleared!"
       opts[:eval_string].clear
@@ -90,62 +118,6 @@ class Pry
       output.puts "Last result: #{Pry.view(Pry.last_result)}"
     end
 
-    # FIXME!!! some methods, e.g Kernel#tap actually require
-    # Object#tap in order to retrieve their docs!!!
-    begin
-      require "yard"
-      if RUBY_VERSION =~ /1.9/
-        YARD::Registry.load_yardoc("#{File.dirname(__FILE__)}/core_docs_19")
-      else
-        YARD::Registry.load_yardoc("#{File.dirname(__FILE__)}/core_docs_18")
-      end
-
-      yard_cache = {}
-      
-      command "doc" do |meth_name|
-        begin
-          meth = target.eval("method(:#{meth_name})")
-        rescue
-          begin
-            meth = target.eval("instance_method(:#{meth_name})")
-          rescue
-            output.puts "Error could not find method: #{meth_name}"
-            next
-          end
-        end
-
-        if meth.source_location
-          file = meth.source_location.first
-          if !yard_cache[file]
-            log.enter_level(Logger::FATAL) do
-              YARD.parse(file)
-            end
-            yard_cache[file] = true
-          end
-        end
-
-        if meth.owner.name # instance method
-          klassinst, klass = '#', meth.owner.name
-        else # class method
-          klassinst, klass = '.', meth.owner.to_s[/#<.+?:(.+?)>/, 1]
-        end
-
-        obj = YARD::Registry.at([klass, meth.name].join(klassinst))
-        
-        if obj.nil? && meth.owner == Kernel 
-          obj = YARD::Registry.at(["Object", meth.name].join(klassinst))
-        end
-
-        if obj
-          output.puts CodeRay.scan(obj.docstring, :plain).term
-        else
-          output.puts "Couldn't find docs for: #{meth_name}"
-        end
-      end
-
-    rescue LoadError
-    end
-      
     command "whereami", "Show the code context for the session." do
       file = target.eval('__FILE__')
       line_num = target.eval('__LINE__')
@@ -184,7 +156,6 @@ class Pry
       end
     end
     
-
     command "version", "Show Pry version." do
       output.puts "Pry version: #{Pry::VERSION} on Ruby #{RUBY_VERSION}."
     end
@@ -247,6 +218,10 @@ Shows local and instance variables by default.
 
         opts.on("-p", "--private", "Display private methods (with -m).") do 
           options[:p] = true
+        end
+
+        opts.on("-j", "--just-singletons", "Display just the singleton methods (with -m).") do 
+          options[:j] = true
         end        
 
         opts.on("-s", "--super", "Include superclass entries (relevant to constant and methods options).") do 
@@ -281,7 +256,7 @@ Shows local and instance variables by default.
                      }) if options.empty? || (options.size == 1 && options[:v])
 
       # Display public methods by default if -m or -M switch is used.
-      options[:P] = true if (options[:m] || options[:M]) && !(options[:p] || options[:r])
+      options[:P] = true if (options[:m] || options[:M]) && !(options[:p] || options[:r] || options[:j])
       
       info = {}
       target_self = target.eval('self')
@@ -310,6 +285,8 @@ Shows local and instance variables by default.
       info["protected methods"] = [Array(target.eval("protected_methods(#{options[:s]})")).sort, i += 1] if (options[:m] && options[:r]) || options[:a]
 
       info["private methods"] = [Array(target.eval("private_methods(#{options[:s]})")).sort, i += 1] if (options[:m] && options[:p]) || options[:a]
+
+      info["just singleton methods"] = [Array(target.eval("methods(#{options[:s]})")).sort, i += 1] if (options[:m] && options[:j]) || options[:a]
       
       info["public instance methods"] = [Array(target.eval("public_instance_methods(#{options[:s]})")).uniq.sort, i += 1] if target_self.is_a?(Module) && ((options[:M] && options[:P]) || options[:a])
 
@@ -345,6 +322,7 @@ Shows local and instance variables by default.
       # plain
       else
         list = info.values.sort_by { |v| v.last }.map { |v| v.first }.inject(&:+)
+        list.uniq! if list
         if Pry.color
           output.puts CodeRay.scan(Pry.view(list), :ruby).term
         else
@@ -431,11 +409,23 @@ e.g: eval-file -c self "hello.rb"
       if obj == "/" 
         throw(:breakout, 1) if opts[:nesting].level > 0
         next
-      end
+      end    
 
       target.eval("#{obj}.pry")
     end
 
+    process_comment_markup = lambda do |comment, code_type|
+      comment.gsub(/<code>(?:\s*\n)?(.*?)\s*<\/code>/m) { Pry.color ? CodeRay.scan($1, code_type).term : $1 }.
+        gsub(/<em>(?:\s*\n)?(.*?)\s*<\/em>/m) { Pry.color ? "\e[32m#{$1}\e[0m": $1 }.
+        gsub(/<i>(?:\s*\n)?(.*?)\s*<\/i>/m) { Pry.color ? "\e[34m#{$1}\e[0m" : $1 }.
+        gsub(/\B\+(\w*?)\+\B/)  { Pry.color ? "\e[32m#{$1}\e[0m": $1 }.
+        gsub(/((?:^[ \t]+.+(?:\n+|\Z))+)/)  { Pry.color ? CodeRay.scan($1, code_type).term : $1 }
+    end
+
+    strip_leading_hash_from_ruby_comments = lambda do |comment|
+      comment.gsub /^\s*#\s*/, ''
+    end
+
     command "show-doc", "Show the comments above METH. Type `show-doc --help` for more info." do |*args|
       options = {}
       target = target()
@@ -443,14 +433,18 @@ e.g: eval-file -c self "hello.rb"
       
       OptionParser.new do |opts|
         opts.banner = %{Usage: show-doc [OPTIONS] [METH]
-Show the comments above method METH. Shows _method_ comments (rather than instance methods) by default.
+Show the comments above method METH. Tries instance methods first and then methods by default.
 e.g show-doc hello_method
 --
 }
-        opts.on("-M", "--instance-methods", "Operate on instance methods instead.") do 
+        opts.on("-M", "--instance-methods", "Operate on instance methods.") do 
           options[:M] = true
         end
 
+        opts.on("-m", "--methods", "Operate on methods.") do 
+          options[:m] = true
+        end
+
         opts.on("-c", "--context CONTEXT", "Select object context to run under.") do |context|
           target = Pry.binding_for(target.eval(context))
         end
@@ -471,30 +465,46 @@ e.g show-doc hello_method
       end
       
       begin
-        if options[:M]
-          meth = target.eval("instance_method(:#{meth_name})")
-        else
-          meth = target.eval("method(:#{meth_name})")
-        end
+        meth = get_method_object.call(meth_name, target, options)
       rescue
         output.puts "Invalid method name: #{meth_name}. Type `show-doc --help` for help"
         next
       end
 
-      doc = meth.comment
+      code_type = :ruby
+      if Pry.has_pry_doc && meth.source_location.nil?
+        info = Pry::MethodInfo.info_for(meth)
+        if !info
+          output.puts "Cannot find docs for C method: #{meth_name}"
+          next
+        end
+        doc = info.docstring
+        code_type = info.source_type
+      else
+        begin
+          doc = meth.comment
+        rescue
+          output.puts "Cannot locate source for this method: #{meth_name}. Try `gem install pry-doc` to get access to Ruby Core documentation."
+          next
+        end
+        doc = strip_leading_hash_from_ruby_comments.call(doc)
+      end
+
+      doc = process_comment_markup.call(doc, code_type)
+      
       file, line = meth.source_location
       check_for_dynamically_defined_method.call(file)
 
-      output.puts "--\nFrom #{file} @ line ~#{line}:\n--"
-
-      if Pry.color
-        doc = CodeRay.scan(doc, :ruby).term
-      end
-
+      output.puts make_header.call(file, line, code_type)
+      
       output.puts doc
       doc
     end
 
+    strip_comments_from_c_code = lambda do |code|
+      code.sub /\A\s*\/\*.*?\*\/\s*/m, ''
+    end
+    
     command "show-method", "Show the source for METH. Type `show-method --help` for more info." do |*args|
       options = {}
       target = target()
@@ -502,14 +512,18 @@ e.g show-doc hello_method
       
       OptionParser.new do |opts|
         opts.banner = %{Usage: show-method [OPTIONS] [METH]
-Show the source for method METH. Shows _method_ source (rather than instance methods) by default.
+Show the source for method METH. Tries instance methods first and then methods by default.
 e.g: show-method hello_method
 --
 }
-        opts.on("-M", "--instance-methods", "Operate on instance methods instead.") do 
+        opts.on("-M", "--instance-methods", "Operate on instance methods.") do 
           options[:M] = true
         end
 
+        opts.on("-m", "--methods", "Operate on methods.") do 
+          options[:m] = true
+        end
+
         opts.on("-c", "--context CONTEXT", "Select object context to run under.") do |context|
           target = Pry.binding_for(target.eval(context))
         end
@@ -526,36 +540,46 @@ e.g: show-method hello_method
 
       # If no method name is given then use current method, if it exists
       meth_name = meth_name_from_binding.call(target) if !meth_name
-
       if !meth_name
         output.puts "You need to specify a method. Type `show-method --help` for help"
         next
       end
       
       begin
-        if options[:M]
-          meth = target.eval("instance_method(:#{meth_name})")
-        else
-          meth = target.eval("method(:#{meth_name})")
-        end
+        meth = get_method_object.call(meth_name, target, options)
       rescue
-        target_self = target.eval('self')
-        if !options[:M]&& target_self.is_a?(Module) &&
-            target_self.method_defined?(meth_name)
-          output.puts "Did you mean: show-method -M #{meth_name} ?"
-        end
         output.puts "Invalid method name: #{meth_name}. Type `show-method --help` for help"
         next
       end
 
-      code = meth.source
+      code_type = :ruby
+
+      # Try to find source for C methods using MethodInfo (if possible)
+      if Pry.has_pry_doc && meth.source_location.nil?
+        info = Pry::MethodInfo.info_for(meth)
+        if !info
+          output.puts "Cannot find source for C method: #{meth_name}"
+          next
+        end
+        code = info.source
+        code = strip_comments_from_c_code.call(code)
+        code_type = info.source_type
+      else
+        begin
+          code = meth.source
+        rescue
+          output.puts "Cannot locate source for this method: #{meth_name}. Try `gem install pry-doc` to get access to Ruby Core documentation."
+          next
+        end
+      end
+      
       file, line = meth.source_location
       check_for_dynamically_defined_method.call(file)
       
-      output.puts "--\nFrom #{file} @ line #{line}:\n--"
+      output.puts make_header.call(file, line, code_type)
 
       if Pry.color
-        code = CodeRay.scan(code, :ruby).term
+        code = CodeRay.scan(code, code_type).term
       end
       
       output.puts code

data/lib/pry/pry_class.rb

@@ -17,6 +17,11 @@ class Pry
     # @return [Object] The last result.
     attr_accessor :last_result
 
+    # Get last exception raised.
+    # This method should not need to be accessed directly.
+    # @return [Exception] The last exception.
+    attr_accessor :last_exception
+
     # Get the active Pry instance that manages the active Pry session.
     # This method should not need to be accessed directly.
     # @return [Pry] The active Pry instance.
@@ -73,6 +78,10 @@ class Pry
     # Set to true if Pry is invoked from command line using `pry` executable
     # @return [Boolean]
     attr_accessor :cli
+
+    # Set to true if the pry-doc extension is loaded.
+    # @return [Boolean]
+    attr_accessor :has_pry_doc
   end
 
   # Load the rc files given in the `Pry::RC_FILES` array.

data/lib/pry/pry_instance.rb

@@ -135,19 +135,20 @@ class Pry
       Readline.completion_proc = Pry::InputCompleter.build_completion_proc(target, commands.commands.keys)
     end
 
-    # eval the expression and save to last_result
-    Pry.last_result = target.eval r(target), __FILE__, __LINE__
 
     # save the pry instance to active_instance
     Pry.active_instance = self
-
-    # define locals _pry_ and _ (active instance and last expression)
     target.eval("_pry_ = Pry.active_instance")
-    target.eval("_ = Pry.last_result")
+
+    # eval the expression and save to last_result
+    # Do not want __FILE__, __LINE__ here because we need to distinguish
+    # (eval) methods for show-method and friends.
+    # This also sets the `_` local for the session.
+    set_last_result(target.eval(r(target)), target)
   rescue SystemExit => e
     exit
   rescue Exception => e
-    e
+    set_last_exception(e, target)
   end
 
   # Perform a read.
@@ -188,6 +189,22 @@ class Pry
     end
   end
 
+  # Set the last result of an eval.
+  # @param [Object] result The result.
+  # @param [Binding] target The binding to set `_` on.
+  def set_last_result(result, target)
+    Pry.last_result = result
+    target.eval("_ = Pry.last_result")
+  end
+
+  # Set the last exception for a session.
+  # @param [Exception] ex The exception.
+  # @param [Binding] target The binding to set `_ex_` on.
+  def set_last_exception(ex, target)
+    Pry.last_exception = ex
+    target.eval("_ex_ = Pry.last_exception")
+  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`