ark-cli
ark-cli is a Ruby library for handling command line options and arguments. See below for basic usage. Full documentation can be found at http://www.rubydoc.info/github/grimheart/ark-cli
Declaring an interface
The usual way to use ark-cli is to call Ark::CLI.report
. This convenience
method builds a new interface and returns a Report
object for inspection.
require 'ark/cli'
# Declare an interface and parse the command line
# Returns a Report instance for inspection as `r`
r = Ark::CLI.report do |s|
s.name 'example'
s.args 'host', 'path'
s.desc "An example demonstrating usage of ark-cli"
s.opt :verbose, :v,
desc: "Increase verbosity"
s.opt :port, :p,
args: 'number',
desc: "Specify an alternate port number"
end
r.args # Get all arguments received, including trailing args
r.arg(:host) # Get the value of the `host` argument
r.opt(:port) # Get the value of the `port` option
r.count(:v) # Get the number of times an option was toggled
The CLI.report
method yields a Spec
instance, which we'll call s
. Calls to
this instance will define how the command line is parsed. The online usage
information will also be generated from this spec.
s
has four important methods:
Name and description
The name
method sets the name of the program to use in usage information. It
expects a string. This should probably be the same as the name of the
executable.
The desc
method sets a description of the program for generating usage
information. It expects a string.
s.name 'example'
s.desc "An example demonstrating usage of ark-cli"
Declaring arguments
The args
method defines what arguments the program will expect.
Declaring two named, expected arguments:
s.args 'host', 'port'
Declare defaults with a colon after the argument name, like 'host:localhost'
.
Arguments with default values are optional - no error will be raised if they
aren't given.
s.args 'file:/tmp/foo'
s.args 'host', 'port:22', "user:#{ENV['USER']}"
Declaring a variadic interface with a glob, 'dest...'
s.args 'target', 'dest...'
Declaring options
The opt
method defines options.
Flags are simple options without arguments:
s.opt :verbose, :v,
desc: "Increase verbosity"
Flags are false by default and set true when given on the command line. A count
is kept of the number of times the flag was specified, and stored in the report
as r.count
. The desc
field is used to generate usage information.
Options can also take arguments:
s.opt :port, :p,
args: 'number',
desc: "Specify an alternate port number"
Inspecting the Report
object
The Ark::CLI#report
method returns a Report
instance which we can inspect
for information parsed from the command line.
Supposing r
is a returned Report
instance, we can get all arguments with the
r.args
method. This will include any trailing arguments.
host, path = r.args
Get the value of a named argument with the r.arg
method:
host = r.arg(:host)
path = r.arg(:path)
Inspect the value of an option with r.opt
:
verbose = r.opt(:v)
port = r.opt(:port)
Get a count of the number of times a flag was specified with r.count
:
verbosity = r.count(:verbose)
Get an array of trailing arguments with r.trailing
:
path1, path2 = r.trailing
Usage information
A help option is defined for all interfaces with the -h
and --help
flags.
When the help option is given, the program will print usage information and exit
immediately. Usage information is constructed from the Spec
built during the
CLI declaration.
Usage information for the above declaration would look like this:
example [-p --port NUMBER] [-v --verbose] [-h --help] HOST PATH
An example demonstrating usage of ark-cli
OPTIONS:
-h --help
Print usage information
-v --verbose
Increase verbosity
-p --port NUMBER
Specify an alternate port number
Example script
A working example script with comments can be found at example/hello.rb
--
invoke the script with the --help
option for usage information.