## Description

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

## New Boson

Starting with 1.0, boson has changed significantly. Please read [the upgrading
doc](https://github.com/cldwalker/boson/blob/master/Upgrading.md) if you have an
older version or if your [reading about
boson](http://tagaholic.me/blog.html#gem:name=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.

## Docs

Nicely formatted docs are available
[here](http://rdoc.info/gems/boson/file/README.md).

## Example Executable

For a gem with an executable, bin/cow:

```ruby
#!/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](http://github.com/cldwalker/vimdb)
or [tag](http://github.com/cldwalker/tag).

## Comparison to Thor

Since boson and it's rewrite are both heavily inspired by [thor](http://github.com/wycats/thor), it
makes sense to compare them.

First, what I consider pros boson has over thor. Boson

* is designed to handle plugins. This means it core parts are extendable by
  modules and core components like commands can have arbitrary metadata
  associated with them.
* has a rich set of plugins. See [boson-more](http://github.com/cldwalker/boson-more).
* has commands that are easily testable. Whereas thor has options that automagically
  appear in command methods, boson explicitly passes options to its command
  method as a hash i.e. `MyRunner.new.subcommand(arg, verbose: true)`. This
  also allows commands to just be called as ruby, with no magic to consider.
* supports custom-user option types i.e. creating a Date option type. See
  Boson::Options.
* supports custom method decorators i.e. methods like desc that add functionality
  to a command. While boson supports option, options, desc and config out of the box,
  users can create their own.
* automatically creates usage for your subcommand. With thor you need to
  manually define your usage with desc: `desc "SOME USAGE", "SOME DESCRIPTION"`
* is lenient about descriptions. Describe commands at your leisure. With thor
  you must define a desc.
* has no blacklist for command names while thor has a
  [blacklist](https://github.com/wycats/thor/blob/a24b6697a37d9bc0c0ea94ef9bf2cdbb33b8abb9/lib/thor/base.rb#L18-19)
  due to its design. With boson you can even name commands after Kernel method
  names but tread with caution in your own Runner class.
* allows for user-defined default global options (i.e. --help) and commands
  (i.e. help). This means that with a plugin you could have your own additional
  default options and commands shared across executables. See the extending
  section below.
* allows default help and command help to be overridden/extended by
  subclassing Runner.display_help and Runner.display_command_help respectively.
* provides an optional custom rc file for your executable. Simply set
  ENV['BOSONRC'] to a path i.e. ~/.myprogramrc. This rc file loads before any
  command processing is done, allowing for users to extend your executable
  easily i.e. to add more subcommands. For an example, see
  [vimdb](http://github.com/cldwalker/vimdb).

Now for pros thor has over boson. Thor

* is widely used and thus has been community QAed thoroughly.
* supports generators as a major feature.
* is more stable as its feature set is mostly frozen.
* is used by rails and thus is guaranteed support for some time.
* supports ruby 1.8.7.
* can conveniently define an option across commands using class_option.
  boson may add this later.
* TODO: I'm sure there's more

## Converting From Thor

* Change your requires and subclass from Boson::Runner instead of Thor.
* Delete the first argument from `desc`. Usage is automatically created in boson.
* Rename `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](http://github.com/cldwalker/vimdb) for an example.

## Writing Plugins

The most common way to write a plugin is to extend one of the many method hooks
available. Any methods that are defined in an API or APIClassMethods module
are extendable. For example, if you want to extend what any boson-based
executable does first, extend Boson::BareRunner.start:

```ruby
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](http://github.com/cldwalker/boson-more).

## Using a Plugin

To use a plugin, just require it. For an executable:

```ruby
require 'boson/runner'
require 'boson/my_plugin'

MyRunner.start
```

For the boson executable, just require the plugins in ~/.bosonrc.

## Extending Your Executables

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:

```ruby
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:

```ruby
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.

## Bugs/Issues

Please report them [on github](http://github.com/cldwalker/boson/issues).
If the issue is about upgrading from old boson, please file it in
[boson-more](http://github.com/cldwalker/boson-more/issues).

## Contributing
[See here](http://tagaholic.me/contributing.html)

## Motiviation

Motivation for the new boson is all the damn executables I'm making.

## Credits
Boson stands on the shoulders of these people and their ideas:

* Contributors: @mirell, @martinos
* Yehuda Katz for Thor and its awesome option parser (Boson::OptionParser).
* Daniel Berger for his original work on thor's option parser.
* Chris Wanstrath for inspiring Boson's libraries with Rip's packages.