| Leonetienne/Hazelnupp Simple, easy to use, command line parameter interface

Public Member Functions | List of all members
Hazelnp::Hazelnupp Class Reference

The main class to interface with. More...

`#include <Hazelnupp.h>`

## Public Member Functions
| Hazelnupp ()
| Hazelnupp (const int argc, const char *const *argv)
| ~Hazelnupp ()
void | Parse (const int argc, const char *const *argv)
| Will parse command line arguments. More...
const std::string & | GetExecutableName () const
| Will return argv[0], the name of the executable. More...
const Value & | operator[] (const std::string &key) const
| Will return the value given a key. More...
bool | HasParam (const std::string &key) const
| Will check wether a parameter exists given a key, or not. More...
void | RegisterAbbreviation (const std::string &abbrev, const std::string &target)
| Will register an abbreviation (like -f for –force) More...
const std::string & | GetAbbreviation (const std::string &abbrev) const
| Will return the long form of an abbreviation (like –force for -f) Returns "" if no match is found. More...
bool | HasAbbreviation (const std::string &abbrev) const
| Will check wether or not an abbreviation is registered. More...
void | ClearAbbreviation (const std::string &abbrevation)
| Will delete the abbreviation for a given parameter. More...
void | ClearAbbreviations ()
| Will delete all abbreviations. More...
void | RegisterConstraint (const std::string &key, const ParamConstraint &constraint)
| Will register a constraint for a parameter. More...
ParamConstraint | GetConstraint (const std::string &parameter) const
| Will return the constraint information for a specific parameter. More...
void | ClearConstraint (const std::string &parameter)
| Will the constraint of a specific parameter. More...
void | ClearConstraints ()
| Will delete all constraints. More...
void | SetCrashOnFail (bool crashOnFail)
| Sets whether to crash the application, and print to stderr, when an exception is raised whilst parsing, or not. More...
bool | GetCrashOnFail () const
| Gets whether the application crashes on an exception whilst parsing, and prints to stderr. More...
void | SetCatchHelp (bool catchHelp)
| Sets whether the Hazelnupp should automatically catch the –help parameter, print the parameter documentation to stdout, and exit or not. More...
bool | GetCatchHelp () const
| Retruns whether the Hazelnupp should automatically catch the –help parameter, print the parameter documentation to stdout, and exit or not. More...
void | SetBriefDescription (const std::string &description)
| Sets a brief description of the application to be automatically added to the documentation. More...
const std::string & | GetBriefDescription ()
| Returns the brief description of the application to be automatically added to the documentation. More...
void | RegisterDescription (const std::string &parameter, const std::string &description)
| Willl register a short description for a parameter. More...
const std::string & | GetDescription (const std::string &parameter) const
| Will return a short description for a parameter, if it exists. More...
bool | HasDescription (const std::string &parameter) const
| Returns whether or not a given parameter has a registered description. More...
void | ClearDescription (const std::string &parameter)
| Will delete the description of a parameter if it exists. More...
void | ClearDescriptions ()
| Will delete all parameter descriptions. More...
std::string | GenerateDocumentation () const
| Will generate a text-based documentation suited to show the user, for example on –help. More...

## Detailed Description

The main class to interface with.

Definition at line 11 of file Hazelnupp.h.

## Constructor & Destructor Documentation

## ◆ Hazelnupp() [1/2]

Hazelnupp::Hazelnupp | ( |  | ) |

Definition at line 15 of file Hazelnupp.cpp.

16 {
17 return;
18 }

## ◆ Hazelnupp() [2/2]

Hazelnupp::Hazelnupp | ( | const int | argc,
|  | const char *const * | argv
| ) |  |

Definition at line 20 of file Hazelnupp.cpp.

21 {
22 Parse(argc, argv);
23 return;
24 }

## ◆ ~Hazelnupp()

Hazelnupp::~Hazelnupp | ( |  | ) |

Definition at line 26 of file Hazelnupp.cpp.

27 {
28 for (auto& it : parameters)
29 delete it.second;
30
31 parameters.clear();
32
33 return;
34 }

