bond 0.1.4 → 0.2.0

data/lib/bond.rb

@@ -1,121 +1,90 @@
-current_dir = File.dirname(__FILE__)
-$:.unshift(current_dir) unless $:.include?(current_dir) || $:.include?(File.expand_path(current_dir))
+require 'bond/m'
+require 'bond/version'
 require 'bond/readline'
 require 'bond/rawline'
 require 'bond/agent'
 require 'bond/search'
-require 'bond/actions'
+require 'bond/input'
+require 'bond/rc'
 require 'bond/mission'
 require 'bond/missions/default_mission'
 require 'bond/missions/method_mission'
 require 'bond/missions/object_mission'
+require 'bond/missions/anywhere_mission'
+require 'bond/missions/operator_method_mission'
 
-# Bond allows easy handling and creation of completion missions/rules with Bond.complete. When Bond is asked to autocomplete, Bond looks
-# up the completion missions in the order they were defined and picks the first one that matches what the user has typed.
-# Bond::Agent handles finding and executing the correct completion mission. 
-# Some pointers on using/understanding Bond:
-# * Bond can work outside of irb and readline when debriefed with Bond.debrief. This should be called before any Bond.complete calls.
-# * Bond doesn't take over completion until an explicit Bond.complete is called.
-# * Order of completion missions matters. The order they're defined in is the order Bond searches
-#   when looking for a matching completion. This means that more specific completions like method and object completions should come
-#   before more general ones. You can tweak completion placement by passing :place to Bond.complete.
-# * If no completion missions match, then Bond falls back on a default mission. If using irb and irb/completion
-#   this falls back on irb's completion. Otherwise an empty completion list is returned.
 module Bond
   extend self
 
-  # Defines a completion mission aka a Bond::Mission. A valid mission consists of a condition and an action block.
-  # A condition is specified with one of the following options: :on, :object or :method. Depending on the condition option, a
-  # different type of Bond::Mission is created. Action blocks are given what the user has typed and should a return a list of possible
-  # completions. By default Bond searches possible completions to only return the ones that match what has been typed. This searching
-  # behavior can be customized with the :search option.
+  # Defines a completion rule (Mission). A valid Mission consists of a condition and an action. A
+  # condition is specified with one of the following options: :on, :object, :anywhere or :method(s). Each
+  # of these options creates a different Mission class. An action is either this method's block or :action.
+  # An action takes what the user has typed (Input) and returns an array of possible completions. Bond
+  # searches these completions and returns matching completions. This searching behavior can be configured
+  # or turned off per mission with :search. If turned off, the action must also handle searching.
   # ====Options:
-  # [:on] Matches the given regular expression with the full line of input.  Creates a Bond::Mission object.
-  #       Access to the matches in the regular expression are passed to the completion proc as the input's attribute :matched.
-  # [:method] Matches the given string or regular expression with any methods (or any non-whitespace string) that start the beginning
-  #           of a line. Creates a Bond::Missions:MethodMission object. If given a string, the match has to be exact.
-  #           Since this is used mainly for argument completion, completions can have an optional quote in front of them.
-  # [:object] Matches the given a string or regular expression to the ancestor of the current object being completed. Creates a 
-  #           Bond::Missions::ObjectMission object. Access to the current object is passed to the completion proc as the input's
-  #           attribute :object. If no action is given, this completion type defaults to all methods the object responds to.
-  # [:search] Given a symbol, proc or false, determines how completions are searched to match what the user has typed. Defaults to
-  #           traditional searching i.e. looking at the beginning of a string for possible matches. If false, search is turned off and
-  #           assumed to be done in the action block. Possible symbols are :anywhere, :ignore_case and :underscore. See Bond::Search for
-  #           more info about them. A proc is given two arguments: the input string and an array of possible completions.
-  # [:place] Given a symbol or number, controls where this completion is placed in relation to existing ones. If a number, the
-  #          completion is placed at that number. If the symbol :last, the completion is placed at the end regardless of completions
-  #          defined after it. Use this symbol as a way of anchoring completions you want to remain at the end. Multiple declarations
-  #          of :last are kept last in the order they are defined.
-  #
+  # [*:on*] Regular expression which matches the full line of input to create a Mission object.
+  # [*:method*, *:methods*, *:class*] See MethodMission.
+  # [*:anywhere*, *:prefix*] See AnywhereMission.
+  # [*:object*] See ObjectMission.
+  # [*:search*] A symbol or false which determines how completions are searched. Defaults to
+  #             Search.default_search. If false, search is turned off and assumed to be done in the action.
+  #             Possible symbols are :anywhere, :ignore_case, :underscore, :normal, :files and :modules.
+  #             See Search for more info.
+  # [*:action*] Rc method name that takes an Input and returns possible completions. See MethodMission for
+  #             specific behavior with :method(s).
+  # [*:place*] A number or :last which indicates where a mission is inserted amongst existing missions.
+  #            If the symbol :last, places the mission at the end regardless of missions defined after
+  #            it. Multiple declarations of :last are kept last in the order they are defined.
+  # [*:name*] A symbol or string that serves a unique id for a mission. This unique id can be passed by
+  #           Bond.recomplete to identify and replace the mission.
   # ==== Examples:
   #  Bond.complete(:method=>'shoot') {|input| %w{to kill} }
   #  Bond.complete(:on=>/^((([a-z][^:.\(]*)+):)+/, :search=>false) {|input| Object.constants.grep(/#{input.matched[1]}/) }
   #  Bond.complete(:object=>ActiveRecord::Base, :search=>:underscore, :place=>:last)
