Bond is on a mission, as usual. This time it’s to make custom autocompletion dead easy in Irb. Simply order Bond to complete arguments, methods or your own twisted regular expressions and they will be executed. No questions asked.

Bond’s Coordinates

Bond’s getting old nowadays, regardless of what Hollywood says. So old that I even got his coordinates:

gem install bond

Debrief

Let’s say you want to autocomplete some quoted arguments for a couple of methods. Here’s how you could do that in Irb:

# Get rid of space and quotes as word delimiters in order to read the full line Readline . basic_word_break_characters = " \t

`><=;|&{(" Readline . completion_proc = proc { | input | begin case input when /^\s*(method1)\s*(['"]?)(.*)$/ meth , quote = $1 , $2 %w{some args to autocomplete} . grep ( /^ #{ $3 } / ) . map { | e | " #{ meth } #{ quote } " + e } when /^\s*(method2)\s*(['"]?)(.*)$/ meth , quote = $1 , $2 %w{more args to autocomplete} . grep ( /^ #{ $3 } / ) . map { | e | " #{ meth } #{ quote } " + e } else # Default to irb's default autocompletion IRB : :InputCompletor :: CompletionProc . call ( input ) end # irb doesn't handle failed completions nicely rescue Exception IRB : :InputCompletor :: CompletionProc . call ( input ) end }

In irb, this would look like:

bash> irb -rirb/completion >> # Copy and paste the above code # Autocompleting method1 >> method1 [TAB] method1 args method1 autocomplete method1 some method1 to >> method1 'a[TAB] method1 'args method1 'autocomplete >> method1 'au[TAB] >> method1 'autocomplete

So is the above completion_proc horrible? No, as long as you don’t mind the way the autocompletion looks and playing with Readline and Irb configuration. Assuming you do, what happens when you start adding more completion cases? Do you really want to string together a long chain of case statements as irb does?

Let’s have Bond take a shot at the above:

# We are loading irb/completion to match the above. Bond can work fine without it in irb. 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

Nice, autocompletion actually looks like it does in normal shells! Note that Bond.complete searches your input for you by default. We’ll talk more about this later.



For Completion Geeks:

In the first example above, notice that the possible completions are the full lines of input. This happens because we have to change the definition of a word to get the full line. We have to hack the word definition because none of the stable Ruby versions have a method to fetch Readline’s full line buffer. Thankfully, Csaba Henk wrote up a C extension for this in his Irb enhancements. Bond comes armed with this C extension. As a side note, future versions of Ruby will come with this Readline enhancement thanks to Takao Kouji’s recent commit.



Autocompleting Files as Arguments

So we know Bond can handle irb’s basic methods. What about class methods?

# Autocomplete with files/directories in the current directory >> Bond.complete(:method=>"File.read") {|e| Dir.entries(Dir.pwd) } => true # Let's use it >> File.read '[TAB] .git/ LICENSE.txt README.rdoc Rakefile VERSION.yml bond.gemspec ext/ lib/ test/ >> File.read 'L[TAB] >> File.read 'LICENSE.txt'

That’s pretty easy. Now what if we want to autocomplete through directories like we do in our shells? We could write one ourself or just use Readline::FILENAME_COMPLETION_PROC :

# Pass :search=>false to turn off Bond searching since FILENAME_COMPLETION_PROC does it for us. >> Bond.recomplete(: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:[email protected](irb):20> >> Bond.recomplete :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"

Nice! Now that we have a decent file autocompletion let’s add it to all our File methods:

>> Bond.reset; Bond.complete :method=>/File\.(#{Regexp.union(*File.methods(false))})/, :search=>false, &file_completion => true # Normal irb method autocompletion still works >> File.f[TAB] File.file? File.fnmatch File.fnmatch? File.for_fd File.foreach File.freeze File.frozen? File.ftype # File autocompletion just works >> File.file? '[TAB] .git/ LICENSE.txt README.rdoc Rakefile VERSION.yml bond.gemspec ext/ lib/ test/ >> File.file? 'V[TAB] >> File.file? 'VERSION.yml'

Method Autocompletion

Autocompleting an object’s methods is Irb’s sweet spot. It achieves this by evaling the object you’ve typed and getting the methods it responds to via methods() . Bond gives you access to your currently typed object and let’s you autocomplete as you see fit. For this example, let’s say we want to 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.recomplete :object=>/^Bond::/

Note that access in the completion proc to the current object you’ve typed is made available via input.object .

Custom Searching of Completions

As we’ve seen Bond defaults to traditional autocompletion searching i.e. possible_completions.grep(/^#{input}/) . But Bond can often be anything but traditional. Let’s revisit the first example:

# Let's have autocompletion search anywhere within possible completions, >> Bond.complete(:method=>'method1', :search=>false) {|input| %w{some args to autocomplete}.grep(/#{input}/) } => true # Crazy anywhere completion (not really) >> method1 'com[TAB] >> method1 'autocomplete' # Let's redefine the anywhere completion. This way we can reuse the anywhere search in other completions. >> anywhere = proc {|input, list| list.grep(/#{input}/) } => #< Proc:[email protected](irb):3> >> Bond.recomplete(:method=>'method1', :search=>anywhere) {|input| %w{some args to autocomplete} } => true

Meh. Is there really any search of possible completions that could improve on the traditional way? Perhaps. Bond comes armed with an underscore search aka textmate-like instant aliasing of underscored words:

# 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

As you can see, customizing the way we search possible completions brings a new twist to autocompletion.

Custom Autocompletions

So far we’ve seen how easy Bond makes autocompletion of methods and arguments. It’s easy because Bond handles the regular expressions. But if you have your own regex’s, Bond is ready:

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:[email protected](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)

Note the completion proc gets access to regex matches via input.matched . This is the MatchData object that results from matching the given regex with the current line. If you’re not familiar with a MatchData object, the relevant thing to know is that you can access matches as you would array elements i.e. input.matched[1] == $1, input.matched[2] == $2 . If you look at the above regex for :on , you’ll see that the first match is what we want to autocomplete and hence input.matched[1] is passed in the completion proc.

With custom autocompletions you can do some surprisingly useful things. Here’s one to make typing known constants and classes oh so easy:

def alias_constants ( input ) fetch_constants = proc { | klass , klass_alias | klass . constants . grep ( /^ #{ klass_alias } /i ) . map { | f | klass . const_get ( f )} } fetch_string_constants = proc { | klass , klass_alias | klass . constants . grep ( /^ #{ klass_alias } /i ) . map { | f | ( val = klass . const_get ( f )) && val . is_a? ( Module ) ? val . to_s : " #{ klass } :: #{ f } " } } index = 1 aliases = input . split ( ":" ) aliases . inject ( [ Object ] ) do | completions , a | completions = completions . select { | e | e . is_a? ( Module ) } . map { | klass | aliases . size != index ? fetch_constants . call ( klass , a ) : fetch_string_constants . call ( klass , a ) } . flatten index += 1 ; completions end end

This completion proc allows us to refer to any constants/classes by the first few unique letters of each namespace. The letters can be in lowercase and are separated by a colon. Let’s try it:

>> # Copy and paste the above method >> Bond.complete :on=>/^((([a-z][^:.\(]*)+):)+/, :search=>false, &method(:alias_constants) => true # First some easy ones >> b:a[TAB] >> Bond::Agent >> b:d:m[TAB] >> Bond::Missions::DefaultMission # If we hit multiple matches we just resort to normal completion >> i:i[TAB] >> IRB:I >> IRB:Il[TAB] >> IRB::IllegalParameter

The Name is Bond

To use Bond or have Bond in your irbrc, you only need to require it and then Bond.complete to your Bond content. Remember that the order you define completions is the order they’re searched in. Be careful when using custom completions. Having something like Bond.complete :on=>/.*/, &mah_search will swallow up any completions defined after it.