Boson is a modular command/task framework. Thanks to its rich set of plugins, it differentiates itself from rake and thor by being usable from irb and the commandline, having automated views generated by hirb and allowing libraries to be written as plain ruby. Works with on all major rubies for ruby >= 1.9.2
Starting with 1.0, boson has changed significantly. Please read the upgrading doc if you have an older version or if your reading about boson predates 2012.
Boson has been rewritten to have a smaller core (no dependencies) with optional plugins to hook into its various features. The major focus of 1.0 has been to provide an easy way for third-party gems to create their executable and define subcommands with options.
Nicely formatted docs are available here.
For a gem with an executable, bin/cow:
#!/usr/bin/env ruby
require 'boson/runner'
class CowRunner < Boson::Runner
option :urgent, type: :boolean
def say(text, options={})
text.capitalize! if options[:urgent]
puts text
end
def moo
puts "MOOOO"
end
end
CowRunner.start
You can now execute cow with say and moo subcommands:
$ cow say hungry
hungry
$ cow moo
MOOOO
# use say's urgent option
$ cow say hungry -urgent
HUNGRY
You'll notice that this syntax is powerful and concise and is very similar to thor's API. Subcommands map to ruby methods and the class represents the executable.
For some examples of executables see vimdb or tag.
Since boson and it's rewrite are both heavily inspired by thor, it makes sense to compare them.
First, what I consider pros boson has over thor. Boson
MyRunner.new.subcommand(arg, verbose: true)
. This
also allows commands to just be called as ruby, with no magic to consider.desc "SOME USAGE", "SOME DESCRIPTION"
Now for pros thor has over boson. Thor
desc
. Usage is automatically created in boson.method_option
to option
class_option
doesn't exist yet but you can emulate it for now by defining
your class option in a class method and then calling your class method before
every command. See vimdb for an example.A Boson plugin is a third-party library that extends Boson through its extension API. Any Boson class/module that includes or extends a module named API or APIClassMethods provides an extension API. Examples of such classes are Boson::BareRunner, Boson::Command, Boson::Inspector and Boson::Library. As an example, let us extend what any boson-based executable does first, extend Boson::BareRunner.start:
module Boson
module CustomStartUp
def start(*)
super
# additional startup
end
end
end
Boson::BareRunner.extend Boson::CustomStartUp
Notice that extend
was used to extend a class method. To extend an instance
method you would use include
. Also notice that you use super
in an
overridden method to call original functionality. If you don't, you're
possibly overridden existing functionality, which is fine as long as you know
what you are overriding.
If you want to gemify your plugin, name it boson-plugin_name and put it under lib/boson/plugin_name. The previous example would go in lib/boson/custom_startup.rb. To use your plugin, a user can simply require your plugin in their executable.
For many plugin examples, see boson-more.
To use a plugin, just require it. For an executable:
require 'boson/runner'
require 'boson/my_plugin'
MyRunner.start
For the boson executable, just require the plugins in ~/.bosonrc.
Boson allows for custom default options and commands. This means you can add your own defaults in a plugin and use them across your executables.
To add a custom default command, simply reopen Boson::DefaultCommandsRunner:
class Boson::DefaultCommandsRunner
desc "whoomp"
def whoomp
puts "WHOOMP there it is!"
end
end
To add a custom global option, add to Boson::Runner::GLOBAL_OPTIONS:
Boson::Runner::GLOBAL_OPTIONS.update(
verbose: {type: :boolean, desc: "Verbose description of loading libraries"}
)
Custom global options are defined in the same format as options for a command.
Please report them on github. If the issue is about upgrading from old boson, please file it in boson-more.
Motivation for the new boson is all the damn executables I'm making.
Boson stands on the shoulders of these people and their ideas: