pry 0.9.8.4 → 0.9.9

data/lib/pry/config.rb

@@ -4,44 +4,82 @@ class Pry
   class Config < OpenStruct
 
     # Get/Set the object to use for input by default by all Pry instances.
+    # Pry.config.input is an option determining the input object - the object from
+    # which Pry retrieves its lines of input. Pry accepts any object that implements the readline method.
+    # This includes IO objects, StringIO, Readline, File and custom objects.
     # @return [#readline] The object to use for input by default by all
     #   Pry instances.
+    # @example
+    #   Pry.config.input = StringIO.new("@x = 10\nexit")
     attr_accessor :input
 
     # Get/Set the object to use for output by default by all Pry instances.
+    # Pry.config.output is an option determining the output object - the object to which
+    # Pry writes its output. Pry accepts any object that implements the puts method. This
+    # includes IO objects, StringIO, File and custom objects.
     # @return [#puts] The object to use for output by default by all
     #   Pry instances.
+    # @example
+    #   Pry.config.output = StringIO.new
     attr_accessor :output
 
     # Get/Set the object to use for commands by default by all Pry instances.
     # @return [Pry::CommandBase] The object to use for commands by default by all
     #   Pry instances.
+    # @example
+    #   Pry.config.commands = Pry::CommandSet.new do
+    #               import_from Pry::Commands, "ls"
+    #
+    #                 command "greet" do |name|
+    #                 output.puts "hello #{name}"
+    #               end
+    #             end
     attr_accessor :commands
 
     # Get/Set the Proc to use for printing by default by all Pry
     # instances.
+    # Two parameters are passed to the print Proc: these are (1) the
+    # output object for the current session and (2) the expression value to print. It is important
+    # that you write to the output object instead of just stdout so that all Pry output can be redirected if necessary.
     # This is the 'print' component of the REPL.
     # @return [Proc] The Proc to use for printing by default by all
     #   Pry instances.
+    # @example
+    #   Pry.config.print = proc { |output, value| output.puts "=> #{value.inspect}" }
     attr_accessor :print
 
+    # Pry.config.exception_handler is an option determining the exception handler object - the
+    # Proc responsible for dealing with exceptions raised by user input to the REPL.
+    # Three parameters are passed to the exception handler Proc: these
+    # are (1) the output object for the current session, (2) the
+    # exception object that was raised inside the Pry session, and (3)
+    # a reference to the associated Pry instance.
     # @return [Proc] The Proc to use for printing exceptions by default by all
     #   Pry instances.
+    # @example
+    #   Pry.config.exception_handler = proc do |output, exception, _|
+    #     output.puts "#{exception.class}: #{exception.message}"
+    #     output.puts "from #{exception.backtrace.first}"
+    #   end
     attr_accessor :exception_handler
 
     # @return [Array] The classes of exception that will not be caught by Pry.
+    # @example
+    #   Pry.config.exception_whitelist = [SystemExit, SignalException]
     attr_accessor :exception_whitelist
 
     # @return [Fixnum] The number of lines of context to show before and after
     #   exceptions, etc.
+    # @example
+    #   Pry.config.default_window_size = 10
     attr_accessor :default_window_size
 
-    # Get/Set the Hash that defines Pry hooks used by default by all Pry
+    # Get/Set the `Pry::Hooks` instance that defines Pry hooks used by default by all Pry
     # instances.
-    # @return [Hash] The hooks used by default by all Pry instances.
+    # @return [Pry::Hooks] The hooks used by default by all Pry instances.
     # @example
-    #   Pry.hooks :before_session => proc { puts "hello" },
-    #     :after_session => proc { puts "goodbye" }
+    #   Pry.config.hooks = Pry::Hooks.new.add_hook(:before_session,
+    #   :default) {  |output, target, _pry_| output.puts "Good morning!" }
     attr_reader :hooks
 
     # FIXME:
@@ -63,23 +101,32 @@ class Pry
     #   Pry.config.input_stack = [StringIO.new("puts 'hello world'\nexit")]
     attr_accessor :input_stack
 
-    # Get the array of Procs to be used for the prompts by default by
+    # Get the array of Procs (or single Proc) to be used for the prompts by default by
     # all Pry instances.
-    # @return [Array<Proc>] The array of Procs to be used for the
+    # Three parameters are passed into the prompt procs, (1) the
+    # object that is the target of the session, (2) the current
+    # nesting level, and (3) a reference to the associated Pry instance. These objects can be used in the prompt, if desired.
+    # @return [Array<Proc>, Proc] The array of Procs to be used for the
     #   prompts by default by all Pry instances.
