Rubycom

Turn your library into a command-line app by simply including Rubycom.


Project maintained by dannypurcell Hosted on GitHub Pages — Theme by mattgraham

Rubycom

© Danny Purcell 2013 | MIT license

Makes creating command line tools as easy as including Rubycom.

When a Module which has included Rubycom is run from the terminal, Rubycom will parse ARGV for a command name, match the command name to a method in the including module, and run the method with the given arguments.

Features

Allows the user to write a properly documented module/class and convert it to a command line tool by simply including Rubycom at the bottom.

Installation

Install with Gem

Building locally

Usage

Write your library, document them as you normally would. include Rubycom at the bottom. Optionally #!/usr/bin/env ruby at the top.

Now any singleton methods def self.method_name will be available to call from the terminal.

Calling ruby ./path/to/module.rb <command_name> will automatically discover and run your <command_name> singleton method. If no method is found by the given name, a usage print out will be given including a summary of each command available and it's description from the corresponding method's comments.

Calling a valid command with incorrect arguments will produce a usage print out for the matched method. Rubycom will include as much documentation on the command line as you provide in your method comments. Currently Rubycom only handles YardDoc style comments for discovering the parameter and return documentation. All other commentary will be included as part of the command description. In the absence of YardDoc annotations, Rubycom will generate a clean usage text which may work for your method doc even though Rubycom is not specifically parsing it.

Special commands
Command Description Options
ruby ./path/to/module.rb help [command_name] Will print out usage for the module or optionally the specified command.
ruby ./path/to/module.rb register_completions Setup bash tab completion
ruby ./path/to/module.rb tab_complete [text] Print a list of possible matches for a given word

Arguments

When using Rubycom's default modules:

Raison d'etre

While these are things do help, we are still writing redundant code and tightly coupling the functional code to the interface which presents it. We also lack a generic command line parser which, if available, could help encourage Rubyists to standardize command line inputs.

So, what to do?

...Ruby is interpreted...use the source.

Rather than making concessions for the presentation and tightly coupling the functional code to the interface, it would be nice if a script author could simply write their code and attach the interface to it.

How it works

Rubycom attaches the CLI to the functional code. The author is free to write the functional code as any other. If a library needs to be accessible from the terminal, just include Rubycom at the bottom of the main Module and run the ruby file.

The result is a library which can be consumed easily from other classes/modules and which is accessible from the command line.

Customizing Rubycom

Note: The plugin_options hash is currently taking Modules and calling specific methods on them. This will change to a Symbol => Proc mapping soon. Please log an issue on GitHub if you want this right away.

Rubycom is designed to fit several different ways of calling command line utilities and to respect many of the strong conventions regarding command line semantics. While Rubycom's default functionality should fit many common use cases it is also built in a modular fashion such that the core functionality can be easily adapted to fit specific requirements or user preferences.

Plugin Module Contracts
Key Expected Inputs Expected Outputs
:arguments ARGV A data structure representing the arguments, options, and flags
:discover The Module which included Rubycom and a parsed command line A Method or Module representing the command which should be run
:documentation The command to run and the :source plugin The command matched to it's documentation
:source A Module or Method object The source code for that reference
:parameters A command, a parsed command line, and the command documentation The command parameters matched to their values for this run
:executor A command to execute and the command parameters matched to their values for this run The result of a call to the given method with the given parameters
:output The command result Some output handling action
:interface A command and it's documentation A string representing the usage text to present in a terminal
:error An Error and a String representing usage text Some error handling action