parser.hpp

Go to the documentation of this file.

// --------------------------------------------------------------------------------------------------------
// Copyright (c) 2006-2022, Knut Reinert & Freie Universität Berlin
// Copyright (c) 2016-2022, Knut Reinert & MPI für molekulare Genetik
// This file may be used, modified and/or redistributed under the terms of the 3-clause BSD-License
// shipped with this file and also available at: https://github.com/seqan/sharg-parser/blob/main/LICENSE.md
// --------------------------------------------------------------------------------------------------------
 
#pragma once
 
#include <set>
#include <variant>
 
#include <sharg/config.hpp>
#include <sharg/detail/format_help.hpp>
#include <sharg/detail/format_html.hpp>
#include <sharg/detail/format_man.hpp>
#include <sharg/detail/format_parse.hpp>
#include <sharg/detail/version_check.hpp>
 
namespace sharg
{
 
class parser
{
public:
    parser() = delete;                            
    parser(parser const &) = default;             
    parser & operator=(parser const &) = default; 
    parser(parser &&) = default;                  
    parser & operator=(parser &&) = default;      
 
    parser(std::string const & app_name,
           int const argc,
           char const * const * const argv,
           update_notifications version_updates = update_notifications::on,
           std::vector<std::string> subcommands = {}) :
        version_check_dev_decision{version_updates},
        subcommands{std::move(subcommands)}
    {
        if (!std::regex_match(app_name, app_name_regex))
        {
            throw design_error{("The application name must only contain alpha-numeric characters or '_' and '-' "
                                "(regex: \"^[a-zA-Z0-9_-]+$\").")};
        }
 
        for (auto & sub : this->subcommands)
        {
            if (!std::regex_match(sub, app_name_regex))
            {
                throw design_error{"The subcommand name must only contain alpha-numeric characters or '_' and '-' "
                                   "(regex: \"^[a-zA-Z0-9_-]+$\")."};
            }
        }
 
        info.app_name = app_name;
 
        init(argc, argv);
    }
 
    ~parser()
    {
        // wait for another 3 seconds
        if (version_check_future.valid())
            version_check_future.wait_for(std::chrono::seconds(3));
    }
 
    template <typename option_type, typename validator_type>
        requires (parsable<option_type> || parsable<std::ranges::range_value_t<option_type>>)
              && std::invocable<validator_type, option_type>
    void add_option(option_type & value, config<validator_type> const & config)
    {
        verify_option_config(config);
 
        // copy variables into the lambda because the calls are pushed to a stack
        // and the references would go out of scope.
        std::visit(
            [&value, &config](auto & f)
            {
                f.add_option(value, config);
            },
            format);
    }
 
    template <typename validator_type>
        requires std::invocable<validator_type, bool>
    void add_flag(bool & value, config<validator_type> const & config)
    {
        verify_flag_config(config);
 
        if (value)
            throw design_error("A flag's default value must be false.");
 
        // copy variables into the lambda because the calls are pushed to a stack
        // and the references would go out of scope.
        std::visit(
            [&value, &config](auto & f)
            {
                f.add_flag(value, config);
            },
            format);
    }
 
    template <typename option_type, typename validator_type>
        requires (parsable<option_type> || parsable<std::ranges::range_value_t<option_type>>)
              && std::invocable<validator_type, option_type>
    void add_positional_option(option_type & value, config<validator_type> const & config)
    {
        verify_positional_option_config(config);
 
        if constexpr (detail::is_container_option<option_type>)
            has_positional_list_option = true; // keep track of a list option because there must be only one!
 
        // copy variables into the lambda because the calls are pushed to a stack
        // and the references would go out of scope.
        std::visit(
            [&value, &config](auto & f)
            {
                f.add_positional_option(value, config);
            },
            format);
    }
 
    void parse()
    {
        if (parse_was_called)
            throw design_error("The function parse() must only be called once!");
 
        detail::version_checker app_version{info.app_name, info.version, info.url};
 
        if (std::holds_alternative<detail::format_parse>(format) && !subcommands.empty() && sub_parser == nullptr)
        {
            assert(!subcommands.empty());
            std::string subcommands_str{"["};
            for (std::string const & command : subcommands)
                subcommands_str += command + ", ";
            subcommands_str.replace(subcommands_str.size() - 2, 2, "]"); // replace last ", " by "]"
 
            throw too_few_arguments{"You either forgot or misspelled the subcommand! Please specify which sub-program "
                                    "you want to use: one of "
                                    + subcommands_str
                                    + ". Use -h/--help for more "
                                      "information."};
        }
 
        if (app_version.decide_if_check_is_performed(version_check_dev_decision, version_check_user_decision))
        {
            // must be done before calling parse on the format because this might std::exit
            std::promise<bool> app_version_prom;
            version_check_future = app_version_prom.get_future();
            app_version(std::move(app_version_prom));
        }
 
        std::visit(
            [this](auto & f)
            {
                f.parse(info);
            },
            format);
        parse_was_called = true;
    }
 