## Member Function Documentation

## ◆ ClearAbbreviation()

void Hazelnupp::ClearAbbreviation | ( | const std::string & | abbrevation | ) |

Will delete the abbreviation for a given parameter.

IMPORTANT: This parameter is the abbreviation! Not the long form!

Definition at line 586 of file Hazelnupp.cpp.

587 {
588 parameterAbreviations.erase(abbrevation);
589 return;
590 }

## ◆ ClearAbbreviations()

void Hazelnupp::ClearAbbreviations | ( |  | ) |

Will delete all abbreviations.

Definition at line 592 of file Hazelnupp.cpp.

593 {
594 parameterAbreviations.clear();
595 return;
596 }

## ◆ ClearConstraint()

void Hazelnupp::ClearConstraint | ( | const std::string & | parameter | ) |

Will the constraint of a specific parameter.

Definition at line 547 of file Hazelnupp.cpp.

548 {
549 parameterConstraints.erase(parameter);
550 return;
551 }

## ◆ ClearConstraints()

void Hazelnupp::ClearConstraints | ( |  | ) |

Will delete all constraints.

Definition at line 605 of file Hazelnupp.cpp.

606 {
607 parameterConstraints.clear();
608 return;
609 }

## ◆ ClearDescription()

void Hazelnupp::ClearDescription | ( | const std::string & | parameter | ) |

Will delete the description of a parameter if it exists.

Definition at line 378 of file Hazelnupp.cpp.

379 {
380 // This will just do nothing if the entry does not exist
381 parameterDescriptions.erase(parameter);
382 return;
383 }

## ◆ ClearDescriptions()

void Hazelnp::Hazelnupp::ClearDescriptions | ( |  | ) |

Will delete all parameter descriptions.

Definition at line 385 of file Hazelnupp.cpp.

386 {
387 parameterDescriptions.clear();
388 return;
389 }

## ◆ GenerateDocumentation()

std::string Hazelnupp::GenerateDocumentation | ( |  | ) | const

Will generate a text-based documentation suited to show the user, for example on –help.

Definition at line 391 of file Hazelnupp.cpp.

392 {
393 std::stringstream ss;
394
395 // Add brief, if available
396 if (briefDescription.length() > 0)
397 ss << briefDescription << std::endl;
398
399 // Collect parameter information
400 struct ParamDocEntry
401 {
402 std::string abbreviation;
403 std::string description;
404 std::string type;
405 bool required = false;
406 bool typeIsForced = false;
407 std::string defaultVal;
408 };
409 std::unordered_map<std::string, ParamDocEntry> paramInfos;
410
411 // Collect descriptions
412 for (const auto& it : parameterDescriptions)
413 {
414 // Do we already have that param in the paramInfo set?
415 if (paramInfos.find(it.first) == paramInfos.end())
416 // No? Create it.
417 paramInfos[it.first] = ParamDocEntry();
418
419 paramInfos[it.first].description = it.second;
420 }
421
422 // Collect abbreviations
423 // first value is abbreviation, second is long form
424 for (const auto& it : parameterAbreviations)
425 {
426 // Do we already have that param in the paramInfo set?
427 if (paramInfos.find(it.second) == paramInfos.end())
428 // No? Create it.
429 paramInfos[it.second] = ParamDocEntry();
430
431 paramInfos[it.second].abbreviation = it.first;
432 }
433
434 // Collect constraints
435 for (const auto& it : parameterConstraints)
436 {
437 // Do we already have that param in the paramInfo set?
438 if (paramInfos.find(it.first) == paramInfos.end())
439 // No? Create it.
440 paramInfos[it.first] = ParamDocEntry();
441
442 ParamDocEntry& cached = paramInfos[it.first];
443 cached.required = it.second.required;
444 cached.typeIsForced = it.second.constrainType;
445 cached.type = DataTypeToString(it.second.requiredType);
446
447 std::stringstream defaultValueSs;
448 for (const std::string& s : it.second.defaultValue)
449 {
450 defaultValueSs << '\'' << s << '\'';
451
452 // Add a space if we are not at the last entry
453 if ((void*)&s != (void*)&it.second.defaultValue.back())
454 defaultValueSs << " ";
455 }
456 cached.defaultVal = defaultValueSs.str();
457 }
458
459 // Now generate the documentatino body
460 if (paramInfos.size() > 0)
461 {
462 ss << std::endl
463 << "==== AVAILABLE PARAMETERS ===="
464 << std::endl << std::endl;
465
466 std::size_t counter = 0;
467 for (const auto& it : paramInfos)
468 {
469 const ParamDocEntry& pde = it.second;
470
471 // Put name
472 ss << it.first << " ";
473
474 // Put abbreviation
475 if (pde.abbreviation.length() > 0)
476 ss << pde.abbreviation << " ";
477
478 // Put type
479 if (pde.typeIsForced)
480 ss << pde.type << " ";
481
482 // Put default value
483 if (pde.defaultVal.length() > 0)
484 ss << "default=[" << pde.defaultVal << "] ";
485
486 // Put required tag, but only if no default value
487 if ((pde.required) && (pde.defaultVal.length() == 0))
488 ss << "[[REQUIRED]] ";
489
490 // Put brief description
491 if (pde.description.length() > 0)
492 ss << pde.description;
493
494 // Omit linebreaks when we're on the last element
495 if (counter < paramInfos.size()-1)
496 ss << std::endl << std::endl;
497
498 counter++;
499 }
500 }
501
502 return ss.str();
503 }

