Hazelnp::CmdArgsInterface Class Reference

The main class to interface with. More...

#include <CmdArgsInterface.h>

Public Member Functions
	CmdArgsInterface ()
	CmdArgsInterface (const int argc, const char *const *argv)
	~CmdArgsInterface ()
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 CmdArgsInterface should automatically catch the –help parameter, print the parameter documentation to stdout, and exit or not. More...
bool	GetCatchHelp () const
	Retruns whether the CmdArgsInterface 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 13 of file CmdArgsInterface.h.

Constructor & Destructor Documentation

CmdArgsInterface() [1/2]

CmdArgsInterface::CmdArgsInterface

(

)

Definition at line 15 of file CmdArgsInterface.cpp.

{
    return;
}

CmdArgsInterface() [2/2]

CmdArgsInterface::CmdArgsInterface	(	const int	argc,
		const char *const *	argv
	)

Definition at line 20 of file CmdArgsInterface.cpp.

{
    Parse(argc, argv);
    return;
}

~CmdArgsInterface()

CmdArgsInterface::~CmdArgsInterface

(

)

Definition at line 26 of file CmdArgsInterface.cpp.

{
    for (auto& it : parameters)
        delete it.second;
 
    parameters.clear();
 
    return;
}

Member Function Documentation

ClearAbbreviation()

void CmdArgsInterface::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 651 of file CmdArgsInterface.cpp.

{
    parameterAbreviations.erase(abbrevation);
    return;
}

ClearAbbreviations()

void CmdArgsInterface::ClearAbbreviations

(

)

Will delete all abbreviations.

Definition at line 657 of file CmdArgsInterface.cpp.

{
    parameterAbreviations.clear();
    return;
}

ClearConstraint()

void CmdArgsInterface::ClearConstraint

(

const std::string &

parameter

)

Will the constraint of a specific parameter.

Definition at line 612 of file CmdArgsInterface.cpp.

{
    parameterConstraints.erase(parameter);
    return;
}

ClearConstraints()

void CmdArgsInterface::ClearConstraints

(

)

Will delete all constraints.

Definition at line 670 of file CmdArgsInterface.cpp.

{
    parameterConstraints.clear();
    return;
}

ClearDescription()

void CmdArgsInterface::ClearDescription

(

const std::string &

parameter

)

Will delete the description of a parameter if it exists.

Definition at line 412 of file CmdArgsInterface.cpp.

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

ClearDescriptions()

void Hazelnp::CmdArgsInterface::ClearDescriptions

(

)

Will delete all parameter descriptions.

Definition at line 419 of file CmdArgsInterface.cpp.

{
    parameterDescriptions.clear();
    return;
}

GenerateDocumentation()

std::string CmdArgsInterface::GenerateDocumentation

(

)

const

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

Definition at line 425 of file CmdArgsInterface.cpp.