    parser & get_sub_parser()
    {
        if (sub_parser == nullptr)
        {
            throw design_error("No subcommand was provided at the construction of the argument parser!");
        }
 
        return *sub_parser;
    }
 
    // clang-format off
    template <typename id_type>
        requires std::same_as<id_type, char> || std::constructible_from<std::string, id_type>
    bool is_option_set(id_type const & id) const
    // clang-format on
    {
        if (!parse_was_called)
            throw design_error{"You can only ask which options have been set after calling the function `parse()`."};
 
        // the detail::format_parse::find_option_id call in the end expects either a char or std::string
        using char_or_string_t = std::conditional_t<std::same_as<id_type, char>, char, std::string>;
        char_or_string_t short_or_long_id = {id}; // e.g. convert char * to string here if necessary
 
        if constexpr (!std::same_as<id_type, char>) // long id was given
        {
            if (short_or_long_id.size() == 1)
            {
                throw design_error{"Long option identifiers must be longer than one character! If " + short_or_long_id
                                   + "' was meant to be a short identifier, please pass it as a char ('') not a string"
                                     " (\"\")!"};
            }
        }
 
        if (std::find(used_option_ids.begin(), used_option_ids.end(), std::string{id}) == used_option_ids.end())
            throw design_error{"You can only ask for option identifiers that you added with add_option() before."};
 
        // we only need to search for an option before the `end_of_options_indentifier` (`--`)
        auto end_of_options = std::find(cmd_arguments.begin(), cmd_arguments.end(), end_of_options_indentifier);
        auto option_it = detail::format_parse::find_option_id(cmd_arguments.begin(), end_of_options, short_or_long_id);
        return option_it != end_of_options;
    }
 
 
    void add_section(std::string const & title, bool const advanced_only = false)
    {
        std::visit(
            [&title, advanced_only](auto & f)
            {
                f.add_section(title, advanced_only);
            },
            format);
    }
 
    void add_subsection(std::string const & title, bool const advanced_only = false)
    {
        std::visit(
            [&title, advanced_only](auto & f)
            {
                f.add_subsection(title, advanced_only);
            },
            format);
    }
 
    void add_line(std::string const & text, bool is_paragraph = false, bool const advanced_only = false)
    {
        std::visit(
            [&text, is_paragraph, advanced_only](auto & f)
            {
                f.add_line(text, is_paragraph, advanced_only);
            },
            format);
    }
 
    void add_list_item(std::string const & key, std::string const & desc, bool const advanced_only = false)
    {
        std::visit(
            [&key, &desc, advanced_only](auto & f)
            {
                f.add_list_item(key, desc, advanced_only);
            },
            format);
    }
 
    parser_meta_data info;
 
private:
    bool parse_was_called{false};
 
    bool has_positional_list_option{false};
 
    update_notifications version_check_dev_decision{};
 
    std::optional<bool> version_check_user_decision;
 
    friend struct ::sharg::detail::test_accessor;
 
    std::future<bool> version_check_future;
 
    std::regex app_name_regex{"^[a-zA-Z0-9_-]+$"};
 
    static constexpr std::string_view const end_of_options_indentifier{"--"};
 
    std::unique_ptr<parser> sub_parser{nullptr};
 
    std::vector<std::string> subcommands{};
 
    std::variant<detail::format_parse,
                 detail::format_help,
                 detail::format_short_help,
                 detail::format_version,
                 detail::format_html,
                 detail::format_man,
                 detail::format_copyright/*,
                 detail::format_ctd*/> format{detail::format_help{{}, false}}; // Will be overwritten in any case.
 
    std::set<std::string> used_option_ids{"h", "hh", "help", "advanced-help", "export-help", "version", "copyright"};
 
    std::vector<std::string> cmd_arguments{};
 
