doc.md

Introduction:

Table of Contents:

• Introduction:
  • Table of Contents:
  • Terminology:
  • Outlook:
  • Examples:
• Value types for arguments or options with or without parameters:
  • CLI-Options:
    • CLI-Option construction:
    • CLI-Option usage:
  • Positional CLI-Arguments:
    • CLI-Argument usage:
  • Complete collection of supported argument or option parameter types:
    • String values:
    • Integral values:
    • Bool values:
    • Filesystem path values:
    • Floating point values:
    • Chrono values:
    • Custom types:
  • Additional parameters for arguments or options
    • Mandatory/Optional:
    • Default value:
    • Min/Max value:
    • Not-null value:
    • Path exists:
    • Found callback:
    • Custom restrictions:
• Parser:
  • Main Parser:
    • Main parser construction:
    • Main parser usage:
      • The parse() methods:
      • The validate() method:
      • The validate_recursive() method:
      • The parse_and_validate() method:
      • The operator bool() method:
      • The get_executable() method:
      • The gen_help_msg() method:
      • The get_num_processed_arguments() method:
      • The get_active_parser() method:
    • Example code listing for a main parser:
    • Example cli-outputs when using the previous listing:
  • Parser-Container:
    • Parser container construction:
    • Parser container usage:
      • The parse() methods:
      • The parse_and_validate() method:
      • The operator->() method:
      • The operator*() method:
    • Example code listing for a parser container:
    • Example cli-outputs when using the previous listing:
  • Sub Parser:
    • Sub parser construction:
    • Sub parser usage:
      • The validate() method:
      • The validate_recursive() method:
      • The bool is_active() method:
      • The operator bool() method:
      • The get_sub_parser_name() method:
      • The get_num_processed_arguments() method:
      • The get_active_parser() method:
    • Example code listing using sub-parsers and parser containers:
    • Example cli-outputs when using the sub-parser listing:

Terminology:

In this project the following terms are used:

• Option: An option can be either a short option or a long option. A short option consists of a single - followed by single character (e.g. -h). A long option consists of two -- followed by an arbitrary string (e.g. --help).
• Parameter: Some options may require additional parameters (.e.g. --file=/path/to/file).
• Argument: An argument is the short form for positional argument. Thus, arguments higly depend on the position where they occur. Unlinke to options that may occur anywhere else.
• Sub-Parser: A subparser can be triggered by a particular argument name. Once the current parser detects an argument name of a sub-parser, the current parser hands over the parsing-task to the corresponding sub-parser. Thus, this sup-parser argument is always implicitly the last argument handled by the current parser. (e.g. the commands git commit -f or git log can be implemented by sub-parsers, where the sub-parser for commit must at least be capable of the option -f and the sub-parser for log does not get any further options or arguments at all)

Outlook:

This document provides an overview of the features of libClaPP.

The first section starts with the individual value types (for options and arguments). This includes an introduction to the supported CLI-options and CLI-arguments. Also, a complete collection of shipped types is given. Including a description, how custom types can be used. Finally, additional options for options, arguments or their parameters are described (containing constraints or additional help information).

The next section concludes with the different parser types: main-parser and sub-parser. This section also contains some complete examples that show, how a ClaPP-based parser looks like.

Examples:

This document already contains some short examples that show the basic usage of this library. However, some further examples can be found in the ../examples folder.

Value types for arguments or options with or without parameters:

This library supports different types for positional arguments and option parameters. The following subsection introduces all supported types and how additional types can be added. In the subsection below, some argument or option parameter restrictions are introduced.

CLI-Options:

CLI-Option construction:

In general, the constructors of all shipped options have these signatures:

ABSTRACT_OPTION(basic_parser_t& parser, LONG_OPTION long_option, SHORT_OPTION short_option, const std::string& description, ADDITIONAL_PARAMS... params);
ABSTRACT_OPTION(basic_parser_t& parser, LONG_OPTION long_option, const std::string& description, ADDITIONAL_PARAMS... params);
ABSTRACT_OPTION(basic_parser_t& parser, SHORT_OPTION short_option, const std::string& description, ADDITIONAL_PARAMS... params);

