Calling the parser

argparse provides CLI template to call the parser covering different use cases. It has the following signatures:

template CLI(Config config, COMMAND) – this is main template that provides multiple API (see below) for all supported use cases.
template CLI(Config config, COMMANDS...) – convenience wrapper of the previous template that provides main template mixin only for the simplest use case with subcommands. See Subcommands section for details.
alias CLI(COMMANDS...) = CLI!(Config.init, COMMANDS) – alias provided for convenience that allows using default Config, i.e., config = Config.init.

Wrapper for `main` function

The recommended and most convenient way to use argparse is through CLI!(...).main(alias newMain) mixin template. It declares the standard main function that parses command line arguments and calls provided newMain function with an object that contains parsed arguments.

newMain function must satisfy these requirements:

It must accept COMMAND type as a first parameter if CLI template is used with one COMMAND.
It must accept all COMMANDS types as a first parameter if CLI template is used with multiple COMMANDS.... argparse uses std.sumtype.match for matching. Possible implementation of such newMain function would be a function that is overridden for every command type from COMMANDS. Another example would be a lambda that does compile-time checking of the type of the first parameter (see examples below for details).
Optionally newMain function can take a string[] parameter as a second argument. Providing such a function will mean that argparse will parse known arguments only and all unknown ones will be passed into the second parameter of newMain function. If newMain function doesn’t have such parameter, then argparse will error out if there is an unknown argument provided in command line.
Optionally newMain can return a result that can be cast to int. In this case, this result will be returned from standard main function.

Usage examples:

import argparse;

struct T
{
    string a;
    string b;
}

mixin CLI!T.main!((args)
{
    // 'args' has 'T' type
    static assert(is(typeof(args) == T));

    // do whatever you need
    import std.stdio: writeln;
    args.writeln;
    return 0;
});

import argparse;

struct cmd1
{
    string a;
}

struct cmd2
{
    string b;
}

mixin CLI!(cmd1, cmd2).main!((args, unparsed)
{
    import std.stdio: writeln;

    // 'args' has either 'cmd1' or 'cmd2' type
    static if(is(typeof(args) == cmd1))
        writeln("cmd1: ", args);
    else static if(is(typeof(args) == cmd2))
        writeln("cmd2: ", args);
    else
        static assert(false); // this would never happen

    // unparsed arguments has 'string[]' type
    static assert(is(typeof(unparsed) == string[]));

    return 0;
});

Call parser with custom `main` function

In the case when wrapping of standard main function does not fit the needs (e.g., some initialization has to be done before parsing the command line), argparse offers CLI!(...).parseArgs function:

int parseArgs(alias newMain)(string[] args, COMMAND initialValue = COMMAND.init)

Parameters:

newMain – function that’s called with object of type COMMAND as a first parameter that is filled with the data parsed from command line; optionally it can take string[] as a second parameter which will contain unknown arguments (see Wrapper for main function section for details).
args – raw command line arguments (excluding argv[0] – first command line argument in main function).
initialValue – initial value for the object passed to newMain function.

Return value:

If there is an error happened during the parsing, then non-zero value is returned. In case of no error, if newMain function returns a value that can be cast to int, then this value is returned, or 0 otherwise.

Usage example:

import argparse;

struct COMMAND
{
    string a;
    string b;
}

static int my_main(COMMAND command)
{
    // Do whatever is needed
    return 0;
}

int main(string[] args)
{
    // Do initialization here
    // If needed, termination code can be done as 'scope(exit) { ...code... }' here as well

    return CLI!COMMAND.parseArgs!my_main(args[1..$]);
}

Low-level calling of parser

For the cases when providing newMain function is not possible or feasible, parseArgs function can accept a reference to an object that receives the values of command line arguments:

Result parseArgs(ref COMMAND receiver, string[] args)

Parameters:

receiver – object that is populated with parsed values.
args – raw command line arguments (excluding argv[0] – first command line argument in main function).

Return value:

An object that can be cast to bool to check whether the parsing was successful or not.

Usage example:

import argparse;

struct COMMAND
{
    string a;
    string b;
}

int main(string[] argv)
{
    COMMAND cmd;

    if(!CLI!COMMAND.parseArgs(cmd, argv[1..$]))
        return 1; // parsing failure

    // Do whatever is needed

    return 0;
}

Partial argument parsing

Sometimes a program may only parse a few of the command line arguments and process the remaining arguments in some different way. In these cases, CLI!(...).parseKnownArgs function can be used. It works much like CLI!(...).parseArgs except that it does not produce an error when unknown arguments are present. It has the following signatures:

Result parseKnownArgs(ref COMMAND receiver, string[] args, out string[] unrecognizedArgs)
Parameters:
- receiver – the object that’s populated with parsed values.
- args – raw command line arguments (excluding argv[0] – first command line argument in main function).
- unrecognizedArgs – raw command line arguments that were not parsed.
Return value:
An object that can be cast to bool to check whether the parsing was successful or not.
Result parseKnownArgs(ref COMMAND receiver, ref string[] args)
Parameters:
- receiver – the object that’s populated with parsed values.
- args – raw command line arguments that are modified to have parsed arguments removed (excluding argv[0] – first command line argument in main function).
Return value:
An object that can be cast to bool to check whether the parsing was successful or not.

Usage example:

import argparse;

struct T
{
    string a;
}

auto arguments = [ "-a", "A", "-c", "C" ];

T result;
assert(CLI!T.parseKnownArgs(result, arguments));
assert(result == T("A"));
assert(arguments == ["-c", "C"]);

Last modified: 07 August 2024

Calling the parser

Wrapper for main function

Call parser with custom main function

Low-level calling of parser

Partial argument parsing

Wrapper for `main` function

Call parser with custom `main` function