|
| | basic_parser_builder (string_type command_name, const string_provider_type *string_provider=nullptr) |
| | Initializes a new instance of the basic_parser_builder class. More...
|
| |
| template<typename Action > |
| action_argument_builder< details::first_argument_type< Action > > & | add_action_argument (Action action, CharType short_name) |
| | Adds a new action argument. More...
|
| |
| template<typename Action > |
| action_argument_builder< details::first_argument_type< Action > > & | add_action_argument (Action action, string_type name) |
| | Adds a new action argument. More...
|
| |
| template<typename T > |
| argument_builder< T > & | add_argument (T &value, CharType short_name) |
| | Adds a new argument, and returns an argument_builder that can be used to further customize it. More...
|
| |
| template<typename T > |
| argument_builder< T > & | add_argument (T &value, string_type name) |
| | Adds a new argument, and returns an argument_builder that can be used to further customize it. More...
|
| |
| template<typename T > |
| multi_value_argument_builder< T > & | add_multi_value_argument (T &value, CharType short_name) |
| | Adds a new multi-value argument. More...
|
| |
| template<typename T > |
| multi_value_argument_builder< T > & | add_multi_value_argument (T &value, string_type name) |
| | Adds a new multi-value argument. More...
|
| |
| action_argument_builder< bool > & | add_version_argument (version_function function) |
| | Adds the standard version argument. More...
|
| |
| action_argument_builder< bool > & | add_win32_version_argument () |
| | Adds the standard version argument, using version information from the VERSIONINFO resource. More...
|
| |
| basic_parser_builder & | allow_duplicate_arguments (bool allow) noexcept |
| | Sets a value that indicates whether arguments may be specified multiple times. More...
|
| |
| basic_parser_builder & | allow_whitespace_separator (bool allow) noexcept |
| | Sets a value that indicates whether argument names and values can be separated by whitespace. More...
|
| |
| basic_parser_builder & | argument_value_separator (CharType separator) noexcept |
| | Sets the character used to separate argument names and values. More...
|
| |
| basic_parser_builder & | automatic_help_argument (bool enable) |
| | Set a value that indicates whether to create an automatic help argument. More...
|
| |
| parser_type | build () |
| | Creates a basic_command_line_parser using the current options and arguments. More...
|
| |
| basic_parser_builder & | case_sensitive (bool case_sensitive) noexcept |
| | Sets a value that indicates whether argument names are case sensitive. More...
|
| |
| basic_parser_builder & | description (string_type description) |
| | Sets a description for the application. More...
|
| |
| basic_parser_builder & | locale (std::locale loc) |
| | Sets the locale to use when converting argument values and writing usage help. More...
|
| |
| basic_parser_builder & | long_prefix (string_type prefix) |
| | Sets the long argument name prefix accepted by the basic_command_line_parser. More...
|
| |
| basic_parser_builder & | mode (parsing_mode mode) |
| | Sets the command line parsing rules to use. More...
|
| |
| template<typename Range > |
| basic_parser_builder & | prefixes (const Range &prefixes) |
| | Sets the argument name prefixes accepted by the basic_command_line_parser. More...
|
| |
| template<typename T > |
| basic_parser_builder & | prefixes (std::initializer_list< T > prefixes) |
| | Sets the argument name prefixes accepted by the basic_command_line_parser. More...
|
| |
| basic_parser_builder & | show_usage_on_error (usage_help_request request) |
| | Sets a value that indicates how usage is shown after a parsing error occurred. More...
|
| |
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>. |
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename Action >
Adds a new action argument.
When using long/short mode, this method adds an argument that only has a short name.
When not using long/short mode, this method is identical to add_argument(T&,string_type) with a single character name.
See add_action_argument(Action,string_type) for more information.
- Template Parameters
-
| Action | The type of a Callable object used for the action. |
- Parameters
-
| action | The action to invoke when the argument is supplied. |
| short_name | The short name of the argument. |
- Returns
- An action_argument_builder that can be used to further customize the argument.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
template<typename Action >
Adds a new action argument.
Action arguments are arguments that don't use a variable to store their value, but which invoke a function when supplied. This function must be a Callable object, such as a function pointer or lambda, which the following signature:
Parses command line arguments into strongly-typed values.
Definition: command_line_parser.h:106
Here, T is the the type of the argument, and the value will be converted to type T before the function is invoked. If T is a bool, the argument is a switch argument. Action arguments cannot be multi-value arguments. They also cannot use std::optional<T> or have a default value.
The function is invoked immediately as the argument is encountered, before the remainder of the command line is parsed. Return false from the function to cancel parsing, causing a parse_result with parse_error::parsing_cancelled to be returned.
- Template Parameters
-
| Action | The type of a Callable object used for the action. |
- Parameters
-
| action | The action to invoke when the argument is supplied. |
| name | The name of the argument. |
- Returns
- An action_argument_builder that can be used to further customize the 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.
When using long/short mode, this method adds an argument that only has a short name.
When not using long/short mode, this method is identical to add_argument(T&,string_type) with a single character name.
See add_argument(T&,string_type) for more information.
- 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. |
| short_name | The short name of the argument, used to supply it on the command line. |
- Returns
- An argument_builder that can be used to further customize the 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.
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.
- 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. |
- Returns
- An argument_builder that can be used to further customize the 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.
When using long/short mode, this method adds an argument that only has a short name.
When not using long/short mode, this method is identical to using add_multi_value_argument(T&,string_type) with a single character name.
See add_multi_value_argument(T&,string_type) for more information.
- 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. |
| short_name | The short name of the argument, used to supply it on the command line. |
- Returns
- A multi_value_argument_builder that can be used to further customize the argument.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Adds the standard version argument.
This method adds an argument with the default name "Version", which invokes the specified function when supplied. The argument cancels parsing, but does not show usage help.
The argument will be called "version" (with a lowercase 'v') if the first letter of the first manually defined argument is lowercase.
You can specify a different name, as well as a custom description, using the basic_localized_string_provider class.
- Parameters
-
| function | A function that displays version information. This will be called when the argument is supplied. |
- Returns
- An action_argument_builder that can be used to further customize the argument.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Adds the standard version argument, using version information from the VERSIONINFO resource.
- Warning
- This function is only available when compiling for Windows.
This method adds an argument with the default name "Version", which when supplied will read the VERSION_INFO resource of the current executable, and print the product name, version and optionally copyright information to the standard output. If these resources don't exist, the text "Unknown version" is shown.
The argument will be called "version" (with a lowercase 'v') if the first letter of the first manually defined argument is lowercase.
You can specify a different name, as well as a custom description, using the basic_localized_string_provider class.
- Returns
- An action_argument_builder that can be used to further customize the argument.
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. |
- Returns
- A reference to this basic_parser_builder.
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.
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 |
- Returns
- A reference to this basic_parser_builder.
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.
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. |
- Returns
- A reference to this basic_parser_builder.
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.
template<typename CharType = details::default_char_type, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
Set a value that indicates whether to create an automatic help argument.
- Parameters
-
| enable | true to create an automatic help argument, otherwise; false. |
- Returns
- A reference to this basic_parser_builder.
If set to true, an argument will be added with the name "-Help" and the aliases "-?" and "-h". If the mode() was set to parsing_mode::long_short, it will have the long name "--Help", the short name "-?" and the short alias "-h".
The argument will be called "help" (with a lowercase 'h') if the first letter of the first argument in usage order is lowercase.
You can specify a different name, as well as a custom description, using the basic_localized_string_provider class.
If any explicitly defined argument conflicts with the name or aliases of the automatic help argument, no argument will be added. Therefore, it's only necessary to set this to false if you do not want a help argument at all.
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. |
- Returns
- A reference to this basic_parser_builder.
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.
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. |
- Returns
- A reference to this basic_parser_builder.
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.
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. |
- Returns
- A reference to this basic_parser_builder.
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).
When using parsing_mode::long_short, this defines the short argument name prefixes.
By default, the parser accepts '-' and '/' on Windows, and only '-' on other systems.
