== 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}[http://github.com/cldwalker/irbfiles].
Works with Ruby 1.8.6 and 1.9.1.
Note: To read a linkable version of this README, {see here}[http://tagaholic.me/boson/doc/].
== 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[http://tagaholic.me/boson/doc/classes/Boson/FileLibrary.html].
== 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}[http://github.com/cldwalker/boson/issues].
== Motivation
My {tagging obsession}[http://github.com/cldwalker/tag-tree] from the ruby console.
== Links
* http://tagaholic.me/2009/10/14/boson-command-your-ruby-universe.html
* http://tagaholic.me/2009/10/15/boson-and-hirb-interactions.html
* http://tagaholic.me/2009/10/19/how-boson-enhances-your-irb-experience.html
== 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.