bond 0.1.4 → 0.2.0

data/lib/bond/m.rb

@@ -0,0 +1,95 @@
+module Bond
+  # Takes international quagmires (a user's completion setup) and passes them on as missions to an Agent.
+  module M
+    extend self
+
+    # See Bond.complete
+    def complete(options={}, &block)
+      if (result = agent.complete(options, &block)).is_a?(String)
+        $stderr.puts result
+        false
+      else
+        true
+      end
+    end
+
+    # See Bond.recomplete
+    def recomplete(options={}, &block)
+      if (result = agent.recomplete(options, &block)).is_a?(String)
+        $stderr.puts result
+        false
+      else
+        true
+      end
+    end
+
+    # See Bond.agent
+    def agent
+      @agent ||= Agent.new(config)
+    end
+
+    # See Bond.config
+    def config
+      @config ||= {:readline_plugin=>Bond::Readline, :debug=>false, :default_search=>:underscore}
+    end
+
+    # Resets M by deleting all missions.
+    def reset
+      MethodMission.reset
+      @agent = nil
+    end
+
+    # See Bond.spy
+    def spy(input)
+      agent.spy(input)
+    end
+
+    # Validates and sets values in M.config.
+    def debrief(options={})
+      config.merge! options
+      plugin_methods = %w{setup line_buffer}
+      unless config[:readline_plugin].is_a?(Module) &&
+        plugin_methods.all? {|e| config[:readline_plugin].instance_methods.map {|f| f.to_s}.include?(e)}
+        $stderr.puts "Invalid readline plugin set. Try again."
+      end
+    end
+
+    # See Bond.start
+    def start(options={}, &block)
+      debrief options
+      load_completions
+      Rc.module_eval(&block) if block
+      true
+    end
+
+    def load_completions #:nodoc:
+      load_file File.join(File.dirname(__FILE__), 'completion.rb')
+      load_file(File.join(home,'.bondrc')) if File.exists?(File.join(home, '.bondrc'))
+      [File.dirname(__FILE__), File.join(home, '.bond')].each do |base_dir|
+        load_dir(base_dir)
+      end
+    end
+
+    # Loads a completion file in Rc namespace.
+    def load_file(file)
+      Rc.module_eval File.read(file)
+    rescue Exception => e
+      $stderr.puts "Bond Error: Completion file '#{file}' failed to load with:", e.message
+    end
+
+    def load_dir(base_dir) #:nodoc:
+      if File.exists?(dir = File.join(base_dir, 'completions'))
+        Dir[dir + '/*.rb'].each {|file| load_file(file) }
+      end
+    end
+
+    # Find a user's home in a cross-platform way
+    def home
+      ['HOME', 'USERPROFILE'].each {|e| return ENV[e] if ENV[e] }
+      return "#{ENV['HOMEDRIVE']}#{ENV['HOMEPATH']}" if ENV['HOMEDRIVE'] && ENV['HOMEPATH']
+      File.expand_path("~")
+    rescue
+      File::ALT_SEPARATOR ? "C:/" : "/"
+    end
+  end
+end

data/lib/bond/mission.rb

@@ -1,109 +1,149 @@
 module Bond
   # Occurs when a mission is incorrectly defined.
   class InvalidMissionError < StandardError; end
-  # Occurs when a mission action is incorrectly defined.
-  class InvalidMissionActionError < StandardError; end
   # Occurs when a mission or search action fails.
-  class FailedExecutionError < StandardError; end
-  # Namespace for subclasses of Bond::Mission.
-  class Missions; end
+  class FailedMissionError < StandardError; end
 
-  # A set of conditions and actions to take for a completion scenario or mission in Bond's mind.
+  # Represents a completion rule, given a condition (:on) on which to match and an action
+  # (block or :action) with which to generate possible completions.
   class Mission
-    include Search
-
     class<<self
-      # default search used across missions
-      attr_accessor :default_search
+      # eval binding used across missions
+      attr_accessor :eval_binding
       # Handles creation of proper Mission class depending on the options passed.
       def create(options)
