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:
# You'll need yard version 0.5.2 or greater for this feature
$ sudo gem install 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
# ...
# If you want to have yard gem completions defined at start up, just pass :yard_gems to Bond.start.
# Bond.start :yard_gems=>%w{yard}
Are there any other gems besides yard that use yard documentation? Sure:
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
$ sudo 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.
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 :).
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.
Previous Topic
