argumentparser.h

Go to the documentation of this file.

#ifndef APPLICATION_UTILITIES_ARGUMENTPARSER_H
#define APPLICATION_UTILITIES_ARGUMENTPARSER_H
 
#include "../conversion/stringconversion.h"
#include "../misc/traits.h"
 
#include <functional>
#include <initializer_list>
#include <limits>
#include <tuple>
#include <vector>
#ifdef CPP_UTILITIES_DEBUG_BUILD
#include <cassert>
#endif
 
class ArgumentParserTests; // not a public class (only used for internal tests)
 
namespace CppUtilities {

struct ApplicationInfo {
    const char *name = nullptr;
    const char *author = nullptr;
    const char *version = nullptr;
    const char *url = nullptr;
    const char *domain = nullptr;
    const char *description = nullptr;
    const char *license = nullptr;
    const char *credits = nullptr;
    std::vector<const char *> dependencyVersions;
};

CPP_UTILITIES_EXPORT extern ApplicationInfo applicationInfo;

#define SET_DEPENDENCY_INFO ::CppUtilities::applicationInfo.dependencyVersions = DEPENCENCY_VERSIONS

#define SET_APPLICATION_INFO                                                                                                                         \
    ::CppUtilities::applicationInfo.name = APP_NAME;                                                                                                 \
    ::CppUtilities::applicationInfo.author = APP_AUTHOR;                                                                                             \
    ::CppUtilities::applicationInfo.version = APP_VERSION;                                                                                           \
    ::CppUtilities::applicationInfo.url = APP_URL;                                                                                                   \
    ::CppUtilities::applicationInfo.domain = APP_DOMAIN;                                                                                             \
    ::CppUtilities::applicationInfo.description = APP_DESCRIPTION;                                                                                   \
    ::CppUtilities::applicationInfo.license = PROJECT_LICENSE;                                                                                       \
    ::CppUtilities::applicationInfo.credits = APP_CREDITS;                                                                                           \
    SET_DEPENDENCY_INFO
 
class Argument;
class ArgumentParser;
class ArgumentReader;
 
using ArgumentInitializerList = std::initializer_list<Argument *>;
using ArgumentVector = std::vector<Argument *>;
using ArgumentPredicate = std::function<bool(Argument *)>;

enum class UnknownArgumentBehavior {
    Ignore, 
    Warn, 
    Fail 
};

enum class ParseArgumentBehavior {
    ReadArguments = 0x0, 
    CheckConstraints = 0x1, 
    InvokeCallbacks = 0x2, 
    ExitOnFailure
    = 0x4, 
};

constexpr ParseArgumentBehavior operator|(ParseArgumentBehavior lhs, ParseArgumentBehavior rhs)
{
    return static_cast<ParseArgumentBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
}
 
constexpr bool operator&(ParseArgumentBehavior lhs, ParseArgumentBehavior rhs)
{
    return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
}

enum class ValueCompletionBehavior : unsigned char {
    None = 0, 
    PreDefinedValues = 2, 
    Files = 4, 
    Directories = 8, 
    FileSystemIfNoPreDefinedValues = 16, 
    AppendEquationSign = 32, 
    InvokeCallback = 64, 
};

constexpr ValueCompletionBehavior operator|(ValueCompletionBehavior lhs, ValueCompletionBehavior rhs)
{
    return static_cast<ValueCompletionBehavior>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
}
 
constexpr bool operator&(ValueCompletionBehavior lhs, ValueCompletionBehavior rhs)
{
    return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
}

namespace ValueConversion {
template <typename TargetType, Traits::EnableIf<std::is_same<TargetType, std::string>> * = nullptr> TargetType convert(const char *value)
{
    return std::string(value);
}
 
template <typename TargetType, Traits::EnableIf<std::is_arithmetic<TargetType>> * = nullptr> TargetType convert(const char *value)
{
    return stringToNumber<TargetType>(value);
}

namespace Helper {
struct CPP_UTILITIES_EXPORT ArgumentValueConversionError {
    const std::string errorMessage;
    const char *const valueToConvert;
    const char *const targetTypeName;
 
