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
-
tagaholic.me/2009/10/14/boson-command-your-ruby-universe.html
-
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.