Main argument parser class. More...

#include <argument_parser.hpp>

Public Member Functions
	argument_parser (const argument_parser &)=delete

argument_parser &	operator= (const argument_parser &)=delete

	argument_parser ()=default

	argument_parser (argument_parser &&)=default

argument_parser &	operator= (argument_parser &&)=default

	~argument_parser ()=default

argument_parser &	program_name (std::string_view name) noexcept
	Set the program name.

argument_parser &	program_version (const version &version) noexcept
	Set the program version.

argument_parser &	program_version (std::string_view version) noexcept
	Set the program version.

argument_parser &	program_description (std::string_view description) noexcept
	Set the program description.

argument_parser &	verbose (const bool v=true) noexcept
	Set the verbosity mode.

template<detail::c_range_of< argument::default_positional > AR>
argument_parser &	default_positional_arguments (const AR &arg_discriminator_range) noexcept
	Set default positional arguments.

argument_parser &	default_positional_arguments (const std::initializer_list< argument::default_positional > arg_discriminator_list) noexcept
	Set default positional arguments.

template<detail::c_range_of< argument::default_optional > AR>
argument_parser &	default_optional_arguments (const AR &arg_discriminator_range) noexcept
	Set default optional arguments.

argument_parser &	default_optional_arguments (const std::initializer_list< argument::default_optional > arg_discriminator_list) noexcept
	Set default optional arguments.

template<detail::c_argument_value_type T = std::string>
argument::positional< T > &	add_positional_argument (const std::string_view primary_name)
	Adds a positional argument to the parser's configuration.

template<detail::c_argument_value_type T = std::string>
argument::positional< T > &	add_positional_argument (const std::string_view primary_name, const std::string_view secondary_name)
	Adds a positional argument to the parser's configuration.

template<detail::c_argument_value_type T = std::string>
argument::optional< T > &	add_optional_argument (const std::string_view name, const detail::argument_name_discriminator name_discr=n_primary)
	Adds a positional argument to the parser's configuration.

template<detail::c_argument_value_type T = std::string>
argument::optional< T > &	add_optional_argument (const std::string_view primary_name, const std::string_view secondary_name)
	Adds a positional argument to the parser's configuration.

template<bool StoreImplicitly = true>
argument::optional< bool > &	add_flag (const std::string_view name, const detail::argument_name_discriminator name_discr=n_primary)
	Adds a boolean flag argument (an optional argument with `value_type = bool`) to the parser's configuration.

template<bool StoreImplicitly = true>
argument::optional< bool > &	add_flag (const std::string_view primary_name, const std::string_view secondary_name)
	Adds a boolean flag argument (an optional argument with `value_type = bool`) to the parser's configuration.

void	parse_args (int argc, char *argv[])
	Parses the command-line arguments.

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>
void	parse_args (const AR &argv_rng)
	Parses the command-line arguments.

void	try_parse_args (int argc, char *argv[])
	Parses the command-line arguments and exits on error.

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>
void	try_parse_args (const AR &argv_rng)
	Parses the command-line arguments and exits on error.

std::vector< std::string >	parse_known_args (int argc, char *argv[])
	Parses the known command-line arguments.

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>
std::vector< std::string >	parse_known_args (const AR &argv_rng)
	Parses the known command-line arguments.

std::vector< std::string >	try_parse_known_args (int argc, char *argv[])
	Parses the known command-line arguments and exits on error.

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>
std::vector< std::string >	try_parse_known_args (const AR &argv_rng)
	Parses known the command-line arguments and exits on error.

void	handle_help_action () const noexcept
	Handles the `help` argument logic.

bool	has_value (std::string_view arg_name) const noexcept

std::size_t	count (std::string_view arg_name) const noexcept

template<detail::c_argument_value_type T = std::string>
T	value (std::string_view arg_name) const

template<detail::c_argument_value_type T = std::string, std::convertible_to< T > U>
T	value_or (std::string_view arg_name, U &&fallback_value) const

template<detail::c_argument_value_type T = std::string>
std::vector< T >	values (std::string_view arg_name) const

void	print_config (const bool verbose, std::ostream &os=std::cout) const noexcept
	Prints the argument parser's details to an output stream.

Private Types
using	arg_ptr_t = std::unique_ptr< detail::argument_base >

using	arg_ptr_list_t = std::vector< arg_ptr_t >

using	arg_ptr_list_iter_t = typename arg_ptr_list_t::iterator

using	arg_ptr_opt_t = detail::uptr_opt_t< detail::argument_base >

using	arg_opt_t = std::optional< std::reference_wrapper< detail::argument_base > >

using	const_arg_opt_t = std::optional< std::reference_wrapper< const detail::argument_base > >

using	arg_token_list_t = std::vector< detail::argument_token >

