CLASP.Ruby
Command-Line Argument Sorting and Parsing, for Ruby
Table of Contents
- Introduction
- libCLImate.Ruby
- Installation
- Components
- Command-line parsing
- Declarative specification of the flags and options for a CLI
- Utility functions for displaying usage and version information
- Examples
- Project Information
- Where to get help
- Contribution guidelines
- Related projects
- License
Introduction
CLASP stands for Command-Line Argument Sorting and Parsing. The first CLASP library was a C library with a C++ wrapper (see project CLASP). There have been several implementations in other languages (as listed in Relation projects). CLASP.Ruby is the Ruby version.
All CLASP libraries provide the facilities to Command Line Interface (CLI) programs as described in detail below.
libCLImate.Ruby
The libCLImate.Ruby library is implemented in terms of CLASP.Ruby but provides a higher-level abstration as well as several utility functions and the facility to fully specify command-line arguments declaratively in the __END__
section of a source file. More information and examples provided in the libCLImate.Ruby project.
Installation
Install via gem as in:
gem install clasp-ruby
or add it to your Gemfile
.
Use via require, as in:
require 'clasp'
Components
Command-line parsing
All CLASP libraries discriminate between three types of command-line arguments:
- flags are hyphen-prefixed arguments that are either present or absent, and hence have a boolean nature;
- options are hyphen-prefixed arguments that are given values; and
- values are non-hyphen-prefixed arguments that represent values.
For example, in the command line
myprog --all -c --opt1=val1 infile outfile
there are:
- two flags,
--all
and-c
; - one option called
--opt1
, which has the valueval1
; and - two values
infile
andoutfile
.
Flags and options may have alias. If the alias for --all
is -a
and the alias for --opt1
is -o
then the following command-line is exactly equivalent to the previous one:
myprog -a -c -o val1 infile outfile
One-letter flags may be combined. Hence, the following command-line is exactly equivalent to the previous ones:
myprog -ac -o val1 infile outfile
Option aliases may specify a value. If the alias -v1
means --opt1=val1
then the following command-line is exactly equivalent to the previous ones:
myprog -ac -v1 infile outfile
Option aliases that are one letter may be combined with one-letter flags. If the alias -v
means --opt1=val1
then the following command-line is exactly equivalent to the previous ones:
myprog -acv infile outfile
UNIX standard arguments confer specific meanings:
-
--help
means that the program should show the usage/help information and terminate; -
--version
means that the program should show the version information and terminate; -
--
means that all subsequent arguments should be treated as values, regardless of any hyphen-prefixes or embedded=
signs.
Declarative specification of the flags and options for a CLI
To support such above special processing, CLASP libraries provide facilities for declarative specification of command-line flags and options, and aliases thereof. For the previous example, the CLASP.Ruby code would look like the following:
# file: cr-example.rb
PROGRAM_VERSION = '0.1.2'
Specifications = [
CLASP.Flag('--all', alias: '-a', help: 'processes all item types'),
CLASP.Flag('-c', help: 'count the processed items'),
CLASP.Option('--opt1', alias: '-o', help: 'an option of some kind', values_range: %w{ val1, val2 }),
CLASP.Flag('--opt1=val1', alias: '-v'),
# see next section for why these two are here
CLASP::Flag.Help,
CLASP::Flag.Version,
]
# assuming the command-line `myprog -acv infile outfile`
Args = CLASP::Arguments.new(ARGV, Specifications)
puts Args.flags.size # => 2
puts Args.flags[0].name # => "--all"
puts Args.flags[1].name # => "-c"
puts Args.options.size # => 1
puts Args.options[0].name # => "--opt1"
puts Args.options[0].value # => "val1"
puts Args.values.size # => 2
puts Args.values[0] # => "infile"
puts Args.values[1] # => "outfile"
Utility functions for displaying usage and version information
There are aspects common to all CLI programs, such as responding to --help
and --version
. All CLASP libraries provide facilities to assist the programmer: CLASP.Ruby provides the two module methods CLASP.show_usage() and CLASP.show_version(), as shown in the following code extending the example above:
Args.flags.each do |f|
case f.name
when CLASP::Flag.Help.name
CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
when CLASP::Flag.Version.name
CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
when '--all'
# do something appropriate to `--all`
. . .
Given the command
./cr-example.rb --help
then the program will output the following
USAGE: cr-example.rb [ ... flags and options ... ] <input-file> <output-file>
flags/options:
-a
--all
processes all item types
-c
count the processed items
-v --opt1=val1
-o <value>
--opt1=<value>
an option of some kind where <value> one of:
val1,
val2
--help
shows this help and terminates
--version
shows version and terminates
and given the command
./cr-example.rb --version
then the program will output the following
cr-example.rb 0.1.2
Examples
Examples are provided in the examples
directory, along with a markdown description for each. A detailed list TOC of them is provided in EXAMPLES.md.
Project Information
Where to get help
Contribution guidelines
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/CLASP.Ruby.
Related projects
CLASP.Ruby is inspired by the C/C++ CLASP library, which is documented in the articles:
- An Introduction to CLASP, Matthew Wilson, CVu, January 2012;
- Anatomy of a CLI Program written in C, Matthew Wilson, CVu, September 2012; and
- Anatomy of a CLI Program written in C++, Matthew Wilson, CVu, September 2015.
Other CLASP libraries include:
Projects in which CLASP.Ruby is used include:
License
CLASP.Ruby is released under the 3-clause BSD license. See LICENSE for details.