pry 0.9.10 → 0.9.11

data/lib/pry/code/code_range.rb

@@ -0,0 +1,70 @@
+class Pry
+  class Code
+
+    # Represents a range of lines in a code listing.
+    #
+    # @api private
+    class CodeRange
+
+      # @param [Integer] start_line
+      # @param [Integer?] end_line
+      def initialize(start_line, end_line = nil)
+        @start_line = start_line
+        @end_line   = end_line
+        force_set_end_line
+      end
+
+      # @param [Array<LOC>] lines
+      # @return [Range]
+      def indices_range(lines)
+        Range.new(*indices(lines))
+      end
+
+      private
+
+      attr_reader :start_line, :end_line
+
+      # If `end_line` is equal to `nil`, then calculate it from the first
+      # parameter, `start_line`. Otherwise, leave it as it is.
+      # @return [void]
+      def force_set_end_line
+        if start_line.is_a?(Range)
+          set_end_line_from_range
+        else
+          @end_line ||= start_line
+        end
+      end
+
+      # Finds indices of `start_line` and `end_line` in the given Array of
+      # +lines+.
+      #
+      # @param [Array<LOC>] lines
+      # @return [Array<Integer>]
+      def indices(lines)
+        [find_start_index(lines), find_end_index(lines)]
+      end
+
+      # @return [Integer]
+      def find_start_index(lines)
+        return start_line if start_line < 0
+        lines.index { |loc| loc.lineno >= start_line } || lines.length
+      end
+
+      # @return [Integer]
+      def find_end_index(lines)
+        return end_line if end_line < 0
+        (lines.index { |loc| loc.lineno > end_line } || 0) - 1
+      end
+
+      # For example, if the range is 4..10, then `start_line` would be equal to
+      # 4 and `end_line` to 10.
+      # @return [void]
+      def set_end_line_from_range
+        @end_line = start_line.last
+        @end_line -= 1 if start_line.exclude_end?
+        @start_line = start_line.first
+      end
+    end
+
+  end
+end

data/lib/pry/code/loc.rb

@@ -0,0 +1,92 @@
+class Pry
+  class Code
+
+    # Represents a line of code. A line of code is a tuple, which consists of a
+    # line and a line number. A `LOC` object's state (namely, the line
+    # parameter) can be changed via instance methods. `Pry::Code` heavily uses
+    # this class.
+    #
+    # @api private
+    # @example
+    #   loc = LOC.new("def example\n  :example\nend", 1)
+    #   puts loc.line
+    #   def example
+    #     :example
+    #   end
+    #   #=> nil
+    #
+    #   loc.indent(3)
+    #   loc.line #=> "   def example\n  :example\nend"
+    class LOC
+
+      # @return [Array<String, Integer>]
+      attr_reader :tuple
+
+      # @param [String] line The line of code.
+      # @param [Integer] lineno The position of the +line+.
+      def initialize(line, lineno)
+        @tuple = [line.chomp, lineno.to_i]
+      end
+
+      # @return [Boolean]
+      def ==(other)
+        other.tuple == tuple
+      end
+
+      def dup
+        self.class.new(line, lineno)
+      end
+
+      # @return [String]
+      def line
+        tuple.first
+      end
+
+      # @return [Integer]
+      def lineno
+        tuple.last
+      end
+
+      # Paints the `line` of code.
+      #
+      # @param [Symbol] code_type
+      # @return [void]
+      def colorize(code_type)
+        tuple[0] = CodeRay.scan(line, code_type).term
+      end
+
+      # Prepends the line number `lineno` to the `line`.
+      #
+      # @param [Integer] max_width
+      # @return [void]
+      def add_line_number(max_width = 0)
+        padded = lineno.to_s.rjust(max_width)
+        colorized_lineno = Pry::Helpers::BaseHelpers.colorize_code(padded)
+        tuple[0] = "#{ colorized_lineno }: #{ line }"
+      end
+
+      # Prepends a marker "=>" or an empty marker to the +line+.
+      #
+      # @param [Integer] marker_lineno If it is equal to the `lineno`, then
+      #   prepend a hashrocket. Otherwise, an empty marker.
+      # @return [void]
+      def add_marker(marker_lineno)
+        tuple[0] =
+          if lineno == marker_lineno
+            " => #{ line }"
+          else
+            "    #{ line }"
+          end
+      end
+
+      # Indents the `line` with +distance+ spaces.
+      #
+      # @param [Integer] distance
+      # @return [void]
+      def indent(distance)
+        tuple[0] = "#{ ' ' * distance }#{ line }"
+      end
+    end
+
+  end
+end

data/lib/pry/code_object.rb

