Note: This is a fork
The version number was reset to 1.0.0 at the time of forking and roughly maps to v4.4.4 of the upstream project.
You can find the original repo at commander-rb/commander.
This fork adds a number of patches and modifications to the upstream project that support the OpenFlightHPC tools.
To ship a new release, do the following:
- Increment the version number in
version.rb
Documentation from the upstream project follows.
Commander
The complete solution for Ruby command-line executables. Commander bridges the gap between other terminal related libraries you know and love (Slop, HighLine), while providing many new features, and an elegant API.
Features
- Auto-generates help documentation via pluggable help formatters
- Optional default command when none is present
- Global / Command level options
- Packaged with one help formatters (Terminal)
- Imports the highline gem for interacting with the terminal
- Adds additional user interaction functionality
- Highly customizable progress bar with intuitive, simple usage
- Sexy paging for long bodies of text
- Command aliasing (very powerful, as both switches and arguments can be used)
- Use the
commander
executable to initialize a commander driven program
Installation
$ gem install commander
Example
require 'rubygems'
require 'commander'
class MyApplication
# :name is optional, otherwise uses the basename of this executable
program :name, 'Foo Bar'
program :version, '1.0.0'
program :description, 'Stupid command that prints foo or bar.'
command :foo do |c|
c.syntax = 'foobar foo'
c.description = 'Displays foo'
c.action do |args, options|
say 'foo'
end
end
command :bar do |c|
c.syntax = 'foobar bar [options]'
c.description = 'Display bar with optional prefix and suffix'
c.slop.string '--prefix', 'Adds a prefix to bar'
c.slop.string '--suffix', 'Adds a suffix to bar', meta: 'CUSTOM_META'
c.action do |args, options, config|
options.default :prefix => '(', :suffix => ')'
say "#{options.prefix}bar#{options.suffix}"
end
end
end
MyApplication.run!(ARGV) if $0 == __FILE__
Example output:
$ foobar bar
# => (bar)
$ foobar bar --suffix '}' --prefix '{'
# => {bar}
Commander Goodies
Option Parsing
Option parsing is done using Simple Lightweight Option Parsing which provides a rich interface for different option types. The main three being:
command do |c|
# Boolean Flag
c.slop.bool '--boolean-flag', 'Sets the :boolean_flag option to true'
# String Value
c.slop.string '--string-value', 'Takes a string from the command line'
c.slop.string '--flag', 'Sets the meta variable to META', meta: 'META'
# Interger Value
c.slop.integer '--integer-value', 'Takes the input and type casts it to an integer'
# Legacy syntax (boolean and string values only)
c.option '--legacy-bool', 'A boolean flag using the legacy syntax'
c.option '--legacy-string LEGACY_STRING', 'A string flag using the legacy syntax'
end
Command Aliasing
Aliases can be created using the #alias_command
method like below:
command :'install gem' do |c|
c.action { puts 'foo' }
end
alias_command :'gem install', :'install gem'
Or more complicated aliases can be made, passing any arguments as if it was invoked via the command line:
command :'install gem' do |c|
c.syntax = 'install gem <name> [options]'
c.option '--dest DIR', String, 'Destination directory'
c.action { |args, options| puts "installing #{args.first} to #{options.dest}" }
end
alias_command :update, :'install gem', 'rubygems', '--dest', 'some_path'
$ foo update
# => installing rubygems to some_path
Command Defaults
Although working with a command executable framework provides many
benefits over a single command implementation, sometimes you still
want the ability to create a terse syntax for your command. With that
in mind we may use #default_command
to help with this. Considering
our previous :'install gem'
example:
default_command :update
$ foo
# => installing rubygems to some_path
Keeping in mind that commander searches for the longest possible match
when considering a command, so if you were to pass arguments to foo
like below, expecting them to be passed to :update
, this would be incorrect,
and would end up calling :'install gem'
, so be careful that the users do
not need to use command names within the arguments.
$ foo install gem
# => installing to
Long descriptions
If you need to have a long command description, keep your short description under summary
, and consider multi-line strings for description
:
program :summary, 'Stupid command that prints foo or bar.'
program :description, %q(
#{c.summary}
More information about that stupid command that prints foo or bar.
And more
)
Additional Global Help
Arbitrary help can be added using the following #program
symbol:
program :help, 'Author', 'TJ Holowaychuk <tj@vision-media.ca>'
Which will output the rest of the help doc, along with:
AUTHOR:
TJ Holowaychuk <tj@vision-media.ca>
Global Options
Global options work in a similar way to command level options. They both are configured using Slop
. Global options are available on all commands. They are configure on the global_slop
directive.
class MyApplication
program :name, 'Foo Bar'
...
global_slop.string '--custom-global', 'Available on all commands'
end
Tracing
WIP: Update OpenFlight --trace behaviour
Running Specifications
$ rake spec
OR
$ spec --color spec
Contrib
Feel free to fork and request a pull, or submit a ticket http://github.com/commander-rb/commander/issues
License
This project is available under the MIT license. See LICENSE for details.