pry 0.10.pre.1-i386-mswin32 → 0.10.0.pre3-i386-mswin32

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,19 +25,23 @@ class Pry
       attr_writer :match
 
       def match(arg=nil)
-        @match = arg if arg
-        @match
+        if arg
+          @command_options ||= default_options(arg)
+          @command_options[:listing] = arg.is_a?(String) ? arg : arg.inspect
+          @match = arg
+        end
+        @match ||= nil
       end
 
       # Define or get the command's description
       def description(arg=nil)
         @description = arg if arg
-        @description
+        @description ||= nil
       end
 
       # 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`
@@ -123,7 +175,7 @@ class Pry
       end
 
       def command_regex
-        pr = defined?(Pry.config.command_prefix) ? Pry.config.command_prefix : ""
+        pr = Pry.respond_to?(:config) ? Pry.config.command_prefix : ""
         prefix = convert_to_regex(pr)
         prefix = "(?:#{prefix})?" unless options[:use_prefix]
 
@@ -142,6 +194,7 @@ class Pry
       # The group in which the command should be displayed in "help" output.
       # This is usually auto-generated from directory naming, but it can be
       # manually overridden if necessary.
+      # Group should not be changed once it is initialized.
       def group(name=nil)
         @group ||= if name
                      name
@@ -149,7 +202,7 @@ class Pry
                      case Pry::Method(block).source_file
                      when %r{/pry/.*_commands/(.*).rb}
                        $1.capitalize.gsub(/_/, " ")
-                     when %r{(pry-\w+)-([\d\.]+([\w\d\.]+)?)}
+                     when %r{(pry-\w+)-([\d\.]+([\w\.]+)?)}
                        name, version = $1, $2
                        "#{name.to_s} (v#{version.to_s})"
                      when /pryrc/
@@ -190,12 +243,13 @@ class Pry
     # @example
     #   run "amend-line",  "5", 'puts "hello world"'
     def run(command_string, *args)
+      command_string = _pry_.config.command_prefix.to_s + command_string
       complete_string = "#{command_string} #{args.join(" ")}".rstrip
       command_set.process_line(complete_string, context)
     end
 
     def commands
-      command_set.commands
+      command_set.to_hash
     end
 
     def text
@@ -209,7 +263,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={})
@@ -232,7 +285,7 @@ class Pry
     #   state.my_state = "my state"  # this will not conflict with any
     #                                # `state.my_state` used in another command.
     def state
-      _pry_.command_state[match] ||= OpenStruct.new
+      _pry_.command_state[match] ||= Pry::Config.from_hash({})
     end
 
     # Revaluate the string (str) and perform interpolation.
@@ -256,8 +309,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}'," +
-                                                          "which conflicts with a #{collision_type}.\n\n"
+        output.puts "#{text.bold('WARNING:')} Calling Pry command '#{command_match}', which conflicts with a #{collision_type}.\n\n"
       end
     rescue Pry::RescuableException
     end
@@ -325,7 +377,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 +413,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 +435,14 @@ 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)
+      []
+    end
+
     private
 
     # Run the `#call` method and all the registered hooks.
@@ -437,7 +500,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 +512,60 @@ 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
+        source_object.source
+      end
+
+      def doc
+        new.help
+      end
+
+      def source_location
+        source_object.source_location
+      end
+
+      def source_file
+        source_object.source_file
+      end
+      alias_method :file, :source_file
+
+      def source_line
+        source_object.source_line
+      end
+      alias_method :line, :source_line
+
+      private
+
+      # The object used to extract the source for the command.
+      #
+      # This should be a `Pry::Method(block)` for a command made with `create_command`
+      # and a `Pry::WrappedModule(self)` for a command that's a standard class.
+      # @return [Pry::WrappedModule, Pry::Method]
+      def source_object
+        @source_object ||= if name =~ /^[A-Z]/
+                             Pry::WrappedModule(self)
+                           else
+                             Pry::Method(block)
+                           end
+      end
+    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 +588,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 that can parse either subcommands or the
+    # options that this command accepts.
     def slop
       Slop.new 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)

data/lib/pry/command_set.rb

@@ -10,19 +10,15 @@ class Pry
   class CommandSet
     include Enumerable
     include Pry::Helpers::BaseHelpers
-
-    attr_reader :commands
     attr_reader :helper_module
 