## ◆ GetAbbreviation()

const std::string & Hazelnupp::GetAbbreviation | ( | const std::string & | abbrev | ) | const

Will return the long form of an abbreviation (like –force for -f)
Returns "" if no match is found.

Definition at line 573 of file Hazelnupp.cpp.

574 {
575 if (!HasAbbreviation(abbrev))
576 return Placeholders::g_emptyString;
577
578 return parameterAbreviations.find(abbrev)->second;
579 }

## ◆ GetBriefDescription()

const std::string & Hazelnupp::GetBriefDescription | ( |  | ) |

Returns the brief description of the application to be automatically added to the documentation.

Definition at line 351 of file Hazelnupp.cpp.

352 {
353 return briefDescription;
354 }

## ◆ GetCatchHelp()

bool Hazelnupp::GetCatchHelp | ( |  | ) | const

Retruns whether the Hazelnupp should automatically catch the –help parameter, print the parameter documentation to stdout, and exit or not.

Definition at line 340 of file Hazelnupp.cpp.

341 {
342 return catchHelp;
343 }

## ◆ GetConstraint()

ParamConstraint Hazelnupp::GetConstraint | ( | const std::string & | parameter | ) | const

Will return the constraint information for a specific parameter.

Definition at line 542 of file Hazelnupp.cpp.

543 {
544 return parameterConstraints.find(parameter)->second;
545 }

## ◆ GetCrashOnFail()

bool Hazelnupp::GetCrashOnFail | ( |  | ) | const

Gets whether the application crashes on an exception whilst parsing, and prints to stderr.

Definition at line 329 of file Hazelnupp.cpp.

330 {
331 return crashOnFail;
332 }

## ◆ GetDescription()

const std::string & Hazelnp::Hazelnupp::GetDescription | ( | const std::string & | parameter | ) | const

Will return a short description for a parameter, if it exists.

Empty string if it does not exist.

Definition at line 362 of file Hazelnupp.cpp.

363 {
364 // Do we already have a description for this parameter?
365 if (!HasDescription(parameter))
366 // No? Then return ""
367 return Placeholders::g_emptyString;
368
369 // We do? Then return it
370 return parameterDescriptions.find(parameter)->second;
371 }

## ◆ GetExecutableName()

const std::string & Hazelnupp::GetExecutableName | ( |  | ) | const

Will return argv[0], the name of the executable.

Definition at line 553 of file Hazelnupp.cpp.

554 {
555 return executableName;
556 }

## ◆ HasAbbreviation()