@@ -0,0 +1,153 @@
+class Pry
+  class CodeObject
+    module Helpers
+      # we need this helper as some Pry::Method objects can wrap Procs
+      # @return [Boolean]
+      def real_method_object?
+        is_a?(::Method) || is_a?(::UnboundMethod)
+      end
+
+      def c_method?
+        real_method_object? && source_type == :c
+      end
+
+      def module_with_yard_docs?
+        is_a?(WrappedModule) && yard_docs?
+      end
+
+      def command?
+        is_a?(Module) && self <= Pry::Command
+      end
+    end
+
+    include Pry::Helpers::CommandHelpers
+
+    class << self
+      def lookup(str, _pry_, options={})
+        co = new(str, _pry_, options)
+
+        co.default_lookup || co.method_or_class_lookup ||
+          co.command_lookup || co.empty_lookup
+      end
+    end
+
+    attr_accessor :str
+    attr_accessor :target
+    attr_accessor :pry
+    attr_accessor :super_level
+
+    def initialize(str, _pry_, options={})
+      options = {
+        :super => 0,
+      }.merge!(options)
+
+      @str = str
+      @pry = _pry_
+      @target = _pry_.current_context
+      @super_level = options[:super]
+    end
+
+    def command_lookup
+      # TODO: just make it so find_command_by_match_or_listing doesn't
+      # raise?
+      pry.commands.find_command_by_match_or_listing(str) rescue nil
+    end
+
+    def empty_lookup
+      return nil if str && !str.empty?
+
+      if internal_binding?(target)
+        mod = target_self.is_a?(Module) ? target_self : target_self.class
+        Pry::WrappedModule(mod)
+      else
+        Pry::Method.from_binding(target)
+      end
+    end
+
+    # lookup variables and constants and `self` that are not modules
+    def default_lookup
+
+      # we skip instance methods as we want those to fall through to method_or_class_lookup()
+      if safe_to_evaluate?(str) && !looks_like_an_instance_method?(str)
+        obj = target.eval(str)
+
+        # restrict to only objects we KNOW for sure support the full API
+        # Do NOT support just any object that responds to source_location
+        if sourcable_object?(obj)
+          Pry::Method(obj)
+        elsif !obj.is_a?(Module)
+          Pry::WrappedModule(obj.class)
+        else
+          nil
+        end
+      end
+
+    rescue Pry::RescuableException
+      nil
+    end
+
+    def method_or_class_lookup
+      # we need this here because stupid Pry::Method.from_str() does a
+      # Pry::Method.from_binding when str is nil.
+      # Once we refactor Pry::Method.from_str() so it doesnt lookup
+      # from bindings, we can get rid of this check
+      return nil if str.to_s.empty?
+
+      obj = if str =~ /::(?:\S+)\Z/
+        Pry::WrappedModule.from_str(str,target) || Pry::Method.from_str(str, target)
+      else
+        Pry::Method.from_str(str,target) || Pry::WrappedModule.from_str(str, target)
+      end
+
+      lookup_super(obj, super_level)
+    end
+
+    private
+
+    def sourcable_object?(obj)
+      [::Proc, ::Method, ::UnboundMethod].any? { |o| obj.is_a?(o) }
+    end
+
+
+    # Returns true if `str` looks like a method, i.e Klass#method
+    # We need to consider this case because method lookups should fall
+    # through to the `method_or_class_lookup()` method but a
+    # defined?() on a "Klass#method` string will see the `#` as a
+    # comment and only evaluate the `Klass` part.
+    # @param [String] str
+    # @return [Boolean] Whether the string looks like an instance method.
+    def looks_like_an_instance_method?(str)
+      str =~ /\S#\S/
+    end
+
+    # We use this method to decide whether code is safe to eval. Method's are
+    # generally not, but everything else is.
+    # TODO: is just checking != "method" enough??
+    # TODO: see duplication of this method in Pry::WrappedModule
+    # @param [String] str The string to lookup
+    # @return [Boolean]
+    def safe_to_evaluate?(str)
+      return true if str.strip == "self"
+      kind = target.eval("defined?(#{str})")
+      kind =~ /variable|constant/
+    end
+
+    def target_self
+      target.eval('self')
+    end
+
+    # grab the nth (`super_level`) super of `obj
+    # @param [Object] obj
+    # @param [Fixnum] super_level How far up the super chain to ascend.
+    def lookup_super(obj, super_level)
+      return nil if !obj
+
+      sup = obj.super(super_level)
+      if !sup
+        raise Pry::CommandError, "No superclass found for #{obj.wrapped}"
+      else
+        sup
+      end
+    end
+  end
+end

data/lib/pry/command.rb

