module watt.text.getopt

Process command line arguments.

The getopt modules provides functions that make handling command line options easy.

The basic approach is to call getopt functions with the args parameter, a flag description, and a parameter that determines what getopt will do if it finds a matching parameter.
Matching parameters are removed from the given args array.

getopt(ref args, "help|h", delegateThatPrintsUsage);
getopt(ref args, "verbose|v", out booleanVariable);

The flag description format is simple. It's just the flag name:

"help"

You can add aliases to the same flag by separating them with a |:

"help|usage|?|h"

Single character flags can be preceded by a a single dash. If a flag takes an argument, it can be specified multiple ways. A value can be separated from the flag by =, or whitespace.
If the flag is a single character, the value can be bundled together:

-i32

Code Map

//! Process command line arguments.
module watt.text.getopt;


//! Thrown when arguments are in error.
class GetoptException : Exception
{
public:
	this(msg: string) { }
}

//! Parse a flag taking a string argument from an array of strings.
fn getopt(args: string[], description: string, _string: string) bool { }
//! Parse a flag taking multiple string argument from an array of strings.
fn getopt(args: string[], description: string, strings: string[]) bool { }
//! Parse a flag that takes an integer argument from an array of strings.
fn getopt(args: string[], description: string, _int: i32) bool { }
//! Handle a simple boolean flag.
fn getopt(args: string[], description: string, _bool: bool) bool { }
//! Calls a delegate each time the flag appears.
fn getopt(args: string[], description: string, dgt: scope (void delegate())) bool { }
//! Calls a delegate with argument each time the flag appears.
fn getopt(args: string[], description: string, dgt: scope (void delegate(string))) bool { }
//! Get the first flag in an array of strings.
fn remainingOptions(args: string[]) string { }
class GetoptException : Exception

Thrown when arguments are in error.

fn getopt(args: string[], description: string, _string: string) bool

Parse a flag taking a string argument from an array of strings.

If a flag (described in description, separated by | characters) shows up in args[1 .. $], an argument is parsed and put into _string. Both the flag and argument are then removed from args. If there are multiple instances of the flag, _string will have the value of the last instance.

Example:

args := ["--fruit", "apple", "--fruit", "banana", "--fruit", "pear"]
fruit: string;
getopt(ref args, "fruit", ref fruit);
assert(fruit == "pear");

Parameters

args

The array of strings to remove applicable flags and arguments from.

description

The description of the flag -- see getopt's module documentation for details.

_string

This argument will be filled with the last value parsed out of args.

Return

true if an argument was removed from args.

fn getopt(args: string[], description: string, strings: string[]) bool

Parse a flag taking multiple string argument from an array of strings.

If a flag (described in description, separated by | characters) shows up in args[1 .. $], an argument is parsed and put into strings. Both the flag and argument are then removed from args. If there are multiple instances of the flag, then strings will contain all given arguments, in the order they appeared.

Example:

args := ["--fruit", "apple", "--fruit", "banana", "--fruit", "pear"]
fruits: string[];
getopt(ref args, "fruit", ref fruit);
assert(fruits == ["apple", "banana", "pear"]);

Parameters

args

The array of strings to remove applicable flags and arguments from.

description

The description of the flag -- see getopt's module documentation for details.

strings

This argument will be filled with the arguments of the flag value parsed out of args.

Return

true if an argument was removed from args.

fn getopt(args: string[], description: string, _int: i32) bool

Parse a flag that takes an integer argument from an array of strings.

Parameters

args

The array of strings to remove flags and arguments from.

description

The description of the flag -- see getopt's module documentation for details.

_int

This argument will be filled with the last value parsed out of args.

Return

true if an argument was removed from args.

Throws

  • GetoptException if the argument could not be parsed as an integer.

fn getopt(args: string[], description: string, _bool: bool) bool

Handle a simple boolean flag.

Given an array of strings, args, and a list of strings separated by a | character, description, remove any strings in args[1 .. $] that start with '-' and contain any of the description strings.

Sets _bool to true if args was modified, and returns the same value.

fn getopt(args: string[], description: string, dgt: scope (void delegate())) bool

Calls a delegate each time the flag appears.

The found flags are removed from args.

Return

true if anything was removed from args.

fn getopt(args: string[], description: string, dgt: scope (void delegate(string))) bool

Calls a delegate with argument each time the flag appears.

The flag and arguments are removed from the args array.

Return

true if anything was removed from args.

fn remainingOptions(args: string[]) string

Get the first flag in an array of strings.

Gets the first element in args[1 .. $] that starts with a -, or an empty string otherwise.

This is intended for error handling purposes:

auto flag = remainingOptions(args);
if (flag.length > 0) {
    writefln("error, unknown flag '%s'", flag);
}