bool Hazelnupp::HasAbbreviation | ( | const std::string & | abbrev | ) | const

Will check wether or not an abbreviation is registered.

Definition at line 581 of file Hazelnupp.cpp.

582 {
583 return parameterAbreviations.find(abbrev) != parameterAbreviations.end();
584 }

## ◆ HasDescription()

bool Hazelnupp::HasDescription | ( | const std::string & | parameter | ) | const

Returns whether or not a given parameter has a registered description.

Definition at line 373 of file Hazelnupp.cpp.

374 {
375 return parameterDescriptions.find(parameter) != parameterDescriptions.end();
376 }

## ◆ HasParam()

bool Hazelnupp::HasParam | ( | const std::string & | key | ) | const

Will check wether a parameter exists given a key, or not.

Definition at line 165 of file Hazelnupp.cpp.

166 {
167 return parameters.find(key) != parameters.end();
168 }

## ◆ operator[]()

const Value & Hazelnupp::operator[] | ( | const std::string & | key | ) | const

Will return the value given a key.

Definition at line 558 of file Hazelnupp.cpp.

559 {
560 // Throw exception if param is unknown
561 if (!HasParam(key))
562 throw HazelnuppInvalidKeyException();
563
564 return *parameters.find(key)->second->GetValue();
565 }

## ◆ Parse()

void Hazelnupp::Parse | ( | const int | argc,
|  | const char *const * | argv
| ) |  |

Will parse command line arguments.

Definition at line 36 of file Hazelnupp.cpp.

37 {
38 try
39 {
40 // Populate raw arguments
41 PopulateRawArgs(argc, argv);
42
43 // Expand abbreviations
44 ExpandAbbreviations();
45
46 executableName = std::string(rawArgs[0]);
47
48 std::size_t i = 1;
49 while (i < rawArgs.size())
50 {
51 if ((rawArgs[i].length() > 2) && (rawArgs[i].substr(0, 2) == "--"))
52 {
53 Parameter* param = nullptr;
54 i = ParseNextParameter(i, param);
55
56 parameters.insert(std::pair<std::string, Parameter*>(param->Key(), param));
57 }
58 else
59 i++;
60 }
61
62 // Apply constraints such as default values, and required parameters.
63 // Types have already been enforced.
64 // Dont apply constraints when we are just printind the param docs
65 if ((!catchHelp) || (!HasParam("--help")))
66 ApplyConstraints();
67 }
68 catch (const HazelnuppConstraintTypeMissmatch& exc)
69 {
70 if (crashOnFail)
71 {
72 std::cout << GenerateDocumentation() << std::endl << std::endl;
73 std::cerr << "Parameter error: " << exc.What() << std::endl;
74 quick_exit(-1009);
75 }
76 else
77 throw exc; // yeet
78 }
79 catch (const HazelnuppConstraintMissingValue& exc)
80 {
81 if (crashOnFail)
82 {
83 std::cout << GenerateDocumentation() << std::endl << std::endl;
84 std::cerr << "Parameter error: " << exc.What() << std::endl;
85 quick_exit(-1010);
86 }
87 else
88 throw exc; // yeet
89 }
90
91 // Catch --help parameter
92 if ((catchHelp) && (HasParam("--help")))
93 {
94 std::cout << GenerateDocumentation() << std::endl;
95 quick_exit(0);
96 }
97
98 return;
99 }

## ◆ RegisterAbbreviation()

void Hazelnupp::RegisterAbbreviation | ( | const std::string & | abbrev,
|  | const std::string & | target
| ) |  |

Will register an abbreviation (like -f for –force)

Definition at line 567 of file Hazelnupp.cpp.

568 {
569 parameterAbreviations.insert(std::pair<std::string, std::string>(abbrev, target));
570 return;
571 }

## ◆ RegisterConstraint()

void Hazelnupp::RegisterConstraint | ( | const std::string & | key,
|  | const ParamConstraint & | constraint
| ) |  |

Will register a constraint for a parameter.

