Class CLIWrapper

Class Documentation

class CLIWrapper

The class used to define and parse command-line arguments.

It is a wrapper around https://github.com/CLIUtils/CLI11 that stores defined command-line arguments in a YAML object.

Usage outline: first call add() methods to create all the options; then call parse(argv, argc) to parse command line and get defined options and their values in a YAML object; finally call parseAliases() to expand alias options. The config object can be also obtained later by calling getConfig().

Options are organized in option groups. Each option group has a header that preceeds all options in the group. The header for the default option group can be set from the class constructor.

Public Functions

CLIWrapper(YAML::Node &config, const std::string &description = "", const std::string &header = "General options", const std::string &footer = "", size_t columnWidth = 40, size_t screenWidth = 0)

Create an instance of the command-line argument parser.

Option help, -h is automatically added.

Parameters

  • config: A reference to the to-be-wrapped yaml tree

  • description: Program description

  • header: Header text for the main option group

  • footer: Text displayed after the list of options

  • columnWidth: Width of the column with option names

  • screenWidth: Maximum allowed width for help messages, 0 means no limit

~CLIWrapper()
template<typename T>
CLI::Option *add(const std::string &args, const std::string &help, T val)

Define an option with a default value.

Explicit default values will appear in help messages.

Return

Option object

Parameters

  • args: Comma-separated list of short and long option names

  • help: Help message

  • val: Default value

template<typename T>
CLI::Option *add(const std::string &args, const std::string &help)

Define an option without an explicit default value.

The implicit default value is T()

The option will be defined in the config file even if not given as a command-line argument. The implicit default value for a boolean or numeric option is 0, for a string is an empty string, and for a vector is an empty vector.

Implicit default values will NOT appear in help messages.

@TODO: require to always state the default value creating the parser as this will be clearer

Return

Option object

Parameters

  • args: Comma-separated list of short and long option names

  • help: Help message

void alias(const std::string &key, const std::string &value, const std::function<void(YAML::Node &config)> &fun)

Transform a command line option into an alias.

This alias will set other options later.

An alias sets one or more options to predefined values. The options expanded by the alias are provided as a function setting a temporary YAML config.

The alias option has to be first defined using add<T>(). Otherwise, the program will abort.

Defining more than one alias for the same key but different value is allowed.

Option values are compared as std::string. If the alias option is a vector, the alias will be triggered if value exists in that vector at least once.

Options set directly via command line have precedence over options defined in an alias, i.e. an option added via alias can be overwritten by setting a specific option via command line.

Parameters

  • key: Alias option name

  • value: Option value that trigger the alias

  • fun: Function setting a temporary YAML config with options expanded by alias

std::string switchGroup(std::string name = "")

Switch to different option group or to the default group if argument is empty.

Return

Previous group.

Parameters

  • name: Header of the option group

void parse(int argc, char **argv)
void parseAliases()

Expand aliases based on arguments parsed with parse(int, char**)

Should be called after parse(int, char**) to take an effect. If any alias tries to expand an undefined option, the method will abort the program.

All options defined as aliases are removed from the global config object to avoid redundancy when options are dumped (explicitly or implicitly) to a config file.

void updateConfig(const YAML::Node &config, cli::OptionPriority priority, const std::string &errorMsg)

Overwrite options with lower priority.

Values for options with lower priority than the provided priority remain unchanged. This allows for overwritting default options by options from config files, or both by options provided in the command line.

This should be a preferred way of updating config options as the class keeps track of options, which values have changed.

Parameters

  • config: YAML config with new default values for options

  • priority: priority of incoming options

  • errorMsg: error message printed if config contains undefined keys. The message is appended with “: <comma-separated list of invalid options>”

std::string dumpConfig(bool skipUnmodified = false) const