    [[noreturn]] void throwFailure(const std::vector<Argument *> &argumentPath) const;
};
 
template <std::size_t N, typename FirstTargetType, typename... RemainingTargetTypes> struct ArgumentValueConverter {
    static std::tuple<FirstTargetType, RemainingTargetTypes...> convertValues(std::vector<const char *>::const_iterator firstValue)
    {
        return std::tuple_cat(ArgumentValueConverter<1, FirstTargetType>::convertValues(firstValue),
            ArgumentValueConverter<N - 1, RemainingTargetTypes...>::convertValues(firstValue + 1));
    }
};
 
template <typename FirstTargetType, typename... RemainingTargetTypes> struct ArgumentValueConverter<1, FirstTargetType, RemainingTargetTypes...> {
    static std::tuple<FirstTargetType> convertValues(std::vector<const char *>::const_iterator firstValue)
    {
        // FIXME: maybe use std::expected here when available
        try {
            return std::make_tuple<FirstTargetType>(ValueConversion::convert<FirstTargetType>(*firstValue));
        } catch (const ConversionException &exception) {
            throw ArgumentValueConversionError{ exception.what(), *firstValue, typeid(FirstTargetType).name() };
        }
    }
};
} // namespace Helper
 
} // namespace ValueConversion

struct CPP_UTILITIES_EXPORT ArgumentOccurrence {
    ArgumentOccurrence(std::size_t index);
    ArgumentOccurrence(std::size_t index, const std::vector<Argument *> parentPath, Argument *parent);

    std::size_t index;

    std::vector<const char *> values;

    std::vector<Argument *> path;
 
    template <typename... RemainingTargetTypes> std::tuple<RemainingTargetTypes...> convertValues() const;
 
private:
    [[noreturn]] void throwNumberOfValuesNotSufficient(unsigned long valuesToConvert) const;
};

template <typename... RemainingTargetTypes> std::tuple<RemainingTargetTypes...> ArgumentOccurrence::convertValues() const
{
    constexpr auto valuesToConvert = sizeof...(RemainingTargetTypes);
    if (values.size() < valuesToConvert) {
        throwNumberOfValuesNotSufficient(valuesToConvert);
    }
    try {
        return ValueConversion::Helper::ArgumentValueConverter<valuesToConvert, RemainingTargetTypes...>::convertValues(values.cbegin());
    } catch (const ValueConversion::Helper::ArgumentValueConversionError &error) {
        error.throwFailure(path);
    }
}

inline ArgumentOccurrence::ArgumentOccurrence(std::size_t index)
    : index(index)
{
}

inline ArgumentOccurrence::ArgumentOccurrence(std::size_t index, const std::vector<Argument *> parentPath, Argument *parent)
    : index(index)
    , path(parentPath)
{
    if (parent) {
        path.push_back(parent);
    }
}
 
class CPP_UTILITIES_EXPORT Argument {
    friend ArgumentParser;
    friend ArgumentReader;
    friend ArgumentParserTests;
 
public:
    typedef std::function<void(const ArgumentOccurrence &)> CallbackFunction;

    enum class Flags : std::uint64_t {
        None = 0x0, 
        Combinable
        = 0x1, 
        Implicit = 0x2, 
        Operation = 0x4, 
        Deprecated = 0x8, 
        Greedy
        = 0x10, 
    };
 
    Argument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
    ~Argument();
 
