format_base.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2006-2024, Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2024, Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
#include <sharg/auxiliary.hpp>
#include <sharg/config.hpp>
#include <sharg/detail/concept.hpp>
#include <sharg/detail/type_name_as_string.hpp>
#include <sharg/validators.hpp>
 
#if __has_include(<seqan3/version.hpp>)
#    include <seqan3/version.hpp>
#endif
 
namespace sharg::detail
{
 
class format_base
{
protected:
    template <typename value_type>
    static std::string get_type_name_as_string(value_type const & )
    {
        using type = std::decay_t<value_type>;
 
        if constexpr (std::is_same_v<type, int8_t>)
            return "signed 8 bit integer";
        else if constexpr (std::is_same_v<type, uint8_t>)
            return "unsigned 8 bit integer";
        else if constexpr (std::is_same_v<type, int16_t>)
            return "signed 16 bit integer";
        else if constexpr (std::is_same_v<type, uint16_t>)
            return "unsigned 16 bit integer";
        else if constexpr (std::is_same_v<type, int32_t>)
            return "signed 32 bit integer";
        else if constexpr (std::is_same_v<type, uint32_t>)
            return "unsigned 32 bit integer";
        else if constexpr (std::is_same_v<type, int64_t>)
            return "signed 64 bit integer";
        else if constexpr (std::is_same_v<type, uint64_t>)
            return "unsigned 64 bit integer";
        else if constexpr (std::is_same_v<type, double>)
            return "double";
        else if constexpr (std::is_same_v<type, float>)
            return "float";
        else if constexpr (std::is_same_v<type, bool>)
            return "bool";
        else if constexpr (std::is_same_v<type, char>)
            return "char";
        else if constexpr (std::is_same_v<type, std::string>)
            return "std::string";
        else if constexpr (std::is_same_v<type, std::filesystem::path>)
            return "std::filesystem::path";
        else
            return sharg::detail::type_name_as_string<value_type>;
    }
 
    template <detail::is_container_option container_type>
    static std::string get_type_name_as_string(container_type const & )
    {
        typename container_type::value_type tmp{};
        return get_type_name_as_string(tmp);
    }
 
    template <typename option_value_type>
    static std::string option_type_and_list_info(option_value_type const & value)
    {
        return ("(\\fI" + get_type_name_as_string(value) + "\\fP)");
    }
 
    template <detail::is_container_option container_type>
    static std::string option_type_and_list_info(container_type const & container)
    {
        return ("(\\fIList\\fP of \\fI" + get_type_name_as_string(container) + "\\fP)");
    }
 
    static std::string prep_id_for_help(char const short_id, std::string const & long_id)
    {
        // Build list item term.
        std::string term;
        if (short_id != '\0')
            term = "\\fB-" + std::string(1, short_id) + "\\fP";
 
        if (short_id != '\0' && !long_id.empty())
            term.append(", ");
 
        if (!long_id.empty())
            term.append("\\fB--" + long_id + "\\fP");
 
        return term;
    }
 
    static std::string escape_special_xml_chars(std::string const & original)
    {
        std::string escaped;
        escaped.reserve(original.size()); // will be at least as long
 
        for (auto c : original)
        {
            if (c == '"')
                escaped.append("&quot;");
            else if (c == '\'')
                escaped.append("&apos;");
            else if (c == '&')
                escaped.append("&amp;");
            else if (c == '<')
                escaped.append("&lt;");
            else if (c == '>')
                escaped.append("&gt;");
            else
                escaped.push_back(c);
        }
 
        return escaped;
    }
 
    static std::string expand_multiple_flags(std::string const & flag_cluster)
    {
        std::string tmp;
        auto it{flag_cluster.begin()};
 
        if (flag_cluster[0] == '-')
            ++it;
 
        for (; it != flag_cluster.end() - 1; ++it)
            tmp.append({'-', *it, ',', ' '});
 
        tmp.erase(tmp.find_last_of(',')); // remove last ', '
        tmp.append({'a', 'n', 'd', ' ', '-', flag_cluster[flag_cluster.size() - 1]});
 
        return tmp;
    }
 
    template <typename option_type, typename default_type>
    static std::string get_default_message(option_type const & SHARG_DOXYGEN_ONLY(option), default_type const & value)
    {
        static_assert(std::same_as<option_type, default_type> || std::same_as<default_type, std::string>);
 
        std::stringstream message{};
        message << " Default: ";
 
        if constexpr (detail::is_container_option<option_type>)
        {
            // If we have a list of strings, we want to quote each string.
            if constexpr (std::same_as<std::ranges::range_value_t<default_type>, std::string>)
            {
                auto view = std::views::transform(value,
                                                  [](auto const & val)
                                                  {
                                                      return std::quoted(val);
                                                  });
                message << detail::to_string(view);
            }
            else // Otherwise we just print the list or the default_message without quotes.
            {
                message << detail::to_string(value);
            }
        }
        else
        {
            static constexpr bool option_is_string = std::same_as<option_type, std::string>;
            static constexpr bool option_is_path = std::same_as<option_type, std::filesystem::path>;
            static constexpr bool value_is_string = std::same_as<default_type, std::string>;
 
            // Quote: std::string (from value + default_message), and std::filesystem::path (default_message).
            // std::filesystem::path is quoted by the STL's operator<< in detail::to_string.
            static constexpr bool needs_string_quote = option_is_string || (option_is_path && value_is_string);
 
            if constexpr (needs_string_quote)
                message << std::quoted(value);
            else
                message << detail::to_string(value);
        }
 
        return message.str();
    }
};
 
template <typename derived_type>
class format_help_base : public format_base
{
private:
    format_help_base() = default;                                        
    format_help_base(format_help_base const & pf) = default;             
    format_help_base & operator=(format_help_base const & pf) = default; 
    format_help_base(format_help_base &&) = default;                     
    format_help_base & operator=(format_help_base &&) = default;         
    ~format_help_base() = default;                                       
 
    format_help_base(std::vector<std::string> const & names,
                     update_notifications const version_updates,
                     bool const advanced) :
        version_check_dev_decision{version_updates},
        command_names{names},
        show_advanced_options{advanced}
    {}
 
public:
    template <typename option_type, typename validator_t>
    void add_option(option_type & value, config<validator_t> const & config)
    {
        std::string id = prep_id_for_help(config.short_id, config.long_id) + " " + option_type_and_list_info(value);
        std::string info{config.description};
 
        if (config.default_message.empty())
            info += ((config.required) ? std::string{} : get_default_message(value, value));
        else
            info += get_default_message(value, config.default_message);
 
        if (auto const & validator_message = config.validator.get_help_page_message(); !validator_message.empty())
            info += ". " + validator_message;
 
        store_help_page_element(
            [this, id, info]()
            {
                derived_t().print_list_item(id, info);
            },
            config);
    }
 
    template <typename validator_t>
    void add_flag(bool & SHARG_DOXYGEN_ONLY(value), config<validator_t> const & config)
    {
        store_help_page_element(
            [this, id = prep_id_for_help(config.short_id, config.long_id), description = config.description]()
            {
                derived_t().print_list_item(id, description);
            },
            config);
    }
 
    template <typename option_type, typename validator_t>
    void add_positional_option(option_type & value, config<validator_t> const & config)
    {
        // a list at the end may be empty and thus have a default value
        auto positional_default_message = [&value]() -> std::string
        {
            if constexpr (detail::is_container_option<option_type>)
            {
                return get_default_message(value, value);
            }
            else
            {
                (void)value; // Silence unused variable warning.
                return {};
            }
        };
 
        auto positional_validator_message = [&config]() -> std::string
        {
            if (auto const & validator_message = config.validator.get_help_page_message(); !validator_message.empty())
                return ". " + validator_message;
            else
                return {};
        };
 
        positional_option_calls.push_back(
            [this,
             &value,
             default_message = positional_default_message(),
             validator_message = positional_validator_message(),
             description = config.description]()
            {
                ++positional_option_count;
                derived_t().print_list_item(detail::to_string("\\fBARGUMENT-",
                                                              positional_option_count,
                                                              "\\fP ",
                                                              option_type_and_list_info(value)),
                                            description + default_message + validator_message);
            });
    }
 
