std.getopt
Processing of command line options.The getopt module implements a getopt function, which adheres to the POSIX syntax for command line options. GNU extensions are supported in the form of long options introduced by a double dash ("--"). Support for bundling of command line options, as was the case with the more traditional single-letter approach, is provided but not enabled by default.
Credits:
This module and its documentation are inspired by Perl's Getopt::Long module. The syntax of D's getopt is simplified because getopt infers the expected parameter types from the static types of the passed-in pointers.
- bool getopt(T...)(ref string[] args, T opts);
- Synopsis:
import std.getopt; string data = "file.dat"; int length = 24; bool verbose; void main(string[] args) { bool result = getopt( args, "length", &length, // numeric "file", &data, // string "verbose", &verbose); // flag ... }
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 pointed-to 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 ConvError exception is thrown.
Depending on the type of the pointer being bound, getopt recognizes the following kinds of options:
- Boolean options. These are the simplest options; all
they do is set a Boolean to true:
bool verbose, debugging; bool result = getopt(args, "verbose", &verbose, "debug", &debugging);
- 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; bool result = getopt(args, "timeout", &timeout);
Invoking the program with "--timeout=5" or "--timeout 5" will set timeout to 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; bool result = 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 set paranoid to 42; instead, paranoid is set to 2 and "42" is not considered as part of the program options. - 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; bool result = 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; bool result = 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" ] . - 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; bool result = 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 ].
In general, keys and values can be of any parsable types.
- Delegate options. An option can be bound to a delegate with
the signature void delegate(string option) or void delegate(string option, string value).
- In the void delegate(string option) case, the option string (without the leading dash(es)) is passed to the delegate. 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; } } bool result = getopt(args, "verbose", &myHandler, "quiet", &myHandler); }
- In the void delegate(string option, string value) case, the option string is handled as an option with one argument, and parsed accordingly. The option and its value are passed to the delegate. After that, whatever was passed to the delegate is considered handled and removed from the list.
void main(string[] args) { uint verbosityLevel = 1; 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 : writeln(stderr, "Dunno how verbose you want me to be by saying ", value); exit(1); } } bool result = getopt(args, "verbosity", &myHandler); }
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, std.getopt.config.caseSensitive, "foo", &foo, "bar", &bar);
In the example above, "--foo", "--bar", "--FOo", "--bAr" etc. are recognized. The directive is active til the end of getopt, or until the converse directive caseInsensitive is encountered:
bool foo, bar; getopt(args, std.getopt.config.caseSensitive, "foo", &foo, std.getopt.config.caseInsensitive, "bar", &bar);
The option "--Foo", is rejected due to std.getopt.config.caseSensitive, but not "--Bar", "--bAr" etc. because the directive std.getopt.config.caseInsensitive turned sensitivity off before option "bar" was parsed.
Bundling
Single-letter options can be bundled together, i.e. "-abc" is the same as "-a -b -c". By default, this confusing option is turned off. You can turn it on with the std.getopt.config.bundling directive:
bool foo, bar; getopt(args, std.getopt.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 std.getopt.config.noBundling.
Passing unrecognized options through
If an application needs to do its own processing of whichever arguments getopt did not understand, it can pass the std.getopt.config.passThrough directive to getopt:
bool foo, bar; getopt(args, std.getopt.config.passThrough, "foo", &foo, "bar", &bar);
An unrecognized option such as "--baz" will be found untouched in args after getopt returns.
Options Terminator
A lonesome 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.
- Boolean options. These are the simplest options; all
they do is set a Boolean to true:
- enum config;
- Configuration options for getopt. You can pass them to
getopt in any position, except in between an option
string and its bound pointer.
- caseSensitive
- Turns case sensitivity on
- caseInsensitive
- Turns case sensitivity off
- bundling
- Turns bundling on
- noBundling
- Turns bundling off
- passThrough
- Pass unrecognized arguments through
- noPassThrough
- Signal unrecognized arguments as errors