Since it’s last release, bond has gained a number of features. The most novel of these is the ability to generate gem-specific autocompletions from a gem’s yard documentation. This release also lets gems ship with their own irb autocompletions and introduces bond to emacs’ inf-ruby mode.

Yard-Based Irb Autocompletions

Update: Yard functionality has been moved to bond-yard.

This feature generates autocompletions for a gem’s methods from a gem’s yard documentation. The only arguments it currently autocompletes are hash keys for a hash argument that has been documented with @option. Let’s take a look:

  $ gem install bond yard bond-yard

  $ irb
  >> require 'bond'; Bond.start
  => true

  # Load autocompletions for yard methods
  >> Bond.load_yard_gems 'yard'
  Bond: Building/loading yard's .yardoc database ...
  => ["yard"]

  # Let's see what yard methods we can autocomplete
  >> Bond.list_methods.grep /YARD/
  => ["YARD::CodeObjects::Base#format", "YARD::CodeObjects::ClassObject#constants", "YARD::CodeObjects::ClassObject#meths",   
  "YARD::CodeObjects::NamespaceObject#constants", "YARD::CodeObjects::NamespaceObject#included_meths", 
  "YARD::CodeObjects::NamespaceObject#meths", "YARD::Serializers::FileSystemSerializer.new", "YARD::Templates::Engine.render", 
  "YARD::Templates::Engine.set_default_options"]

  # Trying one of the above
  >> YARD::Templates::Engine.render :[TAB]
  :format    :template  :type
  >> YARD::Templates::Engine.render :f[TAB]
  >> YARD::Templates::Engine.render :format=>:html, :te[TAB]
  >> YARD::Templates::Engine.render :format=>:html, :template
  # ...

Are there any other gems besides yard that use yard documentation? Sure:

  # gem install spidr
  >> Bond.load_yard_gems 'spidr'
  Bond: Building/loading spidr's .yardoc database ...
  => ["spidr"]
  >> require 'spidr'
  => true

  >> Spidr::Agent.new :h[TAB]
  :history       :host          :host_header   :host_headers
  >> Spidr::Agent.new :hi[TAB]
  >> Spidr::Agent.new :history
  # ...

  # gem install haml
  >> Bond.load_yard_gems 'haml'
  Bond: Building/loading haml's .yardoc database ...
  => ["haml"]
  >> require 'haml/html'
  => true

  >> Haml::HTML.new :[TAB]
  :erb     :xhtml
  >> Haml::HTML.new :x[TAB]
  >> Haml::HTML.new :xhtml
  # ...

  # gem install rdf
  >> Bond.load_yard_gems 'rdf'
  Bond: Building/loading rdf's .yardoc database ...
  => ["rdf"]
  >> require 'rdf'
  => true

  >> RDF::Repository.new :[TAB]
  :title   :uri
  >> RDF::Repository.new :t[TAB]
  >> RDF::Repository.new :title
  # ...

For more gems that use yard documentation, see here.

Gems with Custom Autocompletions

If your gem doesn’t use yard documentation, no worries. You can still ship your gems with custom autocompletions. Completion files are under lib/bond/completions/ which is relative your gem’s base directory. For the format of a completion file, see here. For an example of a gem that ships with autocompletions, let’s use hirb:

  # Install latest hirb
  $ gem install hirb

  $ irb
  >> require 'bond'; Bond.start
  => true
  >> Bond.load_gems 'hirb'
  => ["hirb"]
  >> require 'hirb'
  => true

  # Autocomplete all options to hirb's tables
  >> puts Hirb::Helpers::AutoTable.render [1,2,3], :[TAB]
  :all_fields            :filter_any            :hide_empty            :table_class
  :change_fields         :filter_classes        :max_fields            :vertical
  :description           :filters               :max_width             
  :escape_special_chars  :header_filter         :number                
  :fields                :headers               :resize                
  >> puts Hirb::Helpers::AutoTable.render [1,2,3], :d[TAB]
  >> puts Hirb::Helpers::AutoTable.render [1,2,3], :description
  # ...

  # Let's use hirb's console methods
  >> extend Hirb::Console
  => main

  # Autocomplete all options to hirb's menus
  >> menu [1,2,3], :[TAB]
  :action         :command        :helper_class   :readline       
  :action_object  :default_field  :multi_action   :two_d          
  :ask            :directions     :prompt         
  >> menu [1,2,3], :p[TAB]
  >> menu [1,2,3], :prompt
  # ...

  # If you want to have gem completions defined at start up, just pass :gems to Bond.start.
  # Bond.start :gems=>%w{hirb}

Since this is the initial release of this feature, probably no other gems ship with bond’s irb autocompletions. So what can you do if you want to autocomplete your favorite gem’s methods? Just make your own completion files under ~/.bond/completions/. If you want to share your favorite gem’s completions with others, fork the gem, copy your completion file(s) to the gem’s lib/bond/completions/ directory and send the patch to the author.

Emacs Inf-Ruby and Bond

Bond can be used within emacs’ inf-ruby mode thanks to pd’s inf-ruby-bond. Since I don’t use emacs, I won’t try to go into an example. If any vim gurus are listening, a vim plugin to use bond within vim would be awesome :).

Final Thoughts

Although the idea of creating autocompletion functionality from documentation isn’t new, bond is probably the first to do so among ruby gems. This isn’t anything too special given that bond currently only autocompletes hash keys of hash arguments. But with yard’s excellent api, there isn’t anything stopping a future release from autocompleting any arguments to a method!

Although yard isn’t currently the commonly used documentation tool in the ruby world, this post shows the benefits it provides by letting gem authors easily associate meta-data per method. Yard makes it possible to ask: what gem-specific functionality can someone build from gem’s documentation? Bond’s irb autocompletions is one such answer. Perhaps in a future post another answer will be boson’s ability to make a command from any documented method and its options.