C++ Utilities  5.10.5
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 
15 class ArgumentParserTests; // not a public class (only used for internal tests)
16 
17 namespace 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 
63 class Argument;
64 class ArgumentParser;
65 class ArgumentReader;
66 
67 using ArgumentInitializerList = std::initializer_list<Argument *>;
68 using ArgumentVector = std::vector<Argument *>;
69 using 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 
116 enum 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 
145 namespace ValueConversion {
146 template <typename TargetType, Traits::EnableIf<std::is_same<TargetType, std::string>> * = nullptr> TargetType convert(const char *value)
147 {
148  return std::string(value);
149 }
150 
151 template <typename TargetType, Traits::EnableIf<std::is_arithmetic<TargetType>> * = nullptr> TargetType convert(const char *value)
152 {
153  return stringToNumber<TargetType>(value);
154 }
155 
157 namespace Helper {
158 struct 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 
166 template <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 
174 template <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 
215 private:
216  [[noreturn]] void throwNumberOfValuesNotSufficient(unsigned long valuesToConvert) const;
217 };
218 
224 template <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 
240 inline ArgumentOccurrence::ArgumentOccurrence(std::size_t index)
241  : index(index)
242 {
243 }
244 
253 inline 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 
267 public:
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 
364 private:
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 
394 constexpr 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 
405 template <typename... TargetType> std::tuple<TargetType...> Argument::valuesAs(std::size_t occurrence) const
406 {
407  return m_occurrences[occurrence].convertValues<TargetType...>();
408 }
409 
415 template <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 
426 public:
427  HelpArgument(ArgumentParser &parser);
428 };
429 
431 public:
432  OperationArgument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
433 };
434 
436 public:
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 
444 public:
445  NoColorArgument();
446  void apply() const;
447 };
448 
450 
452  friend ArgumentParserTests;
453  friend ArgumentReader;
454 
455 public:
456  ArgumentParser();
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 
488 private:
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 
514 inline const char *Argument::name() const
515 {
516  return m_name;
517 }
518 
526 inline 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 
544 inline char Argument::abbreviation() const
545 {
546  return m_abbreviation;
547 }
548 
556 inline 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 
567 inline const char *Argument::environmentVariable() const
568 {
569  return m_environmentVar;
570 }
571 
576 inline void Argument::setEnvironmentVariable(const char *environmentVariable)
577 {
578  m_environmentVar = environmentVariable;
579 }
580 
586 inline const char *Argument::description() const
587 {
588  return m_description;
589 }
590 
596 inline void Argument::setDescription(const char *description)
597 {
598  m_description = description;
599 }
600 
606 inline const char *Argument::example() const
607 {
608  return m_example;
609 }
610 
616 inline void Argument::setExample(const char *example)
617 {
618  m_example = example;
619 }
620 
627 inline const std::vector<const char *> &Argument::values(std::size_t occurrence) const
628 {
629  return m_occurrences[occurrence].values;
630 }
631 
645 inline std::size_t Argument::requiredValueCount() const
646 {
647  return m_requiredValueCount;
648 }
649 
662 inline void Argument::setRequiredValueCount(std::size_t requiredValueCount)
663 {
664  m_requiredValueCount = requiredValueCount;
665 }
666 
675 inline const std::vector<const char *> &Argument::valueNames() const
676 {
677  return m_valueNames;
678 }
679 
693 inline void Argument::setValueNames(std::initializer_list<const char *> valueNames)
694 {
695  m_valueNames.assign(valueNames);
696 }
697 
704 inline void Argument::appendValueName(const char *valueName)
705 {
706  m_valueNames.emplace_back(valueName);
707 }
708 
712 inline 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 
722 inline bool Argument::isImplicit() const
723 {
724  return m_flags & Flags::Implicit;
725 }
726 
731 inline void Argument::setImplicit(bool implicit)
732 {
733  setFlags(Flags::Implicit, implicit);
734 }
735 
739 inline bool Argument::isPresent() const
740 {
741  return !m_occurrences.empty();
742 }
743 
747 inline std::size_t Argument::occurrences() const
748 {
749  return m_occurrences.size();
750 }
751 
755 inline std::size_t Argument::index(std::size_t occurrence) const
756 {
757  return m_occurrences[occurrence].index;
758 }
759 
765 inline std::size_t Argument::minOccurrences() const
766 {
767  return m_minOccurrences;
768 }
769 
775 inline std::size_t Argument::maxOccurrences() const
776 {
777  return m_maxOccurrences;
778 }
779 
780 inline bool Argument::isDeprecated() const
781 {
782  return m_flags & Flags::Deprecated;
783 }
784 
788 inline const Argument *Argument::deprecatedBy() const
789 {
790  return m_deprecatedBy;
791 }
792 
798 inline void Argument::markAsDeprecated(const Argument *deprecatedBy)
799 {
801  m_deprecatedBy = deprecatedBy;
802 }
803 
809 inline void Argument::setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
810 {
811  m_minOccurrences = minOccurrences;
812  m_maxOccurrences = maxOccurrences;
813 }
814 
818 inline const std::vector<Argument *> &Argument::path(std::size_t occurrence) const
819 {
820  return m_occurrences[occurrence].path;
821 }
822 
832 inline bool Argument::isRequired() const
833 {
834  return m_minOccurrences;
835 }
836 
844 inline 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 
874 inline 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 
889 inline bool Argument::isCombinable() const
890 {
891  return m_flags & Flags::Combinable;
892 }
893 
902 inline void Argument::setCombinable(bool combinable)
903 {
904  setFlags(Flags::Combinable, combinable);
905 }
906 
917 inline bool Argument::denotesOperation() const
918 {
919  return m_flags & Flags::Operation;
920 }
921 
926 inline 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 
968 inline bool Argument::hasSubArguments() const
969 {
970  return !m_subArgs.empty();
971 }
972 
983 inline const ArgumentVector &Argument::parents() const
984 {
985  return m_parents;
986 }
987 
994 inline 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 
1024 inline const char *Argument::preDefinedCompletionValues() const
1025 {
1026  return m_preDefinedCompletionValues;
1027 }
1028 
1032 inline void Argument::setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
1033 {
1034  m_preDefinedCompletionValues = preDefinedCompletionValues;
1035 }
1036 
1042 inline void Argument::reset()
1043 {
1044  m_occurrences.clear();
1045 }
1046 
1047 inline 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 
1069 inline const std::vector<ArgumentOccurrence> &Argument::occurrenceInfo() const
1070 {
1071  return m_occurrences;
1072 }
1073 
1080 inline std::vector<ArgumentOccurrence> &Argument::occurrenceInfo()
1081 {
1082  return m_occurrences;
1083 }
1084 
1090 {
1091  return m_mainArgs;
1092 }
1093 
1097 inline unsigned int ArgumentParser::actualArgumentCount() const
1098 {
1099  return m_actualArgc;
1100 }
1101 
1105 inline 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 
1171 inline 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).