C++ Utilities  4.12.1
Useful C++ classes and routines such as argument parser, IO and conversion utilities
Public Types | Public Member Functions | Static Public Attributes | List of all members
ApplicationUtilities::Argument Class Reference

The Argument class is a wrapper for command line argument information. More...

#include <argumentparser.h>

Inheritance diagram for ApplicationUtilities::Argument:
[legend]

Public Types

typedef std::function< void(const ArgumentOccurrence &)> CallbackFunction
 

Public Member Functions

 Argument (const char *name, char abbreviation='\0', const char *description=nullptr, const char *example=nullptr)
 Constructs an Argument with the given name, abbreviation and description. More...
 
 ~Argument ()
 Destroys the Argument. More...
 
const char * name () const
 Returns the name of the argument. More...
 
void setName (const char *name)
 Sets the name of the argument. More...
 
char abbreviation () const
 Returns the abbreviation of the argument. More...
 
void setAbbreviation (char abbreviation)
 Sets the abbreviation of the argument. More...
 
const char * environmentVariable () const
 Returns the environment variable queried when firstValue() is called. More...
 
void setEnvironmentVariable (const char *environmentVariable)
 Sets the environment variable queried when firstValue() is called. More...
 
const char * description () const
 Returns the description of the argument. More...
 
void setDescription (const char *description)
 Sets the description of the argument. More...
 
const char * example () const
 Returns the usage example of the argument. More...
 
void setExample (const char *example)
 Sets the a usage example for the argument. More...
 
const std::vector< const char * > & values (std::size_t occurrence=0) const
 Returns the parameter values for the specified occurrence of argument. More...
 
const char * firstValue () const
 Returns the first parameter value of the first occurrence of the argument. More...
 
std::size_t requiredValueCount () const
 Returns the number of values which are required to be given for this argument. More...
 
void setRequiredValueCount (std::size_t requiredValueCount)
 Sets the number of values which are required to be given for this argument. More...
 
const std::vector< const char * > & valueNames () const
 Returns the names of the requried values. More...
 
void setValueNames (std::initializer_list< const char *> valueNames)
 Sets the names of the requried values. More...
 
void appendValueName (const char *valueName)
 Appends a value name. More...
 
bool allRequiredValuesPresent (std::size_t occurrence=0) const
 Returns an indication whether all required values are present. More...
 
bool isPresent () const
 Returns an indication whether the argument could be detected when parsing. More...
 
std::size_t occurrences () const
 Returns how often the argument could be detected when parsing. More...
 
std::size_t index (std::size_t occurrence) const
 Returns the indices of the argument's occurences which could be detected when parsing. More...
 
std::size_t minOccurrences () const
 Returns the minimum number of occurrences. More...
 
std::size_t maxOccurrences () const
 Returns the maximum number of occurrences. More...
 
void setConstraints (std::size_t minOccurrences, std::size_t maxOccurrences)
 Sets the allowed number of occurrences. More...
 
const std::vector< Argument * > & path (std::size_t occurrence=0) const
 Returns the path of the specified occurrence. More...
 
bool isRequired () const
 Returns an indication whether the argument is mandatory. More...
 
void setRequired (bool required)
 Sets whether this argument is mandatory or not. More...
 
bool isCombinable () const
 Returns an indication whether the argument is combinable. More...
 
void setCombinable (bool value)
 Sets whether this argument can be combined. More...
 
bool isImplicit () const
 Returns an indication whether the argument is an implicit argument. More...
 
void setImplicit (bool value)
 Sets whether the argument is an implicit argument. More...
 
bool denotesOperation () const
 Returns whether the argument denotes the operation. More...
 
void setDenotesOperation (bool denotesOperation)
 Sets whether the argument denotes the operation. More...
 
const CallbackFunctioncallback () const
 Returns the assigned callback function. More...
 
