C++ Utilities 5.20.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
271 enum class Flags : std::uint64_t {
272 None = 0x0,
273 Combinable
274 = 0x1,
275 Implicit = 0x2,
276 Operation = 0x4,
277 Deprecated = 0x8,
278 Greedy
279 = 0x10,
280 };
281
282 Argument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
283 ~Argument();
284
285 // declare getter/setter/properties/operations for argument definition:
286 // - those properties must be set *before* parsing
287 // - they control the behaviour of the parser, eg.
288 // - the name/abbreviation to look for
289 // - constraints to be checked
290 // - callbacks to be invoked
291 // TODO v5: It would make sense to move these to a separate class (eg. ArgumentDefinition) to prevent this one from
292 // becoming to big.
293 const char *name() const;
294 void setName(const char *name);
295 char abbreviation() const;
296 void setAbbreviation(char abbreviation);
297 const char *environmentVariable() const;
298 void setEnvironmentVariable(const char *environmentVariable);
299 const char *description() const;
300 void setDescription(const char *description);
301 const char *example() const;
302 void setExample(const char *example);
303 std::size_t requiredValueCount() const;
304 void setRequiredValueCount(std::size_t requiredValueCount);
305 const std::vector<const char *> &valueNames() const;
306 void setValueNames(std::initializer_list<const char *> valueNames);
307 void appendValueName(const char *valueName);
308 void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences);
309 const std::vector<Argument *> &path(std::size_t occurrence = 0) const;
310 bool isRequired() const;
311 void setRequired(bool required);
312 Argument::Flags flags() const;
313 void setFlags(Argument::Flags flags);
314 void setFlags(Argument::Flags flags, bool add);
315 bool isCombinable() const;
316 void setCombinable(bool combinable);
317 bool isImplicit() const;
318 void setImplicit(bool implicit);
319 bool denotesOperation() const;
320 void setDenotesOperation(bool denotesOperation);
321 const CallbackFunction &callback() const;
322 void setCallback(CallbackFunction callback);
323 const ArgumentVector &subArguments() const;
324 void setSubArguments(const ArgumentInitializerList &subArguments);
325 void addSubArguments(const ArgumentInitializerList &subArguments);
326 void addSubArgument(Argument *arg);
327 bool hasSubArguments() const;
328 const ArgumentVector &parents() const;
329 void printInfo(std::ostream &os, unsigned char indentation = 0) const;
330
331 // declare getter/setter/properties for bash completion: those properties must be set *before parsing
332 ValueCompletionBehavior valueCompletionBehaviour() const;
333 void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour);
334 const char *preDefinedCompletionValues() const;
335 void setPreDefinedCompletionValues(const char *preDefinedCompletionValues);
336
337 // declare getter/read-only properties for parsing results: those properties will be populated when parsing
338 const std::vector<const char *> &values(std::size_t occurrence = 0) const;
339 template <typename... TargetType> std::tuple<TargetType...> valuesAs(std::size_t occurrence = 0) const;
340 template <typename... TargetType> std::vector<std::tuple<TargetType...>> allValuesAs() const;
341
342 const char *firstValue() const;
343 const char *firstValueOr(const char *fallback) const;
344 bool allRequiredValuesPresent(std::size_t occurrence = 0) const;
345 bool isPresent() const;
346 std::size_t occurrences() const;
347 std::size_t index(std::size_t occurrence) const;
348 std::size_t minOccurrences() const;
349 std::size_t maxOccurrences() const;
350 bool isDeprecated() const;
351 const Argument *deprecatedBy() const;
352 void markAsDeprecated(const Argument *deprecatedBy = nullptr);
353 bool isMainArgument() const;
354 bool isParentPresent() const;
355 Argument *conflictsWithArgument() const;
356 Argument *wouldConflictWithArgument() const;
357 Argument *specifiedOperation() const;
358 const std::vector<ArgumentOccurrence> &occurrenceInfo() const;
359 std::vector<ArgumentOccurrence> &occurrenceInfo();
360 void reset();
361 void resetRecursively();
362
367 static constexpr std::size_t varValueCount = std::numeric_limits<std::size_t>::max();
368
369private:
370 // declare internal getter/setter/properties/operations for argument definition
371 bool matchesDenotation(const char *denotation, std::size_t denotationLength) const;
372
373 const char *m_name;
374 char m_abbreviation;
375 const char *m_environmentVar;
376 const char *m_description;
377 const char *m_example;
378 std::size_t m_minOccurrences;
379 std::size_t m_maxOccurrences;
380 std::size_t m_requiredValueCount;
381 std::vector<const char *> m_valueNames;
382 Flags m_flags;
383 std::vector<ArgumentOccurrence> m_occurrences;
384 ArgumentVector m_subArgs;
385 CallbackFunction m_callbackFunction;
386 ArgumentVector m_parents;
387 const Argument *m_deprecatedBy;
388 bool m_isMainArg;
389 ValueCompletionBehavior m_valueCompletionBehavior;
390 const char *m_preDefinedCompletionValues;
391};
392
395{
396 return static_cast<Argument::Flags>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
397}
398
399constexpr bool operator&(Argument::Flags lhs, Argument::Flags rhs)
400{
401 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
402}
404
410template <typename... TargetType> std::tuple<TargetType...> Argument::valuesAs(std::size_t occurrence) const
411{
412 return m_occurrences[occurrence].convertValues<TargetType...>();
413}
414
420template <typename... TargetType> std::vector<std::tuple<TargetType...>> Argument::allValuesAs() const
421{
422 std::vector<std::tuple<TargetType...>> res;
423 res.reserve(m_occurrences.size());
424 for (const auto &occurrence : m_occurrences) {
425 res.emplace_back(occurrence.convertValues<TargetType...>());
426 }
427 return res;
428}
429
431public:
433};
434
436public:
437 OperationArgument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
438};
439
441public:
442 ConfigValueArgument(const char *name, char abbreviation = '\0', const char *description = nullptr,
443 std::initializer_list<const char *> valueNames = std::initializer_list<const char *>());
444};
445
447 friend ArgumentParserTests;
448
449public:
451 void apply() const;
452};
453
455
457 friend ArgumentParserTests;
458 friend ArgumentReader;
459
460public:
462
463 // declare getter/setter for argument definitions
464 const ArgumentVector &mainArguments() const;
465 void setMainArguments(const ArgumentInitializerList &mainArguments);
466 void addMainArgument(Argument *argument);
467
468 // declare operations which will consider previously assigned argument definitions and maybe modify parsing results
469 void printHelp(std::ostream &os) const;
470 void parseArgs(int argc, const char *const *argv,
471 ParseArgumentBehavior behavior
473 void readArgs(int argc, const char *const *argv);
474 void resetArgs();
475 void checkConstraints();
476 void invokeCallbacks();
477
478 // declare getter for parsing results
479 unsigned int actualArgumentCount() const;
480 const char *executable() const;
481 UnknownArgumentBehavior unknownArgumentBehavior() const;
482 void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior);
483 Argument *defaultArgument() const;
484 void setDefaultArgument(Argument *argument);
485 Argument *specifiedOperation() const;
486 bool isUncombinableMainArgPresent() const;
487 void setExitFunction(std::function<void(int)> exitFunction);
488 const HelpArgument &helpArg() const;
489 HelpArgument &helpArg();
490 const NoColorArgument &noColorArg() const;
491 NoColorArgument &noColorArg();
492
493private:
494 // declare internal operations
495 CPP_UTILITIES_IF_DEBUG_BUILD(void verifyArgs(const ArgumentVector &args);)
496 ArgumentCompletionInfo determineCompletionInfo(
497 int argc, const char *const *argv, unsigned int currentWordIndex, const ArgumentReader &reader) const;
498 std::string findSuggestions(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
499 void printBashCompletion(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
500 void checkConstraints(const ArgumentVector &args);
501 static void invokeCallbacks(const ArgumentVector &args);
502 void invokeExit(int code);
503
504 ArgumentVector m_mainArgs;
505 unsigned int m_actualArgc;
506 const char *m_executable;
507 UnknownArgumentBehavior m_unknownArgBehavior;
508 Argument *m_defaultArg;
509 HelpArgument m_helpArg;
510 NoColorArgument m_noColorArg;
511 std::function<void(int)> m_exitFunction;
512};
513
519inline const char *Argument::name() const
520{
521 return m_name;
522}
523
531inline void Argument::setName(const char *name)
532{
533#ifdef CPP_UTILITIES_DEBUG_BUILD
534 if (name && *name) {
535 assert(*name != '-');
536 for (const char *c = name; *c; ++c) {
537 assert(*c != ' ' && *c != '=' && *c != '\'' && *c != '\"' && *c != '\n' && *c != '\r');
538 }
539 }
540#endif
541 m_name = name;
542}
543
549inline char Argument::abbreviation() const
550{
551 return m_abbreviation;
552}
553
561inline void Argument::setAbbreviation(char abbreviation)
562{
563 CPP_UTILITIES_IF_DEBUG_BUILD(assert(abbreviation != ' ' && abbreviation != '=' && abbreviation != '-' && abbreviation != '\''
564 && abbreviation != '"' && abbreviation != '\n' && abbreviation != '\r'));
565 m_abbreviation = abbreviation;
566}
567
572inline const char *Argument::environmentVariable() const
573{
574 return m_environmentVar;
575}
576
581inline void Argument::setEnvironmentVariable(const char *environmentVariable)
582{
583 m_environmentVar = environmentVariable;
584}
585
591inline const char *Argument::description() const
592{
593 return m_description;
594}
595
601inline void Argument::setDescription(const char *description)
602{
603 m_description = description;
604}
605
611inline const char *Argument::example() const
612{
613 return m_example;
614}
615
621inline void Argument::setExample(const char *example)
622{
623 m_example = example;
624}
625
632inline const std::vector<const char *> &Argument::values(std::size_t occurrence) const
633{
634 return m_occurrences[occurrence].values;
635}
636
650inline std::size_t Argument::requiredValueCount() const
651{
652 return m_requiredValueCount;
653}
654
667inline void Argument::setRequiredValueCount(std::size_t requiredValueCount)
668{
669 m_requiredValueCount = requiredValueCount;
670}
671
680inline const std::vector<const char *> &Argument::valueNames() const
681{
682 return m_valueNames;
683}
684
698inline void Argument::setValueNames(std::initializer_list<const char *> valueNames)
699{
700 m_valueNames.assign(valueNames);
701}
702
709inline void Argument::appendValueName(const char *valueName)
710{
711 m_valueNames.emplace_back(valueName);
712}
713
717inline bool Argument::allRequiredValuesPresent(std::size_t occurrence) const
718{
719 return m_requiredValueCount == Argument::varValueCount
720 || (m_occurrences[occurrence].values.size() >= static_cast<std::size_t>(m_requiredValueCount));
721}
722
727inline bool Argument::isImplicit() const
728{
729 return m_flags & Flags::Implicit;
730}
731
736inline void Argument::setImplicit(bool implicit)
737{
738 setFlags(Flags::Implicit, implicit);
739}
740
744inline bool Argument::isPresent() const
745{
746 return !m_occurrences.empty();
747}
748
752inline std::size_t Argument::occurrences() const
753{
754 return m_occurrences.size();
755}
756
760inline std::size_t Argument::index(std::size_t occurrence) const
761{
762 return m_occurrences[occurrence].index;
763}
764
770inline std::size_t Argument::minOccurrences() const
771{
772 return m_minOccurrences;
773}
774
780inline std::size_t Argument::maxOccurrences() const
781{
782 return m_maxOccurrences;
783}
784
785inline bool Argument::isDeprecated() const
786{
787 return m_flags & Flags::Deprecated;
788}
789
793inline const Argument *Argument::deprecatedBy() const
794{
795 return m_deprecatedBy;
796}
797
803inline void Argument::markAsDeprecated(const Argument *deprecatedBy)
804{
806 m_deprecatedBy = deprecatedBy;
807}
808
814inline void Argument::setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
815{
816 m_minOccurrences = minOccurrences;
817 m_maxOccurrences = maxOccurrences;
818}
819
823inline const std::vector<Argument *> &Argument::path(std::size_t occurrence) const
824{
825 return m_occurrences[occurrence].path;
826}
827
837inline bool Argument::isRequired() const
838{
839 return m_minOccurrences;
840}
841
849inline void Argument::setRequired(bool required)
850{
851 if (required) {
852 if (!m_minOccurrences) {
853 m_minOccurrences = 1;
854 }
855 } else {
856 m_minOccurrences = 0;
857 }
858}
859
864{
865 return m_flags;
866}
867
872{
873 m_flags = flags;
874}
875
879inline void Argument::setFlags(Argument::Flags flags, bool add)
880{
881 m_flags = add ? (m_flags | flags)
882 : static_cast<Argument::Flags>(static_cast<std::underlying_type<Argument::Flags>::type>(m_flags)
883 & ~static_cast<std::underlying_type<Argument::Flags>::type>(flags));
884}
885
894inline bool Argument::isCombinable() const
895{
896 return m_flags & Flags::Combinable;
897}
898
907inline void Argument::setCombinable(bool combinable)
908{
909 setFlags(Flags::Combinable, combinable);
910}
911
922inline bool Argument::denotesOperation() const
923{
924 return m_flags & Flags::Operation;
925}
926
931inline void Argument::setDenotesOperation(bool denotesOperation)
932{
934}
935
941{
942 return m_callbackFunction;
943}
944
952{
953 m_callbackFunction = callback;
954}
955
963{
964 return m_subArgs;
965}
966
973inline bool Argument::hasSubArguments() const
974{
975 return !m_subArgs.empty();
976}
977
989{
990 return m_parents;
991}
992
999inline bool Argument::isMainArgument() const
1000{
1001 return m_isMainArg;
1002}
1003
1011{
1012 return m_valueCompletionBehavior;
1013}
1014
1022{
1023 m_valueCompletionBehavior = completionValues;
1024}
1025
1030{
1031 return m_preDefinedCompletionValues;
1032}
1033
1037inline void Argument::setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
1038{
1039 m_preDefinedCompletionValues = preDefinedCompletionValues;
1040}
1041
1047inline void Argument::reset()
1048{
1049 m_occurrences.clear();
1050}
1051
1052inline OperationArgument::OperationArgument(const char *name, char abbreviation, const char *description, const char *example)
1053 : Argument(name, abbreviation, description, example)
1054{
1055 setDenotesOperation(true);
1056}
1057
1062 const char *name, char abbreviation, const char *description, std::initializer_list<const char *> valueNames)
1063 : Argument(name, abbreviation, description)
1064{
1065 setCombinable(true);
1068}
1069
1074inline const std::vector<ArgumentOccurrence> &Argument::occurrenceInfo() const
1075{
1076 return m_occurrences;
1077}
1078
1085inline std::vector<ArgumentOccurrence> &Argument::occurrenceInfo()
1086{
1087 return m_occurrences;
1088}
1089
1095{
1096 return m_mainArgs;
1097}
1098
1102inline unsigned int ArgumentParser::actualArgumentCount() const
1103{
1104 return m_actualArgc;
1105}
1106
1110inline const char *ArgumentParser::executable() const
1111{
1112 return m_executable;
1113}
1114
1121{
1122 return m_unknownArgBehavior;
1123}
1124
1131{
1132 m_unknownArgBehavior = behavior;
1133}
1134
1140{
1141 return m_defaultArg;
1142}
1143
1149{
1150 m_defaultArg = argument;
1151}
1152
1159{
1160 checkConstraints(m_mainArgs);
1161}
1162
1168{
1169 invokeCallbacks(m_mainArgs);
1170}
1171
1176inline void ArgumentParser::setExitFunction(std::function<void(int)> exitFunction)
1177{
1178 m_exitFunction = exitFunction;
1179}
1180
1185{
1186 return m_helpArg;
1187}
1188
1193{
1194 return m_helpArg;
1195}
1196
1201{
1202 return m_noColorArg;
1203}
1204
1209{
1210 return m_noColorArg;
1211}
1212
1213} // namespace CppUtilities
1214
1215#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.
Flags
The Flags enum specifies options for treating the argument in a special way.
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).