-  #  Bond.complete(:object=>ActiveRecord::Base) {|input| input.object.class.instance_methods(false) }
   #  Bond.complete(:method=>'you', :search=>proc {|input, list| list.grep(/#{input}/i)} ) {|input| %w{Only Live Twice} }
-  def complete(options={}, &block)
-    if (result = agent.complete(options, &block)).is_a?(String)
-      $stderr.puts result
-      false
-    else
-      true
-    end
-  end
+  #  Bond.complete(:method=>'system', :action=>:shell_commands)
+  def complete(options={}, &block); M.complete(options, &block); end
 
-  # Redefines an existing completion mission. Takes same options as Bond.complete. This is useful when wanting to override existing
-  # completions or when wanting to toggle between multiple definitions or modes of a completion.
-  def recomplete(options={}, &block)
-    if (result = agent.recomplete(options, &block)).is_a?(String)
-      $stderr.puts result
-      false
-    else
-      true
-    end
-  end
-
-  # Resets Bond so that next time Bond.complete is called, a new set of completion missions are created. This does not
-  # change current completion behavior.
-  def reset
-    @agent = nil
-  end
-
-  # Debriefs Bond to set global defaults. Call before defining completions.
-  # ==== Options:
-  # [:readline_plugin] Specifies a Bond plugin to interface with a Readline-like library. Available plugins are Bond::Readline and Bond::Rawline.
-  #                    Defaults to Bond::Readline. Note that a plugin doesn't imply use with irb. Irb is joined to the hip with Readline.
-  # [:default_mission] A proc to be used as the default completion proc when no completions match or one fails. When in irb with completion
-  #                    enabled, uses irb completion. Otherwise defaults to a proc with an empty completion list.
-  # [:default_search] A symbol or proc to be used as the default search in completions. See Bond.complete's :search option for valid symbols.
-  # [:eval_binding] Specifies a binding to be used with Bond::Missions::ObjectMission. When in irb, defaults to irb's main binding. Otherwise
-  #                 defaults to TOPLEVEL_BINDING.
-  # [:debug]  Boolean to print unexpected errors when autocompletion fails. Default is false.
-  #
+  # Redefines an existing completion mission to have a different action. The condition can only be varied if :name is
+  # used to identify and replace a mission. Takes same options as Bond.complete.
   # ==== Example:
-  #   Bond.debrief :default_search=>:underscore, :default_mission=>:default
-  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
+  #   Bond.recomplete(:on=>/man/, :name=>:count) { %w{4 5 6}}
+  def recomplete(options={}, &block); M.recomplete(options, &block); end
 
-  # Reports what completion mission and possible completions would happen for a given input. Helpful for debugging
-  # your completion missions.
+  # Reports what completion mission matches for a given input. Helpful for debugging missions.
   # ==== Example:
   #   >> Bond.spy "shoot oct"
   #   Matches completion mission for method matching "shoot".
   #   Possible completions: ["octopussy"]