-        if options[:method]
-          Missions::MethodMission.new(options)
-        elsif options[:object]
-          Missions::ObjectMission.new(options)
-        else
-          new(options)
+        if options[:method] || options[:methods] then MethodMission.create(options)
+        elsif options[:object]                   then ObjectMission.new(options)
+        elsif options[:anywhere]                 then AnywhereMission.new(options)
+        elsif options[:all_methods]              then MethodMission.new(options)
+        elsif options[:all_operator_methods]     then OperatorMethodMission.new(options)
+        else                                          new(options)
         end
       end
-      #:stopdoc:
-      def action_object
-        @action_object ||= Object.new.extend(Actions)
-      end
-
-      def current_eval(string, eval_binding=nil)
-        eval_binding ||= default_eval_binding
-        eval(string, eval_binding)
-      end
 
-      def default_eval_binding
-        Object.const_defined?(:IRB) ? IRB.CurrentContext.workspace.binding : ::TOPLEVEL_BINDING
+      # Calls eval with either the irb's current workspace binding or TOPLEVEL_BINDING.
+      def current_eval(string, ebinding=eval_binding)
+        eval(string, ebinding)
       end
 
-      def default_search
-        @default_search ||= :default
+      def eval_binding #:nodoc:
+        @eval_binding || IRB.CurrentContext.workspace.binding rescue ::TOPLEVEL_BINDING
       end
-      #:startdoc:
     end
 
-    attr_reader :action, :condition, :place
-    OPERATORS = ["%", "&", "*", "**", "+",  "-",  "/", "<", "<<", "<=", "<=>", "==", "===", "=~", ">", ">=", ">>", "[]", "[]=", "^"]
+    # All known operator methods
+    OPERATORS = %w{% & * ** + - / < << <= <=> == === =~ > >= >> [] []= ^ | ~ ! != !~}
+    # Regular expressions which describe common objects for MethodMission and ObjectMission
+    OBJECTS = %w<\([^\)]*\) '[^']*' "[^"]*" \/[^\/]*\/> +
+      %w<(?:%q|%r|%Q|%w|%s|%)?\[[^\]]*\] (?:proc|lambda|%q|%r|%Q|%w|%s|%)?\s*\{[^\}]*\}>
 
-    # Options are almost the same as those explained at Bond.complete. The only difference is that the action is passed
-    # as an :action option here.
+    # Generates array of possible completions and searches them if search is disabled. Any values
+    # that aren't strings are automatically converted with to_s.
+    attr_reader :action
+    # See Bond.complete's :place.
+    attr_reader :place
+    # A MatchData object generated from matching the user input with the condition.
+    attr_reader :matched
+    # Regexp condition
+    attr_reader :on
+    # Takes same options as Bond.complete.
     def initialize(options)
-      raise InvalidMissionError unless (options[:action] || respond_to?(:default_action)) &&
-        (options[:on] || is_a?(Missions::DefaultMission))
-      raise InvalidMissionError if options[:on] && !options[:on].is_a?(Regexp)
-      @action = options[:action].is_a?(Symbol) && self.class.action_object.respond_to?(options[:action]) ?
-        self.class.action_object.method(options[:action]) : options[:action]
-      raise InvalidMissionActionError if @action && !@action.respond_to?(:call)
-      @condition = options[:on]
-      @place = options[:place]
-      @search = options.has_key?(:search) ? options[:search] : Mission.default_search
-      @search = method("#{@search}_search") unless @search.is_a?(Proc) || @search == false
-    end
-
-    # Returns a boolean indicating if a mission matches the given input.
+      raise InvalidMissionError, ":action" unless (options[:action] || respond_to?(:default_action))
+      raise InvalidMissionError, ":on" unless (options[:on] && options[:on].is_a?(Regexp)) || respond_to?(:default_on)
+      @action, @on = options[:action], options[:on]
+      @place = options[:place] if options[:place]
+      @name = options[:name] if options[:name]
+      @search = options.has_key?(:search) ? options[:search] : Search.default_search
+    end
+
+    # Returns a boolean indicating if a mission matches the given Input and should be executed for completion.
     def matches?(input)