{
    std::stringstream ss;
 
    // Add brief, if available
    if (briefDescription.length() > 0)
        ss << briefDescription << std::endl;
 
    // Collect parameter information
    struct ParamDocEntry
    {
        std::string abbreviation;
        std::string description;
        std::string type;
        bool required = false;
        bool typeIsForced = false;
        std::string defaultVal;
        std::string incompatibilities;
    };
    std::unordered_map<std::string, ParamDocEntry> paramInfos;
 
    // Collect descriptions
    for (const auto& it : parameterDescriptions)
    {
        // Do we already have that param in the paramInfo set?
        if (paramInfos.find(it.first) == paramInfos.end())
            // No? Create it.
            paramInfos[it.first] = ParamDocEntry();
 
        paramInfos[it.first].description = it.second;
    }
 
    // Collect abbreviations
    // first value is abbreviation, second is long form
    for (const auto& it : parameterAbreviations)
    {
        // Do we already have that param in the paramInfo set?
        if (paramInfos.find(it.second) == paramInfos.end())
            // No? Create it.
            paramInfos[it.second] = ParamDocEntry();
 
        paramInfos[it.second].abbreviation = it.first;
    }
 
    // Collect constraints
    for (const auto& it : parameterConstraints)
    {
        // Do we already have that param in the paramInfo set?
        if (paramInfos.find(it.first) == paramInfos.end())
            // No? Create it.
            paramInfos[it.first] = ParamDocEntry();
 
        ParamDocEntry& cached = paramInfos[it.first];
        cached.required = it.second.required;
        cached.typeIsForced = it.second.constrainType;
        cached.type = DataTypeToString(it.second.requiredType);
        
        // Build default-value string
        std::stringstream vec2str_ss;
        for (const std::string& s : it.second.defaultValue)
        {
            vec2str_ss << '\'' << s << '\'';
 
            // Add a space if we are not at the last entry
            if ((void*)&s != (void*)&it.second.defaultValue.back())
                vec2str_ss << " ";
        }
        cached.defaultVal = vec2str_ss.str();
 
 
        // Build incompatibilities string
        vec2str_ss.str("");
        for (const std::string& s : it.second.incompatibleParameters)
        {
            vec2str_ss << s;
 
            // Add a comma-space if we are not at the last entry
            if ((void*)&s != (void*)&it.second.incompatibleParameters.back())
                vec2str_ss << ", ";
        }
        cached.incompatibilities = vec2str_ss.str();
    }
 
    // Now generate the documentation body
    if (paramInfos.size() > 0)
    {
        ss << std::endl 
            << "==== AVAILABLE PARAMETERS ====" 
            << std::endl << std::endl;
 
        std::size_t counter = 0;
        for (const auto& it : paramInfos)
        {
            const ParamDocEntry& pde = it.second;
 
            // Put name
            ss << it.first << "   ";
 
            // Put abbreviation
            if (pde.abbreviation.length() > 0)
                ss << pde.abbreviation << "   ";
 
            // Put type
            if (pde.typeIsForced)
                ss << pde.type << "   ";
 
            // Put default value
            if (pde.defaultVal.length() > 0)
                ss << "default=[" << pde.defaultVal << "]   ";
 
            // Put incompatibilities
            if (pde.incompatibilities.length() > 0)
                ss << "incompatibilities=[" << pde.incompatibilities << "]   ";
 
            // Put required tag, but only if no default value
            if ((pde.required) && (pde.defaultVal.length() == 0))
                ss << "[[REQUIRED]]    ";
 
            // Put brief description
            if (pde.description.length() > 0)
                ss << pde.description;
 
            // Omit linebreaks when we're on the last element
            if (counter < paramInfos.size()-1)
                ss << std::endl << std::endl;
 
            counter++;
        }
    }
 
    return ss.str();
}

GetAbbreviation()

const std::string & CmdArgsInterface::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 638 of file CmdArgsInterface.cpp.

{
    if (!HasAbbreviation(abbrev))
        return Placeholders::g_emptyString;
 
    return parameterAbreviations.find(abbrev)->second;
}

GetBriefDescription()

const std::string & CmdArgsInterface::GetBriefDescription

(

)

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

Definition at line 385 of file CmdArgsInterface.cpp.

{
    return briefDescription;
}

GetCatchHelp()

bool CmdArgsInterface::GetCatchHelp

(

)

const

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

Definition at line 374 of file CmdArgsInterface.cpp.

{
    return catchHelp;
}

GetConstraint()

ParamConstraint CmdArgsInterface::GetConstraint

(

const std::string &

parameter

)

const

Will return the constraint information for a specific parameter.

Definition at line 607 of file CmdArgsInterface.cpp.

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

GetCrashOnFail()

bool CmdArgsInterface::GetCrashOnFail

(

)

const

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

Definition at line 363 of file CmdArgsInterface.cpp.

{
    return crashOnFail;
}

GetDescription()

const std::string & Hazelnp::CmdArgsInterface::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 396 of file CmdArgsInterface.cpp.

{
    // Do we already have a description for this parameter?
    if (!HasDescription(parameter))
        // No? Then return ""
        return Placeholders::g_emptyString;
 
    // We do? Then return it
    return parameterDescriptions.find(parameter)->second;
}

GetExecutableName()

const std::string & CmdArgsInterface::GetExecutableName

(

)

const

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

Definition at line 618 of file CmdArgsInterface.cpp.

{
    return executableName;
}

HasAbbreviation()

bool CmdArgsInterface::HasAbbreviation

(

const std::string &

abbrev

)

const

Will check wether or not an abbreviation is registered.

Definition at line 646 of file CmdArgsInterface.cpp.

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

HasDescription()

bool CmdArgsInterface::HasDescription

(

const std::string &

parameter

)

const

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

Definition at line 407 of file CmdArgsInterface.cpp.

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

HasParam()

bool CmdArgsInterface::HasParam

(

const std::string &

key

)

const

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

Definition at line 199 of file CmdArgsInterface.cpp.

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

operator[]()

const Value & CmdArgsInterface::operator[]

