Note: To read a linked version of this README, {click here}[http://tagaholic.me/bond/doc/]

== Description

Bond is on a mission to improve irb's autocompletion. Aside from doing everything irb's can do and fixing its quirks,
Bond can autocomplete argument(s) to methods, uniquely completing per module, per method and per argument. Bond brings
irb's completion closer to bash/zsh as it provides a configuration system and a DSL for creating custom completions
and completion rules. With this configuration system, users can customize their irb autocompletions and share
it with others. Bond can also generate completions from yard documentation and load completions that ship with gems.
Bond is able to offer more than irb's completion since it uses a Readline C extension to get the full
line of input when completing as opposed to irb's last-word approach.

== Install

Install the gem with:

    sudo gem install bond

== Setup

To start off, replace irb's completion (require 'irb/completion') with Bond's enhanced version in your irbrc :

  require 'bond'
  Bond.start

This gives you more consistent method completion on any object, customizable completions
and argument completion of some 80+ methods including Hash#[], Kernel#system, Kernel#require and some Rails methods.

== Method Argument Completion

By default, Bond autocompletes arguments for a number of core methods:

  $ irb
  # require completes gems and anything in $LOAD_PATH
  >> require 'rb[TAB]
  rbconfig.rb          rbconfig/
  >> require 'rbconfig
  >> require 'rbconfig.rb'

  # hash methods can complete their keys
  >> CONFIG::CONFIG[TAB]
  >> CONFIG::CONFIG['m[TAB]
  >> CONFIG::CONFIG['mandir'
  >> CONFIG::CONFIG['mandir']

  >> ENV['CO[TAB]
  COLUMNS       COMMAND_MODE
  >> ENV['COL[TAB]
  >> ENV['COLUMNS'
  >> ENV['COLUMNS']

  # array methods can complete their elements
  >> %w{ab bc cd de}.delete '[TAB]
  ab  bc  cd  de
  >> %w{ab  bc  cd  de}.delete 'a[TAB]
  >> %w{ab  bc  cd  de}.delete 'ab'

  # system can complete shell commands
  >> system 'ec[TAB]
  >> system 'echo
  >> system 'echo'

Bond also comes with some basic Rails completions, mostly for attributes/columns of models:

  $ script/console
  >> Url.column_names
  => ["id", "name", "description", "created_at", "updated_at"]
  >> Url.create :n[TAB]
  >> Url.create :name
  ...
  >> Url.first.update_attribute :d[TAB]
  >> Url.first.update_attribute :description
  ...

To see more methods whose arguments can be completed:
  >> puts Bond.list_methods
  ActiveRecord::Base#[]
  ActiveRecord::Base#attribute_for_inspect
  ...

== Multiple Arguments
Every time a comma appears after a method, Bond starts a new completion. This allows a method to
complete multiple arguments. *Each* argument can be have a unique set of completions since a completion action
is aware of what argument it is currently completing. Take for example the completion for Object#send:

  >> Bond.send :me[TAB]
  >> Bond.send :method
  >> Bond.send :method, [TAB]
  agent       complete    config      recomplete  spy         start
  >> Bond.send :method, :a[TAB]
  >> Bond.send :method, :agent
  => #<Method: Module#agent>

Notice the arguments were completed differently: the first completing for Bond.send and the second for Bond.method. The second
argument was only able to complete because there's a completion for Module#method. Using Object#send it's possible to
use completions defined for private methods i.e. Module#remove_const:
  >> Bond.send :remove_const, :A[TAB]
  :Agent            :AnywhereMission
  >> Bond.send :remove_const, :Ag[TAB]
  >> Bond.send :remove_const, :Agent

Since Bond uses a comma to delimit completions, methods whose last argument is a hash can have their hash keys
autocompleted. Revisiting the above Rails example:
  >> Url.create :n[TAB]
  >> Url.create :name
  >> Url.create :name=>'example.com', :d[TAB]
  >> Url.create :name=>'example.com', :description
  ...
  >> Url.first.update_attributes :d[TAB]
  >> Url.first.update_attributes :description
  >> Url.first.update_attributes :description=>'zzz', :u[TAB]
  >> Url.first.update_attributes :description=>'zzz', :updated_at
  ...

== Creating Completions
Bond's completion resembles bash/zsh's. When Bond.start is called, Bond looks up completion files in multiple places:
~/.bondrc and ~/.bond/completions/*.rb. Here's how bash and bond completion definitions compare in their config files:
  # Bash
  complete -W "one two three" example
  complete -F _example example

  # Bond
  complete(:method=>'example') { %w{one two three} }
  complete(:method=>'example', :action=>'_example')

To read up on the wealth of completion types one can make, see the docs for Bond.complete.

=== Creating Argument Completions for Methods
While the above method completion was a static list, most completions will dynamically generate completions based on the method's
receiver (object). Let's look at such an example with Hash#[] :
  complete(:method=>"Hash#[]") {|e| e.object.keys }

As you can see, the currently typed object is available as the :object attribute of the block's argument, a Bond::Input object.
This object can offer other useful attributes describing what the user has typed. For example, the :argument attribute holds the
current argument number being completed. Here's a completion that uses this attribute to complete differently for the first argument
and remaining arguments:
   complete(:method=>'example') {|e| e.argument > 1 ? %w{verbose force noop} : %w{one two three} }

=== Creating Other Completions
First you should know Bond works: A user creates completion missions with Bond.start and its config files (which are just
Bond.complete calls). When a user autocompletes, Bond.agent looks up missions in the *order* they were defined and completes
with the first one that matches. The exception to this ordering are :method completions.

To create a completion, Bond.complete needs a regexp to match the user input and an action to generate completions when
it matches. If the completion isn't working, use Bond.spy to see which completion is executing. If a completion needs to be placed
before existing completions, use the :place option.

== Irb's Incorrect Completions

There are a number of incorrect completions irb gives for object methods. Bond fixes all of the ones described below.

Irb completes anything surrounded with '{}' the same:

  >> proc {}.c[TAB]
  }.call     }.class    }.clear    }.clone    }.collect
  >> %w{ab bc}.c[TAB]
  }.call     }.class    }.clear    }.clone    }.collect
  >> %r{ab bc}.c[TAB]
  }.call     }.class    }.clear    }.clone    }.collect
  >> {}.c[TAB]
  }.call     }.class    }.clear    }.clone    }.collect
  >> {}.call
  NoMethodError: undefined method `call' for {}:Hash
          from (irb):1

There are a number of cases where irb gives a default completion because it doesn't know what else to do.
  # The default completion
  >> self.[TAB]
  Display all 496 possibilities? (y or n)

  # And all of these cases are apparently the same:
  >> nil.[TAB]
  Display all 496 possibilities? (y or n)
  >> false.[TAB]
  Display all 496 possibilities? (y or n)
  >> true.[TAB]
  Display all 496 possibilities? (y or n)
  # Regular expressions with spaces
  >> /man oh man/.[TAB]
  Display all 496 possibilities? (y or n)
  # Grouped expressions
 >> (3 + 4).[TAB]
 Display all 496 possibilities? (y or n)

 # Nested hashes and arrays
 >> {:a=>{:a=>1}}.[TAB]
 Display all 496 possibilities? (y or n)
 >> [[1,2], [3,4]].[TAB]
 Display all 496 possibilities? (y or n)

 # Any object produced from a method call
 >> 'awesome'.to_sym.[TAB]
 Display all 496 possibilities? (y or n)
 >> :dude.to_s.[TAB]
 Display all 496 possibilities? (y or n)
 
Ranges don't get much love
  >> (2..4).[TAB]
  # Nothing happens

== Limitations
If on a Mac and using Editline as a Readline replacement (Readline::VERSION =~ /editline/i), Bond will probably not work consistently. I strongly recommend switching to the official Readline. If using rvm, {this post}[http://niwos.com/2010/03/19/rvm-on-osx-snow-leopard-readline-errors/]
has good instructions for reinstalling ruby with the official Readline.

== Credits
* 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.
* Takao Kouji for {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 1.9.2.
* pd for compatibility with emacs' inf-ruby mode.

== Links
* http://tagaholic.me/2010/05/07/screencast-of-argument-autocompletion-for-methods-in-irb.html
* http://tagaholic.me/2009/07/16/bond-from-irb-with-completion-love.html
* http://tagaholic.me/2009/07/22/better-irb-completion-with-bond.html
* http://tagaholic.me/2009/07/23/mini-irb-and-mini-script-console.html

== Todo
* Generate method autocompletions for any arguments based on yardoc documentation.
* Make completion actions more synonymous with argument types.
* Cache expensive completion actions.
* Ensure completions work when there is additional, unrelated text to the right of a completion.