using	arg_token_list_iterator_t = typename arg_token_list_t::const_iterator

Private Member Functions
void	_verify_arg_name_pattern (const std::string_view arg_name) const
	Verifies the pattern of an argument name and if it's invalid, an error is thrown.

auto	_name_match_predicate (const std::string_view arg_name, const detail::argument_name::match_type m_type=detail::argument_name::m_any) const noexcept
	Returns a unary predicate function which checks if the given name matches the argument's name.

auto	_name_match_predicate (const detail::argument_name &arg_name, const detail::argument_name::match_type m_type=detail::argument_name::m_any) const noexcept
	Returns a unary predicate function which checks if the given name matches the argument's name.

bool	_is_arg_name_used (const detail::argument_name &arg_name, const detail::argument_name::match_type m_type=detail::argument_name::m_any) const noexcept
	Check if an argument name is already used.

void	_validate_argument_configuration () const
	Validate whether the definition/configuration of the parser's arguments is correct.

template<detail::c_sized_range_of< std::string_view, detail::type_validator::convertible > AR>
arg_token_list_t	_tokenize (const AR &arg_range)
	Converts the command-line arguments into a list of tokens.

void	_tokenize_arg (arg_token_list_t &toks, const std::string_view arg_value)
	Appends an argument token(s) created from `arg_value` to the `toks` vector.

detail::argument_token	_build_token (const std::string_view arg_value) const noexcept
	Builds an argument token from the given value.

bool	_validate_flag_token (detail::argument_token &tok) noexcept
	Check if a flag token is valid based on its value.

std::vector< detail::argument_token >	_try_split_compound_flag (const detail::argument_token &tok) noexcept
	Tries to split a secondary flag token into separate flag token (one for each character of the token's value).

std::string	_unstripped_token_value (const detail::argument_token &tok) const noexcept
	Get the unstripped token value (including the flag prefix).

void	_parse_args_impl (const arg_token_list_t &arg_tokens, std::vector< std::string > &unknown_args, const bool handle_unknown=true)
	Implementation of parsing command-line arguments.

void	_parse_positional_args (arg_token_list_iterator_t &token_it, const arg_token_list_iterator_t &tokens_end) noexcept
	Parse positional arguments based on command-line input.

void	_parse_optional_args (arg_token_list_iterator_t &token_it, const arg_token_list_iterator_t &tokens_end, std::vector< std::string > &unknown_args, const bool handle_unknown=true)
	Parse optional arguments based on command-line input.

bool	_are_required_args_bypassed () const noexcept
	Check whether required argument bypassing is enabled.

void	_verify_required_args () const
	Check if all required positional and optional arguments are used.

void	_verify_nvalues () const
	Check if the number of argument values is within the specified range.

arg_opt_t	_get_argument (std::string_view arg_name) const noexcept
	Get the argument with the specified name.

arg_ptr_list_iter_t	_find_opt_arg (const detail::argument_token &flag_tok) noexcept
	Find an optional argument based on a flag token.

void	_print (std::ostream &os, const arg_ptr_list_t &args, const bool verbose) const noexcept
	Print the given argument list to an output stream.

Private Attributes
std::optional< std::string >	_program_name

std::optional< std::string >	_program_version

std::optional< std::string >	_program_description

bool	_verbose = false

arg_ptr_list_t	_positional_args

arg_ptr_list_t	_optional_args

Static Private Attributes
static constexpr uint8_t	_primary_flag_prefix_length = 2u

static constexpr uint8_t	_secondary_flag_prefix_length = 1u

static constexpr char	_flag_prefix_char = '-'

static constexpr std::string_view	_flag_prefix = "--"

static constexpr uint8_t	_indent_width = 2

Friends
std::ostream &	operator<< (std::ostream &os, const argument_parser &parser) noexcept
	Prints the argument parser's details to an output stream.

Detailed Description

Main argument parser class.

Definition at line 45 of file argument_parser.hpp.

Member Typedef Documentation

◆ arg_opt_t

using ap::argument_parser::arg_opt_t = std::optional<std::reference_wrapper<detail::argument_base> >

private

Definition at line 641 of file argument_parser.hpp.

◆ arg_ptr_list_iter_t

using ap::argument_parser::arg_ptr_list_iter_t = typename arg_ptr_list_t::iterator

private

Definition at line 639 of file argument_parser.hpp.

◆ arg_ptr_list_t

using ap::argument_parser::arg_ptr_list_t = std::vector<arg_ptr_t>

private

Definition at line 638 of file argument_parser.hpp.

◆ arg_ptr_opt_t

using ap::argument_parser::arg_ptr_opt_t = detail::uptr_opt_t<detail::argument_base>

private

Definition at line 640 of file argument_parser.hpp.

◆ arg_ptr_t

using ap::argument_parser::arg_ptr_t = std::unique_ptr<detail::argument_base>

private

Definition at line 637 of file argument_parser.hpp.

◆ arg_token_list_iterator_t

using ap::argument_parser::arg_token_list_iterator_t = typename arg_token_list_t::const_iterator

private

Definition at line 645 of file argument_parser.hpp.

◆ arg_token_list_t

using ap::argument_parser::arg_token_list_t = std::vector<detail::argument_token>

private

Definition at line 644 of file argument_parser.hpp.

◆ const_arg_opt_t

using ap::argument_parser::const_arg_opt_t = std::optional<std::reference_wrapper<const detail::argument_base> >

private

Definition at line 642 of file argument_parser.hpp.

Constructor & Destructor Documentation

◆ argument_parser() [1/3]

ap::argument_parser::argument_parser ( const argument_parser & )

delete

◆ argument_parser() [2/3]

ap::argument_parser::argument_parser ( )

default

◆ argument_parser() [3/3]

ap::argument_parser::argument_parser ( argument_parser && )

default

◆ ~argument_parser()

ap::argument_parser::~argument_parser ( )

default

Member Function Documentation

◆ _are_required_args_bypassed()

bool ap::argument_parser::_are_required_args_bypassed ( ) const

inlineprivatenoexcept

Check whether required argument bypassing is enabled.

Returns: true if at least one argument with enabled required argument bypassing is used, false otherwise.

Definition at line 985 of file argument_parser.hpp.

◆ _build_token()

detail::argument_token ap::argument_parser::_build_token ( const std::string_view arg_value ) const

inlineprivatenoexcept

Builds an argument token from the given value.

Parameters

arg_value The command-line argument's value to be processed.

Returns: An argument token with removed flag prefix (if present) and an adequate token type.

Definition at line 800 of file argument_parser.hpp.

◆ _find_opt_arg()

arg_ptr_list_iter_t ap::argument_parser::_find_opt_arg ( const detail::argument_token & flag_tok )

inlineprivatenoexcept

Find an optional argument based on a flag token.

Parameters

flag_tok An argument_token instance, the value of which will be used to find the argument.

Returns: An iterator to the argument's position.

Note: If the flag_tok.type is not a valid flag token, then the end iterator will be returned.

Definition at line 1055 of file argument_parser.hpp.

◆ _get_argument()

arg_opt_t ap::argument_parser::_get_argument ( std::string_view arg_name ) const

inlineprivatenoexcept

Get the argument with the specified name.

Parameters

arg_name The name of the argument.

Returns: The argument with the specified name, if found; otherwise, std::nullopt.

Definition at line 1033 of file argument_parser.hpp.

◆ _is_arg_name_used()

bool ap::argument_parser::_is_arg_name_used	(	const detail::argument_name &	arg_name,
		const detail::argument_name::match_type	m_type = `detail::argument_name::m_any`
	)		const

inlineprivatenoexcept

Check if an argument name is already used.

Parameters

arg_name	The name of the argument.
m_type	The match type used to find the argument.

Returns: True if the argument name is already used, false otherwise.

Definition at line 711 of file argument_parser.hpp.

◆ _name_match_predicate() [1/2]

auto ap::argument_parser::_name_match_predicate	(	const detail::argument_name &	arg_name,
		const detail::argument_name::match_type	m_type = `detail::argument_name::m_any`
	)		const

inlineprivatenoexcept

Returns a unary predicate function which checks if the given name matches the argument's name.

Parameters

arg_name	The name of the argument.
m_type	The match type used within the predicate.

Returns: Argument predicate based on the provided name.

Definition at line 696 of file argument_parser.hpp.

◆ _name_match_predicate() [2/2]

auto ap::argument_parser::_name_match_predicate	(	const std::string_view	arg_name,
		const detail::argument_name::match_type	m_type = `detail::argument_name::m_any`
	)		const

inlineprivatenoexcept

Returns a unary predicate function which checks if the given name matches the argument's name.

Parameters

arg_name	The name of the argument.
m_type	The match type used within the predicate.

Returns: Argument predicate based on the provided name.

Definition at line 683 of file argument_parser.hpp.

◆ _parse_args_impl()

void ap::argument_parser::_parse_args_impl	(	const arg_token_list_t &	arg_tokens,
		std::vector< std::string > &	unknown_args,
		const bool	handle_unknown = `true`
	)

inlineprivate

Implementation of parsing command-line arguments.

Parameters

arg_tokens The list of command-line argument tokens.

Exceptions

ap::parsing_failure

Todo:: Use c_range_of<argument_token> instead of arg_token_list_t directly.

Definition at line 894 of file argument_parser.hpp.

◆ _parse_optional_args()

void ap::argument_parser::_parse_optional_args	(	arg_token_list_iterator_t &	token_it,
		const arg_token_list_iterator_t &	tokens_end,
		std::vector< std::string > &	unknown_args,
		const bool	handle_unknown = `true`
	)

inlineprivate

Parse optional arguments based on command-line input.

Parameters

token_it	Iterator for iterating through command-line argument tokens.
tokens_end	The token list end iterator.
unknown_args	Reference to the vector into which the dangling values shall be collected.

Exceptions

ap::parsing_failure

Definition at line 931 of file argument_parser.hpp.

◆ _parse_positional_args()

void ap::argument_parser::_parse_positional_args	(	arg_token_list_iterator_t &	token_it,
		const arg_token_list_iterator_t &	tokens_end
	)

inlineprivatenoexcept

Parse positional arguments based on command-line input.

Parameters

token_it	Iterator for iterating through command-line argument tokens.
tokens_end	The token list end iterator.

Definition at line 909 of file argument_parser.hpp.

◆ _print()

void ap::argument_parser::_print	(	std::ostream &	os,
		const arg_ptr_list_t &	args,
		const bool	verbose
	)		const

inlineprivatenoexcept

Print the given argument list to an output stream.

Parameters

os	The output stream to print to.
args	The argument list to print.

Definition at line 1076 of file argument_parser.hpp.

◆ _tokenize()

template<detail::c_sized_range_of< std::string_view, detail::type_validator::convertible > AR>

arg_token_list_t ap::argument_parser::_tokenize ( const AR & arg_range )

inlineprivate

Converts the command-line arguments into a list of tokens.

Template Parameters

AR	The command-line argument value range type.

Parameters

arg_range The command-line argument value range.

Returns: A list of preprocessed command-line argument tokens.

Definition at line 755 of file argument_parser.hpp.

◆ _tokenize_arg()

void ap::argument_parser::_tokenize_arg	(	arg_token_list_t &	toks,
		const std::string_view	arg_value
	)

inlineprivate

Appends an argument token(s) created from arg_value to the toks vector.

Parameters

toks	The argument token list to which the processed token(s) will be appended.
arg_value	The command-line argument's value to be processed.

Definition at line 773 of file argument_parser.hpp.

◆ _try_split_compound_flag()

std::vector< detail::argument_token > ap::argument_parser::_try_split_compound_flag ( const detail::argument_token & tok )

inlineprivatenoexcept

Tries to split a secondary flag token into separate flag token (one for each character of the token's value).

Parameters

tok	The token to be processed.

Returns: A vector of new argument tokens.

Note: If ANY of the characters in the token's value does not match an argument, an empty vector will be returned.

Definition at line 841 of file argument_parser.hpp.

◆ _unstripped_token_value()

std::string ap::argument_parser::_unstripped_token_value ( const detail::argument_token & tok ) const

inlineprivatenoexcept

Get the unstripped token value (including the flag prefix).

Given an argument token, this function reconstructs and returns the original argument string, including any flag prefix that may have been stripped during tokenization.

Parameters

tok	An argument token, the value of which will be processed.

Returns

The reconstructed argument value:

If the token type is t_flag_primary, returns the value prefixed with "--".
If the token type is t_flag_secondary, returns the value prefixed with "-".
For all other token types, returns the token's value as is (without any prefix).

Definition at line 876 of file argument_parser.hpp.

◆ _validate_argument_configuration()

void ap::argument_parser::_validate_argument_configuration ( ) const

inlineprivate

Validate whether the definition/configuration of the parser's arguments is correct.

What is verified:

No required positional argument can be added after a non-required positional argument.

Definition at line 732 of file argument_parser.hpp.

◆ _validate_flag_token()

bool ap::argument_parser::_validate_flag_token ( detail::argument_token & tok )

inlineprivatenoexcept

Check if a flag token is valid based on its value.

Attention: Sets the arg member of the token if an argument with the given name (token's value) is present.

Parameters

tok	The argument token to validate.

Returns: true if the given token represents a valid argument flag.

Definition at line 826 of file argument_parser.hpp.

◆ _verify_arg_name_pattern()

void ap::argument_parser::_verify_arg_name_pattern ( const std::string_view arg_name ) const

inlineprivate

Verifies the pattern of an argument name and if it's invalid, an error is thrown.

Exceptions

ap::invalid_configuration

Definition at line 651 of file argument_parser.hpp.

◆ _verify_nvalues()

void ap::argument_parser::_verify_nvalues ( ) const

inlineprivate

Check if the number of argument values is within the specified range.

Exceptions

ap::parsing_failure

Definition at line 1017 of file argument_parser.hpp.

◆ _verify_required_args()

void ap::argument_parser::_verify_required_args ( ) const

inlineprivate

Check if all required positional and optional arguments are used.

Exceptions

ap::parsing_failure

Definition at line 1002 of file argument_parser.hpp.

◆ add_flag() [1/2]

template<bool StoreImplicitly = true>

argument::optional< bool > & ap::argument_parser::add_flag	(	const std::string_view	name,
		const detail::argument_name_discriminator	name_discr = `n_primary`
	)

inline

Adds a boolean flag argument (an optional argument with value_type = bool) to the parser's configuration.

Template Parameters

StoreImplicitly A boolean value used as the implicit_value parameter of the argument.

Parameters

name	The primary name of the flag.
name_discr	The discriminator value specifying whether the given name should be treated as primary or secondary.

Returns: Reference to the added boolean flag argument.

Definition at line 274 of file argument_parser.hpp.

◆ add_flag() [2/2]

template<bool StoreImplicitly = true>

argument::optional< bool > & ap::argument_parser::add_flag	(	const std::string_view	primary_name,
		const std::string_view	secondary_name
	)

inline

Adds a boolean flag argument (an optional argument with value_type = bool) to the parser's configuration.

Template Parameters

StoreImplicitly A boolean value used as the implicit_value parameter of the argument.

Parameters

primary_name	The primary name of the flag.
secondary_name	The secondary name of the flag.

Returns: Reference to the added boolean flag argument.

Definition at line 292 of file argument_parser.hpp.

◆ add_optional_argument() [1/2]

template<detail::c_argument_value_type T = std::string>

argument::optional< T > & ap::argument_parser::add_optional_argument	(	const std::string_view	name,
		const detail::argument_name_discriminator	name_discr = `n_primary`
	)

inline

Adds a positional argument to the parser's configuration.

Template Parameters

T	Type of the argument value.

Parameters

name	The name of the argument.
name_discr	The discriminator value specifying whether the given name should be treated as primary or secondary.

Returns: Reference to the added optional argument.

Exceptions

ap::invalid_configuration

Todo:: Check forbidden characters (after adding the assignment character).

Definition at line 216 of file argument_parser.hpp.

◆ add_optional_argument() [2/2]

template<detail::c_argument_value_type T = std::string>

argument::optional< T > & ap::argument_parser::add_optional_argument	(	const std::string_view	primary_name,
		const std::string_view	secondary_name
	)

inline

Adds a positional argument to the parser's configuration.

Template Parameters

T	Type of the argument value.

Parameters

primary_name	The primary name of the argument.
secondary_name	The secondary name of the argument.

Returns: Reference to the added optional argument.

Exceptions

ap::invalid_configuration

Todo:: Check forbidden characters (after adding the assignment character).

Definition at line 248 of file argument_parser.hpp.

◆ add_positional_argument() [1/2]

template<detail::c_argument_value_type T = std::string>

argument::positional< T > & ap::argument_parser::add_positional_argument ( const std::string_view primary_name )

inline

Adds a positional argument to the parser's configuration.

Template Parameters

T	Type of the argument value.

Parameters

primary_name The primary name of the argument.

Returns: Reference to the added positional argument.

Exceptions

ap::invalid_configuration

Todo:: Check forbidden characters (after adding the assignment character).

Definition at line 166 of file argument_parser.hpp.

◆ add_positional_argument() [2/2]

template<detail::c_argument_value_type T = std::string>

argument::positional< T > & ap::argument_parser::add_positional_argument	(	const std::string_view	primary_name,
		const std::string_view	secondary_name
	)

inline

Adds a positional argument to the parser's configuration.

Template Parameters

T	Type of the argument value.

Parameters

primary_name	The primary name of the argument.
secondary_name	The secondary name of the argument.

Returns: Reference to the added positional argument.

Exceptions

ap::invalid_configuration

Todo:: Check forbidden characters (after adding the assignment character).

Definition at line 188 of file argument_parser.hpp.

◆ count()

std::size_t ap::argument_parser::count ( std::string_view arg_name ) const

inlinenoexcept

Parameters

arg_name The name of the argument.

Returns: The count of times the argument has been used.

Definition at line 500 of file argument_parser.hpp.

◆ default_optional_arguments() [1/2]

template<detail::c_range_of< argument::default_optional > AR>

argument_parser & ap::argument_parser::default_optional_arguments ( const AR & arg_discriminator_range )

inlinenoexcept

Set default optional arguments.

Template Parameters

AR	Type of the optional argument discriminator range.

Parameters

arg_discriminator_range A range of default optional argument discriminators.

Returns: Reference to the argument parser.

Definition at line 139 of file argument_parser.hpp.

◆ default_optional_arguments() [2/2]

argument_parser & ap::argument_parser::default_optional_arguments ( const std::initializer_list< argument::default_optional > arg_discriminator_list )

inlinenoexcept

Set default optional arguments.

Parameters

arg_discriminator_list A list of default optional argument discriminators.

Returns: Reference to the argument parser.

Definition at line 150 of file argument_parser.hpp.

◆ default_positional_arguments() [1/2]

template<detail::c_range_of< argument::default_positional > AR>

argument_parser & ap::argument_parser::default_positional_arguments ( const AR & arg_discriminator_range )

inlinenoexcept

Set default positional arguments.

Template Parameters

AR	Type of the positional argument discriminator range.

Parameters

arg_discriminator_range A range of default positional argument discriminators.

Returns: Reference to the argument parser.

Definition at line 115 of file argument_parser.hpp.

◆ default_positional_arguments() [2/2]

argument_parser & ap::argument_parser::default_positional_arguments ( const std::initializer_list< argument::default_positional > arg_discriminator_list )

inlinenoexcept

Set default positional arguments.

Parameters

arg_discriminator_list A list of default positional argument discriminators.

Returns: Reference to the argument parser.

Definition at line 126 of file argument_parser.hpp.

◆ handle_help_action()

void ap::argument_parser::handle_help_action ( ) const

inlinenoexcept

Handles the help argument logic.

Checks the value of the help boolean flag argument and if the value is true, prints the parser to std::cout anb exists with EXIT_SUCCESS status.

Definition at line 478 of file argument_parser.hpp.

◆ has_value()

bool ap::argument_parser::has_value ( std::string_view arg_name ) const

inlinenoexcept

Parameters

arg_name The name of the argument.

Returns: True if the argument has a value, false otherwise.

Definition at line 491 of file argument_parser.hpp.

◆ operator=() [1/2]

argument_parser & ap::argument_parser::operator= ( argument_parser && )

default

◆ operator=() [2/2]

argument_parser & ap::argument_parser::operator= ( const argument_parser & )

delete

◆ parse_args() [1/2]

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>

void ap::argument_parser::parse_args ( const AR & argv_rng )

inline

Parses the command-line arguments.

Template Parameters

AR	The argument range type.

Parameters

argv_rng A range of command-line argument values.

Exceptions

ap::invalid_configuration,ap::parsing_failure

Attention: This overload of the parse_args function assumes that the program name argument has already been discarded.

Definition at line 326 of file argument_parser.hpp.

◆ parse_args() [2/2]

void ap::argument_parser::parse_args	(	int	argc,
		char *	argv[]
	)

inline

Parses the command-line arguments.

Equivalent to:
parse_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)))

ap::argument_parser::parse_args
void parse_args(int argc, char *argv[])
Parses the command-line arguments.
Definition argument_parser.hpp:314

Parameters

argc	Number of command-line arguments.
argv	Array of command-line argument values.

Exceptions

ap::invalid_configuration,ap::parsing_failure

Attention: The first argument (the program name) is ignored.

Definition at line 314 of file argument_parser.hpp.

◆ parse_known_args() [1/2]

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>

std::vector< std::string > ap::argument_parser::parse_known_args ( const AR & argv_rng )

inline

Parses the known command-line arguments.

An argument is considered "known" if it was defined using the parser's argument declaraion methods:
add_positional_argument
add_optional_argument
add_flag

Template Parameters

AR	The argument range type.

Parameters

argv_rng A range of command-line argument values.

Exceptions

ap::invalid_configuration,ap::parsing_failure

Attention: This overload of the parse_known_args function assumes that the program name argument already been discarded.

Definition at line 415 of file argument_parser.hpp.

◆ parse_known_args() [2/2]

std::vector< std::string > ap::argument_parser::parse_known_args	(	int	argc,
		char *	argv[]
	)

inline

Parses the known command-line arguments.

Equivalent to:

try_parse_known_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)))

ap::argument_parser::try_parse_known_args

