== 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 * 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 multiple commands with pipe options. Default pipe options give the ability to search and sort an array of any objects (Boson::Pipe). * 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[http://tagaholic.me/boson/doc/classes/Boson/FileLibrary.html]. == 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. == 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}[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.