    // declare getter/setter/properties/operations for argument definition:
    //  - those properties must be set *before* parsing
    //  - they control the behaviour of the parser, eg.
    //     - the name/abbreviation to look for
    //     - constraints to be checked
    //     - callbacks to be invoked
    // TODO v5: It would make sense to move these to a separate class (eg. ArgumentDefinition) to prevent this one from
    // becoming to big.
    const char *name() const;
    void setName(const char *name);
    char abbreviation() const;
    void setAbbreviation(char abbreviation);
    const char *environmentVariable() const;
    void setEnvironmentVariable(const char *environmentVariable);
    const char *description() const;
    void setDescription(const char *description);
    const char *example() const;
    void setExample(const char *example);
    std::size_t requiredValueCount() const;
    void setRequiredValueCount(std::size_t requiredValueCount);
    const std::vector<const char *> &valueNames() const;
    void setValueNames(std::initializer_list<const char *> valueNames);
    void appendValueName(const char *valueName);
    void setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences);
    const std::vector<Argument *> &path(std::size_t occurrence = 0) const;
    bool isRequired() const;
    void setRequired(bool required);
    Argument::Flags flags() const;
    void setFlags(Argument::Flags flags);
    void setFlags(Argument::Flags flags, bool add);
    bool isCombinable() const;
    void setCombinable(bool combinable);
    bool isImplicit() const;
    void setImplicit(bool implicit);
    bool denotesOperation() const;
    void setDenotesOperation(bool denotesOperation);
    const CallbackFunction &callback() const;
    void setCallback(CallbackFunction callback);
    const ArgumentVector &subArguments() const;
    void setSubArguments(const ArgumentInitializerList &subArguments);
    void addSubArguments(const ArgumentInitializerList &subArguments);
    void addSubArgument(Argument *arg);
    bool hasSubArguments() const;
    const ArgumentVector &parents() const;
    void printInfo(std::ostream &os, unsigned char indentation = 0) const;
 
    // declare getter/setter/properties for bash completion: those properties must be set *before parsing
    ValueCompletionBehavior valueCompletionBehaviour() const;
    void setValueCompletionBehavior(ValueCompletionBehavior valueCompletionBehaviour);
    const char *preDefinedCompletionValues() const;
    void setPreDefinedCompletionValues(const char *preDefinedCompletionValues);
 
    // declare getter/read-only properties for parsing results: those properties will be populated when parsing
    const std::vector<const char *> &values(std::size_t occurrence = 0) const;
    template <typename... TargetType> std::tuple<TargetType...> valuesAs(std::size_t occurrence = 0) const;
    template <typename... TargetType> std::vector<std::tuple<TargetType...>> allValuesAs() const;
 
    const char *firstValue() const;
    const char *firstValueOr(const char *fallback) const;
    bool allRequiredValuesPresent(std::size_t occurrence = 0) const;
    bool isPresent() const;
    std::size_t occurrences() const;
    std::size_t index(std::size_t occurrence) const;
    std::size_t minOccurrences() const;
    std::size_t maxOccurrences() const;
    bool isDeprecated() const;
    const Argument *deprecatedBy() const;
    void markAsDeprecated(const Argument *deprecatedBy = nullptr);
    bool isMainArgument() const;
    bool isParentPresent() const;
    Argument *conflictsWithArgument() const;
    Argument *wouldConflictWithArgument() const;
    Argument *specifiedOperation() const;
    const std::vector<ArgumentOccurrence> &occurrenceInfo() const;
    std::vector<ArgumentOccurrence> &occurrenceInfo();
    void reset();
    void resetRecursively();

    static constexpr std::size_t varValueCount = std::numeric_limits<std::size_t>::max();
 
private:
    // declare internal getter/setter/properties/operations for argument definition
    bool matchesDenotation(const char *denotation, std::size_t denotationLength) const;
 
    const char *m_name;
    char m_abbreviation;
    const char *m_environmentVar;
    const char *m_description;
    const char *m_example;
    std::size_t m_minOccurrences;
    std::size_t m_maxOccurrences;
    std::size_t m_requiredValueCount;
    std::vector<const char *> m_valueNames;
    Flags m_flags;
    std::vector<ArgumentOccurrence> m_occurrences;
    ArgumentVector m_subArgs;
    CallbackFunction m_callbackFunction;
    ArgumentVector m_parents;
    const Argument *m_deprecatedBy;
    bool m_isMainArg;
    ValueCompletionBehavior m_valueCompletionBehavior;
    const char *m_preDefinedCompletionValues;
};

constexpr Argument::Flags operator|(Argument::Flags lhs, Argument::Flags rhs)
{
    return static_cast<Argument::Flags>(static_cast<unsigned char>(lhs) | static_cast<unsigned char>(rhs));
}
 
constexpr bool operator&(Argument::Flags lhs, Argument::Flags rhs)
{
    return static_cast<bool>(static_cast<unsigned char>(lhs) & static_cast<unsigned char>(rhs));
}