std::vector< std::string > try_parse_known_args(int argc, char *argv[])

Parses the known command-line arguments and exits on error.

Definition argument_parser.hpp:442

An argument is considered "known" if it was defined using the parser's argument declaraion methods:

add_positional_argument
add_optional_argument
add_flag

Parameters

argc	Number of command-line arguments.
argv	Array of command-line argument values.

Exceptions

ap::invalid_configuration,ap::parsing_failure

Attention: The first argument (the program name) is ignored.

Definition at line 397 of file argument_parser.hpp.

◆ print_config()

void ap::argument_parser::print_config	(	const bool	verbose,
		std::ostream &	os = `std::cout`
	)		const

inlinenoexcept

Prints the argument parser's details to an output stream.

Parameters

verbose	The verbosity mode value.
os	Output stream.

Definition at line 592 of file argument_parser.hpp.

◆ program_description()

argument_parser & ap::argument_parser::program_description ( std::string_view description )

inlinenoexcept

Set the program description.

Parameters

description The description of the program.

Returns: Reference to the argument parser.

Definition at line 92 of file argument_parser.hpp.

◆ program_name()

argument_parser & ap::argument_parser::program_name ( std::string_view name )

inlinenoexcept

Set the program name.

Parameters

name	The name of the program.

Returns: Reference to the argument parser.