+    # @example
+    #   Pry.config.prompt = proc { |obj, nest_level, _pry_| "#{obj}:#{nest_level}> " }
     attr_accessor :prompt
 
-    # The default editor to use. Defaults to $EDITOR or nano if
-    # $EDITOR is not defined.
+    # The default editor to use. Defaults to $VISUAL, $EDITOR, or a sensible fallback
+    # for the platform.
     # If `editor` is a String then that string is used as the shell
     # command to invoke the editor. If `editor` is callable (e.g a
-    # Proc) then `file` and `line` are passed in as parameters and the
+    # Proc) then `file`, `line`, and `reloading` are passed in as parameters and the
     # return value of that callable invocation is used as the exact
-    # shell command to invoke the editor.
+    # shell command to invoke the editor. `reloading` indicates whether Pry will be
+    # reloading code after the shell command returns. Any or all of these parameters
+    # can be omitted from the callable's signature.
     # @example String
     #   Pry.config.editor = "emacsclient"
     # @example Callable
     #   Pry.config.editor = proc { |file, line| "emacsclient #{file} +#{line}" }
+    # @example Callable waiting only if reloading
+    #   Pry.config.editor = proc { |file, line, reloading| "subl #{'--wait' if reloading} #{file}:#{line}" }
     # @return [String, #call]
     attr_accessor :editor
 
@@ -171,6 +218,12 @@ class Pry
     #   Pry.config.gist.inspecter = proc &:inspect
     # @return [OpenStruct]
     attr_accessor :gist
+
+    # @return [Hash] Additional sticky locals (to the standard ones) to use in Pry sessions.
+    # @example Inject `random_number` sticky local into Pry session
+    #   Pry.config.extra_sticky_locals = { :random_number => proc {
+    #   rand(10) } }
+    attr_accessor :extra_sticky_locals
   end
 end
 

data/lib/pry/core_extensions.rb

@@ -1,23 +1,29 @@
 class Object
-  # Start a Pry REPL.
-  # This method differs from `Pry.start` in that it does not
-  # support an options hash. Also, when no parameter is provided, the Pry
-  # session will start on the implied receiver rather than on
-  # top-level (as in the case of `Pry.start`).
-  # It has two forms of invocation. In the first form no parameter
-  # should be provided and it will start a pry session on the
-  # receiver. In the second form it should be invoked without an
-  # explicit receiver and one parameter; this will start a Pry
-  # session on the parameter.
-  # @param [Object, Binding] target The receiver of the Pry session.
-  # @example First form
+  # Start a Pry REPL.  This method only differs from Pry.start in that it
+  # assumes that the target is `self`.  It also accepts and passses the same
+  # exact options hash that Pry.start accepts. POSSIBLE DEPRICATION WARNING:
+  # In the future the backwards compatibility with pry(binding) could be
+  # removed so please properly use Object.pry or if you use pry(binding)
+  # switch Pry.start(binding).
+
+  # @param [Binding] the binding or options hash if no binding needed.
+  # @param [Hash] the options hash.
+  # @example First
   #   "dummy".pry
-  # @example Second form
-  #    pry "dummy"
-  # @example Start a Pry session on current self (whatever that is)
-  #   pry
-  def pry(target=self)
-    Pry.start(target)
+  # @example Second
+  #    binding.pry
+  # @example An example with options
+  #   def my_method
+  #     binding.pry :quiet => true
+  #   end
+  #   my_method()
+
+  def pry(*args)
+    if args.first.is_a?(Hash) || args.length == 0
+      args.unshift(self)
+    end
+    
+    Pry.start(*args)
   end
 
   # Return a binding object for the receiver.

data/lib/pry/default_commands/context.rb

@@ -1,5 +1,6 @@
 require "pry/default_commands/ls"
 require "pry/default_commands/cd"
+require "pry/default_commands/find_method"
 
 class Pry
   module DefaultCommands
@@ -7,24 +8,62 @@ class Pry
     Context = Pry::CommandSet.new do
       import Ls
       import Cd
+      import FindMethod
 
-      command "whereami", "Show the code context for the session. (whereami <n> shows <n> extra lines of code around the invocation line. Default: 5)" do |num|
-        file, line_num = file_and_line_from_binding(target)
-        i_num = num ? num.to_i : 5
+      create_command "whereami" do
+        description "Show code surrounding the current context."
+        banner <<-BANNER
+          Usage: whereami [OPTIONS]
+        BANNER
 
-        if file != Pry.eval_path && (file =~ /(\(.*\))|<.*>/ || file == "" || file == "-e")
-          raise CommandError, "Cannot find local context. Did you use binding.pry?"
+        def setup
+          @method = Pry::Method.from_binding(target)
         end
 
-        set_file_and_dir_locals(file)
+        def process
+          if show_method?
+            file   = @method.source_file
+            start  = @method.source_range.begin
+            finish = @method.source_range.end
+            marker = target.eval("__LINE__")
+          else
+            file   = target.eval("__FILE__")
+            start  = target.eval("__LINE__")
+            finish = (args.first && args.first.to_i) || 5
+            marker = start
+          end
+
+          if invalid_file?(file)
+            raise Pry::CommandError,
+            "Cannot find local context. Did you use binding.pry?"
+          end
 
-        method = Pry::Method.from_binding(target)
-        method_description = method ? " in #{method.name_with_owner}" : ""
-        output.puts "\n#{text.bold('From:')} #{file} @ line #{line_num}#{method_description}:\n\n"
+          # TODO: refactor.
+          if show_method?
+            code = Pry::Code.from_file(file).between(start, finish)
+          else
+            code = Pry::Code.from_file(file).around(start, finish)
+          end
+
+          desc = (@method && @method.name_with_owner) || ""
+
+          if !code.empty?
+            output.puts "\n#{text.bold('From:')} #{file} @ line #{start} #{desc}:\n\n"
+            output.puts code.with_line_numbers.with_marker(marker)
+            output.puts
+          end
+        end
 
-        code = Pry::Code.from_file(file).around(line_num, i_num)
-        output.puts code.with_line_numbers.with_marker(line_num)
-        output.puts
+        private
+
+        def show_method?
+          args.empty? && @method && !@method.instance_of?(Pry::Method::Disowned) && @method.source_range.count < 20
+        end
+
+        def invalid_file?(file)
+          file != Pry.eval_path &&
+          (file =~ /(\(.*\))|<.*>/ || file == "" || file == "-e")
+        end
       end
 
       create_command "pry-backtrace", "Show the backtrace for the Pry session." do
@@ -87,6 +126,27 @@ class Pry
         end
       end
 
+      # N.B. using a regular expresion here so that "raise-up 'foo'" does the right thing.
+      create_command /raise-up(!?\b.*)/, :listing => 'raise-up' do
+        description "Raise an exception out of the current pry instance."
+        banner <<-BANNER
+          Raise up, like exit, allows you to quit pry. Instead of returning a value however, it raises an exception.
+          If you don't provide the exception to be raised, it will use the most recent exception (in pry _ex_).
+
+          e.g. `raise-up "get-me-out-of-here"` is equivalent to:
+               `raise "get-me-out-of-here"
+                raise-up`
+
+          When called as raise-up! (with an exclamation mark), this command raises the exception through
+          any nested prys you have created by "cd"ing into objects.
+        BANNER
+
+        def process
+          return stagger_output help if captures[0] =~ /(-h|--help)\b/
+          # Handle 'raise-up', 'raise-up "foo"', 'raise-up RuntimeError, 'farble' in a rubyesque manner
+          target.eval("_pry_.raise_up#{captures[0]}")
+        end
+      end
     end
   end
 end

data/lib/pry/default_commands/easter_eggs.rb

@@ -3,6 +3,10 @@ class Pry
 
     EasterEggs = Pry::CommandSet.new do
 
+      command "nyan-cat", "", :requires_gem => ["nyancat"] do
+        run ".nyancat"
+      end
+
       command(/!s\/(.*?)\/(.*?)/, "") do |source, dest|
         eval_string.gsub!(/#{source}/) { dest }
         run "show-input"

data/lib/pry/default_commands/editing.rb

@@ -88,8 +88,9 @@ class Pry
           temp_file do |f|
             f.puts(content)
             f.flush
-            invoke_editor(f.path, line)
-            if !opts.present?(:'no-reload') && !Pry.config.disable_auto_reload
+            reload = !opts.present?(:'no-reload') && !Pry.config.disable_auto_reload
+            invoke_editor(f.path, line, reload)
+            if reload
               silence_warnings do
                 eval_string.replace(File.read(f.path))
               end
@@ -138,10 +139,11 @@ class Pry
 
           line = opts[:l].to_i if opts.present?(:line)
 
-          invoke_editor(file_name, line)
+          reload = opts.present?(:reload) || ((opts.present?(:ex) || file_name.end_with?(".rb")) && !opts.present?(:'no-reload')) && !Pry.config.disable_auto_reload
+          invoke_editor(file_name, line, reload)
           set_file_and_dir_locals(file_name)
 
-          if opts.present?(:reload) || ((opts.present?(:ex) || file_name.end_with?(".rb")) && !opts.present?(:'no-reload')) && !Pry.config.disable_auto_reload
+          if reload
             silence_warnings do
               TOPLEVEL_BINDING.eval(File.read(file_name), file_name)
             end
@@ -202,17 +204,12 @@ class Pry
         def process_patch
           lines = @method.source.lines.to_a
 
-          if ((original_name = @method.original_name) &&
-              lines[0] =~ /^def (?:.*?\.)?#{original_name}(?=[\(\s;]|$)/)
-            lines[0] = "def #{original_name}#{$'}"
-          else
-            raise CommandError, "Pry can only patch methods created with the `def` keyword."
-          end
+          lines[0] = definition_line_for_owner(lines[0])
 
           temp_file do |f|
             f.puts lines.join
             f.flush
-            invoke_editor(f.path, 0)
+            invoke_editor(f.path, 0, true)
 
             if @method.alias?
               with_method_transaction(original_name, @method.owner) do
@@ -228,9 +225,10 @@ class Pry
         def process_file
           file, line = extract_file_and_line
 
-          invoke_editor(file, opts["no-jump"] ? 0 : line)
+          reload = !opts.present?(:'no-reload') && !Pry.config.disable_auto_reload
+          invoke_editor(file, opts["no-jump"] ? 0 : line, reload)
           silence_warnings do
-            load file unless opts.present?(:'no-reload') || Pry.config.disable_auto_reload
+            load file if reload
           end
         end
 
@@ -257,6 +255,34 @@ class Pry
           ensure
             target.eval("undef #{temp_name}") rescue nil
           end
+
+          # The original name of the method, if it's not present raise an error telling
+          # the user why we don't work.
+          #
+          def original_name
+            @method.original_name or raise CommandError, "Pry can only patch methods created with the `def` keyword."
+          end
+
+          # Update the definition line so that it can be eval'd directly on the Method's
+          # owner instead of from the original context.
+          #
+          # In particular this takes `def self.foo` and turns it into `def foo` so that we
+          # don't end up creating the method on the singleton class of the singleton class
+          # by accident.
+          #
+          # This is necessarily done by String manipulation because we can't find out what
+          # syntax is needed for the argument list by ruby-level introspection.
+          #
+          # @param String   The original definition line. e.g. def self.foo(bar, baz=1)
+          # @return String  The new definition line. e.g. def foo(bar, baz=1)
+          #
+          def definition_line_for_owner(line)
+            if line =~ /^def (?:.*?\.)?#{Regexp.escape(original_name)}(?=[\(\s;]|$)/
+              "def #{original_name}#{$'}"
+            else
+              raise CommandError, "Could not find original `def #{original_name}` line to patch."
+            end
+          end
       end
 
       create_command(/amend-line(?: (-?\d+)(?:\.\.(-?\d+))?)?/) do
@@ -301,6 +327,8 @@ class Pry
       end
 
       create_command "play" do
+        include Helpers::DocumentationHelpers
+
         description "Play back a string variable or a method or a file as input."
 
         banner <<-BANNER
@@ -343,7 +371,7 @@ class Pry
             self.content << File.read(File.expand_path(file))
           end
           opt.on :l, :lines, "Only play a subset of lines.", :optional => true, :as => Range, :default => 1..-1
-          opt.on :i, :in, "Play entries from Pry's input expression history. Takes an index or range.", :optional => true,
+          opt.on :i, :in, "Play entries from Pry's input expression history. Takes an index or range. Note this can only replay pure Ruby code, not Pry commands.", :optional => true,
           :as => Range, :default => -5..-1 do |range|
             input_expressions = _pry_.input_array[range] || []
             Array(input_expressions).each { |v| self.content << v }
@@ -353,7 +381,7 @@ class Pry
 
         def process
           perform_play
-          run "show-input" unless _pry_.complete_expression?(eval_string)
+          run "show-input" unless Pry::Code.complete_expression?(eval_string)
         end
 
         def process_non_opt

data/lib/pry/default_commands/find_method.rb

@@ -0,0 +1,171 @@
+class Pry
+  module DefaultCommands
+    FindMethod = Pry::CommandSet.new do
+
+      create_command "find-method" do
+        extend Helpers::BaseHelpers
+
+        group "Context"
+
+        options :requires_gem => "ruby18_source_location" if mri_18?
+
+        description "Recursively search for a method within a Class/Module or the current namespace. find-method [-n | -c] METHOD [NAMESPACE]"
+
+        banner <<-BANNER
+          Usage: find-method  [-n | -c] METHOD [NAMESPACE]
+
+          Recursively search for a method within a Class/Module or the current namespace.
+          Use the `-n` switch (the default) to search for methods whose name matches the given regex.
+          Use the `-c` switch to search for methods that contain the given code.
+
+          e.g find re Pry                # find all methods whose name match /re/ inside the Pry namespace. Matches Pry#repl, etc.
+          e.g find -c 'output.puts' Pry  # find all methods that contain the code: output.puts inside the Pry namepsace.
+        BANNER
+
+        def setup
+          require 'ruby18_source_location' if mri_18?
+        end
+
+        def options(opti)
+          opti.on :n, :name, "Search for a method by name"
+          opti.on :c, :content, "Search for a method based on content in Regex form"
+        end
+
+        def process
+          return if args.size < 1
+          pattern = ::Regexp.new args[0]
+          if args[1]
+            klass = target.eval(args[1])
+            if !klass.is_a?(Module)
+              klass = klass.class
+            end
+          else
+            klass = (target_self.is_a?(Module)) ? target_self : target_self.class
+          end
+
+          matches = if opts.content?
+                      content_search(pattern, klass)
+                    else
+                      name_search(pattern, klass)
+                    end
+
+          if matches.empty?
+            output.puts text.bold("No Methods Matched")
+          else
+            print_matches(matches, pattern)
+          end
+
+        end
+
+        private
+
+        # pretty-print a list of matching methods.
+        #
+        # @param Array[Method]
+        def print_matches(matches, pattern)
+          grouped = matches.group_by(&:owner)
+          order = grouped.keys.sort_by{ |x| x.name || x.to_s }
+
+          order.each do |klass|
+            output.puts text.bold(klass.name)
+            grouped[klass].each do |method|
+              header = method.name_with_owner
+
+              extra = if opts.content?
+                        header += ": "
+                        colorize_code((method.source.split(/\n/).select {|x| x =~ pattern }).join("\n#{' ' * header.length}"))
+                      else
+                        ""
+                      end
+
+              output.puts header + extra
+            end
+          end
+        end
+
+        # Run the given block against every constant in the provided namespace.
+        #
+        # @param Module  The namespace in which to start the search.
+        # @param Hash[Module,Boolean]  The namespaces we've already visited (private)
+        # @yieldparam klazz  Each class/module in the namespace.
+        #
+        def recurse_namespace(klass, done={}, &block)
+          if done[klass] || !(Module === klass)
+            return
+          end
+
+          done[klass] = true
+
+          yield klass
+
+          klass.constants.each do |name|
+            next if klass.autoload?(name)
+            begin
+              const = klass.const_get(name)
+            rescue RescuableException => e
+              # constant loading is an inexact science at the best of times,
+              # this often happens when a constant was .autoload? but someone
+              # tried to load it. It's now not .autoload? but will still raise
+              # a NameError when you access it.
+            else
+              recurse_namespace(const, done, &block)
+            end
+          end
+        end
+
+        # Gather all the methods in a namespace that pass the given block.
+        #
+        # @param Module  The namespace in which to search.
+        # @yieldparam Method  The method to test
+        # @yieldreturn Boolean
+        # @return Array[Method]
+        #
+        def search_all_methods(namespace)
+          done = Hash.new{ |h,k| h[k] = {} }
+          matches = []
+
+          recurse_namespace(namespace) do |klass|
+            (Pry::Method.all_from_class(klass) + Pry::Method.all_from_obj(klass)).each do |method|
+              next if done[method.owner][method.name]
+              done[method.owner][method.name] = true
+
+              matches << method if yield method
+            end
+          end
+
+          matches
+        end
+
+        # Search for all methods with a name that matches the given regex
+        # within a namespace.
+        #
+        # @param Regex  The regex to search for
+        # @param Module  The namespace to search
+        # @return Array[Method]
+        #
+        def name_search(regex, namespace)
+          search_all_methods(namespace) do |meth|
+            meth.name =~ regex
+          end
+        end
+
+        # Search for all methods who's implementation matches the given regex
+        # within a namespace.
+        #
+        # @param Regex  The regex to search for
+        # @param Module  The namespace to search
+        # @return Array[Method]
+        #
+        def content_search(regex, namespace)
+          search_all_methods(namespace) do |meth|
+            begin
+              meth.source =~ regex
+            rescue RescuableException => e
+              false
+            end
+          end
+        end
+      end
+    end
+  end
+end