-  def spy(input)
-    agent.spy(input)
-  end
+  def spy(*args); M.spy(*args); end
+
+  # Global config with the following keys:
+  # [*:readline_plugin*] Specifies a Bond plugin to interface with a Readline-like library. Available
+  #                      plugins are Readline and Rawline. Defaults to Readline.
+  # [*:default_mission*] A proc or name of an Rc method to use as the default completion when no
+  #                      missions match.
+  # [*:default_search*] Name of a *_search method in Rc to use as the default search in completions.
+  #                     Default is :underscore. See Bond.complete's :search option for valid values.
+  # [*:eval_binding*] Specifies a binding to use when evaluating objects in ObjectMission and MethodMission.
+  #                   When in irb, defaults to irb's current binding. Otherwise defaults to TOPLEVEL_BINDING.
+  # [*:debug*]  Boolean to show the stacktrace when autocompletion fails and raise exceptions in Rc.eval.
+  #             Default is false.
+  def config; M.config; end
+
+  # Starts Bond with a default set of completions that replace and improve irb's completion. Loads completion
+  # files in the following order: lib/bond/completion.rb, optional ~/.bondrc, lib/bond/completions/*.rb,
+  # optional ~/.bond/completions/*.rb and optional block. See Rc for the DSL to use in completion files and
+  # in the block. See Bond.config for valid options.
+  # ==== Example:
+  #   Bond.start(:default_search=>:ignore_case) do
+  #     complete(:method=>"Object#respond_to?") {|e| e.object.methods }
+  #   end
+  def start(options={}, &block); M.start(options, &block); end
 
-  def agent #:nodoc:
-    @agent ||= Agent.new(config)
-  end
+  # An Agent who saves all Bond.complete missions and executes the correct one when a completion is called.
+  def agent; M.agent; end
 
-  def config #:nodoc:
-    @config ||= {:readline_plugin=>Bond::Readline, :debug=>false}
-  end
+  # Lists all methods that have argument completion.
+  def list_methods; MethodMission.all_methods; end
 end

data/lib/bond/agent.rb

@@ -1,19 +1,29 @@
 module Bond
-  # Handles finding and executing the first mission that matches the input line. Once found, it calls the mission's action.
+  # Every time a completion is attempted, the Agent searches its missions for the first one that matches the user input.
+  # Using either the found mission or Agent.default_mission, the Agent executes the mission's action.
   class Agent
     # The array of missions that will be searched when a completion occurs.
     attr_reader :missions
+    # An agent's best friend a.k.a. the readline plugin.
+    attr_reader :weapon
 
     def initialize(options={}) #:nodoc:
-      raise ArgumentError unless options[:readline_plugin].is_a?(Module)
-      extend(options[:readline_plugin])
+      setup_readline_plugin(options[:readline_plugin])
       @default_mission_action = options[:default_mission] if options[:default_mission]
-      @eval_binding = options[:eval_binding] if options[:eval_binding]
-      Mission.default_search = options[:default_search] if options[:default_search]
-      setup
+      Mission.eval_binding = options[:eval_binding] if options[:eval_binding]
+      Search.default_search = options[:default_search] || :normal
       @missions = []
     end
 
+    def setup_readline_plugin(plugin) #:nodoc:
+      raise ArgumentError unless plugin.is_a?(Module)
+      @weapon = plugin.extend(plugin)
+      @weapon.setup(self)
+    rescue
+      $stderr.puts "Bond Error: Failed #{plugin.to_s[/[^:]+$/]} setup with '#{$!.message}'"
+    end
+
+    # Creates a mission.
     def complete(options={}, &block)
       if (mission = create_mission(options, &block)).is_a?(Mission)
         mission.place.is_a?(Integer) ? @missions.insert(mission.place - 1, mission).compact! : @missions << mission
@@ -23,19 +33,17 @@ module Bond
     end
 
     def create_mission(options, &block) #:nodoc:
-      options[:action] ||= block
-      Mission.create(options.merge(:eval_binding=>@eval_binding))
+      Mission.create options.merge!(:action=>options[:action] || block)
     rescue InvalidMissionError
-      "Invalid mission given. Mission needs an action and a condition."
-    rescue InvalidMissionActionError
-      "Invalid mission action given. Make sure action responds to :call or refers to a predefined action that does."
+      "Invalid #{$!.message} for completion with options: #{options.inspect}"
     rescue
-      "Mission setup failed with:\n#{$!}"
+      "Unexpected error while creating completion with options #{options.inspect}:\n#{$!}"
     end
 
+    # Creates a mission and replaces the mission it matches if possible.
     def recomplete(options={}, &block)
       if (mission = create_mission(options, &block)).is_a?(Mission)
-        if (existing_mission = @missions.find {|e| e.unique_id == mission.unique_id })
+        if (existing_mission = @missions.find {|e| e.name == mission.name })
           @missions[@missions.index(existing_mission)] = mission
           sort_last_missions
         else
@@ -55,31 +63,29 @@ module Bond
 
     # This is where the action starts when a completion is initiated.
     def call(input)
-      mission_input = line_buffer
+      mission_input = @weapon.line_buffer
       mission_input = $1 if mission_input !~ /#{Regexp.escape(input)}$/ && mission_input =~ /^(.*#{Regexp.escape(input)})/
-      (mission = find_mission(mission_input)) ? mission.execute : default_mission.execute(input)
-    rescue FailedExecutionError
-      $stderr.puts "", $!.message
+      (mission = find_mission(mission_input)) ? mission.execute : default_mission.execute(Input.new(input))
+    rescue FailedMissionError
+      completion_error($!.message[0], "Completion Info: #{$!.message[1]}")
     rescue
-      if Bond.config[:debug]
-        p $!
-        p $!.backtrace.slice(0,5)
-      end
-      default_mission.execute(input)
+      completion_error "Failed internally with '#{$!.message}'.",
+        "Please report this issue with debug on: Bond.config[:debug] = true."
     end
 
+    def completion_error(desc, message) #:nodoc:
+      arr = ["Bond Error: #{desc}", message]
+      arr << "Stack Trace: #{$!.backtrace.inspect}" if Bond.config[:debug]
+      arr
+    end
+
+    # Given a hypothetical user input, reports back what mission it would have found and executed.
     def spy(input)
       if (mission = find_mission(input))
-        if mission.is_a?(Missions::ObjectMission)
-          puts "Matches completion mission for object with an ancestor matching #{mission.object_condition.inspect}."
-        elsif mission.is_a?(Missions::MethodMission)
-          puts "Matches completion mission for method matching #{mission.method_condition.inspect}."
-        else
-          puts "Matches completion mission with condition #{mission.condition.inspect}."
-        end
-        puts "Possible completions: #{mission.execute.inspect}"
+        puts mission.match_message, "Possible completions: #{mission.execute.inspect}",
+          "Matches for #{mission.condition.inspect} are #{mission.matched.to_a.inspect}"
       else
-        puts "Doesn't match a completion mission."
+        puts "Doesn't match a completion."
       end
     end
 
@@ -87,9 +93,9 @@ module Bond
       @missions.find {|mission| mission.matches?(input) }
     end
 
-    # Default mission used by agent.
+    # Default mission used by agent. An instance of DefaultMission.
     def default_mission
-      @default_mission ||= Missions::DefaultMission.new(:action=>@default_mission_action)
+      @default_mission ||= DefaultMission.new(:action=>@default_mission_action)
     end
   end
 end

data/lib/bond/completion.rb