Definition at line 62 of file argument_parser.hpp.

◆ program_version() [1/2]

argument_parser & ap::argument_parser::program_version ( const version & version )

inlinenoexcept

Set the program version.

Parameters

version The version of the program.

Returns: Reference to the argument parser.

Definition at line 72 of file argument_parser.hpp.

◆ program_version() [2/2]

argument_parser & ap::argument_parser::program_version ( std::string_view version )

inlinenoexcept

Set the program version.

Parameters

version The version of the program.

Returns: Reference to the argument parser.

Definition at line 82 of file argument_parser.hpp.

◆ try_parse_args() [1/2]

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>

void ap::argument_parser::try_parse_args ( const AR & argv_rng )

inline

Parses the command-line arguments and exits on error.

Calls parse_args(argv_rng) in a try-catch block. If an error is thrown, then its message and the parser are printed to std::cerr and the function exists with EXIT_FAILURE status.

Template Parameters

AR	The argument range type.

Parameters

argv_rng A range of command-line argument values.

Attention: This overload of the try_parse_args function assumes that the program name argument has already been discarded.

Definition at line 369 of file argument_parser.hpp.

◆ try_parse_args() [2/2]

void ap::argument_parser::try_parse_args	(	int	argc,
		char *	argv[]
	)

inline

