C++ Utilities  5.7.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 
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,
121  FileSystemIfNoPreDefinedValues = 16,
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  bool allRequiredValuesPresent(std::size_t occurrence = 0) const;
339  bool isPresent() const;
340  std::size_t occurrences() const;
341  std::size_t index(std::size_t occurrence) const;
342  std::size_t minOccurrences() const;
343  std::size_t maxOccurrences() const;
344  bool isDeprecated() const;
345  const Argument *deprecatedBy() const;
346  void markAsDeprecated(const Argument *deprecatedBy = nullptr);
347  bool isMainArgument() const;
348  bool isParentPresent() const;
349  Argument *conflictsWithArgument() const;
350  Argument *wouldConflictWithArgument() const;
351  Argument *specifiedOperation() const;
352  const std::vector<ArgumentOccurrence> &occurrenceInfo() const;
353  std::vector<ArgumentOccurrence> &occurrenceInfo();
354  void reset();
355  void resetRecursively();
356 
361  static constexpr std::size_t varValueCount = std::numeric_limits<std::size_t>::max();
362 
363 private:
364  // declare internal getter/setter/properties/operations for argument definition
365  bool matchesDenotation(const char *denotation, size_t denotationLength) const;
366 
367  const char *m_name;
368  char m_abbreviation;
369  const char *m_environmentVar;
370  const char *m_description;
371  const char *m_example;
372  std::size_t m_minOccurrences;
373  std::size_t m_maxOccurrences;
374  std::size_t m_requiredValueCount;
375  std::vector<const char *> m_valueNames;
376  Flags m_flags;
377  std::vector<ArgumentOccurrence> m_occurrences;
378  ArgumentVector m_subArgs;
379  CallbackFunction m_callbackFunction;
380  ArgumentVector m_parents;
381  const Argument *m_deprecatedBy;
382  bool m_isMainArg;
383  ValueCompletionBehavior m_valueCompletionBehavior;
384  const char *m_preDefinedCompletionValues;
385 };
386 
389 {
390  return static_cast<Argument::Flags>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
391 }
392 
393 constexpr bool operator&(Argument::Flags lhs, Argument::Flags rhs)
394 {
395  return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
396 }
398 
404 template <typename... TargetType> std::tuple<TargetType...> Argument::valuesAs(std::size_t occurrence) const
405 {
406  return m_occurrences[occurrence].convertValues<TargetType...>();
407 }
408 
414 template <typename... TargetType> std::vector<std::tuple<TargetType...>> Argument::allValuesAs() const
415 {
416  std::vector<std::tuple<TargetType...>> res;
417  res.reserve(m_occurrences.size());
418  for (const auto &occurrence : m_occurrences) {
419  res.emplace_back(occurrence.convertValues<TargetType...>());
420  }
421  return res;
422 }
423 
425 public:
426  HelpArgument(ArgumentParser &parser);
427 };
428 
430 public:
431  OperationArgument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
432 };
433 
435 public:
436  ConfigValueArgument(const char *name, char abbreviation = '\0', const char *description = nullptr,
437  std::initializer_list<const char *> valueNames = std::initializer_list<const char *>());
438 };
439 
441  friend ArgumentParserTests;
442 
443 public:
444  NoColorArgument();
445  void apply() const;
446 };
447 
449 
451  friend ArgumentParserTests;
452  friend ArgumentReader;
453 
454 public:
455  ArgumentParser();
456 
457  // declare getter/setter for argument definitions
458  const ArgumentVector &mainArguments() const;
459  void setMainArguments(const ArgumentInitializerList &mainArguments);
460  void addMainArgument(Argument *argument);
461 
462  // declare operations which will consider previously assigned argument definitions and maybe modify parsing results
463  void printHelp(std::ostream &os) const;
464  void parseArgs(int argc, const char *const *argv,
465  ParseArgumentBehavior behavior
466  = ParseArgumentBehavior::CheckConstraints | ParseArgumentBehavior::InvokeCallbacks | ParseArgumentBehavior::ExitOnFailure);
467  void readArgs(int argc, const char *const *argv);
468  void resetArgs();
469  void checkConstraints();
470  void invokeCallbacks();
471 
472  // declare getter for parsing results
473  unsigned int actualArgumentCount() const;
474  const char *executable() const;
475  UnknownArgumentBehavior unknownArgumentBehavior() const;
476  void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior);
477  Argument *defaultArgument() const;
478  void setDefaultArgument(Argument *argument);
479  Argument *specifiedOperation() const;
480  bool isUncombinableMainArgPresent() const;
481  void setExitFunction(std::function<void(int)> exitFunction);
482  const HelpArgument &helpArg() const;
483  HelpArgument &helpArg();
484  const NoColorArgument &noColorArg() const;
485  NoColorArgument &noColorArg();
486 
487 private:
488  // declare internal operations
489  CPP_UTILITIES_IF_DEBUG_BUILD(void verifyArgs(const ArgumentVector &args);)
490  ArgumentCompletionInfo determineCompletionInfo(
491  int argc, const char *const *argv, unsigned int currentWordIndex, const ArgumentReader &reader) const;
492  std::string findSuggestions(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
493  void printBashCompletion(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
494  void checkConstraints(const ArgumentVector &args);
495  static void invokeCallbacks(const ArgumentVector &args);
496  void invokeExit(int code);
497 
498  ArgumentVector m_mainArgs;
499  unsigned int m_actualArgc;
500  const char *m_executable;
501  UnknownArgumentBehavior m_unknownArgBehavior;
502  Argument *m_defaultArg;
503  HelpArgument m_helpArg;
504  NoColorArgument m_noColorArg;
505  std::function<void(int)> m_exitFunction;
506 };
507 
513 inline const char *Argument::name() const
514 {
515  return m_name;
516 }
517 
525 inline void Argument::setName(const char *name)
526 {
527 #ifdef CPP_UTILITIES_DEBUG_BUILD
528  if (name && *name) {
529  assert(*name != '-');
530  for (const char *c = name; *c; ++c) {
531  assert(*c != ' ' && *c != '=' && *c != '\'' && *c != '\"' && *c != '\n' && *c != '\r');
532  }
533  }
534 #endif
535  m_name = name;
536 }
537 
543 inline char Argument::abbreviation() const
544 {
545  return m_abbreviation;
546 }
547 
555 inline void Argument::setAbbreviation(char abbreviation)
556 {
557  CPP_UTILITIES_IF_DEBUG_BUILD(assert(abbreviation != ' ' && abbreviation != '=' && abbreviation != '-' && abbreviation != '\''
558  && abbreviation != '"' && abbreviation != '\n' && abbreviation != '\r'));
559  m_abbreviation = abbreviation;
560 }
561 
566 inline const char *Argument::environmentVariable() const
567 {
568  return m_environmentVar;
569 }
570 
575 inline void Argument::setEnvironmentVariable(const char *environmentVariable)
576 {
577  m_environmentVar = environmentVariable;
578 }
579 
585 inline const char *Argument::description() const
586 {
587  return m_description;
588 }
589 
595 inline void Argument::setDescription(const char *description)
596 {
597  m_description = description;
598 }
599 
605 inline const char *Argument::example() const
606 {
607  return m_example;
608 }
609 
615 inline void Argument::setExample(const char *example)
616 {
617  m_example = example;
618 }
619 
626 inline const std::vector<const char *> &Argument::values(std::size_t occurrence) const
627 {
628  return m_occurrences[occurrence].values;
629 }
630 
644 inline std::size_t Argument::requiredValueCount() const
645 {
646  return m_requiredValueCount;
647 }
648 
661 inline void Argument::setRequiredValueCount(std::size_t requiredValueCount)
662 {
663  m_requiredValueCount = requiredValueCount;
664 }
665 
674 inline const std::vector<const char *> &Argument::valueNames() const
675 {
676  return m_valueNames;
677 }
678 
692 inline void Argument::setValueNames(std::initializer_list<const char *> valueNames)
693 {
694  m_valueNames.assign(valueNames);
695 }
696 
703 inline void Argument::appendValueName(const char *valueName)
704 {
705  m_valueNames.emplace_back(valueName);
706 }
707 
711 inline bool Argument::allRequiredValuesPresent(std::size_t occurrence) const
712 {
713  return m_requiredValueCount == Argument::varValueCount
714  || (m_occurrences[occurrence].values.size() >= static_cast<std::size_t>(m_requiredValueCount));
715 }
716 
721 inline bool Argument::isImplicit() const
722 {
723  return m_flags & Flags::Implicit;
724 }
725 
730 inline void Argument::setImplicit(bool implicit)
731 {
732  setFlags(Flags::Implicit, implicit);
733 }
734 
738 inline bool Argument::isPresent() const
739 {
740  return !m_occurrences.empty();
741 }
742 
746 inline std::size_t Argument::occurrences() const
747 {
748  return m_occurrences.size();
749 }
750 
754 inline std::size_t Argument::index(std::size_t occurrence) const
755 {
756  return m_occurrences[occurrence].index;
757 }
758 
764 inline std::size_t Argument::minOccurrences() const
765 {
766  return m_minOccurrences;
767 }
768 
774 inline std::size_t Argument::maxOccurrences() const
775 {
776  return m_maxOccurrences;
777 }
778 
779 inline bool Argument::isDeprecated() const
780 {
781  return m_flags & Flags::Deprecated;
782 }
783 
787 inline const Argument *Argument::deprecatedBy() const
788 {
789  return m_deprecatedBy;
790 }
791 
797 inline void Argument::markAsDeprecated(const Argument *deprecatedBy)
798 {
800  m_deprecatedBy = deprecatedBy;
801 }
802 
808 inline void Argument::setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
809 {
810  m_minOccurrences = minOccurrences;
811  m_maxOccurrences = maxOccurrences;
812 }
813 
817 inline const std::vector<Argument *> &Argument::path(std::size_t occurrence) const
818 {
819  return m_occurrences[occurrence].path;
820 }
821 
831 inline bool Argument::isRequired() const
832 {
833  return m_minOccurrences;
834 }
835 
843 inline void Argument::setRequired(bool required)
844 {
845  if (required) {
846  if (!m_minOccurrences) {
847  m_minOccurrences = 1;
848  }
849  } else {
850  m_minOccurrences = 0;
851  }
852 }
853 
858 {
859  return m_flags;
860 }
861 
866 {
867  m_flags = flags;
868 }
869 
873 inline void Argument::setFlags(Argument::Flags flags, bool add)
874 {
875  m_flags = add ? (m_flags | flags)
876  : static_cast<Argument::Flags>(static_cast<std::underlying_type<Argument::Flags>::type>(m_flags)
877  & ~static_cast<std::underlying_type<Argument::Flags>::type>(flags));
878 }
879 
888 inline bool Argument::isCombinable() const
889 {
890  return m_flags & Flags::Combinable;
891 }
892 
901 inline void Argument::setCombinable(bool combinable)
902 {
903  setFlags(Flags::Combinable, combinable);
904 }
905 
916 inline bool Argument::denotesOperation() const
917 {
918  return m_flags & Flags::Operation;
919 }
920 
925 inline void Argument::setDenotesOperation(bool denotesOperation)
926 {
928 }
929 
935 {
936  return m_callbackFunction;
937 }
938 
946 {
947  m_callbackFunction = callback;
948 }
949 
957 {
958  return m_subArgs;
959 }
960 
967 inline bool Argument::hasSubArguments() const
968 {
969  return !m_subArgs.empty();
970 }
971 
982 inline const ArgumentVector &Argument::parents() const
983 {
984  return m_parents;
985 }
986 
993 inline bool Argument::isMainArgument() const
994 {
995  return m_isMainArg;
996 }
997 
1005 {
1006  return m_valueCompletionBehavior;
1007 }
1008 
1016 {
1017  m_valueCompletionBehavior = completionValues;
1018 }
1019 
1023 inline const char *Argument::preDefinedCompletionValues() const
1024 {
1025  return m_preDefinedCompletionValues;
1026 }
1027 
1031 inline void Argument::setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
1032 {
1033  m_preDefinedCompletionValues = preDefinedCompletionValues;
1034 }
1035 
1041 inline void Argument::reset()
1042 {
1043  m_occurrences.clear();
1044 }
1045 
1046 inline OperationArgument::OperationArgument(const char *name, char abbreviation, const char *description, const char *example)
1047  : Argument(name, abbreviation, description, example)
1048 {
1049  setDenotesOperation(true);
1050 }
1051 
1056  const char *name, char abbreviation, const char *description, std::initializer_list<const char *> valueNames)
1057  : Argument(name, abbreviation, description)
1058 {
1059  setCombinable(true);
1062 }
1063 
1068 inline const std::vector<ArgumentOccurrence> &Argument::occurrenceInfo() const
1069 {
1070  return m_occurrences;
1071 }
1072 
1079 inline std::vector<ArgumentOccurrence> &Argument::occurrenceInfo()
1080 {
1081  return m_occurrences;
1082 }
1083 
1089 {
1090  return m_mainArgs;
1091 }
1092 
1096 inline unsigned int ArgumentParser::actualArgumentCount() const
1097 {
1098  return m_actualArgc;
1099 }
1100 
1104 inline const char *ArgumentParser::executable() const
1105 {
1106  return m_executable;
1107 }
1108 
1115 {
1116  return m_unknownArgBehavior;
1117 }
1118 
1125 {
1126  m_unknownArgBehavior = behavior;
1127 }
1128 
1134 {
1135  return m_defaultArg;
1136 }
1137 
1143 {
1144  m_defaultArg = argument;
1145 }
1146 
1153 {
1154  checkConstraints(m_mainArgs);
1155 }
1156 
1162 {
1163  invokeCallbacks(m_mainArgs);
1164 }
1165 
1170 inline void ArgumentParser::setExitFunction(std::function<void(int)> exitFunction)
1171 {
1172  m_exitFunction = exitFunction;
1173 }
1174 
1179 {
1180  return m_helpArg;
1181 }
1182 
1187 {
1188  return m_helpArg;
1189 }
1190 
1195 {
1196  return m_noColorArg;
1197 }
1198 
1203 {
1204  return m_noColorArg;
1205 }
1206 
1207 } // namespace CppUtilities
1208 
1209 #endif // APPLICATION_UTILITIES_ARGUMENTPARSER_H
CppUtilities::Argument::setConstraints
void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
Sets the allowed number of occurrences.
Definition: argumentparser.h:808
CppUtilities::Argument::varValueCount
static constexpr std::size_t varValueCount
Denotes a variable number of values.
Definition: argumentparser.h:361
CppUtilities::Argument::allRequiredValuesPresent
bool allRequiredValuesPresent(std::size_t occurrence=0) const
Returns an indication whether all required values are present.
Definition: argumentparser.h:711
CppUtilities::Argument::occurrenceInfo
const std::vector< ArgumentOccurrence > & occurrenceInfo() const
Returns information about all occurrences of the argument which have been detected when parsing.
Definition: argumentparser.h:1068
CppUtilities::Argument::markAsDeprecated
void markAsDeprecated(const Argument *deprecatedBy=nullptr)
Marks the argument as deprecated.
Definition: argumentparser.h:797
CppUtilities::ApplicationInfo::dependencyVersions
std::vector< const char * > dependencyVersions
Definition: argumentparser.h:31
CppUtilities::Argument
The Argument class is a wrapper for command line argument information.
Definition: argumentparser.h:262
CppUtilities::ArgumentParser::noColorArg
const NoColorArgument & noColorArg() const
Returns the --no-color argument.
Definition: argumentparser.h:1194
CppUtilities::ArgumentCompletionInfo
The ArgumentCompletionInfo struct holds information internally used for shell completion and suggesti...
Definition: argumentparser.cpp:47
ArgumentParserTests
The ArgumentParserTests class tests the ArgumentParser and Argument classes.
Definition: argumentparsertests.cpp:38
CppUtilities::Argument::setDescription
void setDescription(const char *description)
Sets the description of the argument.
Definition: argumentparser.h:595
CppUtilities::ArgumentParser::checkConstraints
void checkConstraints()
Checks whether contraints are violated.
Definition: argumentparser.h:1152
CppUtilities::Argument::setRequiredValueCount
void setRequiredValueCount(std::size_t requiredValueCount)
Sets the number of values which are required to be given for this argument.
Definition: argumentparser.h:661
CppUtilities::IniFileParseOptions::None
@ None
CppUtilities::Argument::deprecatedBy
const Argument * deprecatedBy() const
Returns the argument which obsoletes this argument.
Definition: argumentparser.h:787
CppUtilities::NoColorArgument
The NoColorArgument class allows to specify whether use of escape codes or similar technique to provi...
Definition: argumentparser.h:440
CppUtilities::ValueCompletionBehavior
ValueCompletionBehavior
The ValueCompletionBehavior enum specifies the items to be considered when generating completion for ...
Definition: argumentparser.h:116
CppUtilities::Argument::appendValueName
void appendValueName(const char *valueName)
Appends a value name.
Definition: argumentparser.h:703
CppUtilities::Argument::setEnvironmentVariable
void setEnvironmentVariable(const char *environmentVariable)
Sets the environment variable queried when firstValue() is called.
Definition: argumentparser.h:575
CppUtilities::Argument::name
const char * name() const
Returns the name of the argument.
Definition: argumentparser.h:513
CppUtilities::ValueCompletionBehavior::None
@ None
CppUtilities::Argument::setExample
void setExample(const char *example)
Sets the a usage example for the argument.
Definition: argumentparser.h:615
CppUtilities::applicationInfo
CPP_UTILITIES_EXPORT ApplicationInfo applicationInfo
Stores global application info used by ArgumentParser::printHelp() and AboutDialog.
Definition: argumentparser.cpp:432
CppUtilities::ApplicationInfo
Stores information about an application.
Definition: argumentparser.h:22
CppUtilities::Argument::occurrences
std::size_t occurrences() const
Returns how often the argument could be detected when parsing.
Definition: argumentparser.h:746
CppUtilities::Argument::callback
const CallbackFunction & callback() const
Returns the assigned callback function.
Definition: argumentparser.h:934
CppUtilities::ApplicationInfo::license
const char * license
Definition: argumentparser.h:29
CppUtilities::OperationArgument::OperationArgument
OperationArgument(const char *name, char abbreviation='\0', const char *description=nullptr, const char *example=nullptr)
Definition: argumentparser.h:1046
CppUtilities::OperationArgument
The OperationArgument class is an Argument where denotesOperation() is true by default.
Definition: argumentparser.h:429
CppUtilities::Argument::minOccurrences
std::size_t minOccurrences() const
Returns the minimum number of occurrences.
Definition: argumentparser.h:764
CppUtilities::Argument::environmentVariable
const char * environmentVariable() const
Returns the environment variable queried when firstValue() is called.
Definition: argumentparser.h:566
CppUtilities::ArgumentParser::mainArguments
const ArgumentVector & mainArguments() const
Returns the main arguments.
Definition: argumentparser.h:1088
CppUtilities::Argument::isDeprecated
bool isDeprecated() const
Definition: argumentparser.h:779
CppUtilities::ArgumentOccurrence::ArgumentOccurrence
ArgumentOccurrence(std::size_t index)
Constructs an argument occurrence for the specified index.
Definition: argumentparser.h:240
CppUtilities::Argument::values
const std::vector< const char * > & values(std::size_t occurrence=0) const
Returns the parameter values for the specified occurrence of argument.
Definition: argumentparser.h:626
CppUtilities::Argument::valuesAs
std::tuple< TargetType... > valuesAs(std::size_t occurrence=0) const
Converts the present values for the specified occurrence to the specified target types.
Definition: argumentparser.h:404
CppUtilities::Argument::CallbackFunction
std::function< void(const ArgumentOccurrence &)> CallbackFunction
Definition: argumentparser.h:268
CppUtilities::Argument::example
const char * example() const
Returns the usage example of the argument.
Definition: argumentparser.h:605
CppUtilities::Argument::valueCompletionBehaviour
ValueCompletionBehavior valueCompletionBehaviour() const
Returns the items to be considered when generating completion for the values.
Definition: argumentparser.h:1004
CppUtilities::Argument::subArguments
const ArgumentVector & subArguments() const
Returns the secondary arguments for this argument.
Definition: argumentparser.h:956
CppUtilities::Argument::setCallback
void setCallback(CallbackFunction callback)
Sets a callback function which will be called by the parser if the argument could be found and no par...
Definition: argumentparser.h:945
CppUtilities::ArgumentParser::defaultArgument
Argument * defaultArgument() const
Returns the default argument.
Definition: argumentparser.h:1133
CppUtilities::Argument::requiredValueCount
std::size_t requiredValueCount() const
Returns the number of values which are required to be given for this argument.
Definition: argumentparser.h:644
CppUtilities::ConfigValueArgument
The ConfigValueArgument class is an Argument where setCombinable() is true by default.
Definition: argumentparser.h:434
CppUtilities::ParseArgumentBehavior::ReadArguments
@ ReadArguments
CppUtilities::Argument::setImplicit
void setImplicit(bool implicit)
Sets whether the argument is an implicit argument.
Definition: argumentparser.h:730
CppUtilities::max
constexpr T max(T first, T second)
Returns the greatest of the given items.
Definition: math.h:100
CppUtilities::ArgumentInitializerList
std::initializer_list< Argument * > ArgumentInitializerList
Definition: argumentparser.h:67
CppUtilities::ConfigValueArgument::ConfigValueArgument
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.
Definition: argumentparser.h:1055
CppUtilities::Argument::isImplicit
bool isImplicit() const
Returns an indication whether the argument is an implicit argument.
Definition: argumentparser.h:721
CppUtilities::Argument::preDefinedCompletionValues
const char * preDefinedCompletionValues() const
Returns the assigned values used when generating completion for the values.
Definition: argumentparser.h:1023
CppUtilities::FlagEnumClassOperations::operator&
constexpr bool operator&(FlagEnumClass lhs, FlagEnumClass rhs)
Definition: flagenumclass.h:50
CppUtilities::ArgumentParser::invokeCallbacks
void invokeCallbacks()
Invokes all assigned callbacks.
Definition: argumentparser.h:1161
CppUtilities::Argument::isRequired
bool isRequired() const
Returns an indication whether the argument is mandatory.
Definition: argumentparser.h:831
CppUtilities::Argument::setPreDefinedCompletionValues
void setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
Assignes the values to be used when generating completion for the values.
Definition: argumentparser.h:1031
CppUtilities::Argument::Flags::Combinable
@ Combinable
CppUtilities::ApplicationInfo::domain
const char * domain
Definition: argumentparser.h:27
CppUtilities::ParseArgumentBehavior
ParseArgumentBehavior
The ParseArgumentBehavior enum specifies the behavior when parsing arguments.
Definition: argumentparser.h:87
CppUtilities::Argument::description
const char * description() const
Returns the description of the argument.
Definition: argumentparser.h:585
CppUtilities::ArgumentParser::unknownArgumentBehavior
UnknownArgumentBehavior unknownArgumentBehavior() const
Returns how unknown arguments are treated.
Definition: argumentparser.h:1114
CppUtilities::ApplicationInfo::url
const char * url
Definition: argumentparser.h:26
CppUtilities::FlagEnumClassOperations::operator|
constexpr FlagEnumClass operator|(FlagEnumClass lhs, FlagEnumClass rhs)
Definition: flagenumclass.h:43
CppUtilities
Contains all utilities provides by the c++utilities library.
Definition: argumentparser.h:17
CppUtilities::ApplicationInfo::version
const char * version
Definition: argumentparser.h:25
CppUtilities::Argument::isPresent
bool isPresent() const
Returns an indication whether the argument could be detected when parsing.
Definition: argumentparser.h:738
CppUtilities::ArgumentParser::setUnknownArgumentBehavior
void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior)
Sets how unknown arguments are treated.
Definition: argumentparser.h:1124
CppUtilities::Argument::setFlags
void setFlags(Argument::Flags flags)
Replaces all Argument::Flags for the argument with the flags.
Definition: argumentparser.h:865
CppUtilities::ValueConversion::convert
TargetType convert(const char *value)
Definition: argumentparser.h:146
CppUtilities::ApplicationInfo::credits
const char * credits
Definition: argumentparser.h:30
CppUtilities::ArgumentParser::executable
const char * executable() const
Returns the name of the current executable.
Definition: argumentparser.h:1104
CppUtilities::UnknownArgumentBehavior
UnknownArgumentBehavior
The UnknownArgumentBehavior enum specifies the behavior of the argument parser when an unknown argume...
Definition: argumentparser.h:75
CppUtilities::Argument::reset
void reset()
Resets occurrences (indices, values and paths).
Definition: argumentparser.h:1041
CppUtilities::ApplicationInfo::description
const char * description
Definition: argumentparser.h:28
CppUtilities::Argument::setValueNames
void setValueNames(std::initializer_list< const char * > valueNames)
Sets the names of the requried values.
Definition: argumentparser.h:692
CppUtilities::Argument::index
std::size_t index(std::size_t occurrence) const
Returns the indices of the argument's occurences which could be detected when parsing.
Definition: argumentparser.h:754
CppUtilities::Argument::isCombinable
bool isCombinable() const
Returns an indication whether the argument is combinable.
Definition: argumentparser.h:888
CppUtilities::ArgumentReader
The ArgumentReader class internally encapsulates the process of reading command line arguments.
Definition: argumentparserprivate.h:9
CppUtilities::Argument::path
const std::vector< Argument * > & path(std::size_t occurrence=0) const
Returns the path of the specified occurrence.
Definition: argumentparser.h:817
CppUtilities::Argument::setName
void setName(const char *name)
Sets the name of the argument.
Definition: argumentparser.h:525
CppUtilities::ArgumentParser::actualArgumentCount
unsigned int actualArgumentCount() const
Returns the actual number of arguments that could be found when parsing.
Definition: argumentparser.h:1096
CppUtilities::Argument::hasSubArguments
bool hasSubArguments() const
Returns an indication whether the argument has secondary arguments.
Definition: argumentparser.h:967
CppUtilities::Argument::Flags
Flags
Definition: argumentparser.h:270
CppUtilities::HelpArgument
The HelpArgument class prints help information for an argument parser when present (–help,...
Definition: argumentparser.h:424
CppUtilities::Argument::flags
Argument::Flags flags() const
Returns Argument::Flags for the argument.
Definition: argumentparser.h:857
CppUtilities::Argument::setDenotesOperation
void setDenotesOperation(bool denotesOperation)
Sets whether the argument denotes the operation.
Definition: argumentparser.h:925
CppUtilities::ArgumentParser::setDefaultArgument
void setDefaultArgument(Argument *argument)
Sets the default argument.
Definition: argumentparser.h:1142
CppUtilities::Argument::Flags::Operation
@ Operation
CppUtilities::Argument::setRequired
void setRequired(bool required)
Sets whether this argument is mandatory or not.
Definition: argumentparser.h:843
CppUtilities::Argument::parents
const ArgumentVector & parents() const
Returns the parents of this argument.
Definition: argumentparser.h:982
CppUtilities::ArgumentOccurrence::values
std::vector< const char * > values
The parameter values which have been specified after the occurrence of the argument.
Definition: argumentparser.h:205
CppUtilities::ArgumentOccurrence::convertValues
std::tuple< RemainingTargetTypes... > convertValues() const
Converts the present values to the specified target types.
Definition: argumentparser.h:224
CppUtilities::Argument::valueNames
const std::vector< const char * > & valueNames() const
Returns the names of the requried values.
Definition: argumentparser.h:674
CppUtilities::Argument::maxOccurrences
std::size_t maxOccurrences() const
Returns the maximum number of occurrences.
Definition: argumentparser.h:774
CppUtilities::Argument::Flags::Implicit
@ Implicit
CppUtilities::Argument::setCombinable
void setCombinable(bool combinable)
Sets whether this argument can be combined.
Definition: argumentparser.h:901
CppUtilities::Argument::abbreviation
char abbreviation() const
Returns the abbreviation of the argument.
Definition: argumentparser.h:543
CppUtilities::ArgumentPredicate
std::function< bool(Argument *)> ArgumentPredicate
Definition: argumentparser.h:69
CppUtilities::Argument::allValuesAs
std::vector< std::tuple< TargetType... > > allValuesAs() const
Converts the present values for all occurrence to the specified target types.
Definition: argumentparser.h:414
CppUtilities::ArgumentOccurrence
The ArgumentOccurrence struct holds argument values for an occurrence of an argument.
Definition: argumentparser.h:193
CppUtilities::ArgumentParser::helpArg
const HelpArgument & helpArg() const
Returns the --help argument.
Definition: argumentparser.h:1178
CppUtilities::ArgumentVector
std::vector< Argument * > ArgumentVector
Definition: argumentparser.h:68
CPP_UTILITIES_EXPORT
#define CPP_UTILITIES_EXPORT
Marks the symbol to be exported by the c++utilities library.
CppUtilities::Argument::isMainArgument
bool isMainArgument() const
Returns an indication whether the argument is used as main argument.
Definition: argumentparser.h:993
CppUtilities::ArgumentParser::setExitFunction
void setExitFunction(std::function< void(int)> exitFunction)
Specifies a function quit the application.
Definition: argumentparser.h:1170
CppUtilities::ArgumentOccurrence::index
std::size_t index
The index of the occurrence.
Definition: argumentparser.h:200
CppUtilities::ArgumentOccurrence::path
std::vector< Argument * > path
The "path" of the occurrence (the parent elements which have been specified before).
Definition: argumentparser.h:211
CppUtilities::Argument::setAbbreviation
void setAbbreviation(char abbreviation)
Sets the abbreviation of the argument.
Definition: argumentparser.h:555
CppUtilities::Argument::Flags::Deprecated
@ Deprecated
CppUtilities::ArgumentParser
The ArgumentParser class provides a means for handling command line arguments.
Definition: argumentparser.h:450
CppUtilities::Argument::setValueCompletionBehavior
void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour)
Sets the items to be considered when generating completion for the values.
Definition: argumentparser.h:1015
CppUtilities::UnknownArgumentBehavior::Ignore
@ Ignore
CppUtilities::ApplicationInfo::name
const char * name
Definition: argumentparser.h:23
CPP_UTILITIES_IF_DEBUG_BUILD
#define CPP_UTILITIES_IF_DEBUG_BUILD(x)
Wraps debug-only lines conveniently.
Definition: global.h:102
CppUtilities::ApplicationInfo::author
const char * author
Definition: argumentparser.h:24
CppUtilities::Argument::denotesOperation
bool denotesOperation() const
Returns whether the argument denotes an operation.
Definition: argumentparser.h:916