Provides functionality to specify options and arguments to create a new basic_command_line_parser.
More...
#include <ookii/command_line_builder.h>
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
class ookii::basic_parser_builder< CharType, Traits, Alloc >
Provides functionality to specify options and arguments to create a new basic_command_line_parser.
To create a basic_command_line_parser, you will first create an instance of the basic_parser_builder, calling various methods to set options that control parsing behavior. Then, use the add_argument() and add_multi_value_argument() methods to add arguments and set their options.
Several typedefs for common character types are provided:
- Template Parameters
-
| CharType | The character type used for arguments and other strings. Only char and wchar_t are supported. Defaults to wchar_t if _UNICODE is defined, otherwise to char. |
| Traits | The character traits to use for strings. Defaults to std::char_traits<CharType>. |
| Alloc | The allocator to use for strings. Defaults to std::allocator<CharType>. |
◆ argument_base_type
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
◆ string_type
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
The specialized type of std::basic_string used.
◆ typed_argument_type
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename T >
The specialized type of the command_line_argument instances that will be built.
- Template Parameters
-
| T | The type of the argument's value. |
◆ basic_parser_builder()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Initializes a new instance of the basic_parser_builder class.
- Parameters
-
| command_name | The name of the command that the arguments belong to. Often, this is the executable name of the application. |
◆ add_argument()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename T >
Adds a new argument, and returns an argument_builder that can be used to further customize it.
- Template Parameters
-
| T | The type of the argument. |
- Parameters
-
| value | A reference to the storage for the argument's value. When the argument is supplied, the converted value will be written to this reference. |
| name | The name of the argument, used to supply it on the command line. |
Any type T can be used as an argument type, as long as it meets the following criteria:
- It must be possible to convert a string to type T, either using stream extraction (
operator>>), or by a specialization of the lexical_convert template.
- It must be possible to convert type T to a string using
std::format (or libfmt if <format> is not available).
For custom argument types, you must provide either a stream extractor (operator>>) or specialize lexical_convert, and you must provide a specialization of std::formatter (fmt::formatter if libfmt is being used).
Providing an std::formatter is required so default values can be displayed in the usage help. A formatter must be provided even if you don't plan to set a default value, to prevent compiler errors (in that case, you could of course provide a non-functional, empty formatter).
Of the argument is of type std::optional<T>, the requirements apply to the contained type, not the std::optional<T> itself.
If type T is either bool or std::optional<bool>, the resulting argument will be a switch argument.
◆ add_multi_value_argument()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename T >
Adds a new multi-value argument, and returns an argument_builder that can be used to further customize it.
- Template Parameters
-
| T | The type of the argument's container. |
- Parameters
-
| value | A reference to the container for the argument's values. When the argument is supplied, the converted value will be added to this container. |
| name | The name of the argument, used to supply it on the command line. |
Any container type T can be used, provided it meets the following requirements.
- It defines a type T::value_type that meets the requirements outlined in the documentation for add_argument().
- It defines the methods T::push_back() and T::clear()
◆ allow_duplicate_arguments()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Sets a value that indicates whether arguments may be specified multiple times.
- Parameters
-
| allow | A value that indicates whether duplicate arguments are allowed. |
If set to true, it's an error to supply an argument whose value was already supplied previously. If false, no error occurs and the last value supplied will be used.
This setting has no effect on multi-value arguments, which can always be supplied multiple times.
The default value is false.
◆ allow_whitespace_separator()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Sets a value that indicates whether argument names and values can be separated by whitespace.
- Parameters
-
| allow | A value that indicates whether argument names and values can be separated by whitespace |
If set to true, argument can be specified like -Name value as well as -Name:value (or the custom separator set using argument_value_separator()). If set to false, only the latter will be accepted.
The default value is true.
◆ argument_value_separator()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Sets the character used to separate argument names and values.
- Parameters
-
| separator | The haracter used to separate argument names and values. |
Using this separator, arguments can be supplied like -Name:value (where : is the separator).
Setting the separator to a white-space character will only work if the name and the value are supplied as a single argument, usually by quoting them or by escaping the white-space character. Use allow_whitespace_separator() to control whether the name and the value can be supplied in separate arguments.
◆ build()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
◆ case_sensitive()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Sets a value that indicates whether argument names are case sensitive.
- Parameters
-
| case_sensitive | Indicates whether argument names are case sensitive. |
If set to true, argument names must be supplied on the command line using their exact case, and it's possible to have multiple arguments whose names only differ by case. If false, argument names don't need to match case when supplied (e.g. -foo will match an argument named "Foo").
The default value is false.
◆ description()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
◆ locale()
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Sets the locale to use when converting argument values and writing usage help.
- Parameters
-
The default value is a copy of the global locale when the basic_parser_builder was created.
◆ prefixes() [1/2]
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename Range >
Sets the argument name prefixes accepted by the basic_command_line_parser.
- Template Parameters
-
| Range | The type of a range containing the prefixes. |
- Parameters
-
| prefixes | A range containing the prefixes. |
Any value that starts with the specified prefixes is considered an argument name (with the exception of a dash followed by a number, which is always considered to be a negative number).
By default, the parser accepts '/' and '-' on Windows, and only '-' on other systems.
The prefixes are evaluated in order, so if for example you wish to use '–' and '-' you must provide the longer prefix first otherwise it will never be considered after the shorter one matches.
◆ prefixes() [2/2]
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename T >
Sets the argument name prefixes accepted by the basic_command_line_parser.
- Template Parameters
-
| T | The type of an element convertable to string_type. |
- Parameters
-
| prefixes | An initializer list containing the prefixes. |
Any value that starts with the specified prefixes is considered an argument name (with the exception of a dash followed by a number, which is always considered to be a negative number).
By default, the parser accepts '/' and '-' on Windows, and only '-' on other systems.
The prefixes are evaluated in order, so if for example you wish to use '–' and '-' you must provide the longer prefix first otherwise it will never be considered after the shorter one matches.
The documentation for this class was generated from the following file:
