The ArgumentParser class provides a means for handling command line arguments. More...

#include <argumentparser.h>

Public Member Functions
	ArgumentParser ()
	Constructs a new ArgumentParser.

const ArgumentVector &	mainArguments () const
	Returns the main arguments.

void	setMainArguments (const ArgumentInitializerList &mainArguments)
	Sets the main arguments for the parser.

void	addMainArgument (Argument *argument)
	Adds the specified argument to the main argument.

void	printHelp (std::ostream &os) const
	Prints help text for all assigned arguments.

void	parseArgs (int argc, const char const argv, ParseArgumentBehavior behavior=ParseArgumentBehavior::CheckConstraints\|ParseArgumentBehavior::InvokeCallbacks\|ParseArgumentBehavior::ExitOnFailure)
	Parses the specified command line arguments.

void	readArgs (int argc, const char const argv)
	Parses the specified command line arguments.

void	resetArgs ()
	Resets all Argument instances assigned as mainArguments() and sub arguments.

void	checkConstraints ()
	Checks whether constraints are violated.

void	invokeCallbacks ()
	Invokes all assigned callbacks.

unsigned int	actualArgumentCount () const
	Returns the actual number of arguments that could be found when parsing.

const char *	executable () const
	Returns the name of the current executable.

UnknownArgumentBehavior	unknownArgumentBehavior () const
	Returns how unknown arguments are treated.

void	setUnknownArgumentBehavior (UnknownArgumentBehavior behavior)
	Sets how unknown arguments are treated.

Argument *	defaultArgument () const
	Returns the default argument.

void	setDefaultArgument (Argument *argument)
	Sets the default argument.

Argument *	specifiedOperation () const
	Returns the first operation argument specified by the user or nullptr if no operation has been specified.

bool	isUncombinableMainArgPresent () const
	Checks whether at least one uncombinable main argument is present.

void	setExitFunction (std::function< void(int)> exitFunction)
	Specifies a function quit the application.

const HelpArgument &	helpArg () const
	Returns the `--help` argument.

HelpArgument &	helpArg ()
	Returns the `--help` argument.

const NoColorArgument &	noColorArg () const
	Returns the `--no-color` argument.

NoColorArgument &	noColorArg ()
	Returns the `--no-color` argument.

Detailed Description

The ArgumentParser class provides a means for handling command line arguments.

To setup the parser create instances of ApplicationUtilities::Argument to define a set of known arguments and assign these to the parser using setMainArguments().

To invoke parsing call parseArgs(). The parser will verify the previously assigned definitions (and might throw std::invalid_argument) and then parse the given command line arguments according the definitions (and might throw CppUtilities::Failure).

Definition at line 457 of file argumentparser.h.

Constructor & Destructor Documentation

◆ ArgumentParser()

CppUtilities::ArgumentParser::ArgumentParser ( )

Constructs a new ArgumentParser.

Definition at line 772 of file argumentparser.cpp.

Member Function Documentation

◆ actualArgumentCount()

unsigned int CppUtilities::ArgumentParser::actualArgumentCount ( ) const

inline

Returns the actual number of arguments that could be found when parsing.

Definition at line 1103 of file argumentparser.h.

◆ addMainArgument()

void CppUtilities::ArgumentParser::addMainArgument ( Argument * argument )

Adds the specified argument to the main argument.

Remarks: The parser does not take ownership. Do not destroy the argument as long as it is used as main argument.

Definition at line 821 of file argumentparser.cpp.

◆ checkConstraints()

void CppUtilities::ArgumentParser::checkConstraints ( )

inline

Checks whether constraints are violated.

Remarks: Automatically called by parseArgs().

Exceptions

Throws Failure if constraints are violated.

Definition at line 1159 of file argumentparser.h.

◆ defaultArgument()

Argument * CppUtilities::ArgumentParser::defaultArgument ( ) const

inline

Returns the default argument.

Remarks: The default argument is assumed to be present if no other arguments have been specified.

Definition at line 1140 of file argumentparser.h.

◆ executable()

const char * CppUtilities::ArgumentParser::executable ( ) const

inline

Returns the name of the current executable.

Definition at line 1111 of file argumentparser.h.

◆ helpArg() [1/2]

HelpArgument & CppUtilities::ArgumentParser::helpArg ( )

inline

Returns the --help argument.

Definition at line 1193 of file argumentparser.h.

◆ helpArg() [2/2]

const HelpArgument & CppUtilities::ArgumentParser::helpArg ( ) const

inline

Returns the --help argument.

Definition at line 1185 of file argumentparser.h.

◆ invokeCallbacks()

void CppUtilities::ArgumentParser::invokeCallbacks ( )

inline

Invokes all assigned callbacks.

Remarks: Automatically called by parseArgs().

Definition at line 1168 of file argumentparser.h.

◆ isUncombinableMainArgPresent()

bool CppUtilities::ArgumentParser::isUncombinableMainArgPresent ( ) const

Checks whether at least one uncombinable main argument is present.

Definition at line 1062 of file argumentparser.cpp.

◆ mainArguments()

const ArgumentVector & CppUtilities::ArgumentParser::mainArguments ( ) const

inline

Returns the main arguments.

See also: setMainArguments()

Definition at line 1095 of file argumentparser.h.

◆ noColorArg() [1/2]

