Website | Report Issue | Source Code ( )
Executable
¶ ↑
Executable
is to the commandline, what ActiveRecord is the database. You can think of Executable
as a COM, a Command-line Object Mapper, just as ActiveRecord is an ORM (Object Relational Mapper). Any class mixing in Executable
or subclassing Executable::Command
can define a complete command line tool using nothing more than Ruby’s standard syntax. No special DSL is required.
Features¶ ↑
-
Easy to use, just mixin or subclass.
-
Define call to control the command procedure.
-
Public writers become options.
-
Namespace children become subcommands.
-
Or easily dispatch subcommands to public methods.
-
Generate help in plain text or markdown.
Limitations¶ ↑
-
Ruby 1.9+ only.
-
Help doesn’t handle aliases well (yet).
Instructions¶ ↑
CLIs can be built by using a Executable
as a mixin, or by subclassing Executable::Command
. Methods seemlessly handle command-line options. Writer methods (those ending in ‘=’) correspond to options and query methods (those ending in ‘?’) modify them to be boolean switches.
For example, here is a simple “Hello, World!” commandline tool.
require 'executable' class HelloCommand include Executable # Say it in uppercase? def loud=(bool) @loud = bool end # def loud? @loud end # Show this message. def help? cli.show_help exit end alias :h? :help? # Say hello. def call(name) name = name || 'World' str = "Hello, #{name}!" str = str.upcase if loud? puts str end end
To make the command available on the command line, add an executable to your project calling the execute or run methods.
#!usr/bin/env ruby require 'hello.rb' HelloCommand.run
If we named this file hello
, set its execute flag and made it available on our systems $PATH, then:
$ hello Hello, World! $ hello John Hello, John! $ hello --loud John HELLO, JOHN!
Executable
can also generate help text for commands.
$ hello --help USAGE: hello [options] Say hello. --loud Say it in uppercase? --help Show this message
If you look back at the class definition you can see it’s pulling comments from the source to provide descriptions. It pulls the description for the command itself from the #call
method.
Basic help like this is fine for personal tools, but for public facing production applications it is desirable to utilize manpages. To this end, Executable
provides Markdown formatted help as well. We can access this, for example, via HelloCommand.help.markdown
. The idea with this is that we can save the output to man/hello.ronn
or copy it the top of our bin/
file, edit it to perfection and then use tools such a ronn, binman or md2man to generate the manpages. What’s particularly cool about Executable
, is that once we have a manpage in the standard man/
location in our project, the #show_help
method will use it instead of the plain text.
For a more detail example see QED and API documentation.
Installation¶ ↑
Install with RubyGems in the usual fashion.
$ gem install executable
CONTRIBUTING¶ ↑
Executable
is a Rubyworks project. As such we largely use in house tools for development.
Testing¶ ↑
QED and Microtest are being used for this project.
Getting In Touch¶ ↑
Copyrights¶ ↑
Executable
is copyrighted open source software.
Copyright (c) 2008 Rubyworks (BSD-2-Clause License)
It can be distributed and modified in accordance with the BSD-2-Clause license.
See LICENSE.txt for details.