Parses the command-line arguments and exits on error.

Equivalent to:

try_parse_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)))

ap::argument_parser::try_parse_args

void try_parse_args(int argc, char *argv[])

Parses the command-line arguments and exits on error.

Definition argument_parser.hpp:353

Parameters

argc	Number of command-line arguments.
argv	Array of command-line argument values.

Note: The first argument (the program name) is ignored.

Definition at line 353 of file argument_parser.hpp.

◆ try_parse_known_args() [1/2]

template<detail::c_range_of< std::string, detail::type_validator::convertible > AR>

std::vector< std::string > ap::argument_parser::try_parse_known_args ( const AR & argv_rng )

inline

Parses known the command-line arguments and exits on error.

Calls parse_known_args(argv_rng) in a try-catch block. If an error is thrown, then its message and the parser are printed to std::cerr and the function exists with EXIT_FAILURE status. Otherwise the result of parse_known_args(argv_rng) is returned.

Template Parameters

AR	The argument range type.

Parameters

argv_rng A range of command-line argument values.

Returns: A vector of unknown argument values.

Attention: This overload of the try_parse_known_args function assumes that the program name argument has already been discarded.

Definition at line 459 of file argument_parser.hpp.

◆ try_parse_known_args() [2/2]

std::vector< std::string > ap::argument_parser::try_parse_known_args	(	int	argc,
		char *	argv[]
	)

inline

Parses the known command-line arguments and exits on error.

Equivalent to:

try_parse_known_args(std::span(argv + 1, static_cast<std::size_t>(argc - 1)))

Parameters

argc	Number of command-line arguments.
argv	Array of command-line argument values.

Returns: A vector of unknown argument values.

Attention: The first argument (the program name) is ignored.

Definition at line 442 of file argument_parser.hpp.

◆ value()

template<detail::c_argument_value_type T = std::string>

T ap::argument_parser::value ( std::string_view arg_name ) const

inline

Template Parameters

T	Type of the argument value.

Parameters

arg_name The name of the argument.

Returns: The value of the argument.

Exceptions

ap::lookup_failure,ap::type_error

Definition at line 512 of file argument_parser.hpp.

◆ value_or()

template<detail::c_argument_value_type T = std::string, std::convertible_to< T > U>

T ap::argument_parser::value_or	(	std::string_view	arg_name,
		U &&	fallback_value
	)		const

inline

Template Parameters

T	Type of the argument value.
U	The default value type.

Parameters

arg_name	The name of the argument.
fallback_value	The fallback value.

Returns: The value of the argument.

Exceptions

ap::lookup_failure,ap::type_error

Definition at line 535 of file argument_parser.hpp.

◆ values()

template<detail::c_argument_value_type T = std::string>

std::vector< T > ap::argument_parser::values ( std::string_view arg_name ) const

inline

Template Parameters

T	Type of the argument values.

Parameters

arg_name The name of the argument.

Returns: The values of the argument as a vector.

Exceptions

ap::lookup_failure,ap::type_error

Definition at line 561 of file argument_parser.hpp.

◆ verbose()

argument_parser & ap::argument_parser::verbose ( const bool v = true )