NoColorArgument & CppUtilities::ArgumentParser::noColorArg ( )

inline

Returns the --no-color argument.

Definition at line 1209 of file argumentparser.h.

◆ noColorArg() [2/2]

const NoColorArgument & CppUtilities::ArgumentParser::noColorArg ( ) const

inline

Returns the --no-color argument.

Definition at line 1201 of file argumentparser.h.

◆ parseArgs()

void CppUtilities::ArgumentParser::parseArgs	(	int	argc,
		const char const	argv,
		ParseArgumentBehavior	behavior = ParseArgumentBehavior::CheckConstraints \| ParseArgumentBehavior::InvokeCallbacks \| ParseArgumentBehavior::ExitOnFailure )

Parses the specified command line arguments.

The behavior is configurable by specifying the behavior argument. See ParseArgumentBehavior for the options. By default, all options are present.

Remarks

The results are stored in the Argument instances assigned as main arguments and sub arguments.
This method will not return in the error case if the ParseArgumentBehavior::ExitOnFailure is present (default).
This method will not return in case shell completion is requested. This behavior can be altered by overriding the exit function via ArgumentParser::setExitFunction() which defaults to &std::exit.

Exceptions

Throws Failure if the specified arguments are invalid and the ParseArgumentBehavior::ExitOnFailure flag is not present.

See also: readArgs()

Definition at line 936 of file argumentparser.cpp.

◆ printHelp()

void CppUtilities::ArgumentParser::printHelp ( std::ostream & os ) const

Prints help text for all assigned arguments.

Definition at line 830 of file argumentparser.cpp.

◆ readArgs()

void CppUtilities::ArgumentParser::readArgs	(	int	argc,
		const char const	argv )

Parses the specified command line arguments.

Remarks

The results are stored in the Argument instances assigned as main arguments and sub arguments.
In contrast to parseArgs() this method does not check whether constraints are violated and it does not call any callbacks.
This method will not return in case shell completion is requested. This behavior can be altered by overriding the exit function via ArgumentParser::setExitFunction() which defaults to &std::exit.

Exceptions

Throws Failure if the specified arguments are invalid.

See also: parseArgs()

Deprecated: In next major release, this method will be private. parseArgs() can serve the same purpose then.

Definition at line 972 of file argumentparser.cpp.

◆ resetArgs()

void CppUtilities::ArgumentParser::resetArgs ( )

Resets all Argument instances assigned as mainArguments() and sub arguments.

See also: Argument::reset()

Definition at line 1036 of file argumentparser.cpp.

◆ setDefaultArgument()

void CppUtilities::ArgumentParser::setDefaultArgument ( Argument * argument )

inline

Sets the default argument.

Remarks: The default argument is assumed to be present if no other arguments have been specified.

Definition at line 1149 of file argumentparser.h.

◆ setExitFunction()

void CppUtilities::ArgumentParser::setExitFunction ( std::function< void(int)> exitFunction )

inline

Specifies a function quit the application.

Remarks: Currently only used after printing Bash completion. Default is std::exit().

Definition at line 1177 of file argumentparser.h.

◆ setMainArguments()

void CppUtilities::ArgumentParser::setMainArguments ( const ArgumentInitializerList & mainArguments )

Sets the main arguments for the parser.

The parser will use these argument definitions to when parsing the command line arguments and when printing help information.

Remarks

The parser does not take ownership. Do not destroy the arguments as long as they are used as main arguments.
Sets the first specified argument as default argument if none has been assigned yet and the first argument does not require any values or has no mandatory sub arguments.

Definition at line 790 of file argumentparser.cpp.

◆ setUnknownArgumentBehavior()

void CppUtilities::ArgumentParser::setUnknownArgumentBehavior ( UnknownArgumentBehavior behavior )

inline

Sets how unknown arguments are treated.

The default value is UnknownArgumentBehavior::Fail.

Definition at line 1131 of file argumentparser.h.

◆ specifiedOperation()

Argument * CppUtilities::ArgumentParser::specifiedOperation ( ) const

Returns the first operation argument specified by the user or nullptr if no operation has been specified.

Remarks: Only main arguments are considered. See Argument::specifiedOperation() to check sub arguments of a specific argument.

Definition at line 1049 of file argumentparser.cpp.

◆ unknownArgumentBehavior()

UnknownArgumentBehavior CppUtilities::ArgumentParser::unknownArgumentBehavior ( ) const

inline

Returns how unknown arguments are treated.

The default value is UnknownArgumentBehavior::Fail.

Definition at line 1121 of file argumentparser.h.

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

application/argumentparser.h
application/argumentparser.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ArgumentParser()

Member Function Documentation

◆ actualArgumentCount()

◆ addMainArgument()

◆ checkConstraints()

◆ defaultArgument()

◆ executable()

◆ helpArg() [1/2]

◆ helpArg() [2/2]

◆ invokeCallbacks()

◆ isUncombinableMainArgPresent()

◆ mainArguments()

◆ noColorArg() [1/2]

◆ noColorArg() [2/2]

◆ parseArgs()

◆ printHelp()

◆ readArgs()

◆ resetArgs()

◆ setDefaultArgument()

◆ setExitFunction()

◆ setMainArguments()

◆ setUnknownArgumentBehavior()

◆ specifiedOperation()

◆ unknownArgumentBehavior()