To read a linkable version of this README, see here.
Description
Boson is a command/task framework with the power to turn any ruby method into a full-fledged executable with options. Some unique features that differentiate it from rake and thor include being usable from irb and the commandline, optional automated views generated by hirb and allowing libraries to be written as plain ruby. For my libraries that use this, see irbfiles. Works with all major ruby versions.
UPDATE
Boson 0.4.x will be the last 1.8 compatible version. Boson 0.5 will be a rewrite compatible with only 1.9. Work is going on in boson2 branch. The goal of boson2 is to have a slimmer core, move everything else to plugins and to allow gems to use boson to make executables like thor.
Features
-
Simple organization: Commands are just methods on an object (default is main) and command libraries are just modules.
-
Commands are accessible from the commandline (Boson::BinRunner) or irb (Boson::ConsoleRunner).
-
Libraries
-
can be written in plain ruby which allows for easy testing and use independent of boson (Boson::FileLibrary).
-
can exist locally as a Bosonfile (Boson::LocalFileLibrary) and under lib/boson/commands or .boson/commands.
-
can be made from gems (Boson::GemLibrary) or any require-able file (Boson::RequireLibrary).
-
are encouraged to be shared. Libraries can be installed with a given url. Users can customize any aspect of a third-party library without modifying it (Boson::Library).
-
-
Commands
-
can have any number of local and global options (Boson::OptionCommand). Options are defined with Boson::OptionParser.
-
can have any view associated to it (via Hirb) without adding view code to the command’s method. These views can be toggled on and manipulated via global render options (Boson::View and Boson::OptionCommand).
-
can pipe their return value into custom pipe options (Boson::Pipe).
-
has default pipe options to search and sort an array of any objects (Boson::Pipes).
-
-
Option parser (Boson::OptionParser)
-
provides option types that map to objects i.e. :array type creates Array objects.
-
come with 5 default option types: boolean, array, string, hash and numeric.
-
can have have custom option types defined by users (Boson::Options).
-
-
Comes with default commands to load, search, list and install commands and libraries (Boson::Commands::Core).
-
Namespaces are optional and when used are methods which allow for method_missing magic.
Creating Command Libraries
See Boson::FileLibrary or here.
Irb Example
To use in irb, drop this in your ~/.irbrc:
require 'boson'
Boson.start
Having done that, let’s start up irb:
bash> irb
Loaded library core
Loaded library web_core
# List default libraries
>> libraries
+----------+----------+------+--------------+
| name | commands | gems | library_type |
+----------+----------+------+--------------+
| core | 6 | | module |
| web_core | 3 | | module |
+----------+----------+------+--------------+
2 rows in set
# List default commands
>> commands
+--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
| full_name | lib | alias | usage | description |
+--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
| usage | core | | [name][--verbose] | Print a command's usage |
| libraries | core | | [query=''][--index] [--query_fields=A,B,C] | List or search libraries |
| render | core | | [object] [options={}] | Render any object using Hirb |
| load_library | core | | [library][--verbose] [--reload] | Load/reload a library |
| commands | core | | [query=''][--index] [--query_fields=A,B,C] | List or search commands |
| menu | core | | [output] [options={}] [&block] | Provide a menu to multi-select elements from a given array |
| get | web_core | | [url] | Gets the body of a url |
| install | web_core | | [url][--force] [--name=NAME] | Installs a library by url. Library should then be loaded with load_library. |
| browser | web_core | | [*urls] | Opens urls in a browser |
+--------------+----------+-------+--------------------------------------------+-----------------------------------------------------------------------------+
9 rows in set
# Boson commands can behave like shell commands:
# Basic help
>> commands '-h'
commands [query=''][--index] [--query_fields=A,B,C]
# Search the lib column for web
>> commands 'web -q=lib' # or 'web --query_fields=lib'
+-----------+----------+-------+------------------------------+-----------------------------------------------------------------------------+
| full_name | lib | alias | usage | description |
+-----------+----------+-------+------------------------------+-----------------------------------------------------------------------------+
| get | web_core | | [url] | Gets the body of a url |
| install | web_core | | [url][--force] [--name=NAME] | Installs a library by url. Library should then be loaded with load_library. |
| browser | web_core | | [*urls] | Opens urls in a browser |
+-----------+----------+-------+------------------------------+-----------------------------------------------------------------------------+
3 rows in set
Commandline Example
# Just like in irb
bash> boson libraries
+----------+----------+------+--------------+
| name | commands | gems | library_type |
+----------+----------+------+--------------+
| core | 6 | | module |
| web_core | 3 | | module |
+----------+----------+------+--------------+
2 rows in set
# Let's install another library
bash> boson install https://github.com/cldwalker/irbfiles/raw/master/boson/commands/public/irb_core.rb
Saved to /Users/bozo/.boson/commands/irb_core.rb
# Let's start irb ...
bash> irb
>> commands
+-------------------------------+----------+------------+--------------------------------------------+-----------------------------------------------------------------------------+
| full_name | lib | alias | usage | description |
+-------------------------------+----------+------------+--------------------------------------------+-----------------------------------------------------------------------------+
| usage | core | | [name][--verbose] | Print a command's usage |
| libraries | core | | [query=''][--index] [--query_fields=name] | List or search libraries |
| render | core | | [object] [options={}] | Render any object using Hirb |
| load_library | core | | [library][--verbose] [--reload] | Load/reload a library |
| commands | core | | [query=''][--index] [--query_fields=A,B,C] | List or search commands |
| menu | core | | [output] [options={}] [&block] | Provide a menu to multi-select elements from a given array |
| get | web_core | | [url] | Gets the body of a url |
| install | web_core | | [url][--force] [--name=NAME] | Installs a library by url. Library should then be loaded with load_library. |
| browser | web_core | | [*urls] | Opens urls in a browser |
| irb_pop_workspace | irb_core | popws | | Pops current workspace and changes to next workspace in context |
| irb_require | irb_core | | | Evals file like require line by line |
| public | irb_core | | | Works same as module#public |
| private | irb_core | | | Works same as module#private |
| irb | irb_core | | | Starts a new workspace/subsession |
| irb_push_workspace | irb_core | pushws | | Creates a workspace for given object and pushes it into the current context |
| irb_load | irb_core | | | Evals file like load line by line |
| irb_change_workspace | irb_core | cws | | Changes current workspace to given object |
| irb_source | irb_core | source | | Evals full path file line by line |
| irb_jobs | irb_core | jobs | | List workspaces/subsessions |
| irb_fg | irb_core | fg | | Switch to a workspace/subsession |
| irb_help | irb_core | help | | Ri based help |
| irb_kill | irb_core | kill | | Kills a given workspace/subsession |
| include | irb_core | | | Works same as module#include |
| irb_exit | irb_core | exit | | Kills the current workspace/subsession |
| irb_workspaces | irb_core | workspaces | | Array of workspaces for current context |
| irb_context | irb_core | conf | | Displays configuration for current workspace/subsession |
| install_alias_method | irb_core | | | Aliases given method, allows lazy loading of dependent file |
| irb_current_working_workspace | irb_core | cwws | | Prints current workspace |
+-------------------------------+----------+------------+--------------------------------------------+-----------------------------------------------------------------------------+
28 rows in set
# Sweet! Now we have a list and description of commands that come with irb.
Todo
-
More tests
-
Making commands out of existing gems easier and more powerful
-
Features based on commands and their argument types i.e. completing and piping
-
Consider dropping alias gem dependency if not using its full potential
Bugs/Issues
Please report them on github.
Contributing
Motivation
My tagging obsession from the ruby console.
Links
-
tagaholic.me/2009/10/14/boson-command-your-ruby-universe.html
-
tagaholic.me/2009/10/19/how-boson-enhances-your-irb-experience.html
Credits
Boson stands on the shoulders of these people and their ideas:
-
Yehuda Katz for inspiring me with Thor and its awesome option parser (Boson::OptionParser).
-
Daniel Berger for his original work on thor’s awesome option parser.
-
Dave Thomas for scraping a method’s comments (Boson::CommentInspector)
-
Mauricio Fernandez for scraping a method’s arguments (Boson::ArgumentInspector)
-
Chris Wanstrath for inspiring Boson’s libraries with Rip’s packages.
-
And its contributors: @mirell