    void init(int argc, char const * const * const argv)
    {
        bool special_format_was_set{false};
 
        for (int i = 1, argv_len = argc; i < argv_len; ++i) // start at 1 to skip binary name
        {
            std::string arg{argv[i]};
 
            if (std::find(subcommands.begin(), subcommands.end(), arg) != subcommands.end())
            {
                sub_parser =
                    std::make_unique<parser>(info.app_name + "-" + arg, argc - i, argv + i, update_notifications::off);
                break;
            }
 
            if (arg == "-h" || arg == "--help")
            {
                format = detail::format_help{subcommands, false};
                init_standard_options();
                special_format_was_set = true;
            }
            else if (arg == "-hh" || arg == "--advanced-help")
            {
                format = detail::format_help{subcommands, true};
                init_standard_options();
                special_format_was_set = true;
            }
            else if (arg == "--version")
            {
                format = detail::format_version{};
                special_format_was_set = true;
            }
            else if (arg.substr(0, 13) == "--export-help") // --export-help=man is also allowed
            {
                std::string export_format;
 
                if (arg.size() > 13)
                {
                    export_format = arg.substr(14);
                }
                else
                {
                    if (argv_len <= i + 1)
                        throw too_few_arguments{"Option --export-help must be followed by a value."};
                    export_format = {argv[i + 1]};
                }
 
                if (export_format == "html")
                    format = detail::format_html{subcommands};
                else if (export_format == "man")
                    format = detail::format_man{subcommands};
                // TODO (smehringer) use when CTD support is available
                // else if (export_format == "ctd")
                //     format = detail::format_ctd{};
                else
                    throw validation_error{"Validation failed for option --export-help: "
                                           "Value must be one of [html, man]"};
                init_standard_options();
                special_format_was_set = true;
            }
            else if (arg == "--copyright")
            {
                format = detail::format_copyright{};
                special_format_was_set = true;
            }
            else if (arg == "--version-check")
            {
                if (++i >= argv_len)
                    throw too_few_arguments{"Option --version-check must be followed by a value."};
 
                arg = argv[i];
 
                if (arg == "1" || arg == "true")
                    version_check_user_decision = true;
                else if (arg == "0" || arg == "false")
                    version_check_user_decision = false;
                else
                    throw validation_error{"Value for option --version-check must be true (1) or false (0)."};
 
                // in case --version-check is specified it shall not be passed to format_parse()
                argc -= 2;
            }
            else
            {
                cmd_arguments.push_back(std::move(arg));
            }
        }
 
        // all special options have been identified, which might involve deleting them from argv (e.g. version-check)
        // check if no actual options remain and then call the short help page.
        if (argc <= 1) // no arguments provided
        {
            format = detail::format_short_help{};
            return;
        }
 
        if (!special_format_was_set)
            format = detail::format_parse(argc, cmd_arguments);
    }
 
    void init_standard_options()
    {
        add_subsection("Basic options:");
        add_list_item("\\fB-h\\fP, \\fB--help\\fP", "Prints the help page.");
        add_list_item("\\fB-hh\\fP, \\fB--advanced-help\\fP", "Prints the help page including advanced options.");
        add_list_item("\\fB--version\\fP", "Prints the version information.");
        add_list_item("\\fB--copyright\\fP", "Prints the copyright/license information.");
        add_list_item("\\fB--export-help\\fP (std::string)",
                      "Export the help page information. Value must be one of [html, man].");
        if (version_check_dev_decision == update_notifications::on)
            add_list_item("\\fB--version-check\\fP (bool)",
                          "Whether to check for the newest app version. Default: true.");
    }
 
    template <typename id_type>
    bool id_exists(id_type const & id)
    {
        if (detail::format_parse::is_empty_id(id))
            return false;
        return (!(used_option_ids.insert(std::string({id}))).second);
    }
 
    void verify_identifiers(char const short_id, std::string const & long_id)
    {
        constexpr std::string_view valid_chars{"@_0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"};
        auto is_valid = [&valid_chars](char const c)
        {
            return valid_chars.find(c) != std::string::npos;
        };
 
        if (id_exists(short_id))
            throw design_error("Option Identifier '" + std::string(1, short_id) + "' was already used before.");
        if (id_exists(long_id))
            throw design_error("Option Identifier '" + long_id + "' was already used before.");
        if (long_id.length() == 1)
            throw design_error("Long IDs must be either empty, or longer than one character.");
        if ((short_id != '\0') && !is_valid(short_id))
            throw design_error("Option identifiers may only contain alphanumeric characters, '_', or '@'.");
        if (long_id.size() > 0 && (long_id[0] == '-'))
            throw design_error("First character of long ID cannot be '-'.");
 
        std::for_each(long_id.begin(),
                      long_id.end(),
                      [&is_valid](char c)
                      {
                          if (!((c == '-') || is_valid(c)))
                              throw design_error(
                                  "Long identifiers may only contain alphanumeric characters, '_', '-', or '@'.");
                      });
        if (detail::format_parse::is_empty_id(short_id) && detail::format_parse::is_empty_id(long_id))
            throw design_error("Option Identifiers cannot both be empty.");
    }
 
    void verify_option_config(config<auto> const & config)
    {
        if (sub_parser != nullptr)
            throw design_error{"You may only specify flags for the top-level parser."};
 
        verify_identifiers(config.short_id, config.long_id);
 
        if (config.required && !config.default_message.empty())
            throw design_error{"A required option cannot have a default message."};
    }
 
    void verify_flag_config(config<auto> const & config)
    {
        verify_identifiers(config.short_id, config.long_id);
 
        if (!config.default_message.empty())
            throw design_error{"A flag may not have a default message because the default is always `false`."};
    }
 
    void verify_positional_option_config(config<auto> const & config) const
    {
        if (config.short_id != '\0' || config.long_id != "")
            throw design_error{"Positional options are identified by their position on the command line. "
                               "Short or long ids are not permitted!"};
 
        if (config.advanced || config.hidden)
            throw design_error{"Positional options are always required and therefore cannot be advanced nor hidden!"};
 
        if (sub_parser != nullptr)
            throw design_error{"You may only specify flags for the top-level parser."};
 
        if (has_positional_list_option)
            throw design_error{"You added a positional option with a list value before so you cannot add "
                               "any other positional options."};
 
        if (!config.default_message.empty())
            throw design_error{"A positional option may not have a default message because it is always required."};
    }
};
 
} // namespace sharg