IMPORTANT: Any parameter can only have ONE constraint. Applying a new one will overwrite the old one! Construct the ParamConstraint struct yourself to combine Require and TypeSafety! You can also use the ParamConstraint constructor!

Definition at line 598 of file Hazelnupp.cpp.

599 {
600 // Magic syntax, wooo
601 (parameterConstraints[key] = constraint).key = key;
602 return;
603 }

## ◆ RegisterDescription()

void Hazelnp::Hazelnupp::RegisterDescription | ( | const std::string & | parameter,
|  | const std::string & | description
| ) |  |

Willl register a short description for a parameter.

Will overwrite existing descriptions for that parameter.

Definition at line 356 of file Hazelnupp.cpp.

357 {
358 parameterDescriptions[parameter] = description;
359 return;
360 }

## ◆ SetBriefDescription()

void Hazelnupp::SetBriefDescription | ( | const std::string & | description | ) |

Sets a brief description of the application to be automatically added to the documentation.

Definition at line 345 of file Hazelnupp.cpp.

346 {
347 briefDescription = description;
348 return;
349 }

## ◆ SetCatchHelp()

void Hazelnupp::SetCatchHelp | ( | bool | catchHelp | ) |

Sets whether the Hazelnupp should automatically catch the –help parameter, print the parameter documentation to stdout, and exit or not.

Definition at line 334 of file Hazelnupp.cpp.

335 {
336 this->catchHelp = catchHelp;
337 return;
338 }

## ◆ SetCrashOnFail()

void Hazelnupp::SetCrashOnFail | ( | bool | crashOnFail | ) |

Sets whether to crash the application, and print to stderr, when an exception is raised whilst parsing, or not.

Definition at line 611 of file Hazelnupp.cpp.

612 {
613 this->crashOnFail = crashOnFail;
614 return;
615 }

The documentation for this class was generated from the following files:

- Hazelnupp/Hazelnupp.h
- Hazelnupp/Hazelnupp.cpp

Hazelnp::HazelnuppInvalidKeyException
Gets thrown when an non-existent key gets dereferenced.
Definition: HazelnuppException.h:29
Hazelnp::Hazelnupp::GenerateDocumentation
std::string GenerateDocumentation() const
Will generate a text-based documentation suited to show the user, for example on –help.
Definition: Hazelnupp.cpp:391
Hazelnp::HazelnuppException::What
const std::string & What() const
Will return an error message.
Definition: HazelnuppException.h:18
Hazelnp::Hazelnupp::HasDescription
bool HasDescription(const std::string &parameter) const
Returns whether or not a given parameter has a registered description.
Definition: Hazelnupp.cpp:373
Hazelnp::Parameter
Definition: Parameter.h:8
Hazelnp::Placeholders::g_emptyString
static const std::string g_emptyString
The only purpose of this is to provide the ability to return an empty string as an error for std::str...
Definition: Placeholders.h:9
Hazelnp::Hazelnupp::HasParam
bool HasParam(const std::string &key) const
Will check wether a parameter exists given a key, or not.
Definition: Hazelnupp.cpp:165
Hazelnp::Hazelnupp::Parse
void Parse(const int argc, const char *const *argv)
Will parse command line arguments.
Definition: Hazelnupp.cpp:36
Hazelnp::Parameter::Key
const std::string & Key() const
Will return the key of this parameter.
Definition: Parameter.cpp:21
Hazelnp::HazelnuppConstraintMissingValue
Gets thrown when a parameter constrained to be required is not provided, and has no default value set...
Definition: HazelnuppException.h:80
Hazelnp::HazelnuppConstraintTypeMissmatch
Gets thrown when a parameter is of a type that does not match the required type, and is not convertib...
Definition: HazelnuppException.h:56
Hazelnp::Hazelnupp::HasAbbreviation
bool HasAbbreviation(const std::string &abbrev) const
Will check wether or not an abbreviation is registered.
Definition: Hazelnupp.cpp:581
Hazelnp::DataTypeToString
static std::string DataTypeToString(DATA_TYPE type)
Definition: DataType.h:17