Overview

A compact command line parser. The options of a constructed parser are specified via a fluent API. Options with and without values are supported. Options can be specified with abbreviated and full names. A final value option is also supported.

The command line parser supports two styles of command line switches. The first style is switch - space - value (SSV). In this style, the switches supplied on the command line start with a "-" for abbreviated switches and "--" for full switches. For arguments with values, the value is separated from the switch with whitespace.

The second supported style is switch - equals - value (SEV). In this style, the switches supplied on the command line do not have a prefix. For arguments with values, the value is separated from the switch with an equals character "=".

The command line parser can be configured to use one or the other style. Alternative, it can be default constructed whereapon it will detect the style from the first switch's leading character.

Quick start

#include <Balau/Application/CommandLine.hpp>

Style

Here are some examples of command lines.

			#
			# Command line that uses the SSV style and that has a final value.
			#
			# -k    = switch without value
			# --max = switch with value
			# foo   = final value
			#
			./myApp1 -k --max 4 foo

			#
			# Command line that uses the SEV style and that has a final value.
			#
			./myApp2 k max=4 foo

			#
			# Command line that uses the SSV style and that does not have a final value.
			#
			./myApp3 -k --max 4

			#
			# Command line that uses the SEV style and that does not have a final value.
			#
			./myApp3 k max=4
		

Configuration

Here is an example of a configured parser. The switches specified in withOption calls do not take "-" or "--" prefixes, regardless of whether the parser is to be configured as SSV, SEV, or detected.

The command line parser is a template class. The single typename is the key type. Typically, this is an enum, the elements of which are the keys.

			// Pre-defined option keys used in code.
			enum Key {
				KEY1, KEY2, KEY3, HELP
			};

			auto commandLine = CommandLine<Key>()
				.withOption(KEY1, "k", "key-one", true, "The first key.")
				.withOption(KEY2, "m", "key-two", true, "The second key.")
				.withOption(KEY3, "3", false, "Specify in order to use third style.")
				.withHelpOption(HELP, "h", "help", "Displays this help message")
				.withFinalValue();
		

This builds a parser with two options that have values, one option that does not have a value, plus a (key-less) final value option.

If the application's command line does not have a final (switch-less) value, the .withFinalValue() call should be omitted.

Each option has a key (KEY1, KEY2, KEY3 in the example above). These keys are used to query the parsed data later on.

The previous example will detect the style from the first command line argument parsed.

More often, one or the other style is chosen for an application. In order to create the same parser as in the previous example that is configured as SSV, the CommandLineStyle::SwitchSpaceValue argument should be passed into the constructor.

			auto commandLine = CommandLine<Key>(CommandLineStyle::SwitchSpaceValue)
				.withOption(KEY1, "k", "key-one", true, "The first key.")
				.withOption(KEY2, "m", "key-two", true, "The second key.")
				.withOption(KEY3, "3", false, "Specify in order to use third style.")
				.withFinalValue();
		

Similarly, if the parser should be configured to parse the SEV style only, the CommandLineStyle::SwitchEqualsValue argument should be passed into the constructor.

			auto commandLine = CommandLine<Key>(CommandLineStyle::SwitchEqualsValue)
				.withOption(KEY1, "k", "key-one", true, "The first key.")
				.withOption(KEY2, "m", "key-two", true, "The second key.")
				.withOption(KEY3, "3", false, "Specify in order to use third style.")
				.withFinalValue();
		

Retrieving data

To parse a command line, call the parse method.

			commandLine.parse(argc, argv, true);
		

The first two arguments in the parse call are the standard argc/argv argument of the main function.

The third argument in the parse call indicates whether the first argument should be ignored (i.e. the first argument is the executable path).

To obtain options from the parser, call the option verification and extraction methods. In addition to string extraction, methods are available for extracting option data in a variety of primitive types. Refer to the command line parser API documentation for details.

Some example code that extracts the options from the previous command line parser is shown below.

			auto o1 = commandLine.getOption(KEY1);
			auto o2 = commandLine.getOption(KEY2);
			auto o3 = commandLine.getOption(KEY3);
			auto fv = commandLine.getFinalValue();
		

Help text

The command line parser has a method called getHelpText that generates a multi-line help text string for use in command line help text.