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:
  • Option-Container:
    • Option container usage:
    • Example code listing for a main-parser and option-container:
    • 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 mandatory. If an option is optional, the additional parameter clapp::parser::types::purpose_t::optional must be given to the constructor. Note: if the option-container that contains the option is an XOR-container (or an XOR-parser), optional options are not allowed! If optional options are registered for an xor-container, the container throws an clapp::exception::option_exception_t.

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::parser::types::purpose_t::optional};
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::parser::types::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:

clapp::string_argument_t string_arg{parser_inst, "string-arg", "String argument"};
clapp::int32_argument_t int_arg{parser_inst, "int-arg", "Int argument", clapp::parser::types::purpose_t::optional};
clapp::variadic_string_argument_t variadic_string_arg{parser_inst, "variadic-string-arg", "Variadic String argument"};

CLI-Argument usage:

In general, all shipped CLI-arguments 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-argument. If the CLI-parser could not parse the argument value from the command line arguments (i.e. the CLI-argument 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 argument 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.

Complete collection of supported argument or option parameter types:

String values:

The most basic types for CLI options are string types (std::string), as all values in the argv parameter can be converted implicitly to (std::string).

If string values should be used for positional arguments, the following types can be used:

• clapp::argument::string_argument_t
• clapp::argument::variadic_string_argument_t

If string values should be used as option parameters, the following types can be used:

• clapp::option::string_param_option_t
• clapp::option::vector_string_param_option_t

Integral values:

The following integral types are supported:

• std::int8_t
• std::int16_t
• std::int32_t
• std::int64_t
• std::uint8_t
• std::uint16_t
• std::uint32_t
• std::uint64_t
• std::ptrdiff_t
• std::size_t

As input format for these values the following formats can be used:

• [+-]?[1-9][0-9]*: Decimal numbers
• [+-]?0[0-7]+: Octal numbers
• [+-]?0[Xx][0-9a-fA-F]+: Hexadecial numbers

If one of these values contains a ., only the decimals before this . are used. Subsequent decimals are truncted.

Examples:

• '0xff' -> std::uint32_t{255}==std::uint8_t{0xff}==std::uint8_t{0377}.
• '077' -> std::int32_t{63}==std::uint8_t{0x3f}==std::uint8_t{077}.
• '100' -> std::int32_t{100}==std::uint8_t{0x64}==std::uint8_t{0144}.

If integral values should be used for positional arguments, the following types can be used:

• clapp::argument::uint8_argument_t
• clapp::argument::uint16_argument_t
• clapp::argument::uint32_argument_t
• clapp::argument::uint64_argument_t
• clapp::argument::int8_argument_t
• clapp::argument::int16_argument_t
• clapp::argument::int32_argument_t
• clapp::argument::int64_argument_t
• clapp::argument::ptrdiff_argument_t
• clapp::argument::size_argument_t
• clapp::argument::variadic_uint8_argument_t
• clapp::argument::variadic_uint16_argument_t
• clapp::argument::variadic_uint32_argument_t
• clapp::argument::variadic_uint64_argument_t
• clapp::argument::variadic_int8_argument_t
• clapp::argument::variadic_int16_argument_t
• clapp::argument::variadic_int32_argument_t
• clapp::argument::variadic_int64_argument_t
• clapp::argument::variadic_ptrdiff_argument_t
• clapp::argument::variadic_size_argument_t

If integral values should be used as option parameters, the following types can be used:

• clapp::option::uint8_param_option_t
• clapp::option::uint16_param_option_t
• clapp::option::uint32_param_option_t
• clapp::option::uint64_param_option_t
• clapp::option::int8_param_option_t
• clapp::option::int16_param_option_t
• clapp::option::int32_param_option_t
• clapp::option::int64_param_option_t
• clapp::option::ptrdiff_param_option_t
• clapp::option::size_param_option_t
• clapp::option::vector_uint8_param_option_t
• clapp::option::vector_uint16_param_option_t
• clapp::option::vector_uint32_param_option_t
• clapp::option::vector_uint64_param_option_t
• clapp::option::vector_int8_param_option_t
• clapp::option::vector_int16_param_option_t
• clapp::option::vector_int32_param_option_t
• clapp::option::vector_int64_param_option_t
• clapp::option::vector_ptrdiff_param_option_t
• clapp::option::vector_size_param_option_t

Bool values:

It is also possible to use bool values.

As input format for these values the following formats can be used:

• true becomes true
• TRUE becomes true
• 1 becomes true
• false becomes false
• FALSE becomes false
• 0 becomes false

If bool values should be used for positional arguments, the following type can be used:

• clapp::argument::bool_argument_t

If integral values should be used as option parameters, the following type can be used:

• clapp::option::bool_option_t

Filesystem path values:

It is also possible to pass regular filesystem paths as argument or option parameter. The underlying type is the standardized filesystem type std::filesystem::path.

If filesystem path values should be used as positional arguments, the following types can be used:

• clapp::argument::path_argument_t
• clapp::argument::variadic_path_argument_t

If filesystem path values should be used as option parameters, the following types can be used:

• clapp::option::path_param_option_t
• clapp::option::vector_path_param_option_t

Floating point values: