std.getopt

Processing of command line options.

The getopt module implements a getopt function and two functions getOptions. All adhere to the POSIX syntax for command line options. GNU extensions are supported in the form of long options introduced by a double dash ("--"). Values can be separated by space/s and additionally by the assignChar character which defaults to '='. Short options with the value directly attached (i.e. without intervening space) are also allowed but configurable to work only for short numeric options. 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.

License:
Boost License 1.0.

Authors:
Andrei Alexandrescu, Jens K. Mueller, Igor Lesik

Credits:
This module and its documentation are inspired by Perl's Getopt::Long module. The syntax of D's getopt is simpler than its Perl counterpart because getopt infers the expected parameter types from the static types of the passed-in pointers.

Source:
std/getopt.d

void getopt(T...)(ref string[] args, T opts);

Synopsis:

import std.getopt;

string data = "file.dat";
int length = 24;
bool verbose;
enum Color { no, yes }
Color color;

void main(string[] args)
{
  getopt(args,
         "length",  &length,    // numeric
         "file",    &data,      // string
         "verbose", &verbose,   // flag
         "color",   &color,     // enum
         ...
        );
}

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 ConvException exception is thrown. If an option is not recognized an Exception is thrown. Further an Exception is thrown if there was an argument expected but non given or an argument was given but non was expected.

Depending on the type of the pointer being bound, getopt recognizes the following kinds of options:

1. Boolean options. These are the simplest options; all they do is set a Boolean to true:

   bool verbose, debugging;
   getopt(args, "verbose", &verbose, "debug", &debugging);
   

2. 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 to 5, invoke the program with either --timeout=5 or --timeout 5.
3. 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+", &paranoid);
   

   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 normal program arguments.
4. 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 to Color.yes, invoke the program with either --color=yes or --color yes.
5. 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'. Note that string, wstring, and dstring are supported.
6. Array options. If an option is bound to an dynamic 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" ]. The same result can be achieved by "--output myfile.txt,yourfile.txt" specifying multiple elements separated by arraySep.
7. 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 ]. Specifying multiple elements separated by arraySep is also possible, e.g. "--tune=alpha=0.5,beta=0.6".
   Keys and values can be of any parsable types.
8. Delegate options. An option can be bound to a delegate with the signature void delegate(), void delegate(string option) or void delegate(string option, string value).

   • In the void delegate() case, the delegate is invoked whenever the option is seen.
   • 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;
         }
       }
       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 :
             stderr.writeln("Dunno how verbose you want me to be by saying ",
               value);
             exit(1);
         }
       }
       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.

"Short" versus "long" options

Single-letter options preceded by only one dash (e.g. -t) are accepted. These options are called short options. If a double-dash is used a multi-letter option must follow, e.g. --timeout. This kind of option is called a long option. A multi-letter option with a single dash (e.g. -timeout) will not be accepted as a single option (but if bundling is enabled it is parsed as -t -i -m -e -o -u -t; see section Bundling) and a single-letter option with a double-dash (e.g. --t) will not be accepted as well. If the option has a parameter, that option must be passed with an intervening space or "=":

uint timeout;
getopt(args, "timeout|t", &timeout);

To set timeout to 5, use either the long options --timeout=5 or --timeout 5 or the short options -t=5 or -t 5. Also the short option with no space -t5 is accepted (see next section).

The forms -timeout=5, -timeout 5, --t=5, --t 5, --t5, --timeout5, and -timeout5 are not accepted. Beware though that -timeout=5, -timeout 5, and -timeout5 would be accepted with values imeout=5, imeout, and imeout5, respectively, if -t was an option of type string. For more details about short options with no space, refer also to the next section.

Omitting spaces for short options

By default omitting space/s for short options is enabled for all types, i.e. std.getopt.config.noSpaceForShortOptions is set.

If you happen to have a short string option and a long string option starting with the same letter like the short option, the behavior may be surprising. Since whenever the value passed to a short option is convertible to its type (via std.conv.to) the option will be accepted. This is e.g. the case for strings as pointed out in the above section. As this behavior is usually confusing, it can be enabled for numeric short options only using the configuration option std.getopt.config.noSpaceOnlyForShortNumericOptions. Given

string timeout;
getopt(args, std.getopt.config.noSpaceOnlyForShortNumericOptions,
             "timeout|t", &timeout);

-timeout=whatever, -timeout whatever, and -timeoutwhatever will throw an exception.

Specifying std.getopt.config.noSpaceOnlyForShortNumericOptions is strongly recommended in cases like above.

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.

Note, when using bundling together with short options the unbundling happens before the short options are handled. E.g.

bool verbose;
string filename;

auto args = ["program.name",
             "-fzv"];
getopt(args, config.bundling,
             "f", &filename,
             "v", &verbose);
assert(verbose, to!string(verbose));
assert(filename == "-z", to!string(filename)); // due to unbundling

But "-vf filename" works as expected.

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. As std.getopt.config.passThrough is only used in these cases the default is std.getopt.config.noPassThrough.

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.

void getOptions(T...)(ref string[] args, T opts);

Same as above but noSpaceForShortNumericOptionsOnly is set and specific Exceptions are thrown.

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), an IllegalArgumentException is thrown. The original exception (usually a std.conv.ConvException) is accessible with Throwable's next. If an option expects an argument (applies to non-Boolean options) but wasn't specified a MissingArgumentException is thrown.

For -timeout=5, -timeout 5, and -timeout5 an IllegalArgumentException is thrown because the argument imeout=5, imeout, and imeout5, respectively, is not convertible to uint. For --t=5, --t 5, --t5, and --timeout5 an UnrecognizedOptionException is thrown.

Beware though that -timeout=5, -timeout 5, and -timeout5 would be accepted with values imeout=5, imeout, and imeout5, respectively, if -t was an option of type string.

-timeout=whatever, -timeout whatever, and -timeoutwhatever will throw an UnrecognizedOptionException.

By default std.getopt.config.noPassThrough is set. In this setting a UnrecognizedOptionException is thrown if any given option is not recognized. E.g. if --bar is given, then

bool foo;
getopt(args, "foo", &foo);

will throw an UnrecognizedOptionException.

void getOptions(T...)(string header, out string usage, ref string[] args, T opts);

Same as above but additionally usage information is being generated using usageOptionsString. The options must include an additional second argument (a help string) for each option.

Synopsis:

// program options with defaults
string inputFile = "test";
string outputFile;

string usage;
getOptions(
   "Usage: " ~ args[0] ~ " { --switch }\n\n",
   usage,
   args,
   "i|input","   input file name must\n"
             "   be an HTML file.",           &inputFile,
   "o|output","  output file name.",          &outputFile,
   "author","     print name of the author",  delegate() {writeln("Somebody");return;},
   "h|help","    print help",                 delegate() {writeln(usage);return;},
);

or

// program options with defaults
string inputFile = "test";
string outputFile;
uint number;

string header =
   "Usage: " ~ args[0] ~ " { --switch }\n\n";

string usage;

import std.typecons;
alias tuple options;
auto opts = options(
   "i|input","   input file name must\n"
             "   be an HTML file.",           &inputFile,
   "o|output","  output file name.",          &outputFile,
   "n|number","  a number.",                  &number,
   "author","     print name of the author",  delegate() {writeln("Somebody");return;},
   "h|help","    print help",                 delegate() {writeln(usage);return;},
);

try getOptions(
       header,
       usage,
       args,
       opts.expand,
    );
catch (GetoptException e)
{
    // if something goes wrong, report usage with current values
    writeln(e.msg);
    writeln("Usage with currently set values:");
    optionFormatValue = " (currently '%s')";
    writeln(usageOptionsString(opts.expand));
}

string usageOptionsString(T...)(T options);

Returns:
a usage string for given options.

Each given option must have a help string as second argument.

dchar optionChar;

The option character. Defaults to '-' but it can be assigned to prior to calling getopt.

dchar optionSep;

The option separation character. Defaults to '|' but it can be assigned to prior to calling getopt.

string endOfOptions;

The string that conventionally marks the end of all options. Defaults to "--" but can be assigned to prior to calling getopt. Assigning an empty string to endOfOptions effectively disables it.

dchar assignChar;

The assignment character used in options with parameters. Defaults to '=' but can be assigned to prior to calling getopt.

string arraySep;

The string used to separate multiple elements of array parameters. Defaults to "," but can be assigned to prior to calling getopt.

string optionFormatValue;

The string used to format values in usage strings. Defaults to " Defaults to '%s' but can be assigned to prior to calling usageOptionsString.

class GetoptException: object.Exception;

This exception is the common base of all exceptions thrown by this module.

class UnrecognizedOptionException: std.getopt.GetoptException;

This exception is thrown if an option is not recognized.

class IllegalArgumentException: std.getopt.GetoptException;

This exception is thrown if the argument given to an option is illegal. There may be other exceptions chained to this one, accessible via Throwable's member next.

class MissingArgumentException: std.getopt.GetoptException;

This exception is thrown if there was no argument given to an option.

Copyright Andrei Alexandrescu 2008 - 2009, Jens K. Mueller 2011-, Igor Lesik 2011. | Page generated by Ddoc.