Mission: Easy custom autocompletion for arguments, methods and beyond. Accomplished for irb and any other readline-like console environments.
== 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}[http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html] (version >=
5.6 recommended) or JLine for JRuby users, install the gem with:
gem install bond
To use bond with {a pure ruby readline}[https://github.com/luislavena/rb-readline] i.e. Windows
users or users without Readline:
gem install bond rb-readline -- --without-readline
To use bond without readline support (and presumably use your own readline plugin):
gem install bond -- --without-readline
== Setup
If you’re using {ripl}[https://github.com/cldwalker/ripl] instead of irb, bond is already setup.
To start off, replace irb’s completion (require ‘irb/completion’) with Bond’s enhanced version in your irbrc:
require ‘bond’
Bond.start
Bond.start :readline => :ruby
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:
$ ripl
require 'rb[TAB]
rbconfig.rb rbconfig/
require 'rbconfig
require ‘rbconfig.rb’
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’]
%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 '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:
complete -W “one two three” example
complete -F _example example
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:
$ irb
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.
self.[TAB]
Display all 496 possibilities? (y or n)
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)
/man oh man/.[TAB]
Display all 496 possibilities? (y or n)
(3 + 4).[TAB]
Display all 496 possibilities? (y or n)
{:a=>{:a=>1}}.[TAB]
Display all 496 possibilities? (y or n)
[[1,2], [3,4]].[TAB]
Display all 496 possibilities? (y or n)
‘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]
== 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
== Bugs/Issues
Please report them {on github}[http://github.com/cldwalker/bond/issues].
== Contributing
{See here}[http://tagaholic.me/contributing.html]
== Links
== Todo