    void parse(parser_meta_data & parser_meta)
    {
        meta = parser_meta;
 
        derived_t().print_header();
 
        if (!meta.synopsis.empty())
        {
            derived_t().print_section("Synopsis");
            derived_t().print_synopsis();
        }
 
        if (!meta.description.empty())
        {
            derived_t().print_section("Description");
            for (auto desc : meta.description)
                print_line(desc);
        }
 
        if (!command_names.empty())
        {
            derived_t().print_section("Subcommands");
            derived_t().print_line("This program must be invoked with one of the following subcommands:", false);
            for (std::string const & name : command_names)
                derived_t().print_line("- \\fB" + name + "\\fP", false);
            derived_t().print_line("See the respective help page for further details (e.g. by calling " + meta.app_name
                                       + " " + command_names[0] + " -h).",
                                   true);
            derived_t().print_line("The following options belong to the top-level parser and need to be "
                                   "specified \\fBbefore\\fP the subcommand key word. Every argument after the "
                                   "subcommand key word is passed on to the corresponding sub-parser.",
                                   true);
        }
 
        // add positional options if specified
        if (!positional_option_calls.empty())
            derived_t().print_section("Positional Arguments");
 
        // each call will evaluate the function derived_t().print_list_item()
        for (auto f : positional_option_calls)
            f();
 
        // There are always options because of the common options
        derived_t().print_section("Options");
 
        // each call will evaluate the function derived_t().print_list_item()
        for (auto f : parser_set_up_calls)
            f();
 
        // print Common options after developer options
        derived_t().print_subsection("Common options");
        derived_t().print_list_item("\\fB-h\\fP, \\fB--help\\fP", "Prints the help page.");
        derived_t().print_list_item("\\fB-hh\\fP, \\fB--advanced-help\\fP",
                                    "Prints the help page including advanced options.");
        derived_t().print_list_item("\\fB--version\\fP", "Prints the version information.");
        derived_t().print_list_item("\\fB--copyright\\fP", "Prints the copyright/license information.");
        derived_t().print_list_item("\\fB--export-help\\fP (std::string)",
                                    "Export the help page information. Value must be one of "
                                        + detail::supported_exports + ".");
        if (version_check_dev_decision == update_notifications::on)
            derived_t().print_list_item("\\fB--version-check\\fP (bool)",
                                        "Whether to check for the newest app version. Default: true");
 
        if (!meta.examples.empty())
        {
            derived_t().print_section("Examples");
            for (auto example : meta.examples)
                print_line(example);
        }
 
        print_version();
 
        print_legal();
 
        derived_t().print_footer();
    }
 
    void add_section(std::string const & title, bool const advanced_only)
    {
        store_help_page_element(
            [this, title]()
            {
                derived_t().print_section(title);
            },
            advanced_only,
            false /* never hidden */);
    }
 
    void add_subsection(std::string const & title, bool const advanced_only)
    {
        store_help_page_element(
            [this, title]()
            {
                derived_t().print_subsection(title);
            },
            advanced_only,
            false /* never hidden */);
    }
 
    void add_line(std::string const & text, bool is_paragraph, bool const advanced_only)
    {
        store_help_page_element(
            [this, text, is_paragraph]()
            {
                derived_t().print_line(text, is_paragraph);
            },
            advanced_only,
            false /* never hidden */);
    }
 
