bond 0.1.0

data/CHANGELOG.rdoc

@@ -0,0 +1,2 @@
+== 0.1.0
+* Intial release. Whoop!

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT LICENSE
+
+Copyright (c) 2009 Gabriel Horner
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,191 @@
+== Description
+
+Bond is on a mission to make custom autocompletion easy in irb and other console/readline-like
+environments. Bond supports custom argument completion of methods, method completion of objects and
+anything else your wicked regex's can do. Bond comes armed with a Readline C extension to get the
+full line of input as opposed to irb's last-word based completion. Bond makes custom searching of
+possible completions easy which allows for nontraditional ways of autocompleting i.e. instant
+aliasing of multi worded methods.
+
+== Install
+
+Install the gem with:
+
+    sudo gem install cldwalker-bond --source http://gems.github.com
+
+== Usage
+
+=== Argument Completion for Methods
+
+    bash> irb -rirb/completion -rubygems
+    # This loads Bond but it doesn't take over completion yet.
+    >> require 'bond'
+
+    # For Bond to handle completions, we must explicitly define a completion mission.
+    # Order matters since the order they're declared in is the order they're searched.
+    >> Bond.complete(:method=>'method1') {|input|  %w{some args to autocomplete} }
+    => true
+    >> Bond.complete(:method=>'method2') {|input|  %w{more args to autocomplete} }
+    => true
+
+    # Works as above
+    >> method1 [TAB]
+    args   autocomplete   some   to
+    >> method1 'a[TAB]
+    args   autocomplete
+    >> method1 'au[TAB]
+    >> method1 'autocomplete'
+
+    # Anything not matched by the above completion missions defaults to irb completion
+    >> $std[TAB]
+    $stderr  $stdin   $stdout
+    
+=== File Argument Completion for Methods
+
+    # Pass :search=>false to turn off Bond searching since FILENAME_COMPLETION_PROC does it for us.
+    >> Bond.complete(:method=>"File.read", :search=>false) {|input| 
+        Readline::FILENAME_COMPLETION_PROC.call(input) || [] }
+    => true
+
+    # Test drive it
+    >> File.read '[TAB]
+    .git/   LICENSE.txt   README.rdoc   Rakefile      VERSION.yml   bond.gemspec  ext/    lib/     test/
+    >> File.read 'l[TAB]
+    >> File.read 'lib/
+    >> File.read 'lib/bond.[TAB]
+    >> File.read 'lib/bond.rb'
+
+    # Since File.read doesn't understand ~, let's improve the above completion proc
+    >> file_completion = proc {|input| (Readline::FILENAME_COMPLETION_PROC.call(input) ||
+        []).map {|f| f =~ /^~/ ?  File.expand_path(f) : f } }
+    => #< Proc:0x0100f1d0@(irb):20>
+    >> Bond.reset; Bond.complete :method=>"File.read", :search=>false, &file_completion
+    => true
+
+    # Tilda test driving
+    >> File.read "~/[TAB]
+    >> File.read "/Users/bozo/
+    >> File.read "/Users/bozo/.alias.[TAB]
+    >> File.read "/Users/bozo/.alias.yml"
+    
+    # Let's add this to *all* our File methods:
+    >> Bond.reset; Bond.complete :method=>/File\.(#{Regexp.union(*File.methods(false))})/,
+        :search=>false, &file_completion
+    => true
+
+=== Method Autocompletion on Specified Objects
+    # Let's explore Bond::Agent's functionality
+     >> ba = Bond.agent; nil
+     => nil
+     # Irb let's you autocomplete everything that an object responds to for better or worse.
+     >> ba.[TAB]
+     ba.__id__                      ba.eql?                        ba.instance_eval               ba.method                      ba.send                        ba.to_yaml
+     ba.__send__                    ba.equal?                      ba.instance_of?                ba.methods                     ba.setup                       ba.to_yaml_properties
+     ba.call                        ba.extend                      ba.instance_variable_defined?  ba.missions                    ba.singleton_methods           ba.to_yaml_style
+     ba.class                       ba.find_mission                ba.instance_variable_get       ba.nil?                        ba.taguri                      ba.type
+     ba.clone                       ba.freeze                      ba.instance_variable_set       ba.object_id                   ba.taguri=                     ba.untaint
+     ba.complete                    ba.frozen?                     ba.instance_variables          ba.private_methods             ba.taint                       
+     ba.default_mission             ba.hash                        ba.is_a?                       ba.protected_methods           ba.tainted?                    
+     ba.display                     ba.id                          ba.kind_of?                    ba.public_methods              ba.to_a                        
+     ba.dup                         ba.inspect                     ba.line_buffer                 ba.respond_to?                 ba.to_s                        
+
+
+     # Since it's hard to see Bond::Agent's functionality amidst all the Object and Kernel methods, 
+     # let's autocomplete just it's instance methods.
+     >> Bond.complete(:object=>Bond::Agent) {|input| input.object.class.instance_methods(false) }
+     => true
+
+     # A less cluttered display of Bond::Agent's functionality.
+     >> ba.[TAB]
+     ba.call             ba.complete         ba.default_mission  ba.find_mission     ba.missions
+
+     # Let's have all Bond::* objects do this.
+     >> Bond.reset; Bond.complete(:object=>/^Bond::/) {|input| input.object.class.instance_methods(false) }
+     => true
+
+    # Let's revert method autocompletion back to irb's defaults for Bond::* objects.
+    >> Bond.reset; Bond.complete :object=>/^Bond::/
+    
+=== Underscore Search
+
+    # Firing up a rails console
+    bash> script/console
+    >> require 'bond'
+    => true
+
+    # Set all ActiveRecord::Base descendants to use the predefined underscore search
+    >> Bond.complete :object=>ActiveRecord::Base, :search=>:underscore
+    => true
+
+    # With this search we can still autocomplete the traditional way.
+    # Url is a model object
+    >> Url.first.tag_[TAB]
+    Url.first.tag_add_and_remove   Url.first.tag_and_save         Url.first.tag_ids=             Url.first.tag_list=            
+    Url.first.tag_add_and_save     Url.first.tag_ids              Url.first.tag_list             Url.first.tag_remove_and_save
+    >> Url.tag_ad[TAB]
+    >> Url.tag_add_and_
+    >> Url.tag_add_and_[TAB]
+    Url.first.tag_add_and_remove  Url.first.tag_add_and_save 
+    >> Url.tag_add_and_s[TAB]
+    >> Url.tag_add_and_save
+
+    # But this search goes the extra mile with textmate-like searching.
+    # Type just the first letter of each underscored word separated by '-'
+    >> Url.first.t-a-a-s[TAB]
+    >> Url.first.tag_add_and_save
+
+    # With this search, most multi-worded methods are just a few keystrokes away.
+    # If multiple methods match the underscore alias, it still autocompletes the beginning of the method:
+    >> Url.first.p[TAB]
+    Url.first.partial_updates                  Url.first.pretty_inspect                   Url.first.pretty_print_instance_variables  Url.first.public_methods
+    Url.first.partial_updates?                 Url.first.pretty_print                     Url.first.primary_key_prefix_type          
+    Url.first.pluralize_table_names            Url.first.pretty_print_cycle               Url.first.private_methods                  
+    Url.first.present?                         Url.first.pretty_print_inspect             Url.first.protected_methods
+    >> Url.first.p-p[TAB]
+    >> Url.first.pretty_print
+    >> Url.first.pretty_print_c[TAB]
+    >> Url.first.pretty_print_cycle
+
+
+=== Custom AutoCompletion
+
+    bash> irb -rirb/completion -rubygems -rbond
+    # Let's reuse the file completion from above
+    >> file_completion = proc {|input| (Readline::FILENAME_COMPLETION_PROC.call(input) ||
+        []).map {|f| f =~ /^~/ ?  File.expand_path(f) : f } }
+    => #< Proc:0x0100f1d0@(irb):1>
+
+    # But this time let's trigger it whenever the last word in the line is quoted
+    # fyi this is default behavior if you use irb without requiring irb/completion
+    >> Bond.complete(:on=>/\S+\s*["']([^'".]*)$/, :search=>false) {|input| file_completion.call(input.matched[1]) }
+    => true
+
+    # Now it doesn't matter what methods come before. If the last word is quoted we get file completion:
+    >> Dir.entries '[TAB]
+    .git/   LICENSE.txt   README.rdoc   Rakefile      VERSION.yml   bond.gemspec  ext/    lib/     test/
+    >> Dir.entries 'l[TAB]
+    >> Dir.entries 'lib/
+    >> `ls 't[TAB]
+    >> `ls 'test/
+    >> `ls 'test/'`
+
+    # String method completion still works
+    >> '007'.[TAB]
+    Display all 137 possibilities? (y or n)
+
+== Credits
+Thanks to Csaba Hank for {providing the C extension}[http://www.creo.hu/~csaba/ruby/irb-enhancements/doc/files/README.html]
+which Bond uses to read Readline's full buffer. Thanks also goes out to Takao Kouji for {recently
+commiting}[http://svn.ruby-lang.org/cgi-bin/viewvc.cgi/trunk/ext/readline/readline.c?view=diff&r1=24018&r2=24019]
+this Readline enhancement to ruby.
+
+== Bugs
+The underscore search intermittently doesn't complete when it should and deletes the last
+character typed.
+
+== Todo
+* Allow Bond to easily get its completion missions from a module.
+* Provide a set of Bond completions which can serve as a drop-in replacement for irb/completion.
+* Bond.spy for easily viewing/debugging what completion mission matches a given input.
+* Argument autocompletion by object class.
+* Make replacement of existing completions not require doing a Bond.reset.

data/Rakefile

@@ -0,0 +1,77 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+begin
+  require 'rcov/rcovtask'
+
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/*_test.rb']
+    t.rcov_opts = ["-T -x '/Library/Ruby/*'"]
+    t.verbose = true
+  end
+rescue LoadError
+  puts "Rcov not available. Install it for rcov-related tasks with: sudo gem install rcov"
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "bond"
+    s.summary = "Mission: Easy custom autocompletion for arguments, methods and beyond. Accomplished for irb and any other readline-like console environments."
+    s.description = "Bond is on a mission to make custom autocompletion easy in irb and other console/readline-like environments. Bond supports custom argument completion of methods, method completion of objects and anything else your wicked regex's can do. Bond comes armed with a Readline C extension to get the full line of input as opposed to irb's last-word based completion. Bond makes custom searching of possible completions easy which allows for nontraditional ways of autocompleting i.e. instant aliasing of multi worded methods."
+    s.email = "gabriel.horner@gmail.com"
+    s.homepage = "http://tagaholic.me/bond/"
+    s.authors = ["Gabriel Horner"]
+    s.rubyforge_project = 'tagaholic'
+    s.has_rdoc = true
+    s.extra_rdoc_files = ["README.rdoc", "LICENSE.txt"]
+    s.extensions = ["ext/readline_line_buffer/extconf.rb"]
+    s.files = FileList["CHANGELOG.rdoc", "Rakefile", "README.rdoc", "VERSION.yml", "LICENSE.txt", "{bin,lib,test,ext}/**/*"]
+  end
+
+rescue LoadError
+  puts "Jeweler not available. Install it for jeweler-related tasks with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'test'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# I assume contributors can edit the gemspec for most attributes except for file-related ones.
+# For those attributes you can use the gemspec_update task. I prefer not to give you the gem-creator-specific rake
+# tasks I use to generate gemspecs to give you the choice of generating gemspecs however you'd like.
+# More about this here: http://tagaholic.me/2009/04/08/building-dry-gems-with-thor-and-jeweler.html .
+desc "Update gemspec from existing one by regenerating path globs specified in *.gemspec.yml or defaults to liberal path globs."
+task :gemspec_update  do
+  if (gemspec_file = Dir['*.gemspec'][0])
+    original_gemspec = eval(File.read(gemspec_file))
+    if File.exists?("#{gemspec_file}.yml")
+      require 'yaml'
+      YAML::load_file("#{gemspec_file}.yml").each do |attribute, globs|
+        original_gemspec.send("#{attribute}=", FileList[globs])
+      end
+    else
+      # liberal defaults
+      original_gemspec.files = FileList["**/*"]
+      test_directories = original_gemspec.test_files.grep(/\//).map {|e| e[/^[^\/]+/]}.compact.uniq
+      original_gemspec.test_files = FileList["{#{test_directories.join(',')}}/**/*"] unless test_directories.empty?
+    end
+    File.open(gemspec_file, 'w') {|f| f.write(original_gemspec.to_ruby) }
+    puts "Updated gemspec."
+  else
+    puts "No existing gemspec file found."
+  end
+end
+
+task :default => :test

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 0

data/ext/readline_line_buffer/extconf.rb

@@ -0,0 +1,3 @@
+require "mkmf"
+dir_config 'readline_line_buffer'
+create_makefile 'readline_line_buffer'

data/ext/readline_line_buffer/readline_line_buffer.c

@@ -0,0 +1,22 @@
+/* readline.c -- GNU Readline module
+   Copyright (C) 1997-2001  Shugo Maeda */
+/* body of line_buffer() from irb enhancements at http://www.creo.hu/~csaba/ruby/ */
+ 
+#include "ruby.h"
+#include <errno.h>
+#include <stdio.h>
+#include <readline/readline.h>
+
+static VALUE line_buffer(VALUE self)
+{
+    rb_secure(4);
+    if (rl_line_buffer == NULL)
+      return Qnil;
+    return rb_tainted_str_new2(rl_line_buffer);
+}
+
+void Init_readline_line_buffer() {
+  VALUE c = rb_cObject;
+  c = rb_const_get(c, rb_intern("Readline"));
+  rb_define_singleton_method(c, "line_buffer", (VALUE(*)(ANYARGS))line_buffer, -1);
+}

data/lib/bond.rb

@@ -0,0 +1,92 @@
+current_dir = File.dirname(__FILE__)
+$:.unshift(current_dir) unless $:.include?(current_dir) || $:.include?(File.expand_path(current_dir))
+require 'bond/readline'
+require 'bond/rawline'
+require 'bond/agent'
+require 'bond/search'
+require 'bond/mission'
+require 'bond/missions/default_mission'
+require 'bond/missions/method_mission'
+require 'bond/missions/object_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 you should probably declare general
+#   completions at the end.
+# * 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.
+  # ====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.
+  #
+  # ==== 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)
+  #  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)
+    agent.complete(options, &block)
+    true
+  rescue InvalidMissionError
+    $stderr.puts "Invalid mission given. Mission needs an action and a condition."
+    false
+  rescue
+    $stderr.puts "Mission setup failed with:", $!
+    false
+  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.
+  # ==== 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.
+  # [: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.
+  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.include?(e)}
+      $stderr.puts "Invalid readline plugin set. Try again."
+    end
+  end
+
+  def agent #:nodoc:
+    @agent ||= Agent.new(config)
+  end
+
+  def config #:nodoc:
+    @config ||= {:readline_plugin=>Bond::Readline, :debug=>false}
+  end
+end

data/lib/bond/agent.rb

@@ -0,0 +1,44 @@
+module Bond
+  # Handles finding and executing the first mission that matches the input line. Once found, it calls the mission's action.
+  class Agent
+    # The array of missions that will be searched when a completion occurs.
+    attr_reader :missions
+
+    def initialize(options={}) #:nodoc:
+      raise ArgumentError unless options[:readline_plugin].is_a?(Module)
+      extend(options[:readline_plugin])
+      @default_mission_action = options[:default_mission] if options[:default_mission]
+      @eval_binding = options[:eval_binding] if options[:eval_binding]
+      setup
+      @missions = []
+    end
+
+    def complete(options={}, &block) #:nodoc:
+      @missions << Mission.create(options.merge(:action=>block, :eval_binding=>@eval_binding))
+    end
+
+    # This is where the action starts when a completion is initiated.
+    def call(input)
+      (mission = find_mission(input)) ? mission.execute : default_mission.execute(input)
+    rescue FailedExecutionError
+      $stderr.puts "", $!.message
+    rescue
+      if Bond.config[:debug]
+        p $!
+        p $!.backtrace.slice(0,5)
+      end
+      default_mission.execute(input)
+    end
+
+    # No need to use what's passed to the completion proc when we can get the full line.
+    def find_mission(input) #:nodoc:
+      all_input = line_buffer
+      @missions.find {|mission| mission.matches?(all_input) }
+    end
+
+    # Default mission used by agent.
+    def default_mission
+      @default_mission ||= Missions::DefaultMission.new(:action=>@default_mission_action)
+    end
+  end
+end

data/lib/bond/mission.rb

@@ -0,0 +1,77 @@
+module Bond
+  # Occurs when a mission is incorrectly defined.
+  class InvalidMissionError < StandardError; end
+  # Occurs when a mission or search action fails.
+  class FailedExecutionError < StandardError; end
+  # Namespace for subclasses of Bond::Mission.
+  class Missions; end
+
+  # A set of conditions and actions to take for a completion scenario or mission in Bond's mind.
+  class Mission
+    include Search
+
+    # Handles creation of proper Mission class depending on the options passed.
+    def self.create(options)
+      if options[:method]
+        Missions::MethodMission.new(options)
+      elsif options[:object]
+        Missions::ObjectMission.new(options)
+      else
+        new(options)
+      end
+    end
+
+    attr_reader :action
+    OPERATORS = ["%", "&", "*", "**", "+",  "-",  "/", "<", "<<", "<=", "<=>", "==", "===", "=~", ">", ">=", ">>", "[]", "[]=", "^"]
+
+    # 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.
+    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]
+      @condition = options[:on]
+      @search = options.has_key?(:search) ? options[:search] : method(:default_search)
+      @search = method("#{options[:search]}_search") if respond_to?("#{options[:search]}_search")
+    end
+
+    # Returns a boolean indicating if a mission matches the given input.
+    def matches?(input)
+      if (match = handle_valid_match(input))
+        @input.instance_variable_set("@matched", @matched)
+        @input.instance_eval("def self.matched; @matched ; end")
+      end
+      !!match
+    end
+
+    # Called when a mission has been chosen to autocomplete.
+    def execute(*args)
+      if args.empty?
+        list = @action.call(@input) || []
+        list = @search ? @search.call(@input, list) : list
+        @list_prefix ? list.map {|e| @list_prefix + e } : list
+      else
+        @action.call(*args)
+      end
+    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
+    end
+
+    #:stopdoc:
+    def set_input(input, match)
+      @input = input[/\S+$/]
+    end
+
+    def handle_valid_match(input)
+      if (match = input.match(@condition))
+        set_input(input, match)
+        @matched ||= match
+      end
+      match
+    end
+    #:startdoc:
+  end
+end

