std.getopt

class GetOptException: object.Exception;

Thrown on one of the following conditions:

• An unrecognized command-line argument is passed, and std.getopt.config.passThrough was not present.
• A command-line option was not found, and std.getopt.config.required was present.

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

Parse and remove command line options from an 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 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 std.getopt.config.passThrough 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:

1. 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 to true, invoke the program with either --verbose or --verbose=true.
   To set debugging to false, invoke the program with --debugging=false.
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'.
6. 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 set arraySep 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".
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 ].
   Alternatively you can set arraySep 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.
8. 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.

     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: 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 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.

Required: An option can be marked as required. If that option is not present in the arguments an exceptin will be thrown.

bool foo, bar;
getopt(args,
    std.getopt.config.required,
    "foo|f", &foo,
    "bar|b", &bar);

Only the option direclty following std.getopt.config.required 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 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.

Help Information Generation: If an option string is followed by another string, this string serves as an description for this option. The function getopt returns a struct of type GetoptResult. This return value contains information about all passed options as well a bool indicating if information about these options where required by the passed arguments.

The function also always adds an option for --help|-h to set the flag GetoptResult.helpWanted if seen on the command line.

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.

Examples:

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);
}

enum config: int;

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

stopOnFirstNonOption

Stop at first argument that does not look like an option

keepEndOfOptions

Do not erase the endOfOptions separator from args

required

Makes the next option a required option

struct GetoptResult;

The result of the getopt function.

helpWanted is set if the option --help or -h was passed to the option parser.

bool helpWanted;

Flag indicating if help was requested

Option[] options;

All possible options

struct Option;

The result of the getoptHelp function.

string optShort;

The short symbol for this option

string optLong;

The long symbol for this option

string help;

The description of this option

bool required;

If a option is required, not passing it will result in an error

dchar optionChar;

The option character (default '-').

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

string endOfOptions;

The string that conventionally marks the end of all options (default '--').

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 (default '=').

Defaults to '=' but can be assigned to prior to calling getopt.

string arraySep;

The string used to separate the elements of an array or associative array (default is "" which means the elements are separated by whitespace).

Defaults to "" but can be assigned to prior to calling getopt.

void defaultGetoptPrinter(string text, Option[] opt);

This function prints the passed Option and text in an aligned manner.

The passed text will be printed first, followed by a newline. Than the short and long version of every option will be printed. The short and long version will be aligned to the longest option of every Option passed. If a help message is present it will be printed after the long version of the Option.

foreach(it; opt)
{
    writefln("%*s %*s %s", lengthOfLongestShortOption, it.optShort,
        lengthOfLongestLongOption, it.optLong, it.help);
}

Parameters:

string text	The text to printed at the beginning of the help output.
Option[] opt	The Option extracted from the getopt parameter.

void defaultGetoptFormatter(Output)(Output output, string text, Option[] opt);

This function writes the passed text and Option into an output range in the manner, described in the documentation of function defaultGetoptPrinter.

Parameters:

Output output	The output range used to write the help information.
string text	The text to printed at the beginning of the help output.
Option[] opt	The Option extracted from the getopt parameter.