The main argument parser class. More...

#include <argument_parser.hpp>

Classes
struct	parsing_state
	A collection of values used during the parsing process. More...

Public Member Functions
	argument_parser (const argument_parser &)=delete

argument_parser &	operator= (const argument_parser &)=delete

	argument_parser (argument_parser &&)=delete

argument_parser &	operator= (argument_parser &&)=delete

	argument_parser (const std::string_view name)

	~argument_parser ()=default

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

argument_parser &	program_version (std::string_view version)
	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.

argument_parser &	unknown_arguments_policy (const unknown_policy policy) noexcept
	Set the unknown argument flags handling policy.

template<util::c_range_of< default_argument > AR>
argument_parser &	default_arguments (const AR &arg_discriminators) noexcept
	Add default arguments to the argument parser.

argument_parser &	default_arguments (const std::initializer_list< default_argument > &arg_discriminators) noexcept
	Add default arguments to the argument parser.

argument_parser &	default_arguments (const std::same_as< default_argument > auto... arg_discriminators) noexcept
	Add default arguments to the argument parser.

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

template<util::c_argument_value_type T = std::string>
positional_argument< T > &	add_positional_argument (argument_group &group, const std::string_view name)
	Adds a positional argument to the parser's configuration and binds it to the given group.

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

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

template<util::c_argument_value_type T = std::string>
optional_argument< T > &	add_optional_argument (argument_group &group, const std::string_view name, const detail::argument_name_discriminator name_discr=n_primary)
	Adds an optional argument to the parser's configuration and binds it to the given group.

template<util::c_argument_value_type T = std::string>
optional_argument< T > &	add_optional_argument (argument_group &group, const std::string_view primary_name, const std::string_view secondary_name)
	Adds an optional argument to the parser's configuration and binds it to the given group.

template<bool StoreImplicitly = true>
optional_argument< 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>
optional_argument< 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.

