C++ Utilities: CppUtilities::ArgumentParser Class Reference

C++ Utilities 5.35.0 Useful C++ classes and routines such as argument parser, IO and conversion utilities

Loading...
Searching...
No Matches
Public Member Functions | List of all members
CppUtilities::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.
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