-    # @param [Array<CommandSet>] imported_sets Sets which will be imported
-    #   automatically
+    # @param [Array<Commandset>] imported_sets
+    #   Sets which will be imported automatically
     # @yield Optional block run to define commands
     def initialize(*imported_sets, &block)
       @commands      = {}
       @helper_module = Module.new
-
       import(*imported_sets)
-
       instance_eval(&block) if block
     end
 
@@ -81,9 +77,9 @@ class Pry
     #   # number-N regex command
     def block_command(match, description="No description.", options={}, &block)
       description, options = ["No description.", description] if description.is_a?(Hash)
-      options = default_options(match).merge!(options)
+      options = Pry::Command.default_options(match).merge!(options)
 
-      commands[match] = Pry::BlockCommand.subclass(match, description, options, helper_module, &block)
+      @commands[match] = Pry::BlockCommand.subclass(match, description, options, helper_module, &block)
     end
     alias_method :command, :block_command
 
@@ -113,11 +109,11 @@ class Pry
     #
     def create_command(match, description="No description.", options={}, &block)
       description, options = ["No description.", description] if description.is_a?(Hash)
-      options = default_options(match).merge!(options)
+      options = Pry::Command.default_options(match).merge!(options)
 
-      commands[match] = Pry::ClassCommand.subclass(match, description, options, helper_module, &block)
-      commands[match].class_eval(&block)
-      commands[match]
+      @commands[match] = Pry::ClassCommand.subclass(match, description, options, helper_module, &block)
+      @commands[match].class_eval(&block)
+      @commands[match]
     end
 
     # Execute a block of code before a command is invoked. The block also
@@ -126,7 +122,7 @@ class Pry
     # @param [String, Regexp] search The match or listing of the command.
     # @yield The block to be run before the command.
     # @example Display parameter before invoking command
-    #   Pry.commands.before_command("whereami") do |n|
+    #   Pry.config.commands.before_command("whereami") do |n|
     #     output.puts "parameter passed was #{n}"
     #   end
     def before_command(search, &block)
@@ -140,7 +136,7 @@ class Pry
     # @param [String, Regexp] search The match or listing of the command.
     # @yield The block to be run after the command.
     # @example Display text 'command complete' after invoking command
-    #   Pry.commands.after_command("whereami") do |n|
+    #   Pry.config.commands.after_command("whereami") do |n|
     #     output.puts "command complete!"
     #   end
     def after_command(search, &block)
@@ -148,22 +144,16 @@ class Pry
       cmd.hooks[:after] << block
     end
 
-    def each &block
+    def each(&block)
       @commands.each(&block)
     end
 
-    # Add a given command object to this set.
-    # @param [Command] command The subclass of Pry::Command you wish to add.
-    def add_command(command)
-      commands[command.match] = command
-    end
-
     # Removes some commands from the set
     # @param [Array<String>] searches the matches or listings of the commands to remove
     def delete(*searches)
       searches.each do |search|
         cmd = find_command_by_match_or_listing(search)
-        commands.delete cmd.match
+        @commands.delete cmd.match
       end
     end
 
@@ -173,7 +163,7 @@ class Pry
     # @return [Pry::CommandSet] Returns the reciever (a command set).
     def import(*sets)
       sets.each do |set|
-        commands.merge! set.commands
+        @commands.merge! set.to_hash
         helper_module.send :include, set.helper_module
       end
       self
@@ -187,7 +177,7 @@ class Pry
       helper_module.send :include, set.helper_module
       matches.each do |match|
         cmd = set.find_command_by_match_or_listing(match)
-        commands[cmd.match] = cmd
+        @commands[cmd.match] = cmd
       end
       self
     end
@@ -196,16 +186,10 @@ class Pry
     #   of the command to retrieve.
     # @return [Command] The command object matched.
     def find_command_by_match_or_listing(match_or_listing)
-      if commands[match_or_listing]
-        cmd = commands[match_or_listing]
-      else
-        _, cmd = commands.find { |match, command| command.options[:listing] == match_or_listing }
-      end
-
-      raise ArgumentError, "Cannot find a command: '#{match_or_listing}'!" if !cmd
-      cmd
+      cmd = (@commands[match_or_listing] ||
+        Pry::Helpers::BaseHelpers.find_command(match_or_listing, @commands))
+      cmd or raise ArgumentError, "Cannot find a command: '#{match_or_listing}'!"
     end
-    protected :find_command_by_match_or_listing
 
     # Aliases a command
     # @param [String, Regex] match The match of the alias (can be a regex).