template <typename... TargetType> std::tuple<TargetType...> Argument::valuesAs(std::size_t occurrence) const
{
    return m_occurrences[occurrence].convertValues<TargetType...>();
}

template <typename... TargetType> std::vector<std::tuple<TargetType...>> Argument::allValuesAs() const
{
    std::vector<std::tuple<TargetType...>> res;
    res.reserve(m_occurrences.size());
    for (const auto &occurrence : m_occurrences) {
        res.emplace_back(occurrence.convertValues<TargetType...>());
    }
    return res;
}
 
class CPP_UTILITIES_EXPORT HelpArgument : public Argument {
public:
    HelpArgument(ArgumentParser &parser);
};
 
class CPP_UTILITIES_EXPORT OperationArgument : public Argument {
public:
    OperationArgument(const char *name, char abbreviation = '\0', const char *description = nullptr, const char *example = nullptr);
};
 
class CPP_UTILITIES_EXPORT ConfigValueArgument : public Argument {
public:
    ConfigValueArgument(const char *name, char abbreviation = '\0', const char *description = nullptr,
        std::initializer_list<const char *> valueNames = std::initializer_list<const char *>());
};
 
class CPP_UTILITIES_EXPORT NoColorArgument : public Argument {
    friend ArgumentParserTests;
 
public:
    NoColorArgument();
    void apply() const;
};
 
struct ArgumentCompletionInfo;
 
class CPP_UTILITIES_EXPORT ArgumentParser {
    friend ArgumentParserTests;
    friend ArgumentReader;
 
public:
    ArgumentParser();
 
    // declare getter/setter for argument definitions
    const ArgumentVector &mainArguments() const;
    void setMainArguments(const ArgumentInitializerList &mainArguments);
    void addMainArgument(Argument *argument);
 
    // declare operations which will consider previously assigned argument definitions and maybe modify parsing results
    void printHelp(std::ostream &os) const;
    void parseArgs(int argc, const char *const *argv,
        ParseArgumentBehavior behavior
        = ParseArgumentBehavior::CheckConstraints | ParseArgumentBehavior::InvokeCallbacks | ParseArgumentBehavior::ExitOnFailure);
    void readArgs(int argc, const char *const *argv);
    void resetArgs();
    void assumeDefaultArgument();
    void ensureDefaultOperation();
    void checkConstraints();
    void invokeCallbacks();
 
    // declare getter for parsing results
    unsigned int actualArgumentCount() const;
    const char *executable() const;
    UnknownArgumentBehavior unknownArgumentBehavior() const;
    void setUnknownArgumentBehavior(UnknownArgumentBehavior behavior);
    Argument *defaultArgument() const;
    void setDefaultArgument(Argument *argument);
    Argument *specifiedOperation() const;
    bool isUncombinableMainArgPresent() const;
    void setExitFunction(std::function<void(int)> exitFunction);
    const HelpArgument &helpArg() const;
    HelpArgument &helpArg();
    const NoColorArgument &noColorArg() const;
    NoColorArgument &noColorArg();
 
private:
    // declare internal operations
    CPP_UTILITIES_IF_DEBUG_BUILD(void verifyArgs(const ArgumentVector &args);)
    ArgumentCompletionInfo determineCompletionInfo(
        int argc, const char *const *argv, unsigned int currentWordIndex, const ArgumentReader &reader) const;
    std::string findSuggestions(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
    void printBashCompletion(int argc, const char *const *argv, unsigned int cursorPos, const ArgumentReader &reader) const;
    void checkConstraints(const ArgumentVector &args);
    static void invokeCallbacks(const ArgumentVector &args);
    void invokeExit(int code);
 
    ArgumentVector m_mainArgs;
    unsigned int m_actualArgc;
    const char *m_executable;
    UnknownArgumentBehavior m_unknownArgBehavior;
    Argument *m_defaultArg;
    HelpArgument m_helpArg;
    NoColorArgument m_noColorArg;
    std::function<void(int)> m_exitFunction;
};

inline const char *Argument::name() const
{
    return m_name;
}

inline void Argument::setName(const char *name)
{
#if defined(CPP_UTILITIES_DEBUG_BUILD) && !defined(_MSC_VER)
    if (name && *name) {
        assert(*name != '-');
        for (const char *c = name; *c; ++c) {
            assert(*c != ' ' && *c != '=' && *c != '\'' && *c != '\"' && *c != '\n' && *c != '\r');
        }
    }
#endif
    m_name = name;
}

inline char Argument::abbreviation() const
{
    return m_abbreviation;
}

inline void Argument::setAbbreviation(char abbreviation)
{
    CPP_UTILITIES_IF_DEBUG_BUILD(assert(abbreviation != ' ' && abbreviation != '=' && abbreviation != '-' && abbreviation != '\''
        && abbreviation != '"' && abbreviation != '\n' && abbreviation != '\r'));
    m_abbreviation = abbreviation;
}

inline const char *Argument::environmentVariable() const
{
    return m_environmentVar;
}

inline void Argument::setEnvironmentVariable(const char *environmentVariable)
{
    m_environmentVar = environmentVariable;
}

inline const char *Argument::description() const
{
    return m_description;
}

inline void Argument::setDescription(const char *description)
{
    m_description = description;
}

inline const char *Argument::example() const
{
    return m_example;
}

inline void Argument::setExample(const char *example)
{
    m_example = example;
}

inline const std::vector<const char *> &Argument::values(std::size_t occurrence) const
{
    return m_occurrences[occurrence].values;
}

inline std::size_t Argument::requiredValueCount() const
{
    return m_requiredValueCount;
}

inline void Argument::setRequiredValueCount(std::size_t requiredValueCount)
{
    m_requiredValueCount = requiredValueCount;
}

inline const std::vector<const char *> &Argument::valueNames() const
{
    return m_valueNames;
}

inline void Argument::setValueNames(std::initializer_list<const char *> valueNames)
{
    m_valueNames.assign(valueNames);
}

inline void Argument::appendValueName(const char *valueName)
{
    m_valueNames.emplace_back(valueName);
}

inline bool Argument::allRequiredValuesPresent(std::size_t occurrence) const
{
    return m_requiredValueCount == Argument::varValueCount
        || (m_occurrences[occurrence].values.size() >= static_cast<std::size_t>(m_requiredValueCount));
}

inline bool Argument::isImplicit() const
{
    return m_flags & Flags::Implicit;
}

inline void Argument::setImplicit(bool implicit)
{
    setFlags(Flags::Implicit, implicit);
}

inline bool Argument::isPresent() const
{
    return !m_occurrences.empty();
}

inline std::size_t Argument::occurrences() const
{
    return m_occurrences.size();
}

inline std::size_t Argument::index(std::size_t occurrence) const
{
    return m_occurrences[occurrence].index;
}

inline std::size_t Argument::minOccurrences() const
{
    return m_minOccurrences;
}

inline std::size_t Argument::maxOccurrences() const
{
    return m_maxOccurrences;
}
 
inline bool Argument::isDeprecated() const
{
    return m_flags & Flags::Deprecated;
}

inline const Argument *Argument::deprecatedBy() const
{
    return m_deprecatedBy;
}

inline void Argument::markAsDeprecated(const Argument *deprecatedBy)
{
    setFlags(Flags::Deprecated, true);
    m_deprecatedBy = deprecatedBy;
}

inline void Argument::setConstraints(std::size_t minOccurrences, std::size_t maxOccurrences)
{
    m_minOccurrences = minOccurrences;
    m_maxOccurrences = maxOccurrences;
}

inline const std::vector<Argument *> &Argument::path(std::size_t occurrence) const
{
    return m_occurrences[occurrence].path;
}

inline bool Argument::isRequired() const
{
    return m_minOccurrences;
}

inline void Argument::setRequired(bool required)
{
    if (required) {
        if (!m_minOccurrences) {
            m_minOccurrences = 1;
        }
    } else {
        m_minOccurrences = 0;
    }
}

inline Argument::Flags Argument::flags() const
{
    return m_flags;
}

inline void Argument::setFlags(Argument::Flags flags)
{
    m_flags = flags;
}

inline void Argument::setFlags(Argument::Flags flags, bool add)
{
    m_flags = add ? (m_flags | flags)
                  : static_cast<Argument::Flags>(static_cast<std::underlying_type<Argument::Flags>::type>(m_flags)
                        & ~static_cast<std::underlying_type<Argument::Flags>::type>(flags));
}

inline bool Argument::isCombinable() const
{
    return m_flags & Flags::Combinable;
}

inline void Argument::setCombinable(bool combinable)
{
    setFlags(Flags::Combinable, combinable);
}

inline bool Argument::denotesOperation() const
{
    return m_flags & Flags::Operation;
}

inline void Argument::setDenotesOperation(bool denotesOperation)
{
    setFlags(Flags::Operation, denotesOperation);
}

inline const Argument::CallbackFunction &Argument::callback() const
{
    return m_callbackFunction;
}

inline void Argument::setCallback(Argument::CallbackFunction callback)
{
    m_callbackFunction = callback;
}

inline const ArgumentVector &Argument::subArguments() const
{
    return m_subArgs;
}

inline bool Argument::hasSubArguments() const
{
    return !m_subArgs.empty();
}

inline const ArgumentVector &Argument::parents() const
{
    return m_parents;
}

inline bool Argument::isMainArgument() const
{
    return m_isMainArg;
}

inline ValueCompletionBehavior Argument::valueCompletionBehaviour() const
{
    return m_valueCompletionBehavior;
}

inline void Argument::setValueCompletionBehavior(ValueCompletionBehavior completionValues)
{
    m_valueCompletionBehavior = completionValues;
}

inline const char *Argument::preDefinedCompletionValues() const
{
    return m_preDefinedCompletionValues;
}

inline void Argument::setPreDefinedCompletionValues(const char *preDefinedCompletionValues)
{
    m_preDefinedCompletionValues = preDefinedCompletionValues;
}

inline void Argument::reset()
{
    m_occurrences.clear();
}
 
inline OperationArgument::OperationArgument(const char *name, char abbreviation, const char *description, const char *example)
    : Argument(name, abbreviation, description, example)
{
    setDenotesOperation(true);
}

inline ConfigValueArgument::ConfigValueArgument(
    const char *name, char abbreviation, const char *description, std::initializer_list<const char *> valueNames)
    : Argument(name, abbreviation, description)
{
    setCombinable(true);
    setRequiredValueCount(valueNames.size());
    setValueNames(valueNames);
}

inline const std::vector<ArgumentOccurrence> &Argument::occurrenceInfo() const
{
    return m_occurrences;
}

inline std::vector<ArgumentOccurrence> &Argument::occurrenceInfo()
{
    return m_occurrences;
}

inline const ArgumentVector &ArgumentParser::mainArguments() const
{
    return m_mainArgs;
}

inline unsigned int ArgumentParser::actualArgumentCount() const
{
    return m_actualArgc;
}

inline const char *ArgumentParser::executable() const
{
    return m_executable;
}

inline UnknownArgumentBehavior ArgumentParser::unknownArgumentBehavior() const
{
    return m_unknownArgBehavior;
}

inline void ArgumentParser::setUnknownArgumentBehavior(UnknownArgumentBehavior behavior)
{
    m_unknownArgBehavior = behavior;
}

inline Argument *ArgumentParser::defaultArgument() const
{
    return m_defaultArg;
}

inline void ArgumentParser::setDefaultArgument(Argument *argument)
{
    m_defaultArg = argument;
}

inline void ArgumentParser::checkConstraints()
{
    checkConstraints(m_mainArgs);
}

inline void ArgumentParser::invokeCallbacks()
{
    invokeCallbacks(m_mainArgs);
}

inline void ArgumentParser::setExitFunction(std::function<void(int)> exitFunction)
{
    m_exitFunction = exitFunction;
}

inline const HelpArgument &ArgumentParser::helpArg() const
{
    return m_helpArg;
}

inline HelpArgument &ArgumentParser::helpArg()
{
    return m_helpArg;
}

inline const NoColorArgument &ArgumentParser::noColorArg() const
{
    return m_noColorArg;
}

inline NoColorArgument &ArgumentParser::noColorArg()
{
    return m_noColorArg;
}
 
} // namespace CppUtilities
 
#endif // APPLICATION_UTILITIES_ARGUMENTPARSER_H