C++ Utilities 5.26.1
Useful C++ classes and routines such as argument parser, IO and conversion utilities
Loading...
Searching...
No Matches
argumentparser.h
Go to the documentation of this file.
1#ifndef APPLICATION_UTILITIES_ARGUMENTPARSER_H
2#define APPLICATION_UTILITIES_ARGUMENTPARSER_H
3
5#include "../misc/traits.h"
6
7#include <functional>
8#include <initializer_list>
9#include <limits>
10#include <tuple>
11#include <vector>
12#ifdef CPP_UTILITIES_DEBUG_BUILD
13#include <cassert>
14#endif
15
16class ArgumentParserTests; // not a public class (only used for internal tests)
17
18namespace CppUtilities {
19
24 const char *name = nullptr;
25 const char *author = nullptr;
26 const char *version = nullptr;
27 const char *url = nullptr;
28 const char *domain = nullptr;
29 const char *description = nullptr;
30 const char *license = nullptr;
31 const char *credits = nullptr;
32 std::vector<const char *> dependencyVersions;
33};
34
39
46#define SET_DEPENDENCY_INFO ::CppUtilities::applicationInfo.dependencyVersions = DEPENCENCY_VERSIONS
47
53#define SET_APPLICATION_INFO \
54 ::CppUtilities::applicationInfo.name = APP_NAME; \
55 ::CppUtilities::applicationInfo.author = APP_AUTHOR; \
56 ::CppUtilities::applicationInfo.version = APP_VERSION; \
57 ::CppUtilities::applicationInfo.url = APP_URL; \
58 ::CppUtilities::applicationInfo.domain = APP_DOMAIN; \
59 ::CppUtilities::applicationInfo.description = APP_DESCRIPTION; \
60 ::CppUtilities::applicationInfo.license = PROJECT_LICENSE; \
61 ::CppUtilities::applicationInfo.credits = APP_CREDITS; \
62 SET_DEPENDENCY_INFO
63
64class Argument;
65class ArgumentParser;
66class ArgumentReader;
67
68using ArgumentInitializerList = std::initializer_list<Argument *>;
69using ArgumentVector = std::vector<Argument *>;
70using ArgumentPredicate = std::function<bool(Argument *)>;
71
77 Ignore,
78 Warn,
79 Fail
80};
81
89 ReadArguments = 0x0,
90 CheckConstraints = 0x1,
91 InvokeCallbacks = 0x2,
93 = 0x4,
94};
95
98{
99 return static_cast<ParseArgumentBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
100}
101
103{
104 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
105}
107
117enum class ValueCompletionBehavior : unsigned char {
118 None = 0,
119 PreDefinedValues = 2,
120 Files = 4,
121 Directories = 8,
123 AppendEquationSign = 32,
124 InvokeCallback = 64,
125};
126
129{
130 return static_cast<ValueCompletionBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
131}
132
134{
135 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
136}
138
146namespace ValueConversion {
147template <typename TargetType, Traits::EnableIf<std::is_same<TargetType, std::string>> * = nullptr> TargetType convert(const char *value)
148{
149 return std::string(value);
150}
151
152template <typename TargetType, Traits::EnableIf<std::is_arithmetic<TargetType>> * = nullptr> TargetType convert(const char *value)
153{
154 return stringToNumber<TargetType>(value);
155}
156
158namespace Helper {
159struct CPP_UTILITIES_EXPORT ArgumentValueConversionError {
160 const std::string errorMessage;
161 const char *const valueToConvert;
162 const char *const targetTypeName;
163
164 [[noreturn]] void throwFailure(const std::vector<Argument *> &argumentPath) const;
165};
166
167template <std::size_t N, typename FirstTargetType, typename... RemainingTargetTypes> struct ArgumentValueConverter {
168 static std::tuple<FirstTargetType, RemainingTargetTypes...> convertValues(std::vector<const char *>::const_iterator firstValue)
169 {
170 return std::tuple_cat(ArgumentValueConverter<1, FirstTargetType>::convertValues(firstValue),
171 ArgumentValueConverter<N - 1, RemainingTargetTypes...>::convertValues(firstValue + 1));
172 }
173};
174
175template <typename FirstTargetType, typename... RemainingTargetTypes> struct ArgumentValueConverter<1, FirstTargetType, RemainingTargetTypes...> {
176 static std::tuple<FirstTargetType> convertValues(std::vector<const char *>::const_iterator firstValue)
177 {
178 // FIXME: maybe use std::expected here when available
179 try {
180 return std::make_tuple<FirstTargetType>(ValueConversion::convert<FirstTargetType>(*firstValue));
181 } catch (const ConversionException &exception) {
182 throw ArgumentValueConversionError{ exception.what(), *firstValue, typeid(FirstTargetType).name() };
183 }
184 }
185};
186} // namespace Helper
188
189} // namespace ValueConversion
190
195 ArgumentOccurrence(std::size_t index);
196 ArgumentOccurrence(std::size_t index, const std::vector<Argument *> parentPath, Argument *parent);
197
201 std::size_t index;
202
206 std::vector<const char *> values;
207
212 std::vector<Argument *> path;
213
214 template <typename... RemainingTargetTypes> std::tuple<RemainingTargetTypes...> convertValues() const;
215
216private:
217 [[noreturn]] void throwNumberOfValuesNotSufficient(unsigned long valuesToConvert) const;
218};
219
225template <typename... RemainingTargetTypes> std::tuple<RemainingTargetTypes...> ArgumentOccurrence::convertValues() const
226{
227 constexpr auto valuesToConvert = sizeof...(RemainingTargetTypes);
228 if (values.size() < valuesToConvert) {
229 throwNumberOfValuesNotSufficient(valuesToConvert);
230 }
231 try {
232 return ValueConversion::Helper::ArgumentValueConverter<valuesToConvert, RemainingTargetTypes...>::convertValues(values.cbegin());
233 } catch (const ValueConversion::Helper::ArgumentValueConversionError &error) {
234 error.throwFailure(path);
235 }
236}
237
242 : index(index)
243{
244}
245
254inline ArgumentOccurrence::ArgumentOccurrence(std::size_t index, const std::vector<Argument *> parentPath, Argument *parent)
255 : index(index)
256 , path(parentPath)
257{
258 if (parent) {
259 path.push_back(parent);
260 }
261}
262
264 friend ArgumentParser;
265 friend ArgumentReader;
266 friend ArgumentParserTests;
267
268public:
269 typedef std::function<void(const ArgumentOccurrence &)> CallbackFunction;
270
272 enum class Flags : std::uint64_t {
273 None = 0x0,
274 Combinable
275 = 0x1,
276 Implicit = 0x2,
277 Operation = 0x4,
278 Deprecated = 0x8,
279 Greedy
280 = 0x10,
281 };
282
283 Argument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
284 ~Argument();
285
286 // declare getter/setter/properties/operations for argument definition:
287 // - those properties must be set *before* parsing
288 // - they control the behaviour of the parser, eg.
289 // - the name/abbreviation to look for
290 // - constraints to be checked
291 // - callbacks to be invoked
292 // TODO v5: It would make sense to move these to a separate class (eg. ArgumentDefinition) to prevent this one from
293 // becoming to big.
294 const char *name() const;
295 void setName(const char *name);
296 char abbreviation() const;
297 void setAbbreviation(char abbreviation);
298 const char *environmentVariable() const;
299 void setEnvironmentVariable(const char *environmentVariable);
300 const char *description() const;
301 void setDescription(const char *description);
302 const char *example() const;
303 void setExample(const char *example);
304 std::size_t requiredValueCount() const;
305 void setRequiredValueCount(std::size_t requiredValueCount);
306 const std::vector<const char *> &valueNames() const;
307 void setValueNames(std::initializer_list<const char *> valueNames);
308 void appendValueName(const char *valueName);
309 void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences);
310 const std::vector<Argument *> &path(std::size_t occurrence = 0) const;
311 bool isRequired() const;
312 void setRequired(bool required);
313 Argument::Flags flags() const;
314 void setFlags(Argument::Flags flags);
315 void setFlags(Argument::Flags flags, bool add);
316 bool isCombinable() const;
317 void setCombinable(bool combinable);
318 bool isImplicit() const;
319 void setImplicit(bool implicit);
320 bool denotesOperation() const;
321 void setDenotesOperation(bool denotesOperation);
322 const CallbackFunction &callback() const;
323 void setCallback(CallbackFunction callback);
324 const ArgumentVector &subArguments() const;
325 void setSubArguments(const ArgumentInitializerList &subArguments);
326 void addSubArguments(const ArgumentInitializerList &subArguments);
327 void addSubArgument(Argument *arg);
328 bool hasSubArguments() const;
329 const ArgumentVector &parents() const;
330 void printInfo(std::ostream &os, unsigned char indentation = 0) const;
331
332 // declare getter/setter/properties for bash completion: those properties must be set *before parsing
333 ValueCompletionBehavior valueCompletionBehaviour() const;
334 void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour);
335 const char *preDefinedCompletionValues() const;
336 void setPreDefinedCompletionValues(const char *preDefinedCompletionValues);
337
338 // declare getter/read-only properties for parsing results: those properties will be populated when parsing
339 const std::vector<const char *> &values(std::size_t occurrence = 0) const;
340 template <typename... TargetType> std::tuple<TargetType...> valuesAs(std::size_t occurrence = 0) const;
341 template <typename... TargetType> std::vector<std::tuple<TargetType...>> allValuesAs() const;
342
343 const char *firstValue() const;
344 const char *firstValueOr(const char *fallback) const;
345 bool allRequiredValuesPresent(std::size_t occurrence = 0) const;
346 bool isPresent() const;
347 std::size_t occurrences() const;
348 std::size_t index(std::size_t occurrence) const;
349 std::size_t minOccurrences() const;
350 std::size_t maxOccurrences() const;
351 bool isDeprecated() const;
352 const Argument *deprecatedBy() const;
353 void markAsDeprecated(const Argument *deprecatedBy = nullptr);
354 bool isMainArgument() const;
355 bool isParentPresent() const;
356 Argument *conflictsWithArgument() const;
357 Argument *wouldConflictWithArgument() const;
358 Argument *specifiedOperation() const;
359 const std::vector<ArgumentOccurrence> &occurrenceInfo() const;
360 std::vector<ArgumentOccurrence> &occurrenceInfo();
361 void reset();
362 void resetRecursively();
363
368 static constexpr std::size_t varValueCount = std::numeric_limits<std::size_t>::max();
369
370private:
371 // declare internal getter/setter/properties/operations for argument definition
372 bool matchesDenotation(const char *denotation, std::size_t denotationLength) const;
373
374 const char *m_name;
375 char m_abbreviation;
376 const char *m_environmentVar;
377 const char *m_description;
378 const char *m_example;
379 std::size_t m_minOccurrences;
380 std::size_t m_maxOccurrences;
381 std::size_t m_requiredValueCount;
382 std::vector<const char *> m_valueNames;
383 Flags m_flags;
384 std::vector<ArgumentOccurrence> m_occurrences;
385 ArgumentVector m_subArgs;
386 CallbackFunction m_callbackFunction;
387 ArgumentVector m_parents;
388 const Argument *m_deprecatedBy;
389 bool m_isMainArg;
390 ValueCompletionBehavior m_valueCompletionBehavior;
391 const char *m_preDefinedCompletionValues;
392};
393
395constexpr Argument::Flags operator|(Argument::Flags lhs, Argument::Flags rhs)
396{
397 return static_cast<Argument::Flags>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
398}
399
400constexpr bool operator&(Argument::Flags lhs, Argument::Flags rhs)
401{
402 return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
403}
405
411template <typename... TargetType> std::tuple<TargetType...> Argument::valuesAs(std::size_t occurrence) const
412{
413 return m_occurrences[occurrence].convertValues<TargetType...>();
414}
415
421template <typename... TargetType> std::vector<std::tuple<TargetType...>> Argument::allValuesAs() const
422{
423 std::vector<std::tuple<TargetType...>> res;
424 res.reserve(m_occurrences.size());
425 for (const auto &occurrence : m_occurrences) {
426 res.emplace_back(occurrence.convertValues<TargetType...>());
427 }
428 return res;
429}
430
432public:
434};
435
437public:
438 OperationArgument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
439};
440
442public:
443 ConfigValueArgument(const char *name, char abbreviation = '\0', const char *description = nullptr,
444 std::initializer_list<const char *> valueNames = std::initializer_list<const char *>());
445};
446
448 friend ArgumentParserTests;
449
450public:
452 void apply() const;
453};
454
456
458 friend ArgumentParserTests;
459 friend ArgumentReader;
460
461public:
463
464 // declare getter/setter for argument definitions
465 const ArgumentVector &mainArguments() const;
466 void setMainArguments(const ArgumentInitializerList &mainArguments);
467 void addMainArgument(Argument *argument);
468
469 // declare operations which will consider previously assigned argument definitions and maybe modify parsing results
470 void printHelp(std::ostream &os) const;
471 void parseArgs(int argc, const char *const *argv,
472 ParseArgumentBehavior behavior
473 = ParseArgumentBehavior::CheckConstraints | ParseArgumentBehavior::InvokeCallbacks | ParseArgumentBehavior::ExitOnFailure);
474 void readArgs(int argc, const char *const *argv);
475 void resetArgs();
476 void checkConstraints();
477 void invokeCallbacks();
478
479 // declare getter for parsing results
480 unsigned int actualArgumentCount() const;
481 const char *executable() const;
482 UnknownArgumentBehavior unknownArgumentBehavior() const;
483 void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior);
484 Argument *defaultArgument() const;
485 void setDefaultArgument(Argument *argument);
486 Argument *specifiedOperation() const;
487 bool isUncombinableMainArgPresent() const;
488 void setExitFunction(std::function<void(int)> exitFunction);
489 const HelpArgument &helpArg() const;
490 HelpArgument &helpArg();
491 const NoColorArgument &noColorArg() const;
492 NoColorArgument &noColorArg();
493
494private:
495 // declare internal operations
496 CPP_UTILITIES_IF_DEBUG_BUILD(void verifyArgs(const ArgumentVector &args);)
497 ArgumentCompletionInfo determineCompletionInfo(
498 int argc, const char *const *argv, unsigned int currentWordIndex, const ArgumentReader &reader) const;
499 std::string findSuggestions(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
500 void printBashCompletion(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
501 void checkConstraints(const ArgumentVector &args);
502 static void invokeCallbacks(const ArgumentVector &args);
503 void invokeExit(int code);
504
505 ArgumentVector m_mainArgs;
506 unsigned int m_actualArgc;
507 const char *m_executable;
508 UnknownArgumentBehavior m_unknownArgBehavior;
509 Argument *m_defaultArg;
510 HelpArgument m_helpArg;
511 NoColorArgument m_noColorArg;
512 std::function<void(int)> m_exitFunction;
513};
514
520inline const char *Argument::name() const
521{
522 return m_name;
523}
524
532inline void Argument::setName(const char *name)
533{
534#if defined(CPP_UTILITIES_DEBUG_BUILD) && !defined(_MSC_VER)
535 if (name && *name) {
536 assert(*name != '-');
537 for (const char *c = name; *c; ++c) {
538 assert(*c != ' ' && *c != '=' && *c != '\'' && *c != '\"' && *c != '\n' && *c != '\r');
539 }
540 }
541#endif
542 m_name = name;
543}
544
550inline char Argument::abbreviation() const
551{
552 return m_abbreviation;
553}
554
562inline void Argument::setAbbreviation(char abbreviation)
563{
564 CPP_UTILITIES_IF_DEBUG_BUILD(assert(abbreviation != ' ' && abbreviation != '=' && abbreviation != '-' && abbreviation != '\''
565 && abbreviation != '"' && abbreviation != '\n' && abbreviation != '\r'));
566 m_abbreviation = abbreviation;
567}
568
573inline const char *Argument::environmentVariable() const
574{
575 return m_environmentVar;
576}
577
582inline void Argument::setEnvironmentVariable(const char *environmentVariable)
583{
584 m_environmentVar = environmentVariable;
585}
586
592inline const char *Argument::description() const
593{
594 return m_description;
595}
596
602inline void Argument::setDescription(const char *description)
603{
604 m_description = description;
605}
606
612inline const char *Argument::example() const
613{
614 return m_example;
615}
616
622inline void Argument::setExample(const char *example)
623{
624 m_example = example;
625}
626
633inline const std::vector<const char *> &Argument::values(std::size_t occurrence) const
634{
635 return m_occurrences[occurrence].values;
636}
637
651inline std::size_t Argument::requiredValueCount() const
652{
653 return m_requiredValueCount;
654}
655
668inline void Argument::setRequiredValueCount(std::size_t requiredValueCount)
669{
670 m_requiredValueCount = requiredValueCount;
671}
672
681inline const std::vector<const char *> &Argument::valueNames() const
682{
683 return m_valueNames;
684}
685
699inline void Argument::setValueNames(std::initializer_list<const char *> valueNames)
700{
701 m_valueNames.assign(valueNames);
702}
703
710inline void Argument::appendValueName(const char *valueName)
711{
712 m_valueNames.emplace_back(valueName);
713}
714
718inline bool Argument::allRequiredValuesPresent(std::size_t occurrence) const
719{
720 return m_requiredValueCount == Argument::varValueCount
721 || (m_occurrences[occurrence].values.size() >= static_cast<std::size_t>(m_requiredValueCount));
722}
723
728inline bool Argument::isImplicit() const
729{
730 return m_flags & Flags::Implicit;
731}
732
737inline void Argument::setImplicit(bool implicit)
738{
739 setFlags(Flags::Implicit, implicit);
740}
741
745inline bool Argument::isPresent() const
746{
747 return !m_occurrences.empty();
748}
749
753inline std::size_t Argument::occurrences() const
754{
755 return m_occurrences.size();
756}
757
761inline std::size_t Argument::index(std::size_t occurrence) const
762{
763 return m_occurrences[occurrence].index;
764}
765
771inline std::size_t Argument::minOccurrences() const
772{
773 return m_minOccurrences;
774}
775
781inline std::size_t Argument::maxOccurrences() const
782{
783 return m_maxOccurrences;
784}
785
786inline bool Argument::isDeprecated() const
787{
788 return m_flags & Flags::Deprecated;
789}
790
794inline const Argument *Argument::deprecatedBy() const
795{
796 return m_deprecatedBy;
797}
798
804inline void Argument::markAsDeprecated(const Argument *deprecatedBy)
805{
807 m_deprecatedBy = deprecatedBy;
808}
809
815inline void Argument::setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
816{
817 m_minOccurrences = minOccurrences;
818 m_maxOccurrences = maxOccurrences;
819}
820
824inline const std::vector<Argument *> &Argument::path(std::size_t occurrence) const
825{
826 return m_occurrences[occurrence].path;
827}
828
838inline bool Argument::isRequired() const
839{
840 return m_minOccurrences;
841}
842
850inline void Argument::setRequired(bool required)
851{
852 if (required) {
853 if (!m_minOccurrences) {
854 m_minOccurrences = 1;
855 }
856 } else {
857 m_minOccurrences = 0;
858 }
859}
860
865{
866 return m_flags;
867}
868
873{
874 m_flags = flags;
875}
876
880inline void Argument::setFlags(Argument::Flags flags, bool add)
881{
882 m_flags = add ? (m_flags | flags)
883 : static_cast<Argument::Flags>(static_cast<std::underlying_type<Argument::Flags>::type>(m_flags)
884 & ~static_cast<std::underlying_type<Argument::Flags>::type>(flags));
885}
886
895inline bool Argument::isCombinable() const
896{
897 return m_flags & Flags::Combinable;
898}
899
908inline void Argument::setCombinable(bool combinable)
909{
910 setFlags(Flags::Combinable, combinable);
911}
912
923inline bool Argument::denotesOperation() const
924{
925 return m_flags & Flags::Operation;
926}
927
932inline void Argument::setDenotesOperation(bool denotesOperation)
933{
935}
936
942{
943 return m_callbackFunction;
944}
945
953{
954 m_callbackFunction = callback;
955}
956
964{
965 return m_subArgs;
966}
967
974inline bool Argument::hasSubArguments() const
975{
976 return !m_subArgs.empty();
977}
978
990{
991 return m_parents;
992}
993
1000inline bool Argument::isMainArgument() const
1001{
1002 return m_isMainArg;
1003}
1004
1012{
1013 return m_valueCompletionBehavior;
1014}
1015
1023{
1024 m_valueCompletionBehavior = completionValues;
1025}
1026
1031{
1032 return m_preDefinedCompletionValues;
1033}
1034
1038inline void Argument::setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
1039{
1040 m_preDefinedCompletionValues = preDefinedCompletionValues;
1041}
1042
1048inline void Argument::reset()
1049{
1050 m_occurrences.clear();
1051}
1052
1053inline OperationArgument::OperationArgument(const char *name, char abbreviation, const char *description, const char *example)
1054 : Argument(name, abbreviation, description, example)
1055{
1056 setDenotesOperation(true);
1057}
1058
1063 const char *name, char abbreviation, const char *description, std::initializer_list<const char *> valueNames)
1064 : Argument(name, abbreviation, description)
1065{
1066 setCombinable(true);
1069}
1070
1075inline const std::vector<ArgumentOccurrence> &Argument::occurrenceInfo() const
1076{
1077 return m_occurrences;
1078}
1079
1086inline std::vector<ArgumentOccurrence> &Argument::occurrenceInfo()
1087{
1088 return m_occurrences;
1089}
1090
1096{
1097 return m_mainArgs;
1098}
1099
1103inline unsigned int ArgumentParser::actualArgumentCount() const
1104{
1105 return m_actualArgc;
1106}
1107
1111inline const char *ArgumentParser::executable() const
1112{
1113 return m_executable;
1114}
1115
1122{
1123 return m_unknownArgBehavior;
1124}
1125
1132{
1133 m_unknownArgBehavior = behavior;
1134}
1135
1141{
1142 return m_defaultArg;
1143}
1144
1150{
1151 m_defaultArg = argument;
1152}
1153
1160{
1161 checkConstraints(m_mainArgs);
1162}
1163
1169{
1170 invokeCallbacks(m_mainArgs);
1171}
1172
1177inline void ArgumentParser::setExitFunction(std::function<void(int)> exitFunction)
1178{
1179 m_exitFunction = exitFunction;
1180}
1181
1186{
1187 return m_helpArg;
1188}
1189
1194{
1195 return m_helpArg;
1196}
1197
1202{
1203 return m_noColorArg;
1204}
1205
1210{
1211 return m_noColorArg;
1212}
1213
1214} // namespace CppUtilities
1215
1216#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.
std::function< void(const ArgumentOccurrence &)> CallbackFunction
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::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.
Definition global.h:14
constexpr bool operator&(FlagEnumClass lhs, FlagEnumClass rhs)
TargetType convert(const char *value)
Contains all utilities provides by the c++utilities library.
std::initializer_list< Argument * > ArgumentInitializerList
std::vector< Argument * > ArgumentVector
UnknownArgumentBehavior
The UnknownArgumentBehavior enum specifies the behavior of the argument parser when an unknown argume...
IntegralType stringToNumber(const StringType &string, BaseType base=10)
Converts the given string to an unsigned/signed number assuming string uses the specified base.
ParseArgumentBehavior
The ParseArgumentBehavior enum specifies the behavior when parsing arguments.
ValueCompletionBehavior
The ValueCompletionBehavior enum specifies the items to be considered when generating completion for ...
std::function< bool(Argument *)> ArgumentPredicate
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).