C++ Utilities
4.17.0
Useful C++ classes and routines such as argument parser, IO and conversion utilities
|
The Argument class is a wrapper for command line argument information. More...
#include <argumentparser.h>
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 CallbackFunction & | callback () 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 ArgumentVector & | subArguments () 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... | |
Argument * | conflictsWithArgument () const |
Checks if this arguments conflicts with other arguments. More... | |
Argument * | wouldConflictWithArgument () const |
Checks if this argument would conflict with other arguments if it was present. More... | |
Argument * | specifiedOperation () 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... | |
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.
typedef std::function<void(const ArgumentOccurrence &)> ApplicationUtilities::Argument::CallbackFunction |
Definition at line 261 of file argumentparser.h.
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.
ApplicationUtilities::Argument::~Argument | ( | ) |
Destroys the Argument.
Definition at line 472 of file argumentparser.cpp.
|
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.
void ApplicationUtilities::Argument::addSubArgument | ( | Argument * | arg | ) |
Adds arg as a secondary argument for this argument.
Definition at line 608 of file argumentparser.cpp.
|
inline |
Returns an indication whether all required values are present.
Definition at line 648 of file argumentparser.h.
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.
Throws | ArgumentUtilities::Failure when the number of present values is not sufficient or a conversion error occurs. |
Definition at line 382 of file argumentparser.h.
|
inline |
Appends a value name.
The value names names will be shown when printing information about the argument.
Definition at line 640 of file argumentparser.h.
|
inline |
Returns the assigned callback function.
Definition at line 821 of file argumentparser.h.
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.
Definition at line 643 of file argumentparser.cpp.
|
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.
Definition at line 803 of file argumentparser.h.
|
inline |
Returns the description of the argument.
The parser uses the description when printing help information.
Definition at line 522 of file argumentparser.h.
|
inline |
Returns the environment variable queried when firstValue() is called.
Definition at line 503 of file argumentparser.h.
|
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.
const char * ApplicationUtilities::Argument::firstValue | ( | ) | const |
Returns the first parameter value of the first occurrence of the argument.
Definition at line 483 of file argumentparser.cpp.
|
inline |
Returns an indication whether the argument has secondary arguments.
Definition at line 854 of file argumentparser.h.
|
inline |
Returns the indices of the argument's occurences which could be detected when parsing.
Definition at line 691 of file argumentparser.h.
|
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.
Definition at line 775 of file argumentparser.h.
|
inline |
Returns an indication whether the argument is an implicit argument.
Definition at line 658 of file argumentparser.h.
|
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.
bool ApplicationUtilities::Argument::isParentPresent | ( | ) | const |
Returns whether at least one parent argument is present.
Definition at line 622 of file argumentparser.cpp.
|
inline |
Returns an indication whether the argument could be detected when parsing.
Definition at line 675 of file argumentparser.h.
|
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.
Definition at line 744 of file argumentparser.h.
|
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.
|
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.
|
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.
|
inline |
Returns information about all occurrences of the argument which have been detected when parsing.
Definition at line 939 of file argumentparser.h.
|
inline |
Returns information about all occurrences of the argument which have been detected when parsing.
Definition at line 950 of file argumentparser.h.
|
inline |
Returns how often the argument could be detected when parsing.
Definition at line 683 of file argumentparser.h.
|
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 871 of file argumentparser.h.
|
inline |
Returns the path of the specified occurrence.
Definition at line 730 of file argumentparser.h.
|
inline |
Returns the assigned values used when generating completion for the values.
Definition at line 912 of file argumentparser.h.
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.
|
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.
Definition at line 581 of file argumentparser.h.
|
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.
void ApplicationUtilities::Argument::resetRecursively | ( | ) |
Resets this argument and all sub arguments recursively.
Definition at line 688 of file argumentparser.cpp.
|
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.
|
inline |
Sets a callback function which will be called by the parser if the argument could be found and no parsing errors occured.
Definition at line 832 of file argumentparser.h.
|
inline |
Sets whether this argument can be combined.
The parser will complain if two arguments labeled as uncombinable are present at the same time.
Definition at line 788 of file argumentparser.h.
|
inline |
Sets the allowed number of occurrences.
Definition at line 721 of file argumentparser.h.
|
inline |
Sets whether the argument denotes the operation.
Definition at line 812 of file argumentparser.h.
|
inline |
Sets the description of the argument.
The parser uses the description when printing help information.
Definition at line 532 of file argumentparser.h.
|
inline |
Sets the environment variable queried when firstValue() is called.
Definition at line 512 of file argumentparser.h.
|
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.
|
inline |
Sets whether the argument is an implicit argument.
Definition at line 667 of file argumentparser.h.
|
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.
|
inline |
Assignes the values to be used when generating completion for the values.
Definition at line 920 of file argumentparser.h.
|
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.
|
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.
Definition at line 598 of file argumentparser.h.
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.
Definition at line 584 of file argumentparser.cpp.
|
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.
|
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.
Definition at line 629 of file argumentparser.h.
Argument * ApplicationUtilities::Argument::specifiedOperation | ( | ) | const |
Returns the first operation argument specified by the user or nullptr if no operation has been specified.
Definition at line 674 of file argumentparser.cpp.
|
inline |
Returns the secondary arguments for this argument.
Definition at line 843 of file argumentparser.h.
|
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.
|
inline |
Returns the names of the requried values.
These names will be shown when printing information about the argument.
Definition at line 611 of file argumentparser.h.
|
inline |
Returns the parameter values for the specified occurrence of argument.
Definition at line 563 of file argumentparser.h.
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.
Throws | ArgumentUtilities::Failure when the number of present values is not sufficient or a conversion error occurs. |
Definition at line 372 of file argumentparser.h.
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.
Definition at line 656 of file argumentparser.cpp.
|
static |
Denotes a variable number of values.
Definition at line 340 of file argumentparser.h.