void setCallback (CallbackFunction callback)
 Sets a callback function which will be called by the parser if the argument could be found and no parsing errors occured. More...
 
void printInfo (std::ostream &os, unsigned char indentation=0) const
 Writes the name, the abbreviation and other information about the Argument to the give ostream. More...
 
const ArgumentVectorsubArguments () const
 Returns the secondary arguments for this argument. More...
 
void setSubArguments (const ArgumentInitializerList &subArguments)
 Sets the secondary arguments for this arguments. More...
 
void addSubArgument (Argument *arg)
 Adds arg as a secondary argument for this argument. More...
 
bool hasSubArguments () const
 Returns an indication whether the argument has secondary arguments. More...
 
const ArgumentVector parents () const
 Returns the parents of this argument. More...
 
bool isMainArgument () const
 Returns an indication whether the argument is used as main argument. More...
 
bool isParentPresent () const
 Returns whether at least one parent argument is present. More...
 
ValueCompletionBehavior valueCompletionBehaviour () const
 Returns the items to be considered when generating completion for the values. More...
 
void setValueCompletionBehavior (ValueCompletionBehavior valueCompletionBehaviour)
 Sets the items to be considered when generating completion for the values. More...
 
const char * preDefinedCompletionValues () const
 Returns the assigned values used when generating completion for the values. More...
 
void setPreDefinedCompletionValues (const char *preDefinedCompletionValues)
 Assignes the values to be used when generating completion for the values. More...
 
ArgumentconflictsWithArgument () const
 Checks if this arguments conflicts with other arguments. More...
 
ArgumentwouldConflictWithArgument () const
 Checks if this argument would conflict with other arguments if it was present. More...
 
ArgumentspecifiedOperation () const
 Returns the first operation argument specified by the user or nullptr if no operation has been specified. More...
 
void reset ()
 Resets occurrences (indices, values and paths). More...
 
void resetRecursively ()
 Resets this argument and all sub arguments recursively. More...
 
const std::vector< ArgumentOccurrence > & occurrenceInfo () const
 Returns information about all occurrences of the argument which have been detected when parsing. More...
 
std::vector< ArgumentOccurrence > & occurrenceInfo ()
 Returns information about all occurrences of the argument which have been detected when parsing. More...
 

Static Public Attributes

static constexpr std::size_t varValueCount = std::numeric_limits<std::size_t>::max()
 Denotes a variable number of values. More...
 

Detailed Description

The Argument class is a wrapper for command line argument information.

Instaces of the Argument class are used as definition when parsing command line arguments. Arguments can be assigned to an ArgumentParser using ArgumentParser::setMainArguments() and to another Argument instance using Argument::setSecondaryArguments().

Definition at line 176 of file argumentparser.h.

Member Typedef Documentation

◆ CallbackFunction

Definition at line 182 of file argumentparser.h.

Constructor & Destructor Documentation

◆ Argument()

ApplicationUtilities::Argument::Argument ( const char *  name,
char  abbreviation = '\0',
const char *  description = nullptr,
const char *  example = nullptr 
)

Constructs an Argument with the given name, abbreviation and description.

The name and the abbreviation mustn't contain any whitespaces. The name mustn't be empty. The abbreviation and the description might be empty.

Definition at line 372 of file argumentparser.cpp.

◆ ~Argument()

ApplicationUtilities::Argument::~Argument ( )

Destroys the Argument.

Definition at line 394 of file argumentparser.cpp.

Member Function Documentation

◆ abbreviation()

char ApplicationUtilities::Argument::abbreviation ( ) const
inline

Returns the abbreviation of the argument.

The parser compares the abbreviation with the characters following a "-" prefix to identify arguments.

Definition at line 349 of file argumentparser.h.

◆ addSubArgument()

void ApplicationUtilities::Argument::addSubArgument ( Argument arg)

Adds arg as a secondary argument for this argument.

See also
secondaryArguments()
setSecondaryArguments()
hasSecondaryArguments()

