Repository files navigation

A command line and config file parser for DLang

import args : Arg, Optional, parseArgsWithConfigFile, printArgsHelp;staticstructMyOptions {@Arg("the input file", Optional.yes)string inputFilename;@Arg("test values",'t')int[] testValues;@Arg("Enable feature")bool enableFeature;}MyOptionsgetOptions(refstring[] args) {MyOptions options;bool helpWanted = parseArgsWithConfigFile(options, args);if (helpWanted) {printArgsHelp(options,"A text explaining the program");}return options;}voidmain(string[] args) {const options = getOptions(args);// or args.dup to keep the original args// use options here....}

This gives:

❯ ./quick_example--helpA text explaining the program--inputFilename   Type: dchar[]default:        Help: the input file-t--testValues      Type: int[]default: []     Help: test values--enableFeature   Type: booldefault: false  Help: Enable feature

argsd arguments are structures as shown below.Each argument that should be searched for needs to have@Arg()attached to it.

@Arg() takes three kinds of parameter.

1. Astring which is used as the help message for that argument.
2. Achar which is used as the character for the short argumentselector.
3. AOptional value to make the argument as optional or not (defaultOptional.yes).The order of the three parameter is not relevant.

Arguments can be nested, see the nestedNestedArgument struct inMyAppArguments.

Arguments can be of all primitive types, arrays of primitive types andD enums.

All arguments take the shape "name value". Equal sign syntax is notsupported.

Array values can be given as a comma separated list.

The name of the argument will be derived from the name of the member inthe struct. The names are case sensitive.

Arguments in nested structs have the name of the struct prefixed (compare--nested.someFloatValue).

Short names must be unique. If they are not unique an Exception will bethrown. Short names are used by prefixing the character with a single-.The short name-h is reserved for requestion the help page.

Long names are unique by definition. Long names are prefixed with--.The long name "--help" is reserved for requestion the help page.

IfparseArgsWithConfigFile is used two more long names are reserved,--config, and--genConfig. Both take astring as argument.--config filename will try to parse the file with namefilename andassign the values in that file to the argument struct passed.

--genConfig filename can be used to create a config file withthe default values of the argument struct. The name of the config file isagainfilename.

/** A enum used inside of NestedArguments*/enum NestedEnumArgument {one,two,many}/** A struct nested in MyAppArguments*/staticstructNestedArguments {@Arg("Important Help Message")float someFloatValue;// D allows to assign default values to the arguments@Arg('z') NestedEnumArgument enumArg = NestedEnumArgument.two;@Arg()bool someBool;}/** The options to the created program.*/staticstructMyAppArguments {@Arg(Optional.no)string inputFilename;@Arg('b')int[] testValues;/** All options inside of nested need to be prefixed with  "nested.".*/@Arg() NestedArguments nested;}importstd.algorithm.comparison : equal;importstd.format : format;importstd.math : isClose;

It is good practice to have the arguments write-protected by default.The following three declarations show a possible implementation.

In order to look up a argument the developer would use theconfig()function, returning him a write-protected version of the arguments.In order to populate the arguments the writable version returned fromconfigWriteable is passed toparseArgsWithConfigFile.This, and the option definitions is usually placed in a separate file andthe visibility ofMyAppArguments argument is set toD private.

MyAppArguments arguments;

refMyAppArgumentsconfigWriteable() {return arguments;}ref const(MyAppArguments)config() {return arguments;}

Thisstring[] serves as an example of what would be passed to themain function from the command line.

string[] args = ["./executablename","--nested.someBool","--nested.someFloatValue","12.34","--testValues","10","-b","11,12","--nested.enumArg","many","--inputFilename","nice.d"];

Populates the argument struct returned from configWriteable with thevalues passed inargs.

true is returned if the help page is requested with either-h or--help.parseArgsWithConfigFile, andparseArgs will remove all usedstrings fromargs.After the unused strings and the application name are left inargs.

ReplacingparseArgsWithConfigFile withparseArgs will disablethe config file parsing option.

bool helpWanted = parseArgsWithConfigFile(configWriteable(), args);if(helpWanted) {/** If the help page is wanted by the user the printArgsHelpfunction can be used to print help page.*/printArgsHelp(config(),"A text explaining the program");}/** Here it is tested if the parsing of args was successful.*/assert(equal(config().testValues, [10,11,12]));assert(config().nested.enumArg== NestedEnumArgument.many);assert(isClose(config().nested.someFloatValue,12.34));assert(config().nested.someBool);assert(config().inputFilename=="nice.d");