    void add_list_item(std::string const & key, std::string const & desc, bool const advanced_only)
    {
        store_help_page_element(
            [this, key, desc]()
            {
                derived_t().print_list_item(key, desc);
            },
            advanced_only,
            false /* never hidden */);
    }
 
    parser_meta_data meta;
 
    friend derived_type;
 
protected:
    update_notifications version_check_dev_decision{};
 
    derived_type & derived_t()
    {
        return static_cast<derived_type &>(*this);
    }
 
    void print_synopsis()
    {
        for (unsigned i = 0; i < meta.synopsis.size(); ++i)
        {
            std::string text = "\\fB";
            text.append(meta.synopsis[i]);
            text.insert(text.find_first_of(" \t"), "\\fP");
 
            derived_t().print_line(text, false);
        }
    }
 
    void print_line(std::string const & text)
    {
        derived_t().print_line(text, true);
    }
 
    void print_version()
    {
        std::string const version_str{sharg::sharg_version_cstring};
 
        // Print version, date and url.
        derived_t().print_section("Version");
        derived_t().print_line(derived_t().in_bold("Last update: ") + meta.date, false);
        derived_t().print_line(derived_t().in_bold(meta.app_name + " version: ") + meta.version, false);
        derived_t().print_line(derived_t().in_bold("Sharg version: ") + version_str, false);
 
#ifdef SEQAN3_VERSION_CSTRING
        std::string const seqan3_version_str{seqan3::seqan3_version_cstring};
        derived_t().print_line(derived_t().in_bold("SeqAn version: ") + seqan3_version_str, false);
#endif
 
        if (!empty(meta.url))
        {
            derived_t().print_section("Url");
            derived_t().print_line(meta.url, false);
        }
    }
 
    void print_legal()
    {
        // Print legal stuff
        if ((!empty(meta.short_copyright)) || (!empty(meta.long_copyright)) || (!empty(meta.citation))
            || (!empty(meta.author)) || (!empty(meta.email)))
        {
            derived_t().print_section("Legal");
 
            if (!empty(meta.short_copyright))
            {
                derived_t().print_line(derived_t().in_bold(meta.app_name + " Copyright: ") + meta.short_copyright,
                                       false);
            }
 
            if (!empty(meta.author))
            {
                derived_t().print_line(derived_t().in_bold("Author: ") + meta.author, false);
            }
 
            if (!empty(meta.email))
            {
                derived_t().print_line(derived_t().in_bold("Contact: ") + meta.email, false);
            }
 
            derived_t().print_line(derived_t().in_bold("SeqAn Copyright: ")
                                       + "2006-2024 Knut Reinert, FU-Berlin; released under the 3-clause BSDL.",
                                   false);
 
            if (!empty(meta.citation))
            {
                derived_t().print_line(derived_t().in_bold("In your academic works please cite: ") + meta.citation,
                                       false);
            }
 
            if (!empty(meta.long_copyright))
            {
                derived_t().print_line("For full copyright and/or warranty information see "
                                           + derived_t().in_bold("--copyright") + ".",
                                       false);
            }
        }
    }
 
    std::vector<std::function<void()>> parser_set_up_calls;
    std::vector<std::function<void()>> positional_option_calls; // singled out to be printed on top
    unsigned positional_option_count{0};
    std::vector<std::string> command_names{};
    bool show_advanced_options{true};
 
private:
    void store_help_page_element(std::function<void()> printer, bool const advanced, bool const hidden)
    {
        if (!(hidden) && (!(advanced) || show_advanced_options))
            parser_set_up_calls.push_back(std::move(printer));
    }
 
    template <typename validator_t>
    void store_help_page_element(std::function<void()> printer, config<validator_t> const & config)
    {
        if (!(config.hidden) && (!(config.advanced) || show_advanced_options))
            parser_set_up_calls.push_back(std::move(printer));
    }
};
 
} // namespace sharg::detail