Definition at line 530 of file argumentparser.cpp.

◆ allRequiredValuesPresent()

bool ApplicationUtilities::Argument::allRequiredValuesPresent ( std::size_t  occurrence = 0) const
inline

Returns an indication whether all required values are present.

Definition at line 517 of file argumentparser.h.

◆ appendValueName()

void ApplicationUtilities::Argument::appendValueName ( const char *  valueName)
inline

Appends a value name.

The value names names will be shown when printing information about the argument.

See also
setValueNames()
valueNames()

Definition at line 509 of file argumentparser.h.

◆ callback()

const Argument::CallbackFunction & ApplicationUtilities::Argument::callback ( ) const
inline

Returns the assigned callback function.

See also
setCallback()

Definition at line 690 of file argumentparser.h.

◆ conflictsWithArgument()

Argument * ApplicationUtilities::Argument::conflictsWithArgument ( ) const

Checks if this arguments conflicts with other arguments.

If the argument is in conflict with an other argument this argument will be returned. Otherwise nullptr will be returned.

Remarks
Conflicts with main arguments aren't considered by this method!

Definition at line 565 of file argumentparser.cpp.

◆ denotesOperation()

bool ApplicationUtilities::Argument::denotesOperation ( ) const
inline

Returns whether the argument denotes the operation.

An argument which denotes the operation might be specified withouth "--" or "-" prefix as first main argument.

The default value is false, except for OperationArgument instances.

See also
setDenotesOperation()

Definition at line 672 of file argumentparser.h.

◆ description()

const char * ApplicationUtilities::Argument::description ( ) const
inline

Returns the description of the argument.

The parser uses the description when printing help information.

Definition at line 391 of file argumentparser.h.

◆ environmentVariable()

const char * ApplicationUtilities::Argument::environmentVariable ( ) const
inline

Returns the environment variable queried when firstValue() is called.

See also
firstValue(), setEnvironmentVariable()

Definition at line 372 of file argumentparser.h.

◆ example()

const char * ApplicationUtilities::Argument::example ( ) const
inline

Returns the usage example of the argument.

The parser uses the description when printing help information.

Definition at line 411 of file argumentparser.h.

◆ firstValue()

const char * ApplicationUtilities::Argument::firstValue ( ) const

Returns the first parameter value of the first occurrence of the argument.

Remarks
  • If the argument is not present and the an environment variable has been set using setEnvironmentVariable() the value of the specified variable will be returned.
  • Returns nullptr if no value is available though.

Definition at line 405 of file argumentparser.cpp.

◆ hasSubArguments()

bool ApplicationUtilities::Argument::hasSubArguments ( ) const
inline

Returns an indication whether the argument has secondary arguments.

See also
secondaryArguments()
setSecondaryArguments()

Definition at line 723 of file argumentparser.h.

◆ index()

std::size_t ApplicationUtilities::Argument::index ( std::size_t  occurrence) const
inline

Returns the indices of the argument's occurences which could be detected when parsing.

Definition at line 560 of file argumentparser.h.

◆ isCombinable()

bool ApplicationUtilities::Argument::isCombinable ( ) const
inline

Returns an indication whether the argument is combinable.

The parser will complain if two arguments labeled as uncombinable are present at the same time.

See also
setCombinable()

Definition at line 644 of file argumentparser.h.

◆ isImplicit()

bool ApplicationUtilities::Argument::isImplicit ( ) const
inline

Returns an indication whether the argument is an implicit argument.

See also
setImplicit()

Definition at line 527 of file argumentparser.h.

◆ isMainArgument()

bool ApplicationUtilities::Argument::isMainArgument ( ) const
inline

Returns an indication whether the argument is used as main argument.

An argument used as main argument shouldn't be used as secondary arguments at the same time.

Definition at line 749 of file argumentparser.h.

◆ isParentPresent()

bool ApplicationUtilities::Argument::isParentPresent ( ) const

Returns whether at least one parent argument is present.

Remarks
Returns always true for main arguments.

Definition at line 544 of file argumentparser.cpp.

◆ isPresent()

bool ApplicationUtilities::Argument::isPresent ( ) const
inline

Returns an indication whether the argument could be detected when parsing.

Definition at line 544 of file argumentparser.h.

◆ isRequired()

bool ApplicationUtilities::Argument::isRequired ( ) const
inline

Returns an indication whether the argument is mandatory.

The parser will complain if a mandatory argument is not present.

The default value is false.

See also
setRequired()

Definition at line 613 of file argumentparser.h.

◆ maxOccurrences()

std::size_t ApplicationUtilities::Argument::maxOccurrences ( ) const
inline

Returns the maximum number of occurrences.

If the argument occurs more often, the parser will complain.

Definition at line 580 of file argumentparser.h.

◆ minOccurrences()

std::size_t ApplicationUtilities::Argument::minOccurrences ( ) const
inline

Returns the minimum number of occurrences.

If the argument occurs not that many times, the parser will complain.

Definition at line 570 of file argumentparser.h.

◆ name()

const char * ApplicationUtilities::Argument::name ( ) const
inline

Returns the name of the argument.

The parser compares the name with the characters following a "--" prefix to identify arguments.

Definition at line 319 of file argumentparser.h.

◆ occurrenceInfo() [1/2]

const std::vector< ArgumentOccurrence > & ApplicationUtilities::Argument::occurrenceInfo ( ) const
inline

Returns information about all occurrences of the argument which have been detected when parsing.

Remarks
The convenience methods isPresent(), values() and path() provide direct access to these information for a particular occurrence.

Definition at line 804 of file argumentparser.h.

◆ occurrenceInfo() [2/2]

std::vector< ArgumentOccurrence > & ApplicationUtilities::Argument::occurrenceInfo ( )
inline

Returns information about all occurrences of the argument which have been detected when parsing.

Remarks
This information is meant to be set by the ArgumentParser. Modifying it directly is likely not a good idea. This method has been added primarily for testing purposes. In this case it might make sense to skip the actual parsing and just provide some dummy values.

Definition at line 815 of file argumentparser.h.

◆ occurrences()

std::size_t ApplicationUtilities::Argument::occurrences ( ) const
inline

Returns how often the argument could be detected when parsing.

Definition at line 552 of file argumentparser.h.

◆ parents()

const ArgumentVector ApplicationUtilities::Argument::parents ( ) const
inline

Returns the parents of this argument.

If this argument is used as secondary argument, the arguments which contain this argument as secondary arguments are returned as "parents" of this argument.

If this argument is used as a main argument shouldn't be used as secondary argument at the same time and thus have no parents.

Definition at line 738 of file argumentparser.h.

◆ path()

const std::vector< Argument * > & ApplicationUtilities::Argument::path ( std::size_t  occurrence = 0) const
inline

Returns the path of the specified occurrence.

Definition at line 599 of file argumentparser.h.

◆ preDefinedCompletionValues()

const char * ApplicationUtilities::Argument::preDefinedCompletionValues ( ) const
inline

Returns the assigned values used when generating completion for the values.

Definition at line 779 of file argumentparser.h.

◆ printInfo()

void ApplicationUtilities::Argument::printInfo ( std::ostream &  os,
unsigned char  indentation = 0 
) const

Writes the name, the abbreviation and other information about the Argument to the give ostream.

Definition at line 419 of file argumentparser.cpp.

◆ requiredValueCount()

std::size_t ApplicationUtilities::Argument::requiredValueCount ( ) const
inline

Returns the number of values which are required to be given for this argument.

The parser will expect that many values when parsing command line arguments. A negative value indicates a variable number of arguments to be expected.

The default value is 0, except for ConfigValueArgument instances.

See also
setRequiredValueCount()
valueNames()
setValueNames()

Definition at line 450 of file argumentparser.h.

◆ reset()

void ApplicationUtilities::Argument::reset ( )
inline

Resets occurrences (indices, values and paths).

Definition at line 795 of file argumentparser.h.

◆ resetRecursively()

void ApplicationUtilities::Argument::resetRecursively ( )

Resets this argument and all sub arguments recursively.

See also
Argument::reset()

Definition at line 610 of file argumentparser.cpp.

◆ setAbbreviation()

void ApplicationUtilities::Argument::setAbbreviation ( char  abbreviation)
inline

Sets the abbreviation of the argument.

The abbreviation might be empty but mustn't be white spaces, equation char, single quote, double quote or newline.

The parser compares the abbreviation with the characters following a "-" prefix to identify arguments.

Definition at line 361 of file argumentparser.h.

◆ setCallback()

void ApplicationUtilities::Argument::setCallback ( Argument::CallbackFunction  callback)
inline

Sets a callback function which will be called by the parser if the argument could be found and no parsing errors occured.

Remarks
The callback will be called for each occurrence of the argument.
See also
callback()

Definition at line 701 of file argumentparser.h.

◆ setCombinable()

void ApplicationUtilities::Argument::setCombinable ( bool  value)
inline

Sets whether this argument can be combined.

The parser will complain if two arguments labeled as uncombinable are present at the same time.

See also
isCombinable()

Definition at line 657 of file argumentparser.h.

◆ setConstraints()

void ApplicationUtilities::Argument::setConstraints ( std::size_t  minOccurrences,
std::size_t  maxOccurrences 
)
inline

Sets the allowed number of occurrences.

See also
minOccurrences()
maxOccurrences()

Definition at line 590 of file argumentparser.h.

◆ setDenotesOperation()

void ApplicationUtilities::Argument::setDenotesOperation ( bool  denotesOperation)
inline

Sets whether the argument denotes the operation.

See also
denotesOperation()

Definition at line 681 of file argumentparser.h.

◆ setDescription()

void ApplicationUtilities::Argument::setDescription ( const char *  description)
inline

Sets the description of the argument.

The parser uses the description when printing help information.

Definition at line 401 of file argumentparser.h.

◆ setEnvironmentVariable()

void ApplicationUtilities::Argument::setEnvironmentVariable ( const char *  environmentVariable)
inline

Sets the environment variable queried when firstValue() is called.

See also
firstValue(), environmentVariable()

Definition at line 381 of file argumentparser.h.

◆ setExample()

void ApplicationUtilities::Argument::setExample ( const char *  example)
inline

Sets the a usage example for the argument.

The parser uses the description when printing help information.

Definition at line 421 of file argumentparser.h.

◆ setImplicit()

void ApplicationUtilities::Argument::setImplicit ( bool  implicit)
inline

Sets whether the argument is an implicit argument.

See also
isImplicit()

Definition at line 536 of file argumentparser.h.

◆ setName()

void ApplicationUtilities::Argument::setName ( const char *  name)
inline

Sets the name of the argument.

The name mustn't be empty, start with a minus or contain white spaces, equation chars, quotes and newlines.

The parser compares the name with the characters following a "--" prefix to identify arguments.

Definition at line 331 of file argumentparser.h.

◆ setPreDefinedCompletionValues()

void ApplicationUtilities::Argument::setPreDefinedCompletionValues ( const char *  preDefinedCompletionValues)
inline

Assignes the values to be used when generating completion for the values.

Definition at line 787 of file argumentparser.h.

◆ setRequired()

void ApplicationUtilities::Argument::setRequired ( bool  required)
inline

Sets whether this argument is mandatory or not.

The parser will complain if a mandatory argument is not present.

Definition at line 625 of file argumentparser.h.

◆ setRequiredValueCount()

void ApplicationUtilities::Argument::setRequiredValueCount ( std::size_t  requiredValueCount)
inline