template<bool StoreImplicitly = true>
optional_argument< bool > &	add_flag (argument_group &group, 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 and binds it to the given group.

template<bool StoreImplicitly = true>
optional_argument< bool > &	add_flag (argument_group &group, 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 and binds it to the given group.

argument_group &	add_group (const std::string_view name) noexcept
	Adds an argument group with the given name to the parser's configuration.

argument_parser &	add_subparser (const std::string_view name)
	Adds an subparser with the given name to the parser's configuration.

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

template<util::c_forward_range_of< std::string, util::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<util::c_forward_range_of< std::string, util::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<util::c_forward_range_of< std::string, util::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<util::c_forward_range_of< std::string, util::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.

std::string_view	name () const noexcept
	Returns the parser's name.

std::string_view	program_name () const noexcept

bool	invoked () const noexcept
	Check whether this parser was invoked.

bool	finalized () const noexcept
	Check whether the parser has finalized parsing its own arguments.

argument_parser &	resolved_parser () noexcept
	Returns the deepest invoked parser.

bool	is_used (std::string_view arg_name) const noexcept
	Check if a specific argument was used in the command-line.

bool	has_value (std::string_view arg_name) const noexcept
	Check if the given argument has a value.

std::size_t	count (std::string_view arg_name) const noexcept
	Get the given argument's usage count.

template<util::c_argument_value_type T = std::string>
T	value (std::string_view arg_name) const
	Get the value of the given argument.

template<util::c_argument_value_type T = std::string, std::convertible_to< T > U>
T	value_or (std::string_view arg_name, U &&fallback_value) const
	Get the value of the given argument, if it has any, or a fallback value, if not.

template<util::c_argument_value_type T = std::string>
std::vector< T >	values (std::string_view arg_name) const
	Get all values of the given argument.

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

void	print_version (std::ostream &os=std::cout) const noexcept
	Prints the argument parser's version info to an output stream.

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

using	arg_ptr_vec_t = std::vector< arg_ptr_t >

using	arg_ptr_vec_iter_t = typename arg_ptr_vec_t::iterator

using	arg_group_ptr_t = std::unique_ptr< argument_group >

using	arg_group_ptr_vec_t = std::vector< arg_group_ptr_t >

using	arg_parser_ptr_t = std::unique_ptr< argument_parser >

using	arg_parser_ptr_vec_t = std::vector< arg_parser_ptr_t >

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

using	arg_token_vec_iter_t = typename arg_token_vec_t::const_iterator

Private Member Functions
	argument_parser (const std::string_view name, const std::string_view parent_name)

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_group (const argument_group &group)
	Check if the given group belongs to the parser.

template<util::c_forward_iterator_of< std::string, util::type_validator::convertible > AIt>
void	_parse_args_impl (AIt args_begin, const AIt args_end, parsing_state &state)
	Implementation of parsing command-line arguments.

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

template<util::c_forward_iterator_of< std::string, util::type_validator::convertible > AIt>
arg_token_vec_t	_tokenize (AIt args_begin, const AIt args_end, const parsing_state &state)
	Converts the command-line arguments into a list of tokens.

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

detail::argument_token::token_type	_deduce_token_type (const std::string_view arg_value) const noexcept
	Returns the most appropriate initial token type based on a command-line argument's value.

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

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

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

std::string_view	_strip_flag_prefix (const detail::argument_token &tok) const noexcept
	Removes the flag prefix from a flag token's value.

void	_parse_token (const detail::argument_token &tok, parsing_state &state)
	Parse a single command-line argument token.

void	_parse_flag_token (const detail::argument_token &tok, parsing_state &state)
	Parse a single command-line argument flag token.

void	_parse_value_token (const detail::argument_token &tok, parsing_state &state)
	Parse a single command-line argument value token.

void	_set_argument_value (const std::string_view value, parsing_state &state) noexcept
	Set the value for the currently processed argument.

void	_verify_final_state () const
	Verifies the correctness of the parsed command-line arguments.

std::pair< bool, bool >	_are_checks_suppressed () const noexcept
	Check whether required argument group checks or argument checks suppressing is enabled.

void	_verify_group_requirements (const argument_group &group, const bool suppress_group_checks, const bool suppress_arg_checks) const
	Verifies whether the requirements of the given argument group are satisfied.

void	_verify_argument_requirements (const arg_ptr_t &arg, const bool suppress_arg_checks) const
	Verifies whether the requirements of the given argument are satisfied.

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

void	_print_subparsers (std::ostream &os) const noexcept

void	_print_group (std::ostream &os, const argument_group &group, const bool verbose) const noexcept
	Print the given argument list to an output stream.

Private Attributes
std::string	_name
	The name of the parser.

std::string	_program_name
	The name of the program in the format "<parent-parser-names>... <program-name>".

std::optional< std::string >	_program_version
	The version of the program.

std::optional< std::string >	_program_description
	The description of the program.

bool	_verbose = false
	Verbosity flag.

unknown_policy	_unknown_policy = unknown_policy::fail
	Policy for unknown arguments.

arg_ptr_vec_t	_positional_args
	The list of positional arguments.

arg_ptr_vec_t	_optional_args
	The list of optional arguments.

arg_group_ptr_vec_t	_argument_groups
	The list of argument groups.

argument_group &	_gr_positional_args
	The positional argument group.

argument_group &	_gr_optional_args
	The optional argument group.

arg_parser_ptr_vec_t	_subparsers
	The list of subparsers.

bool	_invoked
	A flag indicating whether the parser has been invoked to parse arguments.

bool	_finalized = false
	A flag indicating whether the parsing process has been finalized.

Static Private Attributes
static constexpr std::uint8_t	_primary_flag_prefix_length = 2u

static constexpr std::uint8_t	_secondary_flag_prefix_length = 1u

static constexpr char	_flag_prefix_char = '-'

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

static constexpr std::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

The main argument parser class.

This class provides methods to define positional and optional arguments, set parser options, and parse the command-line input.

Example usage:

#include <ap/argument_parser.hpp>
 
int main(int argc, char* argv[]) {
    // Create the argument parser instance
    ap::argument_parser parser("fcopy");
    parser.program_version({ .major = 1, .minor = 0, .patch = 0 })
          .program_description("A simple file copy utility.")
          .default_arguments(
              ap::default_argument::o_help,
              ap::default_argument::o_input,
              ap::default_argument::o_output
          )
          .verbose()
          .unknown_arguments_policy(ap::unknown_policy::ignore)
          .try_parse_args(argc, argv);
 
    // Access parsed argument values
    const std::string input_file = parser.value("input");
    const std::string output_file = parser.value("output");
 
    // Application logic here
    std::cout << "Copying from " << input_file << " to " << output_file << std::endl;
 
    return 0;
}

Definition at line 179 of file argument_parser.hpp.

Member Typedef Documentation

◆ arg_group_ptr_t

using ap::argument_parser::arg_group_ptr_t = std::unique_ptr<argument_group>

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 906 of file argument_parser.hpp.

◆ arg_group_ptr_vec_t

using ap::argument_parser::arg_group_ptr_vec_t = std::vector<arg_group_ptr_t>

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 907 of file argument_parser.hpp.

◆ arg_parser_ptr_t

using ap::argument_parser::arg_parser_ptr_t = std::unique_ptr<argument_parser>

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 909 of file argument_parser.hpp.

◆ arg_parser_ptr_vec_t

using ap::argument_parser::arg_parser_ptr_vec_t = std::vector<arg_parser_ptr_t>

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 910 of file argument_parser.hpp.

◆ arg_ptr_t

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

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 902 of file argument_parser.hpp.

◆ arg_ptr_vec_iter_t

using ap::argument_parser::arg_ptr_vec_iter_t = typename arg_ptr_vec_t::iterator

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 904 of file argument_parser.hpp.

◆ arg_ptr_vec_t

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

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 903 of file argument_parser.hpp.

◆ arg_token_vec_iter_t

using ap::argument_parser::arg_token_vec_iter_t = typename arg_token_vec_t::const_iterator

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 913 of file argument_parser.hpp.

◆ arg_token_vec_t

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

private

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 912 of file argument_parser.hpp.

Constructor & Destructor Documentation

◆ argument_parser() [1/4]

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

delete

◆ argument_parser() [2/4]

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

delete

◆ argument_parser() [3/4]

ap::argument_parser::argument_parser ( const std::string_view name )

inline

Definition at line 187 of file argument_parser.hpp.

◆ ~argument_parser()

ap::argument_parser::~argument_parser ( )

default

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

◆ argument_parser() [4/4]

ap::argument_parser::argument_parser	(	const std::string_view	name,
		const std::string_view	parent_name
	)

inlineprivate

Definition at line 937 of file argument_parser.hpp.

Member Function Documentation

◆ _are_checks_suppressed()

std::pair< bool, bool > ap::argument_parser::_are_checks_suppressed ( ) const

inlineprivatenoexcept

Check whether required argument group checks or argument checks suppressing is enabled.

Returns: A pair of boolean flags indicating whether suppressing is enabled.

Note: The first flag of the returned pair indicates whetehr argument group check suppressing is enabled,; while the second flag indicated whether argument check suppressing is enabled.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1374 of file argument_parser.hpp.

◆ _deduce_token_type()

detail::argument_token::token_type ap::argument_parser::_deduce_token_type ( const std::string_view arg_value ) const

inlineprivatenoexcept

Returns the most appropriate initial token type based on a command-line argument's value.

The token's initial type is deduced using the following rules:

t_value: an argument contains whitespace characters or cannot be a flag token
t_flag_primary: an argument begins with a primary flag prefix (--)
t_flag_secondary: an argument begins with a secondary flag prefix (-)
t_flag_compound: INITIALLY a token can NEVER have a compound flag type (may only be set when a flag token is validated)

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1173 of file argument_parser.hpp.

◆ _find_opt_arg()

arg_ptr_vec_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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1243 of file argument_parser.hpp.

◆ _get_argument()

arg_ptr_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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1464 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1015 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 1000 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 987 of file argument_parser.hpp.

◆ _parse_args_impl()

template<util::c_forward_iterator_of< std::string, util::type_validator::convertible > AIt>

void ap::argument_parser::_parse_args_impl	(	AIt	args_begin,
		const AIt	args_end,
		parsing_state &	state
	)

inlineprivate

Implementation of parsing command-line arguments.

Template Parameters

AIt	The command-line argument value iterator type.

Note: AIt must be a std::forward_iterator with a value type convertible to std::string.

Parameters

args_begin	The begin iterator for the command-line argument value range.
args_end	The end iterator for the command-line argument value range.
state	The current parsing state.

Exceptions

ap::invalid_configuration,ap::parsing_failure

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1052 of file argument_parser.hpp.

◆ _parse_flag_token()

void ap::argument_parser::_parse_flag_token	(	const detail::argument_token &	tok,
		parsing_state &	state
	)

inlineprivate

Parse a single command-line argument flag token.

Parameters

tok	The token to be parsed.
state	The current parsing state.

Exceptions

ap::parsing_failure

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1300 of file argument_parser.hpp.

◆ _parse_token()

void ap::argument_parser::_parse_token	(	const detail::argument_token &	tok,
		parsing_state &	state
	)

inlineprivate

Parse a single command-line argument token.

Parameters

tok	The token to be parsed.
state	The current parsing state.

Exceptions

ap::parsing_failure

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1282 of file argument_parser.hpp.

◆ _parse_value_token()

void ap::argument_parser::_parse_value_token	(	const detail::argument_token &	tok,
		parsing_state &	state
	)

inlineprivate

Parse a single command-line argument value token.

Parameters

tok	The token to be parsed.
state	The current parsing state.

Exceptions

ap::parsing_failure

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1327 of file argument_parser.hpp.

◆ _print_group()

void ap::argument_parser::_print_group	(	std::ostream &	os,
		const argument_group &	group,
		const bool	verbose
	)		const

inlineprivatenoexcept

Print the given argument list to an output stream.

Parameters

os	The output stream to print to.
group	The argument group to print.
verbose	A verbosity mode indicator flag.

Attention: If a group has no visible arguments, nothing will be printed.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1509 of file argument_parser.hpp.

◆ _print_subparsers()

void ap::argument_parser::_print_subparsers ( std::ostream & os ) const

inlineprivatenoexcept

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1480 of file argument_parser.hpp.

◆ _set_argument_value()

void ap::argument_parser::_set_argument_value	(	const std::string_view	value,
		parsing_state &	state
	)

inlineprivatenoexcept

Set the value for the currently processed argument.

Attention: This function assumes that the current argument is set (i.e. state.curr_arg != nullptr).

Parameters

value	The value to be set for the current argument.
state	The current parsing state.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1346 of file argument_parser.hpp.

◆ _strip_flag_prefix()

std::string_view ap::argument_parser::_strip_flag_prefix ( const detail::argument_token & tok ) const

inlineprivatenoexcept

Removes the flag prefix from a flag token's value.

Parameters

tok	The argument token to be processed.

Returns: The token's value without the flag prefix.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1264 of file argument_parser.hpp.

◆ _tokenize()

template<util::c_forward_iterator_of< std::string, util::type_validator::convertible > AIt>

arg_token_vec_t ap::argument_parser::_tokenize	(	AIt	args_begin,
		const AIt	args_end,
		const parsing_state &	state
	)

inlineprivate

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

Template Parameters

AIt	The command-line argument value iterator type.

Note: AIt must be a std::forward_iterator with a value type convertible to std::string.

Parameters

args_begin	The begin iterator for the command-line argument value range.
args_end	The end iterator for the command-line argument value range.
state	The current parsing state.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1112 of file argument_parser.hpp.

◆ _tokenize_arg()

void ap::argument_parser::_tokenize_arg	(	const std::string_view	arg_value,
		arg_token_vec_t &	toks,
		const parsing_state &	state
	)

inlineprivate

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

Parameters

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1129 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1083 of file argument_parser.hpp.

◆ _validate_compound_flag_token()

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

inlineprivatenoexcept

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

Attention: If the token indeed represents valid compound flag, the token's type is changed to t_flag_compuund; and its args list is filled with all the arguments the token represents.

Parameters

tok	The argument token to validate.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1210 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: Extends the args 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1194 of file argument_parser.hpp.

◆ _validate_group()

void ap::argument_parser::_validate_group ( const argument_group & group )

inlineprivate

Check if the given group belongs to the parser.

Parameters

group The group to validate.

Exceptions

std::logic_error if the group doesn't belong to the parser.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1035 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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 955 of file argument_parser.hpp.

◆ _verify_argument_requirements()

void ap::argument_parser::_verify_argument_requirements	(	const arg_ptr_t &	arg,
		const bool	suppress_arg_checks
	)		const

inlineprivate

Verifies whether the requirements of the given argument are satisfied.

Parameters

arg	The argument to verify.
suppress_arg_checks	A flag indicating whether argument checks are suppressed.

Exceptions

ap::parsing_failure if the requirements are not satistied.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1447 of file argument_parser.hpp.

◆ _verify_final_state()

void ap::argument_parser::_verify_final_state ( ) const

inlineprivate

Verifies the correctness of the parsed command-line arguments.

Exceptions

ap::parsing_failure if the state of the parsed arguments is invalid.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1362 of file argument_parser.hpp.

◆ _verify_group_requirements()

void ap::argument_parser::_verify_group_requirements	(	const argument_group &	group,
		const bool	suppress_group_checks,
		const bool	suppress_arg_checks
	)		const

inlineprivate

Verifies whether the requirements of the given argument group are satisfied.

Parameters

group	The argument group to verify.
suppress_arg_checks	A flag indicating whether argument checks are suppressed.

Exceptions

ap::parsing_failure if the requirements are not satistied.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1399 of file argument_parser.hpp.

◆ add_flag() [1/4]

template<bool StoreImplicitly = true>

optional_argument< bool > & ap::argument_parser::add_flag	(	argument_group &	group,
		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 and binds it to the given group.

Template Parameters

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

Note: The argument's default_values attribute will be set to not StoreImplicitly.

Parameters

group	The argument group to bind the new argument to.
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 468 of file argument_parser.hpp.

◆ add_flag() [2/4]

template<bool StoreImplicitly = true>

optional_argument< bool > & ap::argument_parser::add_flag	(	argument_group &	group,
		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 and binds it to the given group.

Template Parameters

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

Note: The argument's default_values attribute will be set to not StoreImplicitly.

Parameters

group	The argument group to bind the new argument to.
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 489 of file argument_parser.hpp.

◆ add_flag() [3/4]

template<bool StoreImplicitly = true>

optional_argument< 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_values parameter of the argument.

Note: The argument's default_values attribute will be set to not StoreImplicitly.

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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 430 of file argument_parser.hpp.

◆ add_flag() [4/4]

template<bool StoreImplicitly = true>

optional_argument< 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_values parameter of the argument.

Note: The argument's default_values attribute will be set to not StoreImplicitly.

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 449 of file argument_parser.hpp.

◆ add_group()

argument_group & ap::argument_parser::add_group ( const std::string_view name )

inlinenoexcept

Adds an argument group with the given name to the parser's configuration.

Parameters

name	Name of the group.

Returns: Reference to the added argument group.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 505 of file argument_parser.hpp.

◆ add_optional_argument() [1/4]

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

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

inline

Adds an optional argument to the parser's configuration and binds it to the given group.

Template Parameters

T	Type of the argument value.

Parameters

group	The argument group to bind the new argument to.
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

std::logic_error,ap::invalid_configuration

Definition at line 363 of file argument_parser.hpp.

◆ add_optional_argument() [2/4]

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

optional_argument< T > & ap::argument_parser::add_optional_argument	(	argument_group &	group,
		const std::string_view	primary_name,
		const std::string_view	secondary_name
	)

inline

Adds an optional argument to the parser's configuration and binds it to the given group.

Template Parameters

T	Type of the argument value.

Parameters

group	The argument group to bind the new argument to.
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

Definition at line 398 of file argument_parser.hpp.

◆ add_optional_argument() [3/4]

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

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

inline

Adds an optional 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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 329 of file argument_parser.hpp.

◆ add_optional_argument() [4/4]

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

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

inline

Adds an optional 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

Definition at line 345 of file argument_parser.hpp.

◆ add_positional_argument() [1/2]

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

positional_argument< T > & ap::argument_parser::add_positional_argument	(	argument_group &	group,
		const std::string_view	name
	)

inline

Adds a positional argument to the parser's configuration and binds it to the given group.

Template Parameters

T	Type of the argument value.

Parameters

primary_name The name of the argument.

Returns: Reference to the added positional argument.

Exceptions

ap::invalid_configuration

Definition at line 304 of file argument_parser.hpp.

◆ add_positional_argument() [2/2]

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

positional_argument< T > & ap::argument_parser::add_positional_argument ( const std::string_view name )

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.

Returns: Reference to the added positional argument.

Exceptions

ap::invalid_configuration

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 292 of file argument_parser.hpp.

◆ add_subparser()

argument_parser & ap::argument_parser::add_subparser ( const std::string_view name )

inline

Adds an subparser with the given name to the parser's configuration.

Parameters

name	Name of the subparser.

Returns: Reference to the added subparser.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 514 of file argument_parser.hpp.

◆ count()

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

inlinenoexcept

Get the given argument's usage count.

Parameters

arg_name The name of the argument.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 766 of file argument_parser.hpp.

◆ default_arguments() [1/3]

template<util::c_range_of< default_argument > AR>

argument_parser & ap::argument_parser::default_arguments ( const AR & arg_discriminators )

inlinenoexcept

Add default arguments to the argument parser.

Template Parameters

AR	Type of the positional argument discriminator range.

Parameters

arg_discriminators A range of default positional argument discriminators.

Note: arg_discriminators must be a std::ranges::range with the ap::default_argument value type.

Returns: Reference to the argument parser.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 255 of file argument_parser.hpp.

◆ default_arguments() [2/3]

argument_parser & ap::argument_parser::default_arguments ( const std::initializer_list< default_argument > & arg_discriminators )

inlinenoexcept

Add default arguments to the argument parser.

Parameters

arg_discriminators A list of default positional argument discriminators.

Returns: Reference to the argument parser.

Definition at line 266 of file argument_parser.hpp.

◆ default_arguments() [3/3]

argument_parser & ap::argument_parser::default_arguments ( const std::same_as< default_argument > auto... arg_discriminators )

inlinenoexcept

Add default arguments to the argument parser.

Parameters

arg_discriminators A list of default positional argument discriminators.

Returns: Reference to the argument parser.

Definition at line 277 of file argument_parser.hpp.

◆ finalized()

bool ap::argument_parser::finalized ( ) const

inlinenoexcept

Check whether the parser has finalized parsing its own arguments.

Returns: true if parsing was completed for the parser, false otherwise.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 724 of file argument_parser.hpp.

◆ has_value()

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

inlinenoexcept

Check if the given argument has a value.

Parameters

arg_name The name of the argument.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 756 of file argument_parser.hpp.

◆ invoked()

bool ap::argument_parser::invoked ( ) const

inlinenoexcept

Check whether this parser was invoked.

Returns: true if the parser was selected when parsing the command-line arguments, false otherwise.

Note: A parser is invoked as soon as the parser is selected during parsing, even if parsing is later delegated to one of its subparsers.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 716 of file argument_parser.hpp.

◆ is_used()

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

inlinenoexcept

Check if a specific argument was used in the command-line.

Parameters

arg_name The name of the argument.

Returns: true if the argument was used on the command line, false otherwise.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 746 of file argument_parser.hpp.

◆ name()

std::string_view ap::argument_parser::name ( ) const

inlinenoexcept

Returns the parser's name.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 692 of file argument_parser.hpp.

◆ operator=() [1/2]

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

delete

◆ operator=() [2/2]

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

delete

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

◆ parse_args() [1/2]

template<util::c_forward_range_of< std::string, util::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.

Note: argv_rng must be a std::ranges::forward_range with a value type convertible to std::string.

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 556 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:543

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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 543 of file argument_parser.hpp.

◆ parse_known_args() [1/2]

template<util::c_forward_range_of< std::string, util::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.

Note: argv_rng must be a std::ranges::forward_range with a value type convertible to std::string.

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 643 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:662

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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 624 of file argument_parser.hpp.

◆ print_help()

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

inlinenoexcept

Prints the argument parser's help message to an output stream.

Parameters

verbose	The verbosity mode value.
os	The output stream.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 853 of file argument_parser.hpp.

◆ print_version()

void ap::argument_parser::print_version ( std::ostream & os = std::cout ) const

inlinenoexcept

Prints the argument parser's version info to an output stream.

If no version was spcified for the parser, unspecified will be printed.

Parameters

os	The output stream.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 876 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 220 of file argument_parser.hpp.

◆ program_name()

std::string_view ap::argument_parser::program_name ( ) const

inlinenoexcept

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 707 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 196 of file argument_parser.hpp.

◆ program_version() [2/2]

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

inline

Set the program version.

Parameters

version The version of the program.

Returns: Reference to the argument parser.

Definition at line 206 of file argument_parser.hpp.

◆ resolved_parser()

argument_parser & ap::argument_parser::resolved_parser ( )

inlinenoexcept

Returns the deepest invoked parser.

Returns: Reference to the finalized parser that ultimately processed the arguments.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 732 of file argument_parser.hpp.

◆ try_parse_args() [1/2]

template<util::c_forward_range_of< std::string, util::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.

Note: argv_rng must be a std::ranges::forward_range with a value type convertible to std::string.

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

Definition at line 595 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)))

Parameters

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

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 578 of file argument_parser.hpp.

◆ try_parse_known_args() [1/2]

template<util::c_forward_range_of< std::string, util::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.

Note: argv_rng must be a std::ranges::forward_range with a value type convertible to std::string.

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 680 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 662 of file argument_parser.hpp.

◆ unknown_arguments_policy()

argument_parser & ap::argument_parser::unknown_arguments_policy ( const unknown_policy policy )

inlinenoexcept

Set the unknown argument flags handling policy.

Parameters

policy The unknown arguments policy value.

Returns: Reference to the argument parser.

Note: The default unknown arguments policy value is ap::unknown_policy::fail.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 242 of file argument_parser.hpp.

◆ value()

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

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

inline

Get the value of the given argument.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 779 of file argument_parser.hpp.

◆ value_or()

template<util::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

Get the value of the given argument, if it has any, or a fallback value, if not.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 803 of file argument_parser.hpp.

◆ values()

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

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

inline

Get all values of the given argument.

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

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 830 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.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 231 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_help(_verbose, os) call, where _verbose is the inner verbosity mode, which can be set with the verbose function.

Parameters

os	The output stream.
parser	The argument parser to print.

Returns: The modified output stream.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 891 of file argument_parser.hpp.

Member Data Documentation

◆ _argument_groups

arg_group_ptr_vec_t ap::argument_parser::_argument_groups

private

The list of argument groups.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1562 of file argument_parser.hpp.

◆ _finalized

bool ap::argument_parser::_finalized = false

private

A flag indicating whether the parsing process has been finalized.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1569 of file argument_parser.hpp.

◆ _flag_prefix

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

staticconstexprprivate

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1574 of file argument_parser.hpp.

◆ _flag_prefix_char

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

staticconstexprprivate

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1573 of file argument_parser.hpp.

◆ _gr_optional_args

argument_group& ap::argument_parser::_gr_optional_args

private

The optional argument group.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1564 of file argument_parser.hpp.

◆ _gr_positional_args

argument_group& ap::argument_parser::_gr_positional_args

private

The positional argument group.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1563 of file argument_parser.hpp.

◆ _indent_width

constexpr std::uint8_t ap::argument_parser::_indent_width = 2

staticconstexprprivate

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1575 of file argument_parser.hpp.

◆ _invoked

bool ap::argument_parser::_invoked

private

Initial value:

=

false

A flag indicating whether the parser has been invoked to parse arguments.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1567 of file argument_parser.hpp.

◆ _name

std::string ap::argument_parser::_name

private

The name of the parser.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1552 of file argument_parser.hpp.

◆ _optional_args

arg_ptr_vec_t ap::argument_parser::_optional_args

private

The list of optional arguments.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1561 of file argument_parser.hpp.

◆ _positional_args

arg_ptr_vec_t ap::argument_parser::_positional_args

private

The list of positional arguments.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1560 of file argument_parser.hpp.

◆ _primary_flag_prefix_length

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

staticconstexprprivate

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1571 of file argument_parser.hpp.

◆ _program_description

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

private

The description of the program.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1556 of file argument_parser.hpp.

◆ _program_name

std::string ap::argument_parser::_program_name

private

The name of the program in the format "<parent-parser-names>... <program-name>".

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1554 of file argument_parser.hpp.

◆ _program_version

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

private

The version of the program.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1555 of file argument_parser.hpp.

◆ _secondary_flag_prefix_length

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

staticconstexprprivate

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1572 of file argument_parser.hpp.

◆ _subparsers

arg_parser_ptr_vec_t ap::argument_parser::_subparsers

private

The list of subparsers.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1565 of file argument_parser.hpp.

◆ _unknown_policy

unknown_policy ap::argument_parser::_unknown_policy = unknown_policy::fail

private

Policy for unknown arguments.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1558 of file argument_parser.hpp.

◆ _verbose

bool ap::argument_parser::_verbose = false

private

Verbosity flag.

Examples: /home/runner/work/cpp-ap/cpp-ap/include/ap/argument_parser.hpp.

Definition at line 1557 of file argument_parser.hpp.

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

include/ap/argument_parser.hpp

Classes

Public Member Functions

Private Types

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ arg_group_ptr_t

◆ arg_group_ptr_vec_t

◆ arg_parser_ptr_t

◆ arg_parser_ptr_vec_t

◆ arg_ptr_t

◆ arg_ptr_vec_iter_t

◆ arg_ptr_vec_t

◆ arg_token_vec_iter_t

◆ arg_token_vec_t

Constructor & Destructor Documentation

◆ argument_parser() [1/4]

◆ argument_parser() [2/4]

◆ argument_parser() [3/4]

◆ ~argument_parser()

◆ argument_parser() [4/4]

Member Function Documentation

◆ _are_checks_suppressed()

◆ _deduce_token_type()

◆ _find_opt_arg()

◆ _get_argument()

◆ _is_arg_name_used()

◆ _name_match_predicate() [1/2]

◆ _name_match_predicate() [2/2]

◆ _parse_args_impl()

◆ _parse_flag_token()

◆ _parse_token()

◆ _parse_value_token()

◆ _print_group()

◆ _print_subparsers()

◆ _set_argument_value()

◆ _strip_flag_prefix()

◆ _tokenize()

◆ _tokenize_arg()

◆ _validate_argument_configuration()

◆ _validate_compound_flag_token()

◆ _validate_flag_token()

◆ _validate_group()

◆ _verify_arg_name_pattern()

◆ _verify_argument_requirements()

◆ _verify_final_state()

◆ _verify_group_requirements()

◆ add_flag() [1/4]

◆ add_flag() [2/4]

◆ add_flag() [3/4]

◆ add_flag() [4/4]

◆ add_group()

◆ add_optional_argument() [1/4]

◆ add_optional_argument() [2/4]

◆ add_optional_argument() [3/4]

◆ add_optional_argument() [4/4]

◆ add_positional_argument() [1/2]

◆ add_positional_argument() [2/2]

◆ add_subparser()

◆ count()

◆ default_arguments() [1/3]

◆ default_arguments() [2/3]

◆ default_arguments() [3/3]

◆ finalized()

◆ has_value()

◆ invoked()

◆ is_used()

◆ name()

◆ 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_help()

◆ print_version()

◆ program_description()