where LONG_OPTION, SHORT_OPTION and ADDITIONAL_PARAMS are placeholders for the following types:

• LONG_OPTION can either be a std::string, a C-style string or a std::vector<std::string>.
• SHORT_OPTION can either be a char or a std::vector<char>.
• ADDITIONAL_PARAMS are the variadic types that involve additional parameters for the option (For a complete collection of additional parameters see Additional parameters for arguments or options).

Currently, there exist different types of options:

• non-parameter options: These options do not support any parameters. I.e. the CLI parser only checks if the option is given or not. One example is the common --help|-h option.
• parameter options: Some options require parameters. I.e. options that take numbers, strings or paths. The parameters must be given directly after the option either separated with = or with . Examples are --string-opt='parameter' or --string-opt 'parameter'.
• vector-parameter options: These are required, if parameter options can be given multiple times. In this case, the parsed parameters are stored in a std::vector. E.g. --path /tmp/xxx --path=/tmp/yyy.

As a default, all options are optional. If an option is required, the additional parameter clapp::purpose_t::mandatory must be given to the constructor.

A complete colletion of supported options is available in Complete collection of supported argument or option parameter types.

Example constructor calls for some different options are the following lines:

clapp::option::uint8_param_option_t{parser_inst, "--long-uint8-param", "a description for an unit8-param", clapp::purpose_t::mandatory};
clapp::option::sec_param_option_t{parser_inst, "-s", "number of seconds"}
clapp::option::vector_path_param_option_t{parser_inst, "--path", '-p', "a path the the required file", clapp::value::path_exists_t{}};
clapp::option::vector_path_param_option_t{parser_inst, {"--file", "--f"}, '-f', "a path to the required file", clapp::value::path_exists_t{}};

CLI-Option usage:

In general, all shipped CLI-options can be used in similar ways, as all support the following methods:

template<typename T>
T value() const;
explicit operator bool() const;
bool has_value() const;
bool given() const noexcept;

The method value() can be used to retrieve the parsed value from a CLI-option. If the CLI-parser could not parse the option value from the command line arguments (i.e. the CLI-option contains no value), a call to value() would throw a clapp::exception::value_undefined_t-exception. To check if value() would throw without calling value() directly, the methods has_value() or operator bool() can be used. Both return false, if a call to value() would throw and true if a call to value() would not throw.

If the CLI option was constructed with an additional clapp::value::default_value_t-parameter, a call to T value() will never throw, as value() would return the default value. To distinguish between default values and given values, the method given() can be used: given() returns false, if value() would return the default value from the additional clapp::value::default_value_t-parameter and it returns true, if value() would return a value that is parsed from the CLI arguments.

Positional CLI-Arguments:

In general, the constructors of all shipped (positional) arguments have these signature:

ABSTRACT_ARGUMENT(basic_parser_t& parser, const std::string& argument, const std::string& description, ADDITIONAL_PARAMS... params);

where ADDITIONAL_PARAMS are placeholders for variadic types that involve additional parameters for the argument (For a complete collection of additional parameters see Additional parameters for arguments or options).

Currently, there exist two types of positional arguments:

• regular arguments: are positional arguments that are either mandatory or optional. Note, that mandatory arguments must be registered before optional arguments. Otherwise, positional arguments can't be assigned uniquely.
• variadic arguments: sometimes, it is required to give a variable number of arguments. In this case, variadic position argument types can be used. Similar to the optional arguments before, it is required to define all mandatory arguments before variadic arguments are registered. Also note, that optional arguments and variadic arguments can't be used together. In order to make sure, that the arguments can be parsed uniquely.

As a default, all arguments are mandatory. If an argument is optional, the additional parameter clapp::purpose_t::optional must be given to the constructor.

A complete colletion of supported arguments is available in Complete collection of supported argument or option parameter types.

Example constructor calls for arguments are the following lines: