C++ Utilities  4.17.0
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...
 
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...
 
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 an 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...
 
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...
 
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...
 
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...
 
const std::vector< const char * > & values (std::size_t occurrence=0) const
 Returns the parameter values for the specified occurrence of argument. More...
 
template<typename... TargetType>
std::tuple< TargetType... > valuesAs (std::size_t occurrence=0) const
 Converts the present values for the specified occurrence to the specified target types. More...
 
template<typename... TargetType>
std::vector< std::tuple< TargetType... > > allValuesAs () const
 Converts the present values for all occurrence to the specified target types. More...
 
const char * firstValue () const
 Returns the first parameter value of the first occurrence of the argument. 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...
 
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...
 
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...
 
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...
 
void reset ()
 Resets occurrences (indices, values and paths). More...
 
void resetRecursively ()
 Resets this argument and all sub arguments recursively. 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 255 of file argumentparser.h.

Member Typedef Documentation

◆ CallbackFunction

Definition at line 261 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 450 of file argumentparser.cpp.

◆ ~Argument()

ApplicationUtilities::Argument::~Argument ( )

Destroys the Argument.

Definition at line 472 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 480 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 608 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 648 of file argumentparser.h.

◆ allValuesAs()

template<typename... TargetType>
std::vector< std::tuple< TargetType... > > ApplicationUtilities::Argument::allValuesAs ( ) const

Converts the present values for all occurrence to the specified target types.

For each occurrence, there must be as many values present as types are specified.

Exceptions
ThrowsArgumentUtilities::Failure when the number of present values is not sufficient or a conversion error occurs.
Remarks
Still experimental. Might be removed/adjusted in next minor release.

Definition at line 382 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 640 of file argumentparser.h.

◆ callback()

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

Returns the assigned callback function.

See also
setCallback()

Definition at line 821 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 643 of file argumentparser.cpp.

◆ denotesOperation()

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

Returns whether the argument denotes an operation.

An argument which denotes an operation might be specified without "--" or "-" prefix.

The default value is false, except for OperationArgument instances.

See also
setDenotesOperation()

Definition at line 803 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 522 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 503 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 542 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 483 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 854 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 691 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 775 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 658 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 882 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 622 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 675 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 744 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 711 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 701 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 450 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 939 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 950 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 683 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.

Todo:
Return by reference in v5.

Definition at line 871 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 730 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 912 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 497 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 581 of file argumentparser.h.

◆ reset()

void ApplicationUtilities::Argument::reset ( )
inline

Resets occurrences (indices, values and paths).

So parsing results are wiped while the argument definition is preserved.

Definition at line 930 of file argumentparser.h.

◆ resetRecursively()

void ApplicationUtilities::Argument::resetRecursively ( )

Resets this argument and all sub arguments recursively.

See also
Argument::reset()

Definition at line 688 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 492 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 832 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 788 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 721 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 812 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 532 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 512 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 552 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 667 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 462 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 920 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 756 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 598 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 584 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 904 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 629 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 674 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 843 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 893 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 611 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 563 of file argumentparser.h.

◆ valuesAs()

template<typename... TargetType>
std::tuple< TargetType... > ApplicationUtilities::Argument::valuesAs ( std::size_t  occurrence = 0) const

Converts the present values for the specified occurrence to the specified target types.

There must be as many values present as types are specified.

Exceptions
ThrowsArgumentUtilities::Failure when the number of present values is not sufficient or a conversion error occurs.
Remarks
Still experimental. Might be removed/adjusted in next minor release.

Definition at line 372 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 656 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 340 of file argumentparser.h.


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