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	assumeDefaultArgument ()
	Assumes the default argument is present (if not already present).
void	ensureDefaultOperation ()
	Ensures a main operation argument is present.
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 1105 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.

◆ assumeDefaultArgument()

void CppUtilities::ArgumentParser::assumeDefaultArgument ( )

Assumes the default argument is present (if not already present).

Remarks

Adds an occurrence to the default argument so this argument is assumed to be present (even though it is not actually present).
This function is automatically called if there are no arguments present at all.
This function may be called manually if no actually relevant arguments are present, e.g. if only global flags are present but no main operation argument. Note that for this concrete example there is also ensureDefaultOperation() (which will call assumeDefaultArgument() internally).

Definition at line 1052 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 1161 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 1142 of file argumentparser.h.

◆ ensureDefaultOperation()

void CppUtilities::ArgumentParser::ensureDefaultOperation ( )

Ensures a main operation argument is present.

Remarks

Assumes the default argument is present if no other main operation argument or the help argument is present.
Requires the default argument to be an operation argument.

Definition at line 1066 of file argumentparser.cpp.

◆ executable()

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

inline

Returns the name of the current executable.

Definition at line 1113 of file argumentparser.h.

◆ helpArg() [1/2]

HelpArgument & CppUtilities::ArgumentParser::helpArg ( )

inline

Returns the --help argument.

Definition at line 1195 of file argumentparser.h.

◆ helpArg() [2/2]

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

inline

Returns the --help argument.

Definition at line 1187 of file argumentparser.h.

◆ invokeCallbacks()

void CppUtilities::ArgumentParser::invokeCallbacks ( )

inline

Invokes all assigned callbacks.

Remarks: Automatically called by parseArgs().

Definition at line 1170 of file argumentparser.h.

◆ isUncombinableMainArgPresent()

bool CppUtilities::ArgumentParser::isUncombinableMainArgPresent ( ) const

Checks whether at least one uncombinable main argument is present.

Definition at line 1097 of file argumentparser.cpp.

◆ mainArguments()

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

inline

Returns the main arguments.

See also: setMainArguments()

Definition at line 1097 of file argumentparser.h.

◆ noColorArg() [1/2]

NoColorArgument & CppUtilities::ArgumentParser::noColorArg ( )

inline

Returns the --no-color argument.

Definition at line 1211 of file argumentparser.h.

◆ noColorArg() [2/2]

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

inline

Returns the --no-color argument.

Definition at line 1203 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 1034 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 1151 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 1179 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 1133 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 1084 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 1123 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()

◆ assumeDefaultArgument()

◆ checkConstraints()

◆ defaultArgument()

◆ ensureDefaultOperation()

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