Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A command/task framework similar to rake and thor built with extendability in mind.
Ruby

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
lib
test
CHANGELOG.rdoc
LICENSE.txt
README.rdoc
Rakefile
VERSION.yml
boson.gemspec

README.rdoc

Description

A command/task framework similar to rake and thor that opens your ruby universe to the commandline and irb. For my libraries that use this, see irbfiles. Works with Ruby 1.8.6 and 1.9.1.

Note: To read a linkable version of this README, see here.

Features

  • Commands are just methods extended for a given object, the default being the top level object, main.

  • Commands are accessible from the commandline (Boson::BinRunner) or irb (Boson::ConsoleRunner).

  • Command libraries, which are just modules, are written in non-dsl ruby which allows for easy testing and use outside of boson (Boson::FileLibrary).

  • Comes with default commands to load, search, list and install commands and libraries (Boson::Commands::Core).

  • Commands can be full-blown commandline apps thanks to powerful options (Boson::OptionParser) and hirb's views.

  • There are 5 default option types: boolean, array, string, hash and numeric. Custom option types can be defined to map to any Ruby class with one method (Boson::Options).

  • Commands can have views toggled without adding view code to the original command (Boson::Scientist).

  • Command libraries are social as a user can install them from a url and then customize command names and options without changing the original library.

  • Namespaces are optional and when used are methods which allow for method_missing magic.

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 http://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.

Creating Command Libraries

See Boson::FileLibrary or here.

Todo

  • More tests

  • Making commands out of existing gems easier and more powerful

  • Better local repositories, perhaps a BosonFile

  • Consider managing extensions to core and standard libraries

  • Consider dropping alias gem dependency if not using its full potential

Bugs/Issues

Please report them on github.

Motivation

My tagging obsession from the ruby console.

Links

Acknowledgements

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

  • Yehuda Katz for inspiring me with Thor's power and elegant design

  • Yehuda Katz and Daniel Berger for an awesome option parser (Boson::OptionParser)

  • 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.

Something went wrong with that request. Please try again.