C++ Utilities 5.14.0
Useful C++ classes and routines such as argument parser, IO and conversion utilities
argumentparser.h
Go to the documentation of this file.
1#ifndef APPLICATION_UTILITIES_ARGUMENTPARSER_H
2#define APPLICATION_UTILITIES_ARGUMENTPARSER_H
3
4#include "../conversion/stringconversion.h"
5#include "../misc/traits.h"
6
7#include <functional>
8#include <initializer_list>
9#include <limits>
10#include <vector>
11#ifdef CPP_UTILITIES_DEBUG_BUILD
12#include <cassert>
13#endif
14
15class ArgumentParserTests; // not a public class (only used for internal tests)
16
17namespace CppUtilities {
18
23 const char *name = nullptr;
24 const char *author = nullptr;
25 const char *version = nullptr;
26 const char *url = nullptr;
27 const char *domain = nullptr;
28 const char *description = nullptr;
29 const char *license = nullptr;
30 const char *credits = nullptr;
31 std::vector<const char *> dependencyVersions;
32};
33
38
45#define SET_DEPENDENCY_INFO ::CppUtilities::applicationInfo.dependencyVersions = DEPENCENCY_VERSIONS
46
52#define SET_APPLICATION_INFO \
53 ::CppUtilities::applicationInfo.name = APP_NAME; \
54 ::CppUtilities::applicationInfo.author = APP_AUTHOR; \
55 ::CppUtilities::applicationInfo.version = APP_VERSION; \
56 ::CppUtilities::applicationInfo.url = APP_URL; \
57 ::CppUtilities::applicationInfo.domain = APP_DOMAIN; \
58 ::CppUtilities::applicationInfo.description = APP_DESCRIPTION; \
59 ::CppUtilities::applicationInfo.license = PROJECT_LICENSE; \
60 ::CppUtilities::applicationInfo.credits = APP_CREDITS; \
61 SET_DEPENDENCY_INFO
62
63class Argument;
64class ArgumentParser;
65class ArgumentReader;
66
67using ArgumentInitializerList = std::initializer_list<Argument *>;
68using ArgumentVector = std::vector<Argument *>;
69using ArgumentPredicate = std::function<bool(Argument *)>;
70
76 Ignore,
77 Warn,
78 Fail
79};
80
88 ReadArguments = 0x0,
89 CheckConstraints = 0x1,
90 InvokeCallbacks = 0x2,
92 = 0x4,
93};
94
97{
98 return static_cast<ParseArgumentBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
99}
100
102{
103 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
104}
106
116enum class ValueCompletionBehavior : unsigned char {
117 None = 0,
118 PreDefinedValues = 2,
119 Files = 4,
120 Directories = 8,
122 AppendEquationSign = 32,
123 InvokeCallback = 64,
124};
125
128{
129 return static_cast<ValueCompletionBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
130}
131
133{
134 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
135}
137
145namespace ValueConversion {
146template <typename TargetType, Traits::EnableIf<std::is_same<TargetType, std::string>> * = nullptr> TargetType convert(const char *value)
147{
148 return std::string(value);
149}
150
151template <typename TargetType, Traits::EnableIf<std::is_arithmetic<TargetType>> * = nullptr> TargetType convert(const char *value)
152{
153 return stringToNumber<TargetType>(value);
154}
155
157namespace Helper {
158struct CPP_UTILITIES_EXPORT ArgumentValueConversionError {
159 const std::string errorMessage;
160 const char *const valueToConvert;
161 const char *const targetTypeName;
162
163 [[noreturn]] void throwFailure(const std::vector<Argument *> &argumentPath) const;
164};
165
166template <std::size_t N, typename FirstTargetType, typename... RemainingTargetTypes> struct ArgumentValueConverter {
167 static std::tuple<FirstTargetType, RemainingTargetTypes...> convertValues(std::vector<const char *>::const_iterator firstValue)
168 {
169 return std::tuple_cat(ArgumentValueConverter<1, FirstTargetType>::convertValues(firstValue),
170 ArgumentValueConverter<N - 1, RemainingTargetTypes...>::convertValues(firstValue + 1));
171 }
172};
173
174template <typename FirstTargetType, typename... RemainingTargetTypes> struct ArgumentValueConverter<1, FirstTargetType, RemainingTargetTypes...> {
175 static std::tuple<FirstTargetType> convertValues(std::vector<const char *>::const_iterator firstValue)
176 {
177 // FIXME: maybe use std::expected here when available
178 try {
179 return std::make_tuple<FirstTargetType>(ValueConversion::convert<FirstTargetType>(*firstValue));
180 } catch (const ConversionException &exception) {
181 throw ArgumentValueConversionError{ exception.what(), *firstValue, typeid(FirstTargetType).name() };
182 }
183 }
184};
185} // namespace Helper
187
188} // namespace ValueConversion
189
194 ArgumentOccurrence(std::size_t index);
195 ArgumentOccurrence(std::size_t index, const std::vector<Argument *> parentPath, Argument *parent);
196
200 std::size_t index;
201
205 std::vector<const char *> values;
206
211 std::vector<Argument *> path;
212
213 template <typename... RemainingTargetTypes> std::tuple<RemainingTargetTypes...> convertValues() const;
214
215private:
216 [[noreturn]] void throwNumberOfValuesNotSufficient(unsigned long valuesToConvert) const;
217};
218
224template <typename... RemainingTargetTypes> std::tuple<RemainingTargetTypes...> ArgumentOccurrence::convertValues() const
225{
226 constexpr auto valuesToConvert = sizeof...(RemainingTargetTypes);
227 if (values.size() < valuesToConvert) {
228 throwNumberOfValuesNotSufficient(valuesToConvert);
229 }
230 try {
231 return ValueConversion::Helper::ArgumentValueConverter<valuesToConvert, RemainingTargetTypes...>::convertValues(values.cbegin());
232 } catch (const ValueConversion::Helper::ArgumentValueConversionError &error) {
233 error.throwFailure(path);
234 }
235}
236
241 : index(index)
242{
243}
244
253inline ArgumentOccurrence::ArgumentOccurrence(std::size_t index, const std::vector<Argument *> parentPath, Argument *parent)
254 : index(index)
255 , path(parentPath)
256{
257 if (parent) {
258 path.push_back(parent);
259 }
260}
261
263 friend ArgumentParser;
264 friend ArgumentReader;
265 friend ArgumentParserTests;
266
267public:
268 typedef std::function<void(const ArgumentOccurrence &)> CallbackFunction;
269
270 enum class Flags : std::uint64_t {
271 None = 0x0,
272 Combinable = 0x1,
273 Implicit = 0x2,
274 Operation = 0x4,
275 Deprecated = 0x8,
276 };
277
278 Argument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
279 ~Argument();
280
281 // declare getter/setter/properties/operations for argument definition:
282 // - those properties must be set *before* parsing
283 // - they control the behaviour of the parser, eg.
284 // - the name/abbreviation to look for
285 // - constraints to be checked
286 // - callbacks to be invoked
287 // TODO v5: It would make sense to move these to a separate class (eg. ArgumentDefinition) to prevent this one from
288 // becoming to big.
289 const char *name() const;
290 void setName(const char *name);
291 char abbreviation() const;
292 void setAbbreviation(char abbreviation);
293 const char *environmentVariable() const;
294 void setEnvironmentVariable(const char *environmentVariable);
295 const char *description() const;
296 void setDescription(const char *description);
297 const char *example() const;
298 void setExample(const char *example);
299 std::size_t requiredValueCount() const;
300 void setRequiredValueCount(std::size_t requiredValueCount);
301 const std::vector<const char *> &valueNames() const;
302 void setValueNames(std::initializer_list<const char *> valueNames);
303 void appendValueName(const char *valueName);
304 void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences);
305 const std::vector<Argument *> &path(std::size_t occurrence = 0) const;
306 bool isRequired() const;
307 void setRequired(bool required);
308 Argument::Flags flags() const;
309 void setFlags(Argument::Flags flags);
310 void setFlags(Argument::Flags flags, bool add);
311 bool isCombinable() const;
312 void setCombinable(bool combinable);
313 bool isImplicit() const;
314 void setImplicit(bool implicit);
315 bool denotesOperation() const;
316 void setDenotesOperation(bool denotesOperation);
317 const CallbackFunction &callback() const;
318 void setCallback(CallbackFunction callback);
319 const ArgumentVector &subArguments() const;
320 void setSubArguments(const ArgumentInitializerList &subArguments);
321 void addSubArgument(Argument *arg);
322 bool hasSubArguments() const;
323 const ArgumentVector &parents() const;
324 void printInfo(std::ostream &os, unsigned char indentation = 0) const;
325
326 // declare getter/setter/properties for bash completion: those properties must be set *before parsing
327 ValueCompletionBehavior valueCompletionBehaviour() const;
328 void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour);
329 const char *preDefinedCompletionValues() const;
330 void setPreDefinedCompletionValues(const char *preDefinedCompletionValues);
331
332 // declare getter/read-only properties for parsing results: those properties will be populated when parsing
333 const std::vector<const char *> &values(std::size_t occurrence = 0) const;
334 template <typename... TargetType> std::tuple<TargetType...> valuesAs(std::size_t occurrence = 0) const;
335 template <typename... TargetType> std::vector<std::tuple<TargetType...>> allValuesAs() const;
336
337 const char *firstValue() const;
338 const char *firstValueOr(const char *fallback) const;
339 bool allRequiredValuesPresent(std::size_t occurrence = 0) const;
340 bool isPresent() const;
341 std::size_t occurrences() const;
342 std::size_t index(std::size_t occurrence) const;
343 std::size_t minOccurrences() const;
344 std::size_t maxOccurrences() const;
345 bool isDeprecated() const;
346 const Argument *deprecatedBy() const;
347 void markAsDeprecated(const Argument *deprecatedBy = nullptr);
348 bool isMainArgument() const;
349 bool isParentPresent() const;
350 Argument *conflictsWithArgument() const;
351 Argument *wouldConflictWithArgument() const;
352 Argument *specifiedOperation() const;
353 const std::vector<ArgumentOccurrence> &occurrenceInfo() const;
354 std::vector<ArgumentOccurrence> &occurrenceInfo();
355 void reset();
356 void resetRecursively();
357
362 static constexpr std::size_t varValueCount = std::numeric_limits<std::size_t>::max();
363
364private:
365 // declare internal getter/setter/properties/operations for argument definition
366 bool matchesDenotation(const char *denotation, std::size_t denotationLength) const;
367
368 const char *m_name;
369 char m_abbreviation;
370 const char *m_environmentVar;
371 const char *m_description;
372 const char *m_example;
373 std::size_t m_minOccurrences;
374 std::size_t m_maxOccurrences;
375 std::size_t m_requiredValueCount;
376 std::vector<const char *> m_valueNames;
377 Flags m_flags;
378 std::vector<ArgumentOccurrence> m_occurrences;
379 ArgumentVector m_subArgs;
380 CallbackFunction m_callbackFunction;
381 ArgumentVector m_parents;
382 const Argument *m_deprecatedBy;
383 bool m_isMainArg;
384 ValueCompletionBehavior m_valueCompletionBehavior;
385 const char *m_preDefinedCompletionValues;
386};
387
390{
391 return static_cast<Argument::Flags>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
392}
393
394constexpr bool operator&(Argument::Flags lhs, Argument::Flags rhs)
395{
396 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
397}
399
405template <typename... TargetType> std::tuple<TargetType...> Argument::valuesAs(std::size_t occurrence) const
406{
407 return m_occurrences[occurrence].convertValues<TargetType...>();
408}
409
415template <typename... TargetType> std::vector<std::tuple<TargetType...>> Argument::allValuesAs() const
416{
417 std::vector<std::tuple<TargetType...>> res;
418 res.reserve(m_occurrences.size());
419 for (const auto &occurrence : m_occurrences) {
420 res.emplace_back(occurrence.convertValues<TargetType...>());
421 }
422 return res;
423}
424
426public:
428};
429
431public:
432 OperationArgument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
433};
434
436public:
437 ConfigValueArgument(const char *name, char abbreviation = '\0', const char *description = nullptr,
438 std::initializer_list<const char *> valueNames = std::initializer_list<const char *>());
439};
440
442 friend ArgumentParserTests;
443
444public:
446 void apply() const;
447};
448
450
452 friend ArgumentParserTests;
453 friend ArgumentReader;
454
455public:
457
458 // declare getter/setter for argument definitions
459 const ArgumentVector &mainArguments() const;
460 void setMainArguments(const ArgumentInitializerList &mainArguments);
461 void addMainArgument(Argument *argument);
462
463 // declare operations which will consider previously assigned argument definitions and maybe modify parsing results
464 void printHelp(std::ostream &os) const;
465 void parseArgs(int argc, const char *const *argv,
466 ParseArgumentBehavior behavior
468 void readArgs(int argc, const char *const *argv);
469 void resetArgs();
470 void checkConstraints();
471 void invokeCallbacks();
472
473 // declare getter for parsing results
474 unsigned int actualArgumentCount() const;
475 const char *executable() const;
476 UnknownArgumentBehavior unknownArgumentBehavior() const;
477 void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior);
478 Argument *defaultArgument() const;
479 void setDefaultArgument(Argument *argument);
480 Argument *specifiedOperation() const;
481 bool isUncombinableMainArgPresent() const;
482 void setExitFunction(std::function<void(int)> exitFunction);
483 const HelpArgument &helpArg() const;
484 HelpArgument &helpArg();
485 const NoColorArgument &noColorArg() const;
486 NoColorArgument &noColorArg();
487
488private:
489 // declare internal operations
490 CPP_UTILITIES_IF_DEBUG_BUILD(void verifyArgs(const ArgumentVector &args);)
491 ArgumentCompletionInfo determineCompletionInfo(
492 int argc, const char *const *argv, unsigned int currentWordIndex, const ArgumentReader &reader) const;
493 std::string findSuggestions(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
494 void printBashCompletion(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
495 void checkConstraints(const ArgumentVector &args);
496 static void invokeCallbacks(const ArgumentVector &args);
497 void invokeExit(int code);
498
499 ArgumentVector m_mainArgs;
500 unsigned int m_actualArgc;
501 const char *m_executable;
502 UnknownArgumentBehavior m_unknownArgBehavior;
503 Argument *m_defaultArg;
504 HelpArgument m_helpArg;
505 NoColorArgument m_noColorArg;
506 std::function<void(int)> m_exitFunction;
507};
508
514inline const char *Argument::name() const
515{
516 return m_name;
517}
518
526inline void Argument::setName(const char *name)
527{
528#ifdef CPP_UTILITIES_DEBUG_BUILD
529 if (name && *name) {
530 assert(*name != '-');
531 for (const char *c = name; *c; ++c) {
532 assert(*c != ' ' && *c != '=' && *c != '\'' && *c != '\"' && *c != '\n' && *c != '\r');
533 }
534 }
535#endif
536 m_name = name;
537}
538
544inline char Argument::abbreviation() const
545{
546 return m_abbreviation;
547}
548
556inline void Argument::setAbbreviation(char abbreviation)
557{
558 CPP_UTILITIES_IF_DEBUG_BUILD(assert(abbreviation != ' ' && abbreviation != '=' && abbreviation != '-' && abbreviation != '\''
559 && abbreviation != '"' && abbreviation != '\n' && abbreviation != '\r'));
560 m_abbreviation = abbreviation;
561}
562
567inline const char *Argument::environmentVariable() const
568{
569 return m_environmentVar;
570}
571
576inline void Argument::setEnvironmentVariable(const char *environmentVariable)
577{
578 m_environmentVar = environmentVariable;
579}
580
586inline const char *Argument::description() const
587{
588 return m_description;
589}
590
596inline void Argument::setDescription(const char *description)
597{
598 m_description = description;
599}
600
606inline const char *Argument::example() const
607{
608 return m_example;
609}
610
616inline void Argument::setExample(const char *example)
617{
618 m_example = example;
619}
620
627inline const std::vector<const char *> &Argument::values(std::size_t occurrence) const
628{
629 return m_occurrences[occurrence].values;
630}
631
645inline std::size_t Argument::requiredValueCount() const
646{
647 return m_requiredValueCount;
648}
649
662inline void Argument::setRequiredValueCount(std::size_t requiredValueCount)
663{
664 m_requiredValueCount = requiredValueCount;
665}
666
675inline const std::vector<const char *> &Argument::valueNames() const
676{
677 return m_valueNames;
678}
679
693inline void Argument::setValueNames(std::initializer_list<const char *> valueNames)
694{
695 m_valueNames.assign(valueNames);
696}
697
704inline void Argument::appendValueName(const char *valueName)
705{
706 m_valueNames.emplace_back(valueName);
707}
708
712inline bool Argument::allRequiredValuesPresent(std::size_t occurrence) const
713{
714 return m_requiredValueCount == Argument::varValueCount
715 || (m_occurrences[occurrence].values.size() >= static_cast<std::size_t>(m_requiredValueCount));
716}
717
722inline bool Argument::isImplicit() const
723{
724 return m_flags & Flags::Implicit;
725}
726
731inline void Argument::setImplicit(bool implicit)
732{
733 setFlags(Flags::Implicit, implicit);
734}
735
739inline bool Argument::isPresent() const
740{
741 return !m_occurrences.empty();
742}
743
747inline std::size_t Argument::occurrences() const
748{
749 return m_occurrences.size();
750}
751
755inline std::size_t Argument::index(std::size_t occurrence) const
756{
757 return m_occurrences[occurrence].index;
758}
759
765inline std::size_t Argument::minOccurrences() const
766{
767 return m_minOccurrences;
768}
769
775inline std::size_t Argument::maxOccurrences() const
776{
777 return m_maxOccurrences;
778}
779
780inline bool Argument::isDeprecated() const
781{
782 return m_flags & Flags::Deprecated;
783}
784
788inline const Argument *Argument::deprecatedBy() const
789{
790 return m_deprecatedBy;
791}
792
798inline void Argument::markAsDeprecated(const Argument *deprecatedBy)
799{
801 m_deprecatedBy = deprecatedBy;
802}
803
809inline void Argument::setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
810{
811 m_minOccurrences = minOccurrences;
812 m_maxOccurrences = maxOccurrences;
813}
814
818inline const std::vector<Argument *> &Argument::path(std::size_t occurrence) const
819{
820 return m_occurrences[occurrence].path;
821}
822
832inline bool Argument::isRequired() const
833{
834 return m_minOccurrences;
835}
836
844inline void Argument::setRequired(bool required)
845{
846 if (required) {
847 if (!m_minOccurrences) {
848 m_minOccurrences = 1;
849 }
850 } else {
851 m_minOccurrences = 0;
852 }
853}
854
859{
860 return m_flags;
861}
862
867{
868 m_flags = flags;
869}
870
874inline void Argument::setFlags(Argument::Flags flags, bool add)
875{
876 m_flags = add ? (m_flags | flags)
877 : static_cast<Argument::Flags>(static_cast<std::underlying_type<Argument::Flags>::type>(m_flags)
878 & ~static_cast<std::underlying_type<Argument::Flags>::type>(flags));
879}
880
889inline bool Argument::isCombinable() const
890{
891 return m_flags & Flags::Combinable;
892}
893
902inline void Argument::setCombinable(bool combinable)
903{
904 setFlags(Flags::Combinable, combinable);
905}
906
917inline bool Argument::denotesOperation() const
918{
919 return m_flags & Flags::Operation;
920}
921
926inline void Argument::setDenotesOperation(bool denotesOperation)
927{
929}
930
936{
937 return m_callbackFunction;
938}
939
947{
948 m_callbackFunction = callback;
949}
950
958{
959 return m_subArgs;
960}
961
968inline bool Argument::hasSubArguments() const
969{
970 return !m_subArgs.empty();
971}
972
984{
985 return m_parents;
986}
987
994inline bool Argument::isMainArgument() const
995{
996 return m_isMainArg;
997}
998
1006{
1007 return m_valueCompletionBehavior;
1008}
1009
1017{
1018 m_valueCompletionBehavior = completionValues;
1019}
1020
1025{
1026 return m_preDefinedCompletionValues;
1027}
1028
1032inline void Argument::setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
1033{
1034 m_preDefinedCompletionValues = preDefinedCompletionValues;
1035}
1036
1042inline void Argument::reset()
1043{
1044 m_occurrences.clear();
1045}
1046
1047inline OperationArgument::OperationArgument(const char *name, char abbreviation, const char *description, const char *example)
1048 : Argument(name, abbreviation, description, example)
1049{
1050 setDenotesOperation(true);
1051}
1052
1057 const char *name, char abbreviation, const char *description, std::initializer_list<const char *> valueNames)
1058 : Argument(name, abbreviation, description)
1059{
1060 setCombinable(true);
1063}
1064
1069inline const std::vector<ArgumentOccurrence> &Argument::occurrenceInfo() const
1070{
1071 return m_occurrences;
1072}
1073
1080inline std::vector<ArgumentOccurrence> &Argument::occurrenceInfo()
1081{
1082 return m_occurrences;
1083}
1084
1090{
1091 return m_mainArgs;
1092}
1093
1097inline unsigned int ArgumentParser::actualArgumentCount() const
1098{
1099 return m_actualArgc;
1100}
1101
1105inline const char *ArgumentParser::executable() const
1106{
1107 return m_executable;
1108}
1109
1116{
1117 return m_unknownArgBehavior;
1118}
1119
1126{
1127 m_unknownArgBehavior = behavior;
1128}
1129
1135{
1136 return m_defaultArg;
1137}
1138
1144{
1145 m_defaultArg = argument;
1146}
1147
1154{
1155 checkConstraints(m_mainArgs);
1156}
1157
1163{
1164 invokeCallbacks(m_mainArgs);
1165}
1166
1171inline void ArgumentParser::setExitFunction(std::function<void(int)> exitFunction)
1172{
1173 m_exitFunction = exitFunction;
1174}
1175
1180{
1181 return m_helpArg;
1182}
1183
1188{
1189 return m_helpArg;
1190}
1191
1196{
1197 return m_noColorArg;
1198}
1199
1204{
1205 return m_noColorArg;
1206}
1207
1208} // namespace CppUtilities
1209
1210#endif // APPLICATION_UTILITIES_ARGUMENTPARSER_H
#define CPP_UTILITIES_IF_DEBUG_BUILD(x)
Wraps debug-only lines conveniently.
Definition: global.h:102
The ArgumentParserTests class tests the ArgumentParser and Argument classes.
The ArgumentParser class provides a means for handling command line arguments.
void setDefaultArgument(Argument *argument)
Sets the default argument.
const HelpArgument & helpArg() const
Returns the --help argument.
void checkConstraints()
Checks whether constraints are violated.
const char * executable() const
Returns the name of the current executable.
const ArgumentVector & mainArguments() const
Returns the main arguments.
unsigned int actualArgumentCount() const
Returns the actual number of arguments that could be found when parsing.
void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior)
Sets how unknown arguments are treated.
Argument * defaultArgument() const
Returns the default argument.
void setExitFunction(std::function< void(int)> exitFunction)
Specifies a function quit the application.
void invokeCallbacks()
Invokes all assigned callbacks.
UnknownArgumentBehavior unknownArgumentBehavior() const
Returns how unknown arguments are treated.
const NoColorArgument & noColorArg() const
Returns the --no-color argument.
The ArgumentReader class internally encapsulates the process of reading command line arguments.
The Argument class is a wrapper for command line argument information.
const char * description() const
Returns the description of the argument.
static constexpr std::size_t varValueCount
Denotes a variable number of values.
const std::vector< Argument * > & path(std::size_t occurrence=0) const
Returns the path of the specified occurrence.
bool isMainArgument() const
Returns an indication whether the argument is used as main argument.
const ArgumentVector & subArguments() const
Returns the secondary arguments for this argument.
const char * example() const
Returns the usage example of the argument.
const std::vector< const char * > & valueNames() const
Returns the names of the required values.
void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour)
Sets the items to be considered when generating completion for the values.
const CallbackFunction & callback() const
Returns the assigned callback function.
const std::vector< ArgumentOccurrence > & occurrenceInfo() const
Returns information about all occurrences of the argument which have been detected when parsing.
ValueCompletionBehavior valueCompletionBehaviour() const
Returns the items to be considered when generating completion for the values.
void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
Sets the allowed number of occurrences.
void setImplicit(bool implicit)
Sets whether the argument is an implicit argument.
void setValueNames(std::initializer_list< const char * > valueNames)
Sets the names of the required values.
char abbreviation() const
Returns the abbreviation of the argument.
std::size_t occurrences() const
Returns how often the argument could be detected when parsing.
void setDenotesOperation(bool denotesOperation)
Sets whether the argument denotes the operation.
void markAsDeprecated(const Argument *deprecatedBy=nullptr)
Marks the argument as deprecated.
const char * name() const
Returns the name of the argument.
void setAbbreviation(char abbreviation)
Sets the abbreviation of the argument.
bool isCombinable() const
Returns an indication whether the argument is combinable.
bool denotesOperation() const
Returns whether the argument denotes an operation.
void setDescription(const char *description)
Sets the description of the argument.
void appendValueName(const char *valueName)
Appends a value name.
std::size_t maxOccurrences() const
Returns the maximum number of occurrences.
Argument::Flags flags() const
Returns Argument::Flags for the argument.
const std::vector< const char * > & values(std::size_t occurrence=0) const
Returns the parameter values for the specified occurrence of argument.
const char * preDefinedCompletionValues() const
Returns the assigned values used when generating completion for the values.
std::size_t requiredValueCount() const
Returns the number of values which are required to be given for this argument.
const char * environmentVariable() const
Returns the environment variable queried when firstValue() is called.
std::vector< std::tuple< TargetType... > > allValuesAs() const
Converts the present values for all occurrence to the specified target types.
bool isImplicit() const
Returns an indication whether the argument is an implicit argument.
void reset()
Resets occurrences (indices, values and paths).
const Argument * deprecatedBy() const
Returns the argument which obsoletes this argument.
std::function< void(const ArgumentOccurrence &)> CallbackFunction
std::size_t index(std::size_t occurrence) const
Returns the indices of the argument's occurrences which could be detected when parsing.
bool isPresent() const
Returns an indication whether the argument could be detected when parsing.
void setExample(const char *example)
Sets the a usage example for the argument.
const ArgumentVector & parents() const
Returns the parents of this argument.
void setFlags(Argument::Flags flags)
Replaces all Argument::Flags for the argument with the flags.
std::size_t minOccurrences() const
Returns the minimum number of occurrences.
bool allRequiredValuesPresent(std::size_t occurrence=0) const
Returns an indication whether all required values are present.
void setCombinable(bool combinable)
Sets whether this argument can be combined.
void setCallback(CallbackFunction callback)
Sets a callback function which will be called by the parser if the argument could be found and no par...
bool isRequired() const
Returns an indication whether the argument is mandatory.
void setRequired(bool required)
Sets whether this argument is mandatory or not.
void setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
Assigns the values to be used when generating completion for the values.
void setEnvironmentVariable(const char *environmentVariable)
Sets the environment variable queried when firstValue() is called.
bool hasSubArguments() const
Returns an indication whether the argument has secondary arguments.
std::tuple< TargetType... > valuesAs(std::size_t occurrence=0) const
Converts the present values for the specified occurrence to the specified target types.
void setRequiredValueCount(std::size_t requiredValueCount)
Sets the number of values which are required to be given for this argument.
void setName(const char *name)
Sets the name of the argument.
The ConfigValueArgument class is an Argument where setCombinable() is true by default.
ConfigValueArgument(const char *name, char abbreviation='\0', const char *description=nullptr, std::initializer_list< const char * > valueNames=std::initializer_list< const char * >())
Constructs a new ConfigValueArgument with the specified parameter.
The HelpArgument class prints help information for an argument parser when present (–help,...
The NoColorArgument class allows to specify whether use of escape codes or similar technique to provi...
The OperationArgument class is an Argument where denotesOperation() is true by default.
OperationArgument(const char *name, char abbreviation='\0', const char *description=nullptr, const char *example=nullptr)
#define CPP_UTILITIES_EXPORT
Marks the symbol to be exported by the c++utilities library.
constexpr bool operator&(FlagEnumClass lhs, FlagEnumClass rhs)
Definition: flagenumclass.h:50
constexpr FlagEnumClass operator|(FlagEnumClass lhs, FlagEnumClass rhs)
Definition: flagenumclass.h:43
TargetType convert(const char *value)
Contains all utilities provides by the c++utilities library.
std::vector< Argument * > ArgumentVector
UnknownArgumentBehavior
The UnknownArgumentBehavior enum specifies the behavior of the argument parser when an unknown argume...
ParseArgumentBehavior
The ParseArgumentBehavior enum specifies the behavior when parsing arguments.
std::function< bool(Argument *)> ArgumentPredicate
std::initializer_list< Argument * > ArgumentInitializerList
constexpr T max(T first, T second)
Returns the greatest of the given items.
Definition: math.h:100
ValueCompletionBehavior
The ValueCompletionBehavior enum specifies the items to be considered when generating completion for ...
CPP_UTILITIES_EXPORT ApplicationInfo applicationInfo
Stores global application info used by ArgumentParser::printHelp() and AboutDialog.
Stores information about an application.
std::vector< const char * > dependencyVersions
The ArgumentCompletionInfo struct holds information internally used for shell completion and suggesti...
The ArgumentOccurrence struct holds argument values for an occurrence of an argument.
std::size_t index
The index of the occurrence.
std::vector< const char * > values
The parameter values which have been specified after the occurrence of the argument.
std::tuple< RemainingTargetTypes... > convertValues() const
Converts the present values to the specified target types.
ArgumentOccurrence(std::size_t index)
Constructs an argument occurrence for the specified index.
std::vector< Argument * > path
The "path" of the occurrence (the parent elements which have been specified before).