inlinenoexcept

Set the verbosity mode.

Note: The default verbosity mode value is false.

Parameters

v	The verbosity mode value.

Returns: Reference to the argument parser.

Definition at line 103 of file argument_parser.hpp.

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const argument_parser &	parser
	)

friend

Prints the argument parser's details to an output stream.

An os << parser operation is equivalent to a parser.print_config(_verbose, os) call, where _verbose is the inner verbosity mode, which can be set with the verbose function.

Parameters

os	Output stream.
parser	The argument parser to print.

Returns: The modified output stream.

Definition at line 626 of file argument_parser.hpp.

Member Data Documentation

◆ _flag_prefix

constexpr std::string_view ap::argument_parser::_flag_prefix = "--"

staticconstexprprivate

Definition at line 1113 of file argument_parser.hpp.

◆ _flag_prefix_char

constexpr char ap::argument_parser::_flag_prefix_char = '-'

staticconstexprprivate

Definition at line 1112 of file argument_parser.hpp.

◆ _indent_width

constexpr uint8_t ap::argument_parser::_indent_width = 2

staticconstexprprivate

Definition at line 1114 of file argument_parser.hpp.

◆ _optional_args

arg_ptr_list_t ap::argument_parser::_optional_args

private

Definition at line 1108 of file argument_parser.hpp.

◆ _positional_args

arg_ptr_list_t ap::argument_parser::_positional_args

private

Definition at line 1107 of file argument_parser.hpp.

◆ _primary_flag_prefix_length

constexpr uint8_t ap::argument_parser::_primary_flag_prefix_length = 2u

staticconstexprprivate

Definition at line 1110 of file argument_parser.hpp.

◆ _program_description

std::optional<std::string> ap::argument_parser::_program_description

private

Definition at line 1104 of file argument_parser.hpp.

◆ _program_name

std::optional<std::string> ap::argument_parser::_program_name

private

Definition at line 1102 of file argument_parser.hpp.

◆ _program_version

std::optional<std::string> ap::argument_parser::_program_version

private

Definition at line 1103 of file argument_parser.hpp.

◆ _secondary_flag_prefix_length

constexpr uint8_t ap::argument_parser::_secondary_flag_prefix_length = 1u

staticconstexprprivate

Definition at line 1111 of file argument_parser.hpp.

◆ _verbose

bool ap::argument_parser::_verbose = false

private

Definition at line 1105 of file argument_parser.hpp.

The documentation for this class was generated from the following file:

include/ap/argument_parser.hpp

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ arg_opt_t

◆ arg_ptr_list_iter_t

◆ arg_ptr_list_t

◆ arg_ptr_opt_t

◆ arg_ptr_t

◆ arg_token_list_iterator_t

◆ arg_token_list_t

◆ const_arg_opt_t

Constructor & Destructor Documentation

◆ argument_parser() [1/3]

◆ argument_parser() [2/3]

◆ argument_parser() [3/3]

◆ ~argument_parser()

Member Function Documentation

◆ _are_required_args_bypassed()

◆ _build_token()

◆ _find_opt_arg()

◆ _get_argument()

◆ _is_arg_name_used()

◆ _name_match_predicate() [1/2]

◆ _name_match_predicate() [2/2]

◆ _parse_args_impl()

◆ _parse_optional_args()

◆ _parse_positional_args()

◆ _print()

◆ _tokenize()

◆ _tokenize_arg()

◆ _try_split_compound_flag()

◆ _unstripped_token_value()

◆ _validate_argument_configuration()

◆ _validate_flag_token()

◆ _verify_arg_name_pattern()

◆ _verify_nvalues()

◆ _verify_required_args()

◆ add_flag() [1/2]

◆ add_flag() [2/2]

◆ add_optional_argument() [1/2]

◆ add_optional_argument() [2/2]

◆ add_positional_argument() [1/2]

◆ add_positional_argument() [2/2]

◆ count()

◆ default_optional_arguments() [1/2]

◆ default_optional_arguments() [2/2]

◆ default_positional_arguments() [1/2]

◆ default_positional_arguments() [2/2]

◆ handle_help_action()

◆ has_value()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ parse_args() [1/2]

◆ parse_args() [2/2]

◆ parse_known_args() [1/2]

◆ parse_known_args() [2/2]

◆ print_config()

◆ program_description()

◆ program_name()

◆ program_version() [1/2]

◆ program_version() [2/2]

◆ try_parse_args() [1/2]

◆ try_parse_args() [2/2]

◆ try_parse_known_args() [1/2]

◆ try_parse_known_args() [2/2]

◆ value()

◆ value_or()

◆ values()

◆ verbose()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ _flag_prefix

◆ _flag_prefix_char

◆ _indent_width