@@ -1,9 +1,14 @@
+require 'delegate'
+require 'pry/helpers/documentation_helpers'
+
 class Pry
 
   # The super-class of all commands, new commands should be created by calling
   # {Pry::CommandSet#command} which creates a BlockCommand or {Pry::CommandSet#create_command}
   # which creates a ClassCommand. Please don't use this class directly.
   class Command
+    extend Helpers::DocumentationHelpers
+    extend CodeObject::Helpers
 
     # represents a void return value for a command
     VOID_VALUE = Object.new
@@ -20,7 +25,11 @@ class Pry
       attr_writer :match
 
       def match(arg=nil)
-        @match = arg if arg
+        if arg
+          @command_options ||= default_options(arg)
+          @command_options[:listing] = arg.is_a?(String) ? arg : arg.inspect
+          @match = arg
+        end
         @match
       end
 
@@ -32,7 +41,7 @@ class Pry
 
       # Define or get the command's options
       def command_options(arg=nil)
-        @command_options ||= {}
+        @command_options ||= default_options(match)
         @command_options.merge!(arg) if arg
         @command_options
       end
@@ -47,7 +56,43 @@ class Pry
       end
 
       def block
-        @block || instance_method(:process) && instance_method(:process)
+        @block || instance_method(:process)
+      end
+
+      def source
+        file, line = block.source_location
+        strip_leading_whitespace(Pry::Code.from_file(file).expression_at(line))
+      end
+
+      def doc
+        new.help
+      end
+
+      def source_location
+        block.source_location
+      end
+
+      def source_file
+        Array(block.source_location).first
+      end
+      alias_method :file, :source_file
+
+      def source_line
+        Array(block.source_location).last
+      end
+      alias_method :line, :source_line
+
+      def default_options(match)
+        {
+          :requires_gem      => [],
+          :keep_retval       => false,
+          :argument_required => false,
+          :interpolate       => true,
+          :shellwords        => true,
+          :listing           => (String === match ? match : match.inspect),
+          :use_prefix        => true,
+          :takes_block       => false
+        }
       end
     end
 
@@ -57,16 +102,23 @@ class Pry
     def description; self.class.description; end
     def block; self.class.block; end
     def command_options; self.class.options; end
-    def command_name; command_options[:listing]; end
+    def command_name; self.class.command_name; end
+    def source; self.class.source; end
+    def source_location; self.class.source_location; end
 
     class << self
       def name
         super.to_s == "" ? "#<class(Pry::Command #{match.inspect})>" : super
       end
+
       def inspect
         name
       end
 
+      def command_name
+        self.options[:listing]
+      end
+
       # Create a new command with the given properties.
       # @param [String, Regex] match The thing that triggers this command
       # @param [String] description The description to appear in `help`
@@ -209,7 +261,6 @@ class Pry
     include Pry::Helpers::BaseHelpers
     include Pry::Helpers::CommandHelpers
 
-
     # Instantiate a command, in preparation for calling it.
     # @param [Hash] context The runtime context to use with this command.
     def initialize(context={})
@@ -256,7 +307,7 @@ class Pry
       collision_type ||= 'local-variable' if arg_string.match(%r{\A\s*[-+*/%&|^]*=})
 
       if collision_type
-        output.puts "#{Pry::Helpers::Text.bold('WARNING:')} Calling Pry command '#{command_match}'," +
+        output.puts "#{text.bold('WARNING:')} Calling Pry command '#{command_match}'," +
                                                           "which conflicts with a #{collision_type}.\n\n"
       end
     rescue Pry::RescuableException
@@ -325,7 +376,10 @@ class Pry
     #   Note that if we find the '| do' or '| {' we delete this and the
     #   elements following it from `arg_string`.
     def pass_block(arg_string)
