Joutsen Arguments Parsing

Joutsen Arguments Parsing is the part of the Joutsen framework that makes it possible to easily parse input strings and write the values to object properties. Thus providing a way to ensure syntactical correctness and type safety. By also providing automatically generated usage and description reduces the redundancy to write a parser for every project that uses string input e.g. from the command line. This project is inspired by the argparse module found in python.

Setup and Usage

To use the library just add the Joutsen.ArgumentsParsing.dll and its dependency the Joutsen.System.dll to your project. If you want to build the library yourself simply run the build.sh file located in the scripts folder.

A new parser can then be created by simply calling the default constructor of the ArgumentsParser class. Expected arguments can then be added to the parser by calling the AddArgument method:

ArgumentsParser parser = new ArgumentsParser();
parser.AddArgument(new ValueArgument<int>("name1"));
parser.AddArgument("-n", "--named", new ValueArgument<string>("name2"));

There exists two kinds of arguments and subparsers. Depending on which argument type you choose parameters will be parsed by position or by name. Subparsers realize commands with arguments.

Once the arguments are configured, input can be parsed by calling the Parse method. If no target object is provided a dictionary-like result object will be created automatically.

static int Main(string[] args)
{
    ParseResult result = parser.Parse(args);
    ...
}

If one of the arguments cannot be parsed an exception is thrown. By using the ParseKnown method this behaviour can be changed and the unknown or unparsable parameters will be returned as the UnknownArguments property of the result.

Examples for different argument types can be found in the documentation folder docs/examples and the example folder contains a demonstration implementation for the use of the parser to process command line arguments.

Tests

Unit tests and component tests using the NUnit test framework are available. In order to run them the projects in the tests folder need to be build successfully. The tests can then be run from the commandline using the NUnit projects in the tests folder.

nunit.exe tests/ArgumentParser.All.Tests.nunit

For more information see the development documentation.

Documentation

API documentation using doxygen is generated for each stable version. The resulting HTML API documentation for the latest development version is available at apidocs.norsecorby.de.

It is also possible to generate up to date API documentation using the script docs-html.sh.

Development

Development documentation with guidelines and information is available in docs/development.