C++ Utilities  4.17.0
Useful C++ classes and routines such as argument parser, IO and conversion utilities
Public Member Functions | List of all members
ApplicationUtilities::ArgumentParser Class Reference

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

#include <argumentparser.h>

Public Member Functions

 ArgumentParser ()
 Constructs a new ArgumentParser. More...
 
const ArgumentVectormainArguments () const
 Returns the main arguments. More...
 
void setMainArguments (const ArgumentInitializerList &mainArguments)
 Sets the main arguments for the parser. More...
 
void addMainArgument (Argument *argument)
 Adds the specified argument to the main argument. More...
 
void printHelp (std::ostream &os) const
 Prints help text for all assigned arguments. More...
 
void parseArgs (int argc, const char *const *argv)
 Parses the specified command line arguments. More...
 
void parseArgsOrExit (int argc, const char *const *argv)
 Parses the specified command line arguments. More...
 
void parseArgsExt (int argc, const char *const *argv, ParseArgumentBehavior behavior=ParseArgumentBehavior::CheckConstraints|ParseArgumentBehavior::InvokeCallbacks|ParseArgumentBehavior::ExitOnFailure)
 Parses the specified command line arguments. More...
 
void readArgs (int argc, const char *const *argv)
 Parses the specified command line arguments. More...
 
void resetArgs ()
 Resets all Argument instances assigned as mainArguments() and sub arguments. More...
 
void checkConstraints ()
 Checks whether contraints are violated. More...
 
void invokeCallbacks ()
 Invokes all assigned callbacks. More...
 
unsigned int actualArgumentCount () const
 Returns the actual number of arguments that could be found when parsing. More...
 
const char * executable () const
 Returns the name of the current executable. More...
 
UnknownArgumentBehavior unknownArgumentBehavior () const
 Returns how unknown arguments are treated. More...
 
void setUnknownArgumentBehavior (UnknownArgumentBehavior behavior)
 Sets how unknown arguments are treated. More...
 
ArgumentdefaultArgument () const
 Returns the default argument. More...
 
void setDefaultArgument (Argument *argument)
 Sets the default argument. More...
 
ArgumentspecifiedOperation () const
 Returns the first operation argument specified by the user or nullptr if no operation has been specified. More...
 
bool isUncombinableMainArgPresent () const
 Checks whether at least one uncombinable main argument is present. More...
 

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 ApplicationUtilities::Failure).

Definition at line 394 of file argumentparser.h.

Constructor & Destructor Documentation

◆ ArgumentParser()

ApplicationUtilities::ArgumentParser::ArgumentParser ( )

Constructs a new ArgumentParser.

Definition at line 712 of file argumentparser.cpp.

Member Function Documentation

◆ actualArgumentCount()

unsigned int ApplicationUtilities::ArgumentParser::actualArgumentCount ( ) const
inline

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

Definition at line 967 of file argumentparser.h.

◆ addMainArgument()

void ApplicationUtilities::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 761 of file argumentparser.cpp.

◆ checkConstraints()

void ApplicationUtilities::ArgumentParser::checkConstraints ( )
inline

Checks whether contraints are violated.

Remarks
Automatically called by parseArgs().
Exceptions
ThrowsFailure if constraints are violated.

Definition at line 1023 of file argumentparser.h.

◆ defaultArgument()

Argument * ApplicationUtilities::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 1004 of file argumentparser.h.

◆ executable()

const char * ApplicationUtilities::ArgumentParser::executable ( ) const
inline

Returns the name of the current executable.

Definition at line 975 of file argumentparser.h.

◆ invokeCallbacks()

void ApplicationUtilities::ArgumentParser::invokeCallbacks ( )
inline

Invokes all assigned callbacks.

Remarks
Automatically called by parseArgs().

Definition at line 1032 of file argumentparser.h.

◆ isUncombinableMainArgPresent()

bool ApplicationUtilities::ArgumentParser::isUncombinableMainArgPresent ( ) const

Checks whether at least one uncombinable main argument is present.

Definition at line 1011 of file argumentparser.cpp.

◆ mainArguments()

const ArgumentVector & ApplicationUtilities::ArgumentParser::mainArguments ( ) const
inline

Returns the main arguments.

See also
setMainArguments()

Definition at line 959 of file argumentparser.h.

◆ parseArgs()

void ApplicationUtilities::ArgumentParser::parseArgs ( 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.
  • Calls the assigned callbacks if no constraints are violated.
  • This method will not return in case shell completion is requested. This behavior can be altered by overriding ApplicationUtilities::exitFunction which defaults to &std::exit.
Exceptions
ThrowsFailure if the specified arguments are invalid or violate the constraints defined by the Argument instances.
See also
readArgs(), parseArgsOrExit()

Definition at line 850 of file argumentparser.cpp.

◆ parseArgsExt()

void ApplicationUtilities::ArgumentParser::parseArgsExt ( 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
Exceptions
ThrowsFailure if the specified arguments are invalid and the ParseArgumentBehavior::ExitOnFailure flag is not present.
See also
parseArgs(), readArgs(), parseArgsOrExit()
Deprecated:
In next major release, this method will be available as parseArgs().

Definition at line 886 of file argumentparser.cpp.

◆ parseArgsOrExit()

void ApplicationUtilities::ArgumentParser::parseArgsOrExit ( int  argc,
const char *const *  argv 
)

Parses the specified command line arguments.

Remarks
The same as parseArgs(), except that this method will not throw an exception in the error case. Instead, it will print an error message and terminate the application with exit code 1.
See also
parseArgs(), readArgs()
Deprecated:
In next major release, this method will be removed. parseArgs() can serve the same purpose then.

Definition at line 864 of file argumentparser.cpp.

◆ printHelp()

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

Prints help text for all assigned arguments.

Definition at line 770 of file argumentparser.cpp.

◆ readArgs()

void ApplicationUtilities::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 ApplicationUtilities::exitFunction which defaults to &std::exit.
Exceptions
ThrowsFailure if the specified arguments are invalid.
See also
parseArgs(), parseArgsOrExit()
Deprecated:
In next major release, this method will be private. parseArgs() can serve the same purpose then.

Definition at line 922 of file argumentparser.cpp.

◆ resetArgs()

void ApplicationUtilities::ArgumentParser::resetArgs ( )

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

See also
Argument::reset()

Definition at line 985 of file argumentparser.cpp.

◆ setDefaultArgument()

void ApplicationUtilities::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 1013 of file argumentparser.h.

◆ setMainArguments()

void ApplicationUtilities::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 729 of file argumentparser.cpp.

◆ setUnknownArgumentBehavior()

void ApplicationUtilities::ArgumentParser::setUnknownArgumentBehavior ( UnknownArgumentBehavior  behavior)
inline

Sets how unknown arguments are treated.

The default value is UnknownArgumentBehavior::Fail.

Definition at line 995 of file argumentparser.h.

◆ specifiedOperation()

Argument * ApplicationUtilities::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 998 of file argumentparser.cpp.

◆ unknownArgumentBehavior()

UnknownArgumentBehavior ApplicationUtilities::ArgumentParser::unknownArgumentBehavior ( ) const
inline

Returns how unknown arguments are treated.

The default value is UnknownArgumentBehavior::Fail.

Definition at line 985 of file argumentparser.h.


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