@@ -219,7 +203,8 @@ class Pry
     # @example Pass explicit description (overriding default).
     #   Pry.config.commands.alias_command "lM", "ls -M", :desc => "cutiepie"
     def alias_command(match, action,  options={})
-      original_options = find_command(action).options.dup
+      cmd = find_command(action) or fail "Command: `#{action}` not found"
+      original_options = cmd.options.dup
 
       options = original_options.merge!({
                                           :desc => "Alias for `#{action}`",
@@ -233,6 +218,12 @@ class Pry
         run action, *args
       end
 
+      c.class_eval do
+        define_method(:complete) do |input|
+          cmd.new(context).complete(input)
+        end
+      end
+
       c.group "Aliases"
 
       c
@@ -255,11 +246,22 @@ class Pry
         :description => cmd.description
       }.merge!(options)
 
-      commands[new_match] = cmd.dup
-      commands[new_match].match = new_match
-      commands[new_match].description = options.delete(:description)
-      commands[new_match].options.merge!(options)
-      commands.delete(cmd.match)
+      @commands[new_match] = cmd.dup
+      @commands[new_match].match = new_match
+      @commands[new_match].description = options.delete(:description)
+      @commands[new_match].options.merge!(options)
+      @commands.delete(cmd.match)
+    end
+
+    def disabled_command(name_of_disabled_command, message, matcher=name_of_disabled_command)
+      create_command name_of_disabled_command do
+        match matcher
+        description ""
+
+        define_method(:process) do
+          output.puts "DISABLED: #{message}"
+        end
+      end
     end
 
     # Sets or gets the description for a command (replacing the old
@@ -297,18 +299,71 @@ class Pry
     end
 
 
-    # @return [Array] The list of commands provided by the command set.
+    # @return [Array]
+    #   The list of commands provided by the command set.
     def list_commands
-      commands.keys
+      @commands.keys
     end
+    alias_method :keys, :list_commands
+
+    def to_hash
+      @commands.dup
+    end
+    alias_method :to_h, :to_hash
 
     # Find a command that matches the given line
-    # @param [String] val The line that might be a command invocation
+    # @param [String] pattern The line that might be a command invocation
     # @return [Pry::Command, nil]
-    def find_command(val)
-      commands.values.select{ |c| c.matches?(val) }.sort_by{ |c| c.match_score(val) }.last
+    def [](pattern)
+      @commands.values.select do |command|
+        command.matches?(pattern)
+      end.sort_by do |command|
+        command.match_score(pattern)
+      end.last
+    end
+    alias_method :find_command, :[]
+
+    #
+    # Re-assign the command found at _pattern_ with _command_.
+    #
+    # @param [Regexp, String] pattern
+    #   The command to add or replace(found at _pattern_).
+    #
+    # @param [Pry::Command] command
+    #   The command to add.
+    #
+    # @return [Pry::Command]
+    #   Returns the new command (matched with "pattern".)
+    #
+    # @example
+    #   Pry.config.commands["help"] = MyHelpCommand
+    #
+    def []=(pattern, command)
+      if command.equal?(nil)
+        return @commands.delete(pattern)
+      end
+      unless Class === command && command < Pry::Command
+        raise TypeError, "command is not a subclass of Pry::Command"
+      end
+      bind_command_to_pattern = pattern != command.match
+      if bind_command_to_pattern
+        command_copy = command.dup
+        command_copy.match = pattern
+        @commands[pattern] = command_copy
+      else
+        @commands[pattern] = command
+      end
+    end
+
+    #
+    # Add a command to set.
+    #
+    # @param [Command] command
+    #   a subclass of Pry::Command.
+    #
+    def add_command(command)
+      self[command.match] = command
     end
-    alias_method :[], :find_command
 
     # Find the command that the user might be trying to refer to.
     # @param [String] search The user's search.
@@ -344,23 +399,22 @@ class Pry
 
     # @private (used for testing)
     def run_command(context, match, *args)
-      command = commands[match] or raise NoCommandError.new(match, self)
+      command = @commands[match] or raise NoCommandError.new(match, self)
       command.new(context).call_safely(*args)
     end
 
-    private
-
-    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
-      }
+    # Generate completions for the user's search.
+    # @param [String] search The line to search for
+    # @param [Hash] context  The context to create the command with
+    # @return [Array<String>]
+    def complete(search, context={})
+      if command = find_command(search)
+        command.new(context).complete(search)
+      else
+        @commands.keys.select do |key|
+          String === key && key.start_with?(search)
+        end.map{ |key| key + " " }
+      end
     end
   end