Config

argparse provides decent amount of settings to customize the parser. All customizations can be done by creating Config object with required settings (see below) and passing it to CLI API.

Assign character

Config.assignChar is an assignment character used in arguments with value: -a=5, -b=foo.

Default is equal sign =.

Example:

import argparse;

struct T
{
    string[] a;
}

enum Config cfg = { assignChar: ':' };

T t;
assert(CLI!(cfg, T).parseArgs(t, ["-a:1","-a:2","-a:3"]));
assert(t == T(["1","2","3"]));

Array separator

When Config.arraySep is set to char.init, values to array and associative-array receivers are treated as an individual value. That is, only one argument is appended/inserted per appearance of the argument. If arraySep is set to something else, then each value is first split by the separator, and the individual pieces are treated as values to the same argument.

Default is char.init.

Example:

import argparse;

struct T
{
    string[] a;
}

T t1;
assert(CLI!T.parseArgs(t1, ["-a","1:2:3","-a","4","5"]));
assert(t1 == T(["1:2:3","4","5"]));

enum Config cfg = { arraySep: ':' };

T t2;
assert(CLI!(cfg, T).parseArgs(t2, ["-a","1:2:3","-a","4","5"]));
assert(t2 == T(["1","2","3","4","5"]));

Named argument prefix

Config.namedArgPrefix is a character that named arguments begin with.

Default is dash (-).

Example:

import argparse;

struct T
{
    string a;
    string baz;
}

enum Config cfg = { namedArgPrefix: '+' };

T t;
assert(CLI!(cfg, T).parseArgs(t, ["+a","foo","++baz","BAZZ"]));
assert(t == T("foo","BAZZ"));

End of named arguments

Config.endOfNamedArgs is a string that marks the end of all named arguments. All arguments that are specified after this one are treated as positional regardless to the value which can start with namedArgPrefix (dash - by default) or be a subcommand.

Default is double dash (--).

Example:

import argparse;

struct T
{
    @NamedArgument string a;
    @PositionalArgument(0) string b;
    @PositionalArgument(1) string[] c;
}

enum Config cfg = { endOfNamedArgs: "---" };

T t;
assert(CLI!(cfg, T).parseArgs(t, ["B","-a","foo","---","--","-a","boo"]));
assert(t == T("foo","B",["--","-a","boo"]));

Case sensitivity

Config.caseSensitive controls whether the argument names are case-sensitive. By default they are and it can be changed by setting this member to false.

Default is true.

Example:

import argparse;

struct T
{
    string[] param;
}

enum Config cfg = { caseSensitive: false };

T t;
assert(CLI!(cfg, T).parseArgs(t, ["--param","1","--PARAM","2","--PaRaM","3"]));
assert(t == T(["1","2","3"]));

Bundling of single-character arguments

Config.bundling controls whether single-character arguments (usually boolean flags) can be bundled together. If it is set to true then -abc is the same as -a -b -c.

Default is false.

Example:

import argparse;

struct T
{
    bool a;
    bool b;
    string c;
}

enum Config cfg = { bundling: true };

T t;

assert(CLI!(cfg, T).parseArgs(t, ["-ab"]));
assert(t == T(true, true));

assert(CLI!(cfg, T).parseArgs(t, ["-abc=foo"]));
assert(t == T(true, true, "foo"));

assert(CLI!(cfg, T).parseArgs(t, ["-a","-bc=foo"]));
assert(t == T(true, true, "foo"));

assert(CLI!(cfg, T).parseArgs(t, ["-a","-bcfoo"]));
assert(t == T(true, true, "foo"));

Adding help generation

Config.addHelpArgument can be used to add (if true) or not (if false) -h/--help argument. In case if the command line has -h or --help, then the corresponding help text is printed and the parsing is stopped. If CLI!(...).parseArgs(alias newMain) or CLI!(...).main(alias newMain) is used, then provided newMain function will not be called.

Default is true.

Example:

import argparse;

struct T
{
    string a, b;
}

T t1;
CLI!T.parseArgs(t1, ["-a", "A", "-h", "-b", "B"]);
assert(t1 == T("A"));

enum Config cfg = { addHelpArgument: false };

T t2;
string[] unrecognizedArgs;
CLI!(cfg, T).parseKnownArgs(t2, ["-a", "A", "-h", "-b", "B"], unrecognizedArgs);
assert(t2 == T("A","B"));
assert(unrecognizedArgs == ["-h"]);

Help text from the first part of the example code above:

Styling mode

Config.stylingMode controls whether styling for help text and errors should be enabled. It has the following type: enum StylingMode { autodetect, on, off }:

Config.StylingMode.on: styling is always enabled.
Config.StylingMode.off: styling is always disabled.
Config.StylingMode.autodetect: styling will be enabled when possible.

See ANSI coloring and styling for details.

Default value is Config.StylingMode.autodetect.

Example:

import argparse;

struct T
{
    string a, b;
}

enum Config cfg = { stylingMode: Config.StylingMode.off };

T t;
CLI!(cfg, T).parseArgs(t, ["-a", "A", "-h", "-b", "B"]);
assert(t == T("A"));

Help text from the first part of the example code above:

Styling scheme

Config.styling contains style for the text output (error messages and help text). It has the following members:

programName: style for the program name. Default is bold.
subcommandName: style for the subcommand name. Default is bold.
argumentGroupTitle: style for the title of argument group. Default is bold.underline.
argumentName: style for the argument name. Default is lightYellow.
namedArgumentValue: style for the value of named argument. Default is italic.
positionalArgumentValue: style for the value of positional argument. Default is lightYellow.
errorMessagePrefix: style for Error: prefix in error messages. Default is red.

See ANSI coloring and styling for details.

Example:

import argparse;
import argparse.ansi;

struct T
{
    string a, b;
}

enum Config cfg = { styling: { programName: blue, argumentName: green.italic } };

T t;
CLI!(cfg, T).parseArgs(t, ["-a", "A", "-h", "-b", "B"]);
assert(t == T("A"));

Help text from the first part of the example code above:

Error handling

Config.errorHandler is a handler function for all errors occurred during command line parsing. It is a function that receives string parameter which would contain an error message.

The default behavior is to print error message to stderr.

Example:

import argparse;

struct T
{
    string a;
}

enum Config cfg = {
    errorHandler:
        (text)
        {
            try {
                import std.stdio : stderr;
                stderr.writeln("Detected an error: ", text);
            }
            catch(Exception e)
            {
                throw new Error(e.msg);
            }
        }
};

T t;
assert(!CLI!(cfg, T).parseArgs(t, ["-b"]));

This code prints Detected an error: Unrecognized arguments: ["-b"] to stderr.

Last modified: 07 August 2024