(

const std::string &

key

)

const

Will return the value given a key.

Definition at line 623 of file CmdArgsInterface.cpp.

{
    // Throw exception if param is unknown
    if (!HasParam(key))
        throw HazelnuppInvalidKeyException();
 
    return *parameters.find(key)->second->GetValue();
}

Parse()

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

Will parse command line arguments.

Definition at line 36 of file CmdArgsInterface.cpp.

{
    try
    {
        // Populate raw arguments
        PopulateRawArgs(argc, argv);
 
        // Expand abbreviations
        ExpandAbbreviations();
 
        executableName = std::string(rawArgs[0]);
 
        // Read and parse all parameters
        std::size_t i = 1;
        while (i < rawArgs.size())
        {
            if ((rawArgs[i].length() > 2) && (rawArgs[i].substr(0, 2) == "--"))
            {
                Parameter* param = nullptr;
                i = ParseNextParameter(i, param);
 
                parameters.insert(std::pair<std::string, Parameter*>(param->Key(), param));
            }
            else
                i++;
        }
 
        // Apply constraints such as default values, and required parameters.
        // Types have already been enforced.
        // Dont apply constraints when we are just printind the param docs
        if ((!catchHelp) || (!HasParam("--help")))
            ApplyConstraints();
    }
    catch (const HazelnuppConstraintIncompatibleParameters& exc)
    {
        if (crashOnFail)
        {
            std::cout << GenerateDocumentation() << std::endl << std::endl;
            std::cerr << "Parameter error: " << exc.What() << std::endl;
            quick_exit(-1000);
        }
        else
            throw exc; // yeet
    }
    catch (const HazelnuppConstraintMissingValue& exc)
    {
        if (crashOnFail)
        {
            std::cout << GenerateDocumentation() << std::endl << std::endl;
            std::cerr << "Parameter error: " << exc.What() << std::endl;
            quick_exit(-1001);
        }
        else
            throw exc; // yeet
    }
    catch (const HazelnuppConstraintTypeMissmatch& exc)
    {
        if (crashOnFail)
        {
            std::cout << GenerateDocumentation() << std::endl << std::endl;
            std::cerr << "Parameter error: " << exc.What() << std::endl;
            quick_exit(-1002);
        }
        else
            throw exc; // yeet
    }
    catch (const HazelnuppConstraintException& exc)
    {
        if (crashOnFail)
        {
            std::cout << GenerateDocumentation() << std::endl << std::endl;
            std::cerr << "Parameter error: " << exc.What() << std::endl;
            quick_exit(-1003);
        }
        else
            throw exc; // yeet
    }
    catch (const HazelnuppException& exc)
    {
        if (crashOnFail)
        {
            std::cout << GenerateDocumentation() << std::endl << std::endl;
            std::cerr << "Parameter error: " << exc.What() << std::endl;
            quick_exit(-1004);
        }
        else
            throw exc; // yeet
    }
 
    // Catch --help parameter
    if ((catchHelp) && (HasParam("--help")))
    {
        std::cout << GenerateDocumentation() << std::endl;
        quick_exit(0);
    }
 
    return;
}

RegisterAbbreviation()

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

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

Definition at line 632 of file CmdArgsInterface.cpp.

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

RegisterConstraint()

void CmdArgsInterface::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, TypeSafety and Incompatibilities! You can also use the ParamConstraint constructor!

Definition at line 663 of file CmdArgsInterface.cpp.

{
    // Magic syntax, wooo
    (parameterConstraints[key] = constraint).key = key;
    return;
}

RegisterDescription()

void Hazelnp::CmdArgsInterface::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 390 of file CmdArgsInterface.cpp.

{
    parameterDescriptions[parameter] = description;
    return;
}

SetBriefDescription()

void CmdArgsInterface::SetBriefDescription

(

const std::string &

description

)

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

Definition at line 379 of file CmdArgsInterface.cpp.

{
    briefDescription = description;
    return;
}

SetCatchHelp()

void CmdArgsInterface::SetCatchHelp

(

bool

catchHelp

)

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

Definition at line 368 of file CmdArgsInterface.cpp.

{
    this->catchHelp = catchHelp;
    return;
}

SetCrashOnFail()

void CmdArgsInterface::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 676 of file CmdArgsInterface.cpp.

{
    this->crashOnFail = crashOnFail;
    return;
}

---

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

• Hazelnupp/CmdArgsInterface.h
• Hazelnupp/CmdArgsInterface.cpp