-      block_index = arg_string.rindex(/\| *(?:do|\{)/)
+      # Workaround for weird JRuby bug where rindex in this case can return nil
+      # even when there's a match.
+      arg_string.scan(/\| *(?:do|\{)/)
+      block_index = $~ && $~.offset(0)[0]
 
       return if !block_index
 
@@ -358,8 +412,8 @@ class Pry
     def call_safely(*args)
       unless dependencies_met?
         gems_needed = Array(command_options[:requires_gem])
-        gems_not_installed = gems_needed.select { |g| !gem_installed?(g) }
-        output.puts "\nThe command '#{command_name}' is #{Helpers::Text.bold("unavailable")} because it requires the following gems to be installed: #{(gems_not_installed.join(", "))}"
+        gems_not_installed = gems_needed.select { |g| !Rubygem.installed?(g) }
+        output.puts "\nThe command '#{command_name}' is #{text.bold("unavailable")} because it requires the following gems to be installed: #{(gems_not_installed.join(", "))}"
         output.puts "-"
         output.puts "Type `install-command #{command_name}` to install the required gems and activate this command."
         return void
@@ -380,6 +434,12 @@ class Pry
       @dependencies_met ||= command_dependencies_met?(command_options)
     end
 
+    # Generate completions for this command
+    #
+    # @param [String] search  The line typed so far
+    # @return [Array<String>]  Completion words
+    def complete(search); Bond::DefaultMission.completions; end
+
     private
 
     # Run the `#call` method and all the registered hooks.
@@ -437,7 +497,7 @@ class Pry
     end
   end
 
-  # A super-class ofr Commands with structure.
+  # A super-class of Commands with structure.
   #
   # This class implements the bare-minimum functionality that a command should
   # have, namely a --help switch, and then delegates actual processing to its
@@ -449,13 +509,45 @@ class Pry
   # `setup` which will be called before `options`, for example to require any
   # gems your command needs to run, or to set up state.
   class ClassCommand < Command
+    class << self
+
+      # Ensure that subclasses inherit the options, description and
+      # match from a ClassCommand super class.
+      def inherited(klass)
+        klass.match  match
+        klass.description  description
+        klass.command_options options
+      end
+
+      def source
+        Pry::WrappedModule(self).source
+      end
+
+      def doc
+        new.help
+      end
+
+      def source_location
+        Pry::WrappedModule(self).source_location
+      end
+
+      def source_file
+        Pry::WrappedModule(self).source_file
+      end
+      alias_method :file, :source_file
+
+      def source_line
+        Pry::WrappedModule(self).source_line
+      end
+      alias_method :line, :source_line
+    end
 
     attr_accessor :opts
     attr_accessor :args
 
     # Set up `opts` and `args`, and then call `process`.
     #
-    # This function will display help if necessary.
+    # This method will display help if necessary.
     #
     # @param [Array<String>] args The arguments passed
     # @return [Object] The return value of `process` or VOID_VALUE
@@ -478,32 +570,78 @@ class Pry
       slop.help
     end
 
-    # Return an instance of Slop that can parse the options that this command accepts.
+    # Return an instance of Slop::Commands that can parse either subcommands
+    # or the options that this command accepts.
     def slop
-      Slop.new do |opt|
+      Slop.parse do |opt|
         opt.banner(unindent(self.class.banner))
+        subcommands(opt)
         options(opt)
-        opt.on(:h, :help, "Show this message.")
+        opt.on :h, :help, 'Show this message.'
       end
     end
 
-    # A function called just before `options(opt)` as part of `call`.
+    # Generate shell completions
+    # @param [String] search  The line typed so far
+    # @return [Array<String>]  the words to complete
+    def complete(search)
+      slop.map do |opt|
+        [opt.long && "--#{opt.long} " || opt.short && "-#{opt.short}"]
+      end.flatten(1).compact + super
+    end
+
+    # A method called just before `options(opt)` as part of `call`.
     #
-    # This function can be used to set up any context your command needs to run, for example
-    # requiring gems, or setting default values for options.
+    # This method can be used to set up any context your command needs to run,
+    # for example requiring gems, or setting default values for options.
     #
     # @example
-    #   def setup;
+    #   def setup
     #     require 'gist'
     #     @action = :method
     #   end
     def setup; end
 
-    # A function to setup Slop so it can parse the options your command expects.
+    # A method to setup Slop commands so it can parse the subcommands your
+    # command expects. If you need to set up default values, use `setup`
+    # instead.
+    #
+    # @example A minimal example
+    #   def subcommands(cmd)
+    #     cmd.command :download do |opt|
+    #       description 'Downloads a content from a server'
+    #
+    #       opt.on :verbose, 'Use verbose output'
+    #
+    #       run do |options, arguments|
+    #         ContentDownloader.download(options, arguments)
+    #       end
+    #     end
+    #   end
+    #
+    # @example Define the invokation block anywhere you want
+    #   def subcommands(cmd)
+    #     cmd.command :download do |opt|
+    #       description 'Downloads a content from a server'
+    #
+    #       opt.on :verbose, 'Use verbose output'
+    #     end
+    #   end
+    #
+    #   def process
+    #     # Perform calculations...
+    #     opts.fetch_command(:download).run do |options, arguments|
+    #       ContentDownloader.download(options, arguments)
+    #     end
+    #     # More calculations...
+    #   end
+    def subcommands(cmd); end
+
+    # A method to setup Slop so it can parse the options your command expects.
     #
-    # NOTE: please don't do anything side-effecty in the main part of this method,
-    # as it may be called by Pry at any time for introspection reasons. If you need
-    # to set up default values, use `setup` instead.
+    # @note Please don't do anything side-effecty in the main part of this
+    # method, as it may be called by Pry at any time for introspection reasons.
+    # If you need to set up default values, use `setup` instead.
     #
     # @example
     #  def options(opt)