Sets the number of values which are required to be given for this argument.

The parser will expect that many values when parsing command line arguments. Pass Argument::varValueCount for a variable number of arguments to be expected.

See also
requiredValueCount()
valueNames()
setValueNames()

Definition at line 467 of file argumentparser.h.

◆ setSubArguments()

void ApplicationUtilities::Argument::setSubArguments ( const ArgumentInitializerList secondaryArguments)

Sets the secondary arguments for this arguments.

The given arguments will be considered as secondary arguments of this argument by the argument parser. This means that the parser will complain if these arguments are given, but not this argument. If secondary arguments are labeled as mandatory their parent is also mandatory.

The Argument does not take ownership. Do not destroy the given arguments as long as they are used as secondary arguments.

See also
secondaryArguments()
addSecondaryArgument()
hasSecondaryArguments()

Definition at line 506 of file argumentparser.cpp.

◆ setValueCompletionBehavior()

void ApplicationUtilities::Argument::setValueCompletionBehavior ( ValueCompletionBehavior  completionValues)
inline

Sets the items to be considered when generating completion for the values.

By default, files and directories are considered, unless pre-defined values have been specified using setPreDefinedCompletionValues().

Definition at line 771 of file argumentparser.h.

◆ setValueNames()

void ApplicationUtilities::Argument::setValueNames ( std::initializer_list< const char *>  valueNames)
inline

Sets the names of the requried values.

These names will be used when printing information about the argument.

If the number of value names is higher than the number of requried values the additional value names will be ignored. If the number of value names is lesser than the number of requried values generic values will be used for the missing names.

See also
appendValueName()
valueNames()
requiredValueCount()

Definition at line 498 of file argumentparser.h.

◆ specifiedOperation()

Argument * ApplicationUtilities::Argument::specifiedOperation ( ) const

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

Remarks
Only direct sub arguments of this argument are considered.

Definition at line 596 of file argumentparser.cpp.

◆ subArguments()

const ArgumentVector & ApplicationUtilities::Argument::subArguments ( ) const
inline

Returns the secondary arguments for this argument.

See also
setSecondaryArguments()
hasSecondaryArguments()

Definition at line 712 of file argumentparser.h.

◆ valueCompletionBehaviour()

ValueCompletionBehavior ApplicationUtilities::Argument::valueCompletionBehaviour ( ) const
inline

Returns the items to be considered when generating completion for the values.

By default, files and directories are considered, unless pre-defined values have been specified using setPreDefinedCompletionValues().

Definition at line 760 of file argumentparser.h.

◆ valueNames()

const std::vector< const char * > & ApplicationUtilities::Argument::valueNames ( ) const
inline

Returns the names of the requried values.

These names will be shown when printing information about the argument.

See also
setValueNames()
appendValueName()

Definition at line 480 of file argumentparser.h.

◆ values()

const std::vector< const char * > & ApplicationUtilities::Argument::values ( std::size_t  occurrence = 0) const
inline

Returns the parameter values for the specified occurrence of argument.

Remarks
  • The values are set by the parser when parsing the command line arguments.
  • The specified occurrence must be less than occurrences().

Definition at line 432 of file argumentparser.h.

◆ wouldConflictWithArgument()

Argument * ApplicationUtilities::Argument::wouldConflictWithArgument ( ) const

Checks if this argument would conflict with other arguments if it was present.

If the argument is in conflict with an other argument this argument will be returned. Otherwise nullptr will be returned.

Remarks
Conflicts with main arguments aren't considered by this method!

Definition at line 578 of file argumentparser.cpp.

Member Data Documentation

◆ varValueCount

constexpr std::size_t ApplicationUtilities::Argument::varValueCount = std::numeric_limits<std::size_t>::max()
static

Denotes a variable number of values.

See also
setRequiredValueCount()

Definition at line 246 of file argumentparser.h.


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