Function std.getopt.getopt
Parse and remove command line options from a string array.
Synopsis
import std .getopt;
string data = "file.dat";
int length = 24;
bool verbose;
enum Color { no, yes };
Color color;
void main(string[] args)
{
auto helpInformation = getopt(
args,
"length", &length, // numeric
"file", &data, // string
"verbose", &verbose, // flag
"color", "Information about this color", &color); // enum
...
if (helpInformation .helpWanted)
{
defaultGetoptPrinter("Some information about the program.",
helpInformation .options);
}
}
The getopt
function takes a reference to the command line
(as received by main
) as its first argument, and an
unbounded number of pairs of strings and pointers. Each string is an
option meant to "fill" the value referenced by the pointer to its
right (the "bound" pointer). The option string in the call to
getopt
should not start with a dash.
In all cases, the command-line options that were parsed and used by
getopt
are removed from args
. Whatever in the
arguments did not look like an option is left in args
for
further processing by the program. Values that were unaffected by the
options are not touched, so a common idiom is to initialize options
to their defaults and then invoke getopt
. If a
command-line argument is recognized as an option with a parameter and
the parameter cannot be parsed properly (e.g., a number is expected
but not present), a ConvException
exception is thrown.
If config
was not passed to getopt
and an unrecognized command-line argument is found, a GetOptException
is thrown.
Depending on the type of the pointer being bound, getopt
recognizes the following kinds of options:
- Boolean options. A lone argument sets the option to
true
. Additionally true or false can be set within the option separated with an "=" sign:bool verbose = false, debugging = true; getopt(args, "verbose", &verbose, "debug", &debugging);
To set
verbose
totrue
, invoke the program with either--verbose
or--verbose=true
. To setdebugging
tofalse
, invoke the program with--debugging=false
. - Numeric options. If an option is bound to a numeric type, a
number is expected as the next option, or right within the option separated
with an "=" sign:
uint timeout; getopt(args, "timeout", &timeout);
To set
timeout
to5
, invoke the program with either--timeout=5
or--timeout 5
. - Incremental options. If an option name has a "+" suffix and is
bound to a numeric type, then the option's value tracks the number of times
the option occurred on the command line:
uint paranoid; getopt(args, "paranoid+", ¶noid);
Invoking the program with "--paranoid --paranoid --paranoid" will set
paranoid
to 3. Note that an incremental option never expects a parameter, e.g., in the command line "--paranoid 42 --paranoid", the "42" does not setparanoid
to 42; instead,paranoid
is set to 2 and "42" is not considered as part of the normal program arguments. - Enum options. If an option is bound to an enum, an enum symbol as
a string is expected as the next option, or right within the option
separated with an "=" sign:
enum Color { no, yes }; Color color; // default initialized to Color.no getopt(args, "color", &color);
To set
color
toColor
, invoke the program with either.yes --color=yes
or--color yes
. - String options. If an option is bound to a string, a string is
expected as the next option, or right within the option separated with an
"=" sign:
string outputFile; getopt(args, "output", &outputFile);
Invoking the program with "--output=myfile.txt" or "--output myfile.txt" will set
outputFile
to "myfile.txt". If you want to pass a string containing spaces, you need to use the quoting that is appropriate to your shell, e.g. --output='my file.txt'. - Array options. If an option is bound to an array, a new element
is appended to the array each time the option occurs:
string[] outputFiles; getopt(args, "output", &outputFiles);
Invoking the program with "--output=myfile.txt --output=yourfile.txt" or "--output myfile.txt --output yourfile.txt" will set
outputFiles
to[ "myfile.txt", "yourfile.txt" ]
. Alternatively you can setarraySep
as the element separator:string[] outputFiles; arraySep = ","; // defaults to "", separation by whitespace getopt(args, "output", &outputFiles);
With the above code you can invoke the program with "--output=myfile.txt,yourfile.txt", or "--output myfile.txt,yourfile.txt".
- Hash options. If an option is bound to an associative array, a
string of the form "name=value" is expected as the next option, or right
within the option separated with an "=" sign:
double[string] tuningParms; getopt(args, "tune", &tuningParms);
Invoking the program with e.g. "--tune=alpha=0.5 --tune beta=0.6" will set
tuningParms
to [ "alpha" : 0.5, "beta" : 0.6 ]. Alternatively you can setarraySep
as the element separator:double[string] tuningParms; arraySep = ","; // defaults to "", separation by whitespace getopt(args, "tune", &tuningParms);
With the above code you can invoke the program with "--tune=alpha=0.5,beta=0.6", or "--tune alpha=0.5,beta=0.6". In general, the keys and values can be of any parsable types.
- Callback options. An option can be bound to a function or
delegate with the signature
void function()
,void function(string option)
,void function(string option, string value)
, or their delegate equivalents.- If the callback doesn't take any arguments, the callback is invoked whenever the option is seen.
- If the callback takes one string argument, the option string
(without the leading dash(es)) is passed to the callback. After that,
the option string is considered handled and removed from the options
array.
void main(string[] args) { uint verbosityLevel = 1; void myHandler(string option) { if (option == "quiet") { verbosityLevel = 0; } else { assert(option == "verbose"); verbosityLevel = 2; } } getopt(args, "verbose", &myHandler, "quiet", &myHandler); }
- If the callback takes two string arguments, the option string is
handled as an option with one argument, and parsed accordingly. The
option and its value are passed to the callback. After that, whatever
was passed to the callback is considered handled and removed from the
list.
int main(string[] args) { uint verbosityLevel = 1; bool handlerFailed = false; void myHandler(string option, string value) { switch (value) { case "quiet": verbosityLevel = 0; break; case "verbose": verbosityLevel = 2; break; case "shouting": verbosityLevel = verbosityLevel
.max; break; default : stderr .writeln("Unknown verbosity level ", value); handlerFailed = true; break; } } getopt(args, "verbosity", &myHandler); return handlerFailed ? 1 : 0; }
Options with multiple names
Sometimes option synonyms are desirable, e.g. "--verbose", "--loquacious", and "--garrulous" should have the same effect. Such alternate option names can be included in the option specification, using "|" as a separator:
bool verbose;
getopt(args, "verbose|loquacious|garrulous", &verbose);
Case
By default options are case-insensitive. You can change that behavior
by passing getopt
the caseSensitive
directive like this:
bool foo, bar;
getopt(args,
config .caseSensitive,
"foo", &foo,
"bar", &bar);
In the example above, "--foo" and "--bar" are recognized, but "--Foo", "--Bar",
"--FOo", "--bAr", etc. are rejected.
The directive is active until the end of getopt
, or until the
converse directive caseInsensitive
is encountered:
bool foo, bar;
getopt(args,
config .caseSensitive,
"foo", &foo,
config .caseInsensitive,
"bar", &bar);
The option "--Foo" is rejected due to config
, but not "--Bar", "--bAr"
etc. because the directive config
turned sensitivity off before
option "bar" was parsed.
Short versus long options
Traditionally, programs accepted single-letter options preceded by
only one dash (e.g. -t
). getopt
accepts such parameters
seamlessly. When used with a double-dash (e.g. --t
), a
single-letter option behaves the same as a multi-letter option. When
used with a single dash, a single-letter option is accepted. If the
option has a parameter, that must be "stuck" to the option without
any intervening space or "=":
uint timeout;
getopt(args, "timeout|t", &timeout);
To set timeout
to 5
, use either of the following: --timeout=5
,
--timeout 5
, --t=5
, --t 5
, or -t5
. Forms such as -t 5
and -timeout=5
will be not accepted.
For more details about short options, refer also to the next section.
Bundling
Single-letter options can be bundled together, i.e. "-abc" is the same as
"-a -b -c"
. By default, this option is turned off. You can turn it on
with the config
directive:
bool foo, bar;
getopt(args,
config .bundling,
"foo|f", &foo,
"bar|b", &bar);
In case you want to only enable bundling for some of the parameters,
bundling can be turned off with config
.
Required
An option can be marked as required. If that option is not present in the arguments an exception will be thrown.
bool foo, bar;
getopt(args,
config .required,
"foo|f", &foo,
"bar|b", &bar);
Only the option directly following config
is
required.
Passing unrecognized options through
If an application needs to do its own processing of whichever arguments
getopt
did not understand, it can pass the
config
directive to getopt
:
bool foo, bar;
getopt(args,
config .passThrough,
"foo", &foo,
"bar", &bar);
An unrecognized option such as "--baz" will be found untouched in
args
after getopt
returns.
Help Information Generation
If an option string is followed by another string, this string serves as a
description for this option. The getopt
function returns a struct of type
GetoptResult
. This return value contains information about all passed options
as well a bool GetoptResult
flag indicating whether information
about these options was requested. The getopt
function always adds an option for
--help|-h
to set the flag if the option is seen on the command line.
Options Terminator
A lone double-dash terminates getopt
gathering. It is used to
separate program options from other parameters (e.g., options to be passed
to another program). Invoking the example above with "--foo -- --bar"
parses foo but leaves "--bar" in args
. The double-dash itself is
removed from the argument array unless the config
directive is given.
Example
auto args = ["prog", "--foo", "-b"];
bool foo;
bool bar;
auto rslt = getopt(args, "foo|f", "Some information about foo.", &foo, "bar|b",
"Some help message about bar.", &bar);
if (rslt .helpWanted)
{
defaultGetoptPrinter("Some information about the program.",
rslt .options);
}