data/lib/bond/missions/default_mission.rb

@@ -0,0 +1,11 @@
+# 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
+    super
+  end
+
+  def default_action #:nodoc:
+    Object.const_defined?(:IRB) && IRB.const_defined?(:InputCompletor) ? IRB::InputCompletor::CompletionProc : lambda {|e| [] }
+  end
+end

data/lib/bond/missions/method_mission.rb

@@ -0,0 +1,13 @@
+# Represents a completion mission specified by :method in Bond.complete.
+class Bond::Missions::MethodMission < Bond::Mission
+  def initialize(options={}) #:nodoc:
+    @method = options.delete(:method)
+    @method = Regexp.quote(@method.to_s) unless @method.is_a?(Regexp)
+    options[:on] = /^\s*(#{@method})\s*['"]?(.*)$/    
+    super
+  end
+
+  def set_input(input, match) #:nodoc:
+    @input = match[-1]
+  end
+end

data/lib/bond/missions/object_mission.rb

@@ -0,0 +1,41 @@
+# Represents a completion mission specified by :object in Bond.complete. Unlike other missions, this
+# one needs to both match the mission condition and have the current object being completed have
+# an ancestor specified by :object.
+class Bond::Missions::ObjectMission < Bond::Mission
+  #:stopdoc:
+  def initialize(options={})
+    @object_condition = options.delete(:object)
+    @object_condition = /^#{Regexp.quote(@object_condition.to_s)}$/ unless @object_condition.is_a?(Regexp)
+    options[:on] = /^((\.?[^.]+)+)\.([^.]*)$/
+    @eval_binding = options[:eval_binding] || default_eval_binding
+    super
+  end
+
+  def handle_valid_match(input)
+    match = super
+    if match && eval_object(match) && (match = @evaled_object.class.ancestors.any? {|e| e.to_s =~ @object_condition })
+      @list_prefix = @matched[1] + "."
+      @input = @matched[3]
+      @input.instance_variable_set("@object", @evaled_object)
+      @input.instance_eval("def self.object; @object ; end")
+      @action ||= lambda {|e| default_action(e.object) }
+    else
+      match = false
+    end
+    match
+  end
+
+  def eval_object(match)
+    @matched = match
+    @evaled_object = begin eval("#{match[1]}", @eval_binding); rescue Exception; nil end
+  end
+
+  def default_action(obj)
+    obj.methods - OPERATORS
+  end
+
+  def default_eval_binding
+    Object.const_defined?(:IRB) ? IRB.CurrentContext.workspace.binding : ::TOPLEVEL_BINDING
+  end
+  #:startdoc:
+end

data/lib/bond/rawline.rb

@@ -0,0 +1,16 @@
+module Bond
+  # A readline plugin for use with {Rawline}[http://github.com/h3rald/rawline/tree/master]. This plugin
+  # should be used in conjunction with {a Rawline shell}[http://www.h3rald.com/articles/real-world-rawline-usage].
+  module Rawline
+    def setup
+      require 'rawline'
+      ::Rawline.completion_append_character = nil
+      ::Rawline.basic_word_break_characters= " \t\n\"\\'`><;|&{(" 
+      ::Rawline.completion_proc = self
+    end
+
+    def line_buffer
+      ::Rawline.editor.line.text
+    end
+  end
+end

data/lib/bond/readline.rb

@@ -0,0 +1,47 @@
+
+module Bond
+  # This is the default readline plugin for Bond. A valid plugin must define methods setup() and line_buffer(). setup()
+  # should load the readline-like library and set the completion_proc. line_buffer() should give access to the full line of what
+  # the user has typed.
+  module Readline
+    DefaultBreakCharacters = " \t\n\"\\'`><=;|&{("
+
+    def setup
+      require 'readline'
+      begin
+        require 'readline_line_buffer'
+      rescue LoadError
+        $stderr.puts "Failed to load readline_line_buffer extension. Falling back on RubyInline extension."
+        require 'inline'
+        eval %[
+          module ::Readline
+            inline do |builder|
+              %w(<errno.h> <stdio.h> <readline/readline.h>).each{|h| builder.include h }
+              builder.c_raw_singleton <<-EOC
+          static VALUE line_buffer(VALUE self)
+          {
+            rb_secure(4);
+            if (rl_line_buffer == NULL)
+          return Qnil;
+            return rb_tainted_str_new2(rl_line_buffer);
+          }
+          EOC
+            end
+          end
+        ]
+      end
+
+      # Reinforcing irb defaults
+      ::Readline.completion_append_character = nil
+      if ::Readline.respond_to?("basic_word_break_characters=")
+        ::Readline.basic_word_break_characters = DefaultBreakCharacters
+      end
+
+      ::Readline.completion_proc = self
+    end
+
+    def line_buffer
+      ::Readline.line_buffer
+    end
+  end
+end

data/lib/bond/search.rb

@@ -0,0 +1,30 @@
+module Bond
+  # Contains search methods used to filter possible completions given what the user has typed for that completion.
+  module Search
+    # Searches completions from the beginning of the string.
+    def default_search(input, list)
+      list.grep(/^#{input}/)
+    end
+
+    # Searches completions anywhere in the string.
+    def anywhere_search(input, list)
+      list.grep(/#{input}/)
+    end
+
+    # Searches completions from the beginning and ignores case.
+    def ignore_case_search(input, list)
+      list.grep(/^#{input}/i)
+    end
+
+    # Searches completions from the beginning but also provides aliasing of underscored words.
+    # For example 'some_dang_long_word' can be specified as 's-d-l-w'. Aliases can be any unique string
+    # at the beginning of an underscored word. For example, to choose the first completion between 'so_long' and 'so_larger',
+    # type 's-lo'.
+    def underscore_search(input, list)
+      split_input = input.split("-").join("")
+      list.select {|c|
+        c.split("_").map {|g| g[0,1] }.join("") =~ /^#{split_input}/ || c =~ /^#{input}/
+      }
+    end
+  end
+end

data/test/agent_test.rb

@@ -0,0 +1,64 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class Bond::AgentTest < Test::Unit::TestCase
+  before(:all) {|e| Bond.debrief(:readline_plugin=>valid_readline_plugin) }
+
+  context "InvalidAgent" do
+    test "prints error if no action given for mission" do
+      capture_stderr { Bond.complete :on=>/blah/ }.should =~ /Invalid mission/
+    end
+
+    test "prints error if no condition given" do
+      capture_stderr { Bond.complete {|e| []} }.should =~ /Invalid mission/
+    end
+  
+    test "prints error if invalid condition given" do
+      capture_stderr { Bond.complete(:on=>'blah') {|e| []} }.should =~ /Invalid mission/
+    end
+    
+    test "prints error if setting mission fails unpredictably" do
+      Bond.agent.expects(:complete).raises(ArgumentError)
+      capture_stderr { Bond.complete(:on=>/blah/) {|e| [] } }.should =~ /Mission setup failed/
+    end
+  end
+
+  context "Agent" do
+    before(:each) {|e| Bond.agent.instance_eval("@missions = []") }
+
+    test "chooses default mission if no missions match" do
+      Bond.complete(:on=>/bling/) {|e| [] }
+      Bond.agent.default_mission.expects(:execute)
+      complete 'blah'
+    end
+
+    test "chooses default mission if internal processing fails" do
+      Bond.complete(:on=>/bling/) {|e| [] }
+      Bond.agent.expects(:find_mission).raises
+      Bond.agent.default_mission.expects(:execute)
+      complete('bling')
+    end
+
+    test "prints error if action generates failure" do
+      Bond.complete(:on=>/bling/) {|e| raise "whoops" }
+      capture_stderr { complete('bling') }.should =~ /bling.*whoops/m
+    end
+  end
+
+  # TODO
+  # test "default_mission set to a valid mission if irb doesn't exist" do
+  #   old_default_action = Bond.agent.default_mission.action
+  #   Bond.agent.instance_eval("@default_mission = @default_mission_action = nil")
+  #   Object.expects(:const_defined?).with(:IRB).returns(false)
+  #   Bond.agent.default_mission.is_a?(Bond::Mission).should == true
+  #   Bond.agent.default_mission.action.respond_to?(:call).should == true
+  #   Bond.agent.default_mission.instance_variable_set(:@action, old_default_action)
+  # end
+
+  # test "binding set to toplevel binding if irb doesn't exist" do
+  #   old_binding = Bond.agent.eval_binding
+  #   Object.expects(:const_defined?).with(:IRB).returns(false)
+  #   Bond.agent.instance_eval("@eval_binding = nil")
+  #   Bond.agent.eval_binding.should == ::TOPLEVEL_BINDING
+  #   Bond.agent.instance_variable_set(:@eval_binding, old_binding)
+  # end
+end

data/test/bond_test.rb

@@ -0,0 +1,31 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class BondTest < Test::Unit::TestCase
+  context "debrief" do
+    before(:each) {|e| Bond.instance_eval("@agent = @config = nil")}
+    test "prints error if readline_plugin is not a module" do
+      capture_stderr { Bond.debrief :readline_plugin=>false }.should =~ /Invalid/
+    end
+    
+    test "prints error if readline_plugin doesn't have all required methods" do
+      capture_stderr {Bond.debrief :readline_plugin=>Module.new{ def setup; end } }.should =~ /Invalid/
+    end
+
+    test "no error if valid readline_plugin" do
+      capture_stderr {Bond.debrief :readline_plugin=>valid_readline_plugin }.should == ''
+    end
+
+    test "sets default mission" do
+      default_mission = lambda {}
+      Bond.debrief :default_mission=>default_mission, :readline_plugin=>valid_readline_plugin
+      Bond.agent.default_mission.action.should == default_mission
+    end
+  end
+
+  test "reset clears existing missions" do
+    Bond.complete(:on=>/blah/) {[]}
+    Bond.agent.missions.size.should_not == 0
+    Bond.reset
+    Bond.agent.missions.size.should == 0
+  end
+end

data/test/mission_test.rb

@@ -0,0 +1,87 @@
+require File.join(File.dirname(__FILE__), 'test_helper')
+
+class Bond::MissionTest < Test::Unit::TestCase
+  before(:all) {|e| Bond.debrief(:readline_plugin=>valid_readline_plugin) }
+
+  context "mission" do
+    before(:each) {|e| Bond.agent.instance_eval("@missions = []") }
+    test "completes" do
+      Bond.complete(:on=>/bling/) {|e| %w{ab cd fg hi}}
+      Bond.complete(:method=>'cool') {|e| [] }
+      complete('some bling f', 'f').should == %w{fg}
+    end
+
+    test "with method completes" do
+      Bond.complete(:on=>/bling/) {|e| [] }
+      Bond.complete(:method=>'cool') {|e| %w{ab cd ef gd} }
+      complete('cool c', 'c').should == %w{cd}
+    end
+
+    test "with method and quoted argument completes" do
+      Bond.complete(:on=>/bling/) {|e| [] }
+      Bond.complete(:method=>'cool') {|e| %w{ab cd ef ad} }
+      complete('cool "a', 'a').should == %w{ab ad}
+    end
+
+    test "with string method completes exact matches" do
+      Bond.complete(:method=>'cool?') {|e| [] }
+      Bond.complete(:method=>'cool') {|e| %w{ab cd ef gd} }
+      complete('cool c', 'c').should == %w{cd}
+    end
+
+    test "with regex method completes multiple methods" do
+      Bond.complete(:method=>/cool|ls/) {|e| %w{ab cd ef ad}}
+      complete("cool a").should == %w{ab ad}
+      complete("ls c").should == %w{cd}
+    end
+
+    test "with no search option and matching completes" do
+      Bond.complete(:on=>/\s*'([^']+)$/, :search=>false) {|e| %w{coco for puffs}.grep(/#{e.matched[1]}/) }
+      complete("require 'ff").should == ['puffs']
+    end
+
+    test "with search proc completes" do
+      Bond.complete(:method=>'blah', :search=>proc {|input, list| list.grep(/#{input}/)}) {|e| %w{coco for puffs} }
+      complete("blah 'ff").should == ['puffs']
+    end
+
+    test "with anywhere search completes" do
+      Bond.complete(:method=>'blah', :search=>:anywhere) {|e| %w{coco for puffs} }
+      complete("blah 'ff").should == ['puffs']
+    end
+
+    test "with ignore case search completes" do
+      Bond.complete(:method=>'blah', :search=>:ignore_case) {|e| %w{Coco For PufFs} }
+      complete("blah 'pu").should == ['PufFs']
+    end
+
+    test "with underscore search completes" do
+      Bond.complete(:on=>/blah/, :search=>:underscore) {|e| %w{and_one big_two can_three} }
+      complete("blah and").should == ['and_one']
+      complete("blah b-t").should == ['big_two']
+    end
+
+    test "with object and default action completes" do
+      Bond.complete(:object=>"String")
+      Bond.complete(:on=>/man/) { %w{upper upster upful}}
+      complete("'man'.u").should == ["'man'.upcase!", "'man'.unpack", "'man'.untaint", "'man'.upcase", "'man'.upto"]
+    end
+
+    test "with regex object completes" do
+      Bond.complete(:object=>/Str/) {|e| e.object.class.superclass.instance_methods(true) }
+      Bond.complete(:on=>/man/) { %w{upper upster upful}}
+      complete("'man'.u").should == ["'man'.untaint"]
+    end
+
+    test "with object and explicit action completes" do
+      Bond.complete(:object=>"String") {|e| e.object.class.superclass.instance_methods(true) }
+      Bond.complete(:on=>/man/) { %w{upper upster upful}}
+      complete("'man'.u").should == ["'man'.untaint"]
+    end
+
+    test "ignores invalid objects" do
+      Bond.complete(:object=>"String")
+      complete("blah.upt").should == []
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'test/unit'
+require 'context' #gem install jeremymcanally-context -s http://gems.github.com
+require 'matchy' #gem install jeremymcanally-matchy -s http://gems.github.com
+require 'mocha'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'bond'
+
+class Test::Unit::TestCase
+  before(:all) {
+    # Mock irb
+    unless Object.const_defined?(:IRB)
+      eval %[
+        module ::IRB
+          class<<self; attr_accessor :CurrentContext; end
+          module InputCompletor; CompletionProc = lambda {|e| [] }; end
+        end
+      ]
+      ::IRB.CurrentContext = stub(:workspace=>stub(:binding=>binding))
+    end
+  }
+
+  def capture_stderr(&block)
+    original_stderr = $stderr
+    $stderr = fake = StringIO.new
+    begin
+      yield
+    ensure
+      $stderr = original_stderr
+    end
+    fake.string
+  end
+
+  def complete(full_line, last_word=full_line)
+    Bond.agent.stubs(:line_buffer).returns(full_line)
+    Bond.agent.call(last_word)
+  end
+
+  def valid_readline_plugin
+    Module.new{ def setup; end; def line_buffer; end }
+  end
+end
+

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification 
+name: bond
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Gabriel Horner
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-16 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Bond is on a mission to make custom autocompletion easy in irb and other console/readline-like environments. Bond supports custom argument completion of methods, method completion of objects and anything else your wicked regex's can do. Bond comes armed with a Readline C extension to get the full line of input as opposed to irb's last-word based completion. Bond makes custom searching of possible completions easy which allows for nontraditional ways of autocompleting i.e. instant aliasing of multi worded methods.
+email: gabriel.horner@gmail.com
+executables: []
+
+extensions: 
+- ext/readline_line_buffer/extconf.rb
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- CHANGELOG.rdoc
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- ext/readline_line_buffer/extconf.rb
+- ext/readline_line_buffer/readline_line_buffer.c
+- lib/bond.rb
+- lib/bond/agent.rb
+- lib/bond/mission.rb
+- lib/bond/missions/default_mission.rb
+- lib/bond/missions/method_mission.rb
+- lib/bond/missions/object_mission.rb
+- lib/bond/rawline.rb
+- lib/bond/readline.rb
+- lib/bond/search.rb
+- test/agent_test.rb
+- test/bond_test.rb
+- test/mission_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://tagaholic.me/bond/
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: tagaholic
+rubygems_version: 1.3.2
+signing_key: 
+specification_version: 3
+summary: "Mission: Easy custom autocompletion for arguments, methods and beyond. Accomplished for irb and any other readline-like console environments."
+test_files: 
+- test/agent_test.rb
+- test/bond_test.rb
+- test/mission_test.rb
+- test/test_helper.rb