-      @matched = @input = @list_prefix = nil
-      if (match = handle_valid_match(input))
-        @input.instance_variable_set("@matched", @matched)
-        @input.instance_eval("def self.matched; @matched ; end")
-      end
+      @matched = @input = @completion_prefix = @eval_binding = nil
+      (match = do_match(input)) && after_match(@line = input)
       !!match
     end
 
     # Called when a mission has been chosen to autocomplete.
     def execute(input=@input)
-      completions = @action.call(input)
-      completions = (completions || []).map {|e| e.to_s }
-      completions =  @search.call(input || '', completions) if @search
+      completions = Array(call_action(input)).map {|e| e.to_s }
+      completions = call_search(@search, input, completions) if @search
       if @completion_prefix
-        @completion_prefix = @completion_prefix.split(Regexp.union(*Readline::DefaultBreakCharacters.split('')))[-1]
+        # Everything up to last break char stays on the line.
+        # Must ensure only chars after break are prefixed
+        @completion_prefix = @completion_prefix[/([^#{Readline::DefaultBreakCharacters}]+)$/,1] || ''
         completions = completions.map {|e| @completion_prefix + e }
       end
       completions
+    end
+
+    # Searches possible completions from the action which match the input.
+    def call_search(search, input, list)
+      Rc.send("#{search}_search", input || '', list)
     rescue
-      error_message = "Mission action failed to execute properly. Check your mission action with pattern #{@condition.inspect}.\n" +
-        "Failed with error: #{$!.message}"
-      raise FailedExecutionError, error_message
+      message = $!.is_a?(NoMethodError) && !Rc.respond_to?("#{search}_search") ?
+        "Completion search '#{search}' doesn't exist." :
+        "Failed during completion search with '#{$!.message}'."
+      raise FailedMissionError, [message, match_message]
+    end
+
+    # Calls the action to generate an array of possible completions.
+    def call_action(input)
+      @action.respond_to?(:call) ? @action.call(input) : Rc.send(@action, input)
+    rescue StandardError, SyntaxError
+      message = $!.is_a?(NoMethodError) && !@action.respond_to?(:call) &&
+        !Rc.respond_to?(@action) ? "Completion action '#{@action}' doesn't exist." :
+        "Failed during completion action with '#{$!.message}'."
+      raise FailedMissionError, [message, match_message]
+    end
+
+    # A message used to explains under what conditions a mission matched the user input.
+    # Useful for spying and debugging.
+    def match_message
+      "Matches completion with condition #{condition.inspect}."
+    end
+
+    # A regexp representing the condition under which a mission matches the input.
+    def condition
+      self.class.const_defined?(:CONDITION) ? Regexp.new(self.class.const_get(:CONDITION)) : @on
+    end
+
+    # The name or generated unique_id for a mission. Mostly for use with Bond.recomplete.
+    def name
+      @name ? @name.to_s : unique_id
+    end
+
+    # Method which must return non-nil for a mission to match.
+    def do_match(input)
+      @matched = input.match(@on)
+    end
+
+    # Stuff a mission needs to do after matching successfully, in preparation for Mission.execute.
+    def after_match(input)
+      create_input(input[/\S+$/])
     end
 
     #:stopdoc:
-    def unique_id
-      @condition
+    def condition_with_objects
+      self.class.const_get(:CONDITION).sub('OBJECTS', self.class.const_get(:OBJECTS).join('|'))
     end
 
-    def set_input(input, match)
-      @input = input[/\S+$/]
+    def eval_object(obj)
+      @evaled_object = self.class.current_eval(obj, eval_binding)
+      true
+    rescue Exception
+      false
     end
 
-    def handle_valid_match(input)
-      if (match = input.match(@condition))
-        set_input(input, match)
-        @matched ||= match
-      end
-      match
+    def eval_binding
+      @eval_binding ||= self.class.eval_binding
+    end
+
+    def unique_id
+      @on.inspect
+    end
+
+    def create_input(input, options={})
+      @input = Input.new(input, options.merge(:line=>@line, :matched=>@matched))
     end
     #:startdoc:
   end

data/lib/bond/missions/anywhere_mission.rb

@@ -0,0 +1,18 @@
+# A mission which completes anywhere i.e. even after non word break characters such as '[' or '}'.
+# It generates the following regexp condition /#{prefix}(#{anywhere})$/ and passes the first
+# capture group to the mission action.
+#
+# ==== Bond.complete Options:
+# [*:anywhere*] A regexp string which generates the first capture group in the above regexp.
+# [*:prefix*] An optional string which prefixes the first capture group in the above regexp.
+class Bond::AnywhereMission < Bond::Mission
+  def initialize(options={}) #:nodoc:
+    options[:on] = Regexp.new("#{options[:prefix]}(#{options[:anywhere]})$")
+    super
+  end
+
+  def after_match(input) #:nodoc:
+    @completion_prefix = input.to_s.sub(/#{Regexp.escape(@matched[1])}$/, '')
+    create_input @matched[1]
+  end
+end

data/lib/bond/missions/default_mission.rb

@@ -1,11 +1,21 @@
-# Represents a default mission which doesn't need an explicit action.
-class Bond::Missions::DefaultMission < Bond::Mission
-  def initialize(options={}) #:nodoc:
-    options[:action] ||= default_action
+# This is the mission called when none of the others match.
+class Bond::DefaultMission < Bond::Mission
+  ReservedWords = [
+    "BEGIN", "END", "alias", "and", "begin", "break", "case", "class", "def", "defined", "do", "else", "elsif", "end", "ensure",
+    "false", "for", "if", "in", "module", "next", "nil", "not", "or", "redo", "rescue", "retry", "return", "self", "super",
+    "then", "true", "undef", "unless", "until", "when", "while", "yield"
+  ]
+
+  #:stopdoc:
+  def initialize(options={})
+    options[:action] ||= method(:default)
     super
   end
+  def default_on; end
+  #:startdoc:
 
-  def default_action #:nodoc:
-    Object.const_defined?(:IRB) && IRB.const_defined?(:InputCompletor) ? IRB::InputCompletor::CompletionProc : :default
+  # Default action which generates methods, private methods, reserved words, local variables and constants.
+  def default(input)
+    Bond::Mission.current_eval("methods | private_methods | local_variables | self.class.constants") | ReservedWords
   end
 end

data/lib/bond/missions/method_mission.rb

@@ -1,18 +1,199 @@
-# Represents a completion mission specified by :method in Bond.complete.
-class Bond::Missions::MethodMission < Bond::Mission
-  attr_reader :method_condition
-  def initialize(options={}) #:nodoc:
-    @method_condition = options.delete(:method)
-    @method_condition = Regexp.escape(@method_condition.to_s) unless @method_condition.is_a?(Regexp)
-    options[:on] = /^\s*(#{@method_condition})\s*['"]?(.*)$/
-    super
+module Bond
+  # A mission which completes arguments for any module/class method that isn't an operator method.
+  # To create this mission or OperatorMethodMission, :method or :methods must be passed to Bond.complete.
+  # A completion for a given module/class effects any object that has it as an ancestor. If an object
+  # has two ancestors that have completions for the same method, the ancestor closer to the object is
+  # picked. For example, if Array#collect and Enumerable#collect have completions, argument completion on
+  # '[].collect ' would use Array#collect.
+  #--
+  # Unlike other missions, creating these missions with Bond.complete doesn't add more completion rules
+  # for an Agent to look through. Instead, all :method(s) completions are handled by one MethodMission
+  # object which looks them up with its own hashes. In the same way, all operator methods are
+  # handled by one OperatorMethodMission object.
+  #++
+  # ==== Bond.complete Options:
+  # [*:method*] String representing an instance (Class#method) or class method (Class.method). Gets
+  #             its class from :class or from substring prefixing '#' or '.'. If no class is given,
+  #             'Kernel#' is assumed.
+  # [*:methods*] Array of instance and/or class methods in the format of :method.
+  # [*:class*] Optional string representing module/class of :method(s). Must end in '#' or '.' to
+  #            indicate instance/class method. Suggested for use with :methods.
+  # [*:action*] If a string, value is assumed to be a :method and that method's action is copied.
+  #             Otherwise defaults to normal :action behavior.
+  # [*:search*] If :action is a :method string, defaults to copying its search.
+  #             Otherwise defaults to normal :search behavior.
+  # [*:name*, *:place*] These options aren't supported by a MethodMission/OperatorMethodMission completion.
+  # ==== Examples:
+  #   Bond.complete(:methods=>%w{delete index rindex}, :class=>"Array#") {|e| e.object }
+  #   Bond.complete(:method=>"Hash#index") {|e| e.object.values }
+  #
+  # ==== Argument Format
+  # All method arguments can autocomplete as symbols or strings and the first argument can be prefixed
+  # with '(':
+  #   >> Bond.complete(:method=>'example') { %w{some example eh} }
+  #   => true
+  #   >> example '[TAB]
+  #   eh    example    some
+  #   >> example :[TAB]
+  #   :eh   :example   :some
+  #
+  #  >> example("[TAB]
+  #   eh    example    some
+  #
+  # ==== Multiple Arguments
+  # Every time a comma appears after a method, Bond starts a new completion. This allows a method to
+  # complete multiple arguments as well as complete keys for a hash. *Each* argument can be have a unique
+  # set of completions since a completion action is aware of what argument it is currently completing:
+  #   >> Bond.complete(:method=>'FileUtils.chown') {|e|
+  #        e.argument > 3 ? %w{noop verbose} : %w{root admin me} }
+  #   => true
+  #   >> FileUtils.chown 'r[TAB]
+  #   >> FileUtils.chown 'root'
+  #   >> FileUtils.chown 'root', 'a[TAB]
+  #   >> FileUtils.chown 'root', 'admin'
+  #   >> FileUtils.chown 'root', 'admin', 'some_file', :v[TAB]
+  #   >> FileUtils.chown 'root', 'admin', 'some_file', :verbose
+  #   >> FileUtils.chown 'root', 'admin', 'some_file', :verbose=>true
+  class MethodMission < Bond::Mission
+  class<<self
+    # Hash of instance method completions which maps methods to hashes of modules to arrays ([action, search])
+    attr_accessor :actions
+    # Same as :actions but for class methods
+    attr_accessor :class_actions
+    # Stores last search result from MethodMission.find
+    attr_accessor :last_find
+    # Stores class from last search in MethodMission.find
+    attr_accessor :last_class
+
+    # Creates a method action given the same options as Bond.complete
+    def create(options)
+      if options[:action].is_a?(String)
+        klass, klass_meth = split_method(options[:action])
+        if (arr = (current_actions(options[:action])[klass_meth] || {})[klass])
+          options[:action], options[:search] = [arr[0], options[:search] || arr[1]]
+        else
+          raise InvalidMissionError, "string :action"
+        end
+      end
+
+      meths = options[:methods] || Array(options[:method])
+      raise InvalidMissionError, ":method(s)" unless meths.all? {|e| e.is_a?(String) }
+      if options[:class].is_a?(String)
+        options[:class] << '#' unless options[:class][/[#.]$/]
+        meths.map! {|e| options[:class] + e }
+      end
+
+      meths.each {|meth|
+        klass, klass_meth = split_method(meth)
+        (current_actions(meth)[klass_meth] ||= {})[klass] = [options[:action], options[:search]].compact
+      }
+      nil
+    end
+
+    # Resets all instance and class method actions.
+    def reset
+      @actions = {}
+      @class_actions = {}
+    end
+
+    def action_methods #:nodoc:
+      (actions.keys + class_actions.keys).uniq
+    end
+
+    # Lists all methods that have argument completions.
+    def all_methods
+      (class_actions.map {|m,h| h.map {|k,v| "#{k}.#{m}" } } +
+        actions.map {|m,h| h.map {|k,v| "#{k}##{m}" } }).flatten.sort
+    end
+
+    def current_actions(meth) #:nodoc:
+      meth.include?('.') ? @class_actions : @actions
+    end
+
+    def split_method(meth) #:nodoc:
+      meth = "Kernel##{meth}" if !meth.to_s[/[.#]/]
+      meth.split(/[.#]/,2)
+    end
+
+    # Returns the first completion by looking up the object's ancestors and finding the closest
+    # one that has a completion definition for the given method. Completion is returned
+    # as an array containing action proc and optional search to go with it.
+    def find(obj, meth)
+      last_find = find_with(obj, meth, :<=, @class_actions) if obj.is_a?(Module)
+      last_find = find_with(obj, meth, :is_a?, @actions) unless last_find
+      @last_class = last_find.is_a?(Array) ? last_find[0] : nil
+      @last_find = last_find ? last_find[1] : last_find
+    end
+
+    def find_with(obj, meth, find_meth, actions) #:nodoc:
+      (actions[meth] || {}).select {|k,v| get_class(k) }.
+        sort {|a,b| get_class(a[0]) <=> get_class(b[0]) || -1 }.
+        find {|k,v| obj.send(find_meth, get_class(k)) }
+    end
+
+    def get_class(klass) #:nodoc:
+      (@klasses ||= {})[klass] ||= any_const_get(klass)
+    end
+
+    # Returns a constant like Module#const_get no matter what namespace it's nested in.
+    # Returns nil if the constant is not found.
+    def any_const_get(name)
+      return name if name.is_a?(Module)
+      klass = Object
+      name.split('::').each {|e| klass = klass.const_get(e) }
+      klass
+    rescue
+       nil
+    end
+  end
+
+  self.reset
+  OBJECTS = %w{\S*?} + Mission::OBJECTS
+  CONDITION = %q{(OBJECTS)\.?(METHODS)(?:\s+|\()(['":])?(.*)$}
+
+  #:stopdoc:
+  def do_match(input)
+    (@on = default_on) && super && eval_object(@matched[1] ? @matched[1] : 'self') &&
+      MethodMission.find(@evaled_object, @meth = matched_method)
+  end
+
+  def default_on
+    Regexp.new condition_with_objects.sub('METHODS',Regexp.union(*current_methods).to_s)
   end
 
-  def unique_id #:nodoc:
-    @method_condition.is_a?(Regexp) ? @method_condition : @method_condition.to_s
+  def current_methods
+    self.class.action_methods - OPERATORS
   end
 
-  def set_input(input, match) #:nodoc:
-    @input = match[-1]
+  def default_action
+    MethodMission.last_find[0]
+  end
+
+  def matched_method
+    @matched[2]
+  end
+
+  def set_action_and_search
+    @action = default_action
+    @search = MethodMission.last_find[1] || Search.default_search
+  end
+
+  def after_match(input)
+    set_action_and_search
+    @completion_prefix, typed = @matched[3], @matched[-1]
+    input_options = {:object=>@evaled_object, :argument=>1+typed.count(','),
+      :arguments=>(@completion_prefix.to_s+typed).split(/\s*,\s*/) }
+    if typed.to_s.include?(',') && (match = typed.match(/(.*?\s*)([^,]*)$/))
+      typed = match[2]
+      typed.sub!(/^(['":])/,'')
+      @completion_prefix = typed.empty? ? '' : "#{@matched[3]}#{match[1]}#{$1}"
+    end
+    create_input typed, input_options
+  end
+
+  def match_message
+    "Matches completion for method '#{@meth}' in '#{MethodMission.last_class}'."
+  end
+  #:startdoc:
   end
-end
+end