Class Boson::FileLibrary

This class loads a file by its path relative to the commands directory of a repository. For example the library ‘public/misc’ could refer to the file ’~/.boson/commands/public/misc.rb’. If a file’s basename is unique in its repository, then it can be loaded with its basename i.e. ‘misc’ for the previous example. When loading a library, this class searches repositories in the order given by Boson.repos.

Creating a FileLibrary

Start by creating a file with a module and some methods (See Library for naming a module). Non-private methods are automatically loaded as a library’s commands.

Take for example a library brain.rb:

# Drop this in ~/.boson/commands/brain.rb
module Brain
  def take_over(destination)
    puts "Pinky, it's time to take over the #{destination}!"
  end
end

Once loaded, this library can be run from the commandline or irb:

$ boson take_over world
>> take_over 'world'

If the library is namespaced, the command would be run as brain.take_over.

Let’s give Brain an option in his conquest:

module Brain
  options :execute=>:string
  def take_over(destination, options={})
    puts "Pinky, it's time to take over the #{destination}!"
    system(options[:execute]) if options[:execute]
  end
end

From the commandline and irb this runs as:

$ boson take_over world -e initiate_brainiac
>> take_over 'world -e initiate_brainiac'

Since Boson aims to make your libraries just standard ruby, we can achieve the above by making options a commented method attribute:

module Brain
  # @options :execute=>:string
  # Help Brain live the dream
  def take_over(destination, options={})
    puts "Pinky, it's time to take over the #{destination}!"
    system(options[:execute]) if options[:execute]
  end
end

Some points about the above:

• A ’@’ must prefix options and other method attributes that become comments.
• Note the comment above the method. One-line comments right before a method set a command’s description.
• See Inspector for other method attributes, like config and render_options, that can be placed above a method.

Once a command has a defined option, a command can also recognize a slew of global options:

>> take_over '-h'
take_over [destination] [--execute=STRING]

# prints much more verbose help
>> take_over '-hv'

For more about these global options see OptionCommand and View.