C++ Utilities  5.10.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  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
467  = ParseArgumentBehavior::CheckConstraints | ParseArgumentBehavior::InvokeCallbacks | ParseArgumentBehavior::ExitOnFailure);
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
CppUtilities::Argument::setConstraints
void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
Sets the allowed number of occurrences.
Definition: argumentparser.h:809
CppUtilities::Argument::varValueCount
static constexpr std::size_t varValueCount
Denotes a variable number of values.
Definition: argumentparser.h:362
CppUtilities::Argument::allRequiredValuesPresent
bool allRequiredValuesPresent(std::size_t occurrence=0) const
Returns an indication whether all required values are present.
Definition: argumentparser.h:712
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:1069
CppUtilities::Argument::markAsDeprecated
void markAsDeprecated(const Argument *deprecatedBy=nullptr)
Marks the argument as deprecated.
Definition: argumentparser.h:798
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:1195
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:596
CppUtilities::ArgumentParser::checkConstraints
void checkConstraints()
Checks whether contraints are violated.
Definition: argumentparser.h:1153
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:662
CppUtilities::IniFileParseOptions::None
@ None
CppUtilities::Argument::deprecatedBy
const Argument * deprecatedBy() const
Returns the argument which obsoletes this argument.
Definition: argumentparser.h:788
CppUtilities::NoColorArgument
The NoColorArgument class allows to specify whether use of escape codes or similar technique to provi...
Definition: argumentparser.h:441
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:704
CppUtilities::Argument::setEnvironmentVariable
void setEnvironmentVariable(const char *environmentVariable)
Sets the environment variable queried when firstValue() is called.
Definition: argumentparser.h:576
CppUtilities::Argument::name
const char * name() const
Returns the name of the argument.
Definition: argumentparser.h:514
CppUtilities::ValueCompletionBehavior::None
@ None
CppUtilities::Argument::setExample
void setExample(const char *example)
Sets the a usage example for the argument.
Definition: argumentparser.h:616
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:747
CppUtilities::Argument::callback
const CallbackFunction & callback() const
Returns the assigned callback function.
Definition: argumentparser.h:935
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:1047
CppUtilities::OperationArgument
The OperationArgument class is an Argument where denotesOperation() is true by default.
Definition: argumentparser.h:430
CppUtilities::Argument::minOccurrences
std::size_t minOccurrences() const
Returns the minimum number of occurrences.
Definition: argumentparser.h:765
CppUtilities::Argument::environmentVariable
const char * environmentVariable() const
Returns the environment variable queried when firstValue() is called.
Definition: argumentparser.h:567
CppUtilities::ArgumentParser::mainArguments
const ArgumentVector & mainArguments() const
Returns the main arguments.
Definition: argumentparser.h:1089
CppUtilities::Argument::isDeprecated
bool isDeprecated() const
Definition: argumentparser.h:780
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:627
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:405
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:606
CppUtilities::Argument::valueCompletionBehaviour
ValueCompletionBehavior valueCompletionBehaviour() const
Returns the items to be considered when generating completion for the values.
Definition: argumentparser.h:1005
CppUtilities::Argument::subArguments
const ArgumentVector & subArguments() const
Returns the secondary arguments for this argument.
Definition: argumentparser.h:957
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:946
CppUtilities::ArgumentParser::defaultArgument
Argument * defaultArgument() const
Returns the default argument.
Definition: argumentparser.h:1134
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:645
CppUtilities::ConfigValueArgument
The ConfigValueArgument class is an Argument where setCombinable() is true by default.
Definition: argumentparser.h:435
CppUtilities::ParseArgumentBehavior::ReadArguments
@ ReadArguments
CppUtilities::Argument::setImplicit
void setImplicit(bool implicit)
Sets whether the argument is an implicit argument.
Definition: argumentparser.h:731
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:1056
CppUtilities::Argument::isImplicit
bool isImplicit() const
Returns an indication whether the argument is an implicit argument.
Definition: argumentparser.h:722
CppUtilities::Argument::preDefinedCompletionValues
const char * preDefinedCompletionValues() const
Returns the assigned values used when generating completion for the values.
Definition: argumentparser.h:1024
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:1162
CppUtilities::Argument::isRequired
bool isRequired() const
Returns an indication whether the argument is mandatory.
Definition: argumentparser.h:832
CppUtilities::Argument::setPreDefinedCompletionValues
void setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
Assignes the values to be used when generating completion for the values.
Definition: argumentparser.h:1032
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:586
CppUtilities::ArgumentParser::unknownArgumentBehavior
UnknownArgumentBehavior unknownArgumentBehavior() const
Returns how unknown arguments are treated.
Definition: argumentparser.h:1115
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:739
CppUtilities::ArgumentParser::setUnknownArgumentBehavior
void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior)
Sets how unknown arguments are treated.
Definition: argumentparser.h:1125
CppUtilities::Argument::setFlags
void setFlags(Argument::Flags flags)
Replaces all Argument::Flags for the argument with the flags.
Definition: argumentparser.h:866
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:1105
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:1042
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:693
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:755
CppUtilities::Argument::isCombinable
bool isCombinable() const
Returns an indication whether the argument is combinable.
Definition: argumentparser.h:889
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:818
CppUtilities::Argument::setName
void setName(const char *name)
Sets the name of the argument.
Definition: argumentparser.h:526
CppUtilities::ArgumentParser::actualArgumentCount
unsigned int actualArgumentCount() const
Returns the actual number of arguments that could be found when parsing.
Definition: argumentparser.h:1097
CppUtilities::Argument::hasSubArguments
bool hasSubArguments() const
Returns an indication whether the argument has secondary arguments.
Definition: argumentparser.h:968
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:425
CppUtilities::Argument::flags
Argument::Flags flags() const
Returns Argument::Flags for the argument.
Definition: argumentparser.h:858
CppUtilities::Argument::setDenotesOperation
void setDenotesOperation(bool denotesOperation)
Sets whether the argument denotes the operation.
Definition: argumentparser.h:926
CppUtilities::ArgumentParser::setDefaultArgument
void setDefaultArgument(Argument *argument)
Sets the default argument.
Definition: argumentparser.h:1143
CppUtilities::Argument::Flags::Operation
@ Operation
CppUtilities::Argument::setRequired
void setRequired(bool required)
Sets whether this argument is mandatory or not.
Definition: argumentparser.h:844
CppUtilities::Argument::parents
const ArgumentVector & parents() const
Returns the parents of this argument.
Definition: argumentparser.h:983
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:675
CppUtilities::Argument::maxOccurrences
std::size_t maxOccurrences() const
Returns the maximum number of occurrences.
Definition: argumentparser.h:775
CppUtilities::Argument::Flags::Implicit
@ Implicit
CppUtilities::Argument::setCombinable
void setCombinable(bool combinable)
Sets whether this argument can be combined.
Definition: argumentparser.h:902
CppUtilities::Argument::abbreviation
char abbreviation() const
Returns the abbreviation of the argument.
Definition: argumentparser.h:544
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:415
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:1179
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:994
CppUtilities::ArgumentParser::setExitFunction
void setExitFunction(std::function< void(int)> exitFunction)
Specifies a function quit the application.
Definition: argumentparser.h:1171
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:556
CppUtilities::Argument::Flags::Deprecated
@ Deprecated
CppUtilities::ArgumentParser
The ArgumentParser class provides a means for handling command line arguments.
Definition: argumentparser.h:451
CppUtilities::Argument::setValueCompletionBehavior
void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour)
Sets the items to be considered when generating completion for the values.
Definition: argumentparser.h:1016
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:917