README.rdoc

Description

Bond is on a mission to improve autocompletion in ruby, especially for
irb/ripl. 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 ruby autocompletion
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 autocompletions and share it with others.
Bond can also load completions that ship with gems. Bond is able to offer
more than irb's completion since it uses the full line of input when
completing as opposed to irb's last-word approach.

Install

Note: Bond is only supported on platforms with make e.g. OSX, Linux and
Cygwin Windows. Once 1.8 support is dropped this won't be an issue.

To use bond with Readline
(version >= 5.6 recommended) or JLine for JRuby users, install the gem
with:

This setup 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:

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:

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:

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:

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.

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 has good instructions for reinstalling ruby with the official
Readline.