@@ -1,28 +1,16 @@
-# You shouldn't place Bond.complete statements before requiring this file
-# unless you're also reproducing this Bond.debrief
-Bond.debrief(:default_search=>:underscore) unless Bond.config[:default_search]
-Bond.debrief(:default_mission=>:default) unless Bond.config[:default_mission]
-Bond.complete(:method=>/system|`/, :action=>:shell_commands)
-Bond.complete(:method=>'require', :action=>:method_require, :search=>false)
-
-# irb/completion reproduced without the completion quirks
-# Completes classes and constants
-Bond.complete(:on=>/(((::)?[A-Z][^:.\(]*)+)::?([^:.]*)$/, :action=>:constants, :search=>false)
-# Completes absolute constants
-Bond.complete(:on=>/::([A-Z][^:\.\(]*)$/, :search=>false) {|e|
-  Object.constants.grep(/^#{Regexp.escape(e.matched[1])}/).collect{|f| "::" + f}
+# any object's methods
+complete :object=>"Object"
+# method arguments
+complete :all_methods=>true
+complete :all_operator_methods=>true
+# classes and constants
+complete(:name=>:constants, :anywhere=>'(((::)?[A-Z][^:.\(]*)+)::?([^:.]*)') {|e|
+  receiver = e.matched[2]
+  candidates = eval("#{receiver}.constants | #{receiver}.methods") || []
+  normal_search(e.matched[5], candidates).map {|e| receiver + "::" + e}
 }
-# Completes symbols
-Bond.complete(:on=>/(:[^:\s.]*)$/) {|e|
-  Symbol.respond_to?(:all_symbols) ? Symbol.all_symbols.map {|f| ":#{f}" } : []
-}
-# Completes global variables
-Bond.complete(:on=>/(\$[^\s.]*)$/, :search=>false) {|e|
-  global_variables.grep(/^#{Regexp.escape(e.matched[1])}/)
-}
-# Completes files
-Bond.complete(:on=>/[\s(]["']([^'"]*)$/, :search=>false, :action=>:quoted_files, :place=>:last)
-# Completes any object's methods
-Bond.complete(:object=>"Object", :place=>:last)
-# Completes method completion anywhere in the line
-Bond.complete(:on=>/([^.\s]+)\.([^.\s]*)$/, :object=>"Object", :place=>:last)
+# absolute constants
+complete(:prefix=>'::', :anywhere=>'[A-Z][^:\.\(]*') {|e| Object.constants }
+complete(:anywhere=>':[^:\s.]*') {|e|  Symbol.all_symbols.map {|f| ":#{f}" } rescue [] }
+complete(:anywhere=>'\$[^\s.]*') {|e| global_variables }
+complete(:name=>:quoted_files, :on=>/[\s(]["']([^'"]*)$/, :search=>false, :place=>:last) {|e| files(e.matched[1]) }

data/lib/bond/completions/activerecord.rb

@@ -0,0 +1,12 @@
+attribute_imethods = %w{attribute_for_inspect column_for_attribute decrement} +
+  %w{increment update_attribute toggle update_attributes []}
+complete(:methods=>attribute_imethods, :class=>"ActiveRecord::Base#") {|e| e.object.attribute_names }
+
+attribute_cmethods = %w{attr_accessible attr_protected attr_readonly create create! decrement_counter} +
+  %w{destroy_all exists? increment_counter new serialize update update_all update_counters where}
+complete(:methods=>attribute_cmethods, :class=>'ActiveRecord::Base.') {|e| e.object.column_names }
+
+complete(:method=>"ActiveRecord::Base.establish_connection") { %w{adapter host username password database} }
+complete(:methods=>%w{find all first last}, :class=>'ActiveRecord::Base.') {
+  %w{conditions order group having limit offset joins include select from readonly lock}
+}

data/lib/bond/completions/array.rb

@@ -0,0 +1 @@
+complete(:methods=>%w{delete index rindex include?}, :class=>"Array#") {|e| e.object }

data/lib/bond/completions/bond.rb

@@ -0,0 +1,2 @@
+complete(:methods=>%w{Bond.complete Bond.recomplete}) {
+  %w{on action method methods class object prefix search place name} }

data/lib/bond/completions/hash.rb

@@ -0,0 +1,3 @@
+complete(:methods=>%w{delete fetch store, [] has_key? key? include? member? values_at},
+  :class=>"Hash#") {|e| e.object.keys }
+complete(:methods=>%w{index value? has_value?}, :class=>"Hash#") {|e| e.object.values }

data/lib/bond/completions/kernel.rb

@@ -0,0 +1,13 @@
+complete(:methods=>%w{Kernel#raise Kernel#fail}) { objects_of(Class).select {|e| e < StandardError } }
+complete(:method=>%w{Kernel#system Kernel#exec}) {|e|
+  ENV['PATH'].split(File::PATH_SEPARATOR).uniq.map {|e| Dir.entries(e) }.flatten.uniq - ['.', '..']
+}
+complete(:method=>"Kernel#require", :search=>:files) {
+  paths = $:.map {|e| Dir["#{e}/**/*.{rb,bundle,dll,so}"].map {|f| f.sub(e+'/', '') } }.flatten
+  if Object.const_defined?(:Gem)
+    paths += Gem.path.map {|e| Dir["#{e}/gems/*/lib/*.{rb,bundle,dll,so}"].
+      map {|f| f.sub(/^.*\//,'') } }.flatten
+  end
+  paths.uniq
+}
+complete(:methods=>%w{Kernel#trace_var Kernel#untrace_var}) { global_variables.map {|e| ":#{e}"} }

data/lib/bond/completions/module.rb

@@ -0,0 +1,7 @@
+complete(:methods=>%w{const_get const_set const_defined? remove_const}, :class=>"Module#") {|e| e.object.constants }
+complete(:methods=>%w{class_variable_defined? class_variable_get class_variable_set remove_class_variable},
+  :class=>"Module#") {|e| e.object.class_variables }
+complete(:methods=>%w{instance_method method_defined? module_function public private protected remove_method undef_method},
+  :class=>"Module#") {|e| e.object.instance_methods }
+complete(:methods=>%w{< <= <=> > >= include? include}, :class=>"Module#", :search=>:modules) { objects_of(Module) }
+complete(:method=>'Module#alias_method') {|e| e.argument > 1 ? e.object.instance_methods : [] }

data/lib/bond/completions/object.rb

@@ -0,0 +1,21 @@
+instance_meths = %w{instance_variable_get instance_variable_set remove_instance_variable instance_variable_defined?}
+complete(:methods=>instance_meths, :class=>"Object#") {|e| e.object.instance_variables }
+complete(:method=>"Object#instance_of?", :search=>:modules) { objects_of(Class) }
+complete(:methods=>%w{is_a? kind_a? extend}, :class=>"Object#", :search=>:modules) { objects_of(Module) }
+complete(:methods=>%w{Object#method Object#respond_to?}) {|e| e.object.methods }
+complete(:method=>"Object#[]") {|e| e.object.keys rescue [] }
+complete(:method=>"Object#send") {|e|
+  if e.argument > 1
+    if (meth = eval(e.arguments[0])) && meth.to_s != 'send' &&
+      (action = MethodMission.find(e.object, meth.to_s))
+      e.argument -= 1
+      e.arguments.shift
+      action[0].call(e)
+    end
+  else
+    send_methods(e.object)
+  end
+}
+def send_methods(obj)
+  (obj.methods + obj.private_methods(false)).map {|e| e.to_s } - Mission::OPERATORS
+end

data/lib/bond/completions/struct.rb

@@ -0,0 +1 @@
+complete(:method=>"Struct#[]") {|e| e.object.members }

data/lib/bond/input.rb

@@ -0,0 +1,28 @@
+module Bond
+  # A string representing the last word the user has typed. This string is passed to a mission
+  # action to generate possible completions. This string contains a number of attributes from the
+  # matching mission, useful in generating completions.
+  class Input < String
+    # Actual object a user has just typed. Used by MethodMission and ObjectMission.
+    attr_accessor :object
+    # MatchData object from the matching mission (Mission#matched).
+    attr_reader :matched
+    # Current argument number and array of argument strings. Used by MethodMission.
+    attr_accessor :argument, :arguments
+    # The full line the user has typed.
+    attr_reader :line
+    def initialize(str, options={}) #:nodoc:
+      super(str || '')
+      @matched = options[:matched]
+      @line = options[:line]
+      @object = options[:object] if options[:object]
+      @argument = options[:argument] if options[:argument]
+      @arguments = options[:arguments] if options[:arguments]
+    end
+
+    def inspect #:nodoc:
+      "#<Bond::Input #{self.to_s.inspect} @matched=#{@matched.to_a.inspect} @line=#{@line.inspect} "+
+      "@argument=#{@argument.inspect} @arguments=#{@arguments.inspect} @object=#{@object.inspect}>"
+    end
+  end
+end