cli.h

Go to the documentation of this file.

/*
* Copyright (C) 2020-2026 MEmilio
*
* Authors: René Schmieding
*
* Contact: Martin J. Kuehn <Martin.Kuehn@DLR.de>
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef MIO_IO_CLI_H
#define MIO_IO_CLI_H
 
#include "memilio/config.h" // IWYU pragma: keep
 
#ifdef MEMILIO_HAS_JSONCPP
 
#include "memilio/io/io.h"
#include "memilio/io/json_serializer.h"
#include "memilio/utils/metaprogramming.h"
#include "memilio/utils/parameter_set.h"
#include "memilio/utils/string_literal.h"
#include "memilio/utils/type_list.h"
 
#include <cassert>
#include <iostream>
#include <memory>
#include <span>
#include <sstream>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
 
namespace mio
{
 
namespace cli
{
 
namespace details
{
 
template <class Parameter>
const std::string get_name(const Parameter& p)
{
    return p.name();
}
 
template <class Parameter>
const std::string get_alias(const Parameter& p)
{
    if constexpr (requires { p.alias(); }) {
        return p.alias();
    }
    else {
        return "";
    }
}
 
template <class Parameter>
const std::string get_description(const Parameter& p)
{
    if constexpr (requires { p.description(); }) {
        return p.description();
    }
    else {
        return "";
    }
}
 
template <class Parameter>
constexpr bool get_is_required(const Parameter& p)
{
    if constexpr (requires { p.is_required(); }) {
        return p.is_required();
    }
    else {
        return false;
    }
}
 
struct DatalessParameter {
    std::string name, alias = "", description = "";
    bool is_required = false;
};
 
struct OptionalFields {
    std::string alias = "", description = "";
    bool is_required = false;
};
 
enum class IdentifierType
{
    Name, // e.g. "--help"
    Alias, // e.g. "-h"
    Raw // either a name or alias without dashes, e.g. "help"
};
 
class Identifier
{
private:
    Identifier(std::string str, IdentifierType t)
        : string(std::move(str))
        , type(t)
    {
    }
 
public:
    static IOResult<Identifier> parse(const std::string& str)
    {
        if (is_name(str)) {
            return mio::success(Identifier(str, IdentifierType::Name));
        }
        else if (is_alias(str)) {
            return mio::success(Identifier(str, IdentifierType::Alias));
        }
        else {
            return mio::failure(mio::StatusCode::InvalidValue, "Expected an option, got \"" + str + "\".");
        }
    }
 
    static Identifier make_raw(const std::string& raw_name)
    {
        return {raw_name, IdentifierType::Raw};
    }
 
    static bool is_name(std::string_view unverified_id)
    {
        // check for two dashes and at least one more character
        return (unverified_id.size() > 2) && (unverified_id[0] == '-' && unverified_id[1] == '-');
    }
 
    static bool is_alias(std::string_view unverified_id)
    {
        // check for exactly one dash and at least one more non-dash character
        return (unverified_id.size() > 1) && (unverified_id[0] == '-') && (unverified_id[1] != '-');
    }
 
    static bool is_option(std::string_view unverified_id)
    {
        return is_name(unverified_id) || is_alias(unverified_id);
    }
 
    inline const std::string_view strip() const
    {
        switch (type) {
        case IdentifierType::Name:
            return std::string_view{string}.substr(2);
        case IdentifierType::Alias:
            return std::string_view{string}.substr(1);
        case IdentifierType::Raw:
            return std::string_view{string};
        }
        assert(false && "Invalid IdentifierType");
        // this return is practically inaccessible, but needed to avoid a "reached end of non-void function" warning
        return std::string_view{};
    }
 
    inline bool matches_parameter(const DatalessParameter& p) const
    {
        switch (type) {
        case IdentifierType::Name:
            return p.name == strip();
        case IdentifierType::Alias:
            return p.alias == strip();
        case IdentifierType::Raw:
            return (p.name == string) || (string.size() > 0 && p.alias == string);
        }
        assert(false && "Invalid IdentifierType");
        // this return is practically inaccessible, but needed to avoid a "reached end of non-void function" warning
        return false;
    }
 
    std::string string; 
    IdentifierType type; 
};
 
struct PresetOptions {
    const inline static DatalessParameter help{
        .name = "help", .alias = "h", .description = "Show this dialogue and exit.", .is_required = false};
 
    const inline static DatalessParameter print_option{
        .name  = "print_option",
        .alias = "",
        .description =
            "Use with parameter option name(s) without \"--\" as value(s). Prints the current values of specified "
            "options in their correct json format, then exits.",
        .is_required = false};
 
    const inline static DatalessParameter read_from_json{
        .name  = "read_from_json",
        .alias = "",
        .description =
            "Takes a filepath as value. Reads and assigns parameter option values from the specified json file.",
        .is_required = false};
 
    const inline static DatalessParameter write_to_json{
        .name  = "write_to_json",
        .alias = "",
        .description =
            "Takes a filepath as value. Writes current values of all parameter options to the specified json file.",
        .is_required = false};
 
    const inline static std::vector<DatalessParameter> all_presets{help, print_option, read_from_json, write_to_json};
};
 
class AbstractParameter : public DatalessParameter
{
public:
    template <class Type>
    AbstractParameter(mio::Tag<Type>, const DatalessParameter& p, std::shared_ptr<void>&& value)
        : DatalessParameter(p)
        , m_data(std::move(value))
        , m_serialize([](const std::shared_ptr<void>& param) -> IOResult<Json::Value> {
            return mio::serialize_json(*static_cast<Type*>(param.get()));
        })
        , m_set([](std::shared_ptr<void>& param, const std::string& name, const Json::Value& json) -> IOResult<void> {
            mio::unused(param); // prevent a "set, but unused" compiler warning
            // deserialize the json value to the parameter's type, then assign it
            auto param_result = mio::deserialize_json(json, mio::Tag<Type>());
            if (param_result) {
                // assign the json to the parameter
                *(static_cast<Type*>(param.get())) = std::move(param_result.value());
                return mio::success();
            }
            else { // deserialize failed
                // insert more information to the error message
                std::string msg = "While setting \"" + name + "\": " + param_result.error().message();
                if (param_result.error().message() == "Json value is not a string.") {
                    msg += " Try using escaped quotes (\\\") around your input strings.";
                }
                return mio::failure(param_result.error().code(), msg);
            }
        })
    {
    }
 
    template <class Param>
    AbstractParameter(mio::Tag<Param>, typename Param::Type& value)
        : AbstractParameter(mio::Tag<typename Param::Type>{},
                            DatalessParameter{get_name(Param{}), get_alias(Param{}), get_description(Param{}),
                                              get_is_required(Param{})},
                            std::shared_ptr<void>(static_cast<void*>(&value), [](void*) {}))
    {
    }
 
    template <class Param>
    AbstractParameter(mio::Tag<Param>, AbstractParameter& other)
        : AbstractParameter(other)
    {
    }
 
    IOResult<Json::Value> get() const
    {
        auto json_result = m_serialize(m_data);
        if (json_result) {
            return json_result;
        }
        else {
            std::string msg = "While getting \"" + name() + "\": " + json_result.error().message();
            return mio::failure(json_result.error().code(), msg);
        }
    }
 
    IOResult<void> set(const Json::Value& value)
    {
        return m_set(m_data, name(), value);
    }
 
    const std::string& name() const
    {
        return DatalessParameter::name;
    }
    const std::string& alias() const
    {
        return DatalessParameter::alias;
    }
    const std::string& description() const
    {
        return DatalessParameter::description;
    }
    bool is_required() const
    {
        return DatalessParameter::is_required;
    }
    void* data()
    {
        return m_data.get();
    }
 
private:
    std::shared_ptr<void> m_data; 
    IOResult<Json::Value> (*m_serialize)(
        const std::shared_ptr<void>&); 
    IOResult<void> (*m_set)(std::shared_ptr<void>&, const std::string&,
                            const Json::Value&); 
};
 
class AbstractSet
{
public:
    using MapType = std::unordered_map<std::string_view, AbstractParameter&>;
 
    template <class Set>
    static IOResult<AbstractSet> build(Set& parameter_set)
    {
        AbstractSet set(parameter_set);
        BOOST_OUTCOME_TRY(fill_maps(set));
        return mio::success(std::move(set));
    }
 
    IOResult<Json::Value> get_param(const Identifier& id)
    {
        auto param = find(id);
        if (!param) {
            return mio::failure(param.error().code(), "Could not get parameter: " + param.error().message());
        }
        else {
            return param.value()->second.get();
        }
    }
 
    IOResult<void> set_param(const Identifier& id, const std::string& args)
    {
        Json::Value js;
        std::string errors;
        std::stringstream args_stream(args);
        Json::parseFromStream(Json::CharReaderBuilder{}, args_stream, &js, &errors);
        // do not directly raise errors, to avoid hiding e.g. a "parameter not found"
        return set_param(id, js, errors);
    }
 
    IOResult<void> set_param(const Identifier& id, const Json::Value& value, const std::string& parse_errors = "")
    {
        auto param = find(id);
        if (!param) {
            return mio::failure(param.error().code(), "Could not set parameter: " + param.error().message());
        }
        else {
            // try to set the value
            IOResult<void> result = param.value()->second.set(value);
            if (result) {
                // mark as set. we reuse the is_required flag for this, to make checks and repeated CLI calls easier
                param.value()->second.DatalessParameter::is_required = false;
                return result;
            }
            else if (parse_errors.empty()) {
                // no need to modify result if there are no parsing errors
                return result;
            }
            else {
                // append parsing errors to original error
                return mio::failure(result.error().code(), result.error().message() + "\n" + parse_errors);
            }
        }
    }
 
    bool contains(const Identifier& id)
    {
        return static_cast<bool>(find(id));
    }
 
    std::vector<AbstractParameter>& parameters()
    {
        return m_parameters;
    }
    const std::vector<AbstractParameter>& parameters() const
    {
        return m_parameters;
    }
private:
    AbstractSet() = default;
 
    template <class... T, template <class...> class Set>
    AbstractSet(Set<T...>& parameter_set)
        : m_parameters(std::vector{AbstractParameter(mio::Tag<T>{}, parameter_set.template get<T>())...})
    {
    }
 
    AbstractSet(std::vector<AbstractParameter>& parameters)
        : m_parameters(parameters)
    {
    }
 
    IOResult<MapType::iterator> find(const Identifier& id)
    {
        auto param_itr = m_map_by_alias.find(id.strip());
        if (param_itr != m_map_by_alias.end()) {
            return mio::success(param_itr);
        }
        param_itr = m_map_by_name.find(id.strip());
        if (param_itr != m_map_by_name.end()) {
            return mio::success(param_itr);
        }
        return mio::failure(mio::StatusCode::KeyNotFound, "No such option \"" + id.string + "\".");
    }
 
    static IOResult<void> fill_maps(AbstractSet& set)
    {
        for (AbstractParameter& p : set.m_parameters) {
            if (p.name().empty()) {
                return mio::failure(mio::StatusCode::InvalidValue, "An option is missing a name.");
            }
            if (!set.m_map_by_name.insert({p.name(), p}).second) {
                return mio::failure(mio::StatusCode::InvalidValue, "Options may not have duplicate names. "
                                                                   "Found two instances of \"" +
                                                                       p.name() + "\".");
            }
            if (!p.alias().empty() && !set.m_map_by_alias.insert({p.alias(), p}).second) {
                return mio::failure(mio::StatusCode::InvalidValue, "Options may not have duplicate aliases. "
                                                                   "Found two instances of \"" +
                                                                       p.alias() + "\".");
            }
        }
        return mio::success();
    }
 
    std::vector<AbstractParameter> m_parameters;
    MapType m_map_by_name;
    MapType m_map_by_alias;
};
 
void write_help(const std::string& executable_name, const AbstractSet& set,
                const std::vector<std::string>& default_options, std::ostream& os);
 
mio::IOResult<void> command_line_interface(const std::string& executable_name, const std::span<char*>& argv,
                                           cli::details::AbstractSet& parameters,
                                           const std::vector<std::string>& default_options);
 
template <StringLiteral>
struct NamedType;
 
template <class... Tags>
class ParameterSet
{
    using Names = TypeList<type_at_index_t<0, Tags>...>;
    using Types = TypeList<type_at_index_t<1, Tags>...>;
 
public:
    ParameterSet(std::vector<details::AbstractParameter>&& parameters)
        : m_parameters(std::move(parameters))
    {
    }
 
    template <mio::StringLiteral Name>
    inline auto& get()
    {
        constexpr size_t parameter_index = index_of_type_v<details::NamedType<Name>, Names>;
        using ReturnType                 = type_at_index_t<parameter_index, Types>;
        return *static_cast<ReturnType*>(m_parameters[parameter_index].data());
    }
 
    template <class Tag>
    inline details::AbstractParameter& get()
    {
        constexpr size_t parameter_index = index_of_type_v<Tag, Tags...>;
        return m_parameters[parameter_index];
    }
 
private:
    std::vector<details::AbstractParameter> m_parameters; 
};
 
mio::IOResult<void> write_abstract_set_to_file(mio::cli::details::AbstractSet& set, const std::string& filepath);
 
mio::IOResult<void> read_abstract_set_from_file(mio::cli::details::AbstractSet& set, const std::string& filepath);
 
} // namespace details
 
template <class... Params>
class ParameterSetBuilder
{
    // make private constructor accessible independent of template arguments
    template <class...>
    friend class ParameterSetBuilder;
 
public:
    ParameterSetBuilder() = default;
 
    template <mio::StringLiteral Name, class Type>
    [[nodiscard]] inline auto add(Type&& initial_value, details::OptionalFields&& optionals = {}) &&
    {
        using ValueType = std::decay_t<Type>; // get base type in case Type was deduced and is e.g. const or &
        // since we get *this as rvalue, we can move the parameters
        auto new_params = std::move(m_parameters);
        // create a new owning data pointer, stored as void*
        std::shared_ptr<void> data(new ValueType(std::forward<Type>(initial_value)), std::default_delete<ValueType>{});
        // create a new abstract parameter, then move all parameters to a new builder
        new_params.emplace_back(Tag<ValueType>{},
                                details::DatalessParameter{.name        = std::string(Name),
                                                           .alias       = std::move(optionals).alias,
                                                           .description = std::move(optionals).description,
                                                           .is_required = std::move(optionals).is_required},
                                std::move(data));
        return ParameterSetBuilder<Params..., TypeList<details::NamedType<Name>, ValueType>>{std::move(new_params)};
    }
 
    [[nodiscard]] inline mio::cli::details::ParameterSet<Params...> build() &&
    {
        return mio::cli::details::ParameterSet<Params...>(std::move(m_parameters));
    }
 
private:
    ParameterSetBuilder(std::vector<details::AbstractParameter>&& parameters)
        : m_parameters(std::move(parameters))
    {
    }
 
    std::vector<details::AbstractParameter> m_parameters; 
};
 
} // namespace cli
 
template <class Set>
IOResult<void> write_parameters_to_file(Set& parameters, const std::string& filepath)
{
    BOOST_OUTCOME_TRY(auto&& set, cli::details::AbstractSet::build(parameters));
    return write_abstract_set_to_file(set, filepath);
}
 
template <class... Parameters, template <class...> class Set>
IOResult<void> read_parameters_from_file(Set<Parameters...>& parameters, const std::string& filepath)
{
    BOOST_OUTCOME_TRY(auto&& set, cli::details::AbstractSet::build(parameters));
    return read_abstract_set_from_file(set, filepath);
}
 
template <class Set>
mio::IOResult<void> command_line_interface(const std::string& executable_name, const int argc, char** argv,
                                           Set& parameters, const std::vector<std::string>& default_options = {})
{
    // parse the parameters into an iterable format
    BOOST_OUTCOME_TRY(auto&& set, cli::details::AbstractSet::build(parameters));
    return cli::details::command_line_interface(executable_name, std::span(argv, argc), set, default_options);
}
 
template <class... Parameters, template <class...> class Set = mio::ParameterSet>
mio::IOResult<Set<Parameters...>> command_line_interface(const std::string& executable_name, const int argc,
                                                         char** argv,
                                                         const std::vector<std::string>& default_options = {})
{
    static_assert(sizeof...(Parameters) != 0, "At least one Parameter is required.");
    // create a new parameter set, and pass it and all other arguments to the main cli function
    Set<Parameters...> parameters{};
    auto result = command_line_interface(executable_name, argc, argv, parameters, default_options);
    // check the result, return parameters if appropriate
    if (result) {
        return mio::IOResult<Set<Parameters...>>(mio::success(std::move(parameters)));
    }
    else {
        return mio::IOResult<Set<Parameters...>>(mio::failure(result.error()));
    }
}
 
} // namespace mio
 
#endif // MEMILIO_HAS_JSONCPP
 
#endif // MIO_IO_CLI_H