parser.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2006-2025, Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025, Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: BSD-3-Clause
 
#pragma once
 
#include <unordered_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/format_tdl.hpp>
#include <sharg/detail/version_check.hpp>
 
namespace sharg
{
 
class parser
{
public:
    parser() = delete;                           
    parser(parser const &) = delete;             
    parser & operator=(parser const &) = delete; 
    parser(parser &&) = default;                 
    parser & operator=(parser &&) = default;     
 
    parser(std::string app_name,
           std::vector<std::string> arguments,
           update_notifications version_updates = update_notifications::on,
           std::vector<std::string> const & subcommands = {}) :
        version_check_dev_decision{version_updates},
        arguments{std::move(arguments)}
    {
        add_subcommands(subcommands);
        info.app_name = std::move(app_name);
    }
 
    parser(std::string app_name,
           int const argc,
           char const * const * const argv,
           update_notifications version_updates = update_notifications::on,
           std::vector<std::string> const & subcommands = {}) :
        parser{std::move(app_name), std::vector<std::string>{argv, argv + argc}, version_updates, subcommands}
    {}
 
    ~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)
    {
        check_parse_not_called("add_option");
        verify_option_config(config);
 
        auto operation = [this, &value, config]()
        {
            auto visit_fn = [&value, &config](auto & f)
            {
                f.add_option(value, config);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    template <typename validator_type>
        requires std::invocable<validator_type, bool>
    void add_flag(bool & value, config<validator_type> const & config)
    {
        check_parse_not_called("add_flag");
        verify_flag_config(config);
 
        if (value)
            throw design_error("A flag's default value must be false.");
 
        auto operation = [this, &value, config]()
        {
            auto visit_fn = [&value, &config](auto & f)
            {
                f.add_flag(value, config);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    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)
    {
        check_parse_not_called("add_positional_option");
        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!
 
        auto operation = [this, &value, config]()
        {
            auto visit_fn = [&value, &config](auto & f)
            {
                f.add_positional_option(value, config);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    void parse()
    {
        if (parse_was_called)
            throw design_error("The function parse() must only be called once!");
 
        parse_was_called = true;
 
        // User input sanitization must happen before version check!
        verify_app_and_subcommand_names();
 
        // Determine the format and subcommand.
        determine_format_and_subcommand();
 
        // Apply all defered operations to the parser, e.g., `add_option`, `add_flag`, `add_positional_option`.
        for (auto & operation : operations)
            operation();
 
        // The version check, which might exit the program, must be called before calling parse on the format.
        run_version_check();
 
        // Parse the command line arguments.
        parse_format();
 
        // Exit after parsing any special format.
        if (!std::holds_alternative<detail::format_parse>(format))
            std::exit(EXIT_SUCCESS);
    }
 
    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()`."};
 
        detail::id_pair const id_pair{id};
 
        if (id_pair.long_id.size() == 1u)
        {
            throw design_error{"Long option identifiers must be longer than one character! If " + id_pair.long_id
                               + "' was meant to be a short identifier, please pass it as a char ('') not a string"
                                 " (\"\")!"};
        }
 
        auto const it = detail::id_pair::find(used_option_ids, id_pair);
        if (it == 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 `option_end_identifier` (`--`)
        auto option_end = std::ranges::find(format_arguments, option_end_identifier);
        auto option_it = detail::format_parse::find_option_id(format_arguments.begin(), option_end, *it);
        return option_it != option_end;
    }
 
 
    void add_section(std::string const & title, bool const advanced_only = false)
    {
        check_parse_not_called("add_section");
 
        auto operation = [this, title, advanced_only]()
        {
            auto visit_fn = [&title, advanced_only](auto & f)
            {
                f.add_section(title, advanced_only);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    void add_subsection(std::string const & title, bool const advanced_only = false)
    {
        check_parse_not_called("add_subsection");
 
        auto operation = [this, title, advanced_only]()
        {
            auto visit_fn = [&title, advanced_only](auto & f)
            {
                f.add_subsection(title, advanced_only);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    void add_line(std::string const & text, bool is_paragraph = false, bool const advanced_only = false)
    {
        check_parse_not_called("add_line");
 
        auto operation = [this, text, is_paragraph, advanced_only]()
        {
            auto visit_fn = [&text, is_paragraph, advanced_only](auto & f)
            {
                f.add_line(text, is_paragraph, advanced_only);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    void add_list_item(std::string const & key, std::string const & desc, bool const advanced_only = false)
    {
        check_parse_not_called("add_list_item");
 
        auto operation = [this, key, desc, advanced_only]()
        {
            auto visit_fn = [&key, &desc, advanced_only](auto & f)
            {
                f.add_list_item(key, desc, advanced_only);
            };
 
            std::visit(std::move(visit_fn), format);
        };
 
        operations.push_back(std::move(operation));
    }
 
    void add_subcommands(std::vector<std::string> const & subcommands)
    {
        auto & parser_subcommands = this->subcommands;
        parser_subcommands.insert(parser_subcommands.end(), subcommands.cbegin(), subcommands.cend());
 
        std::ranges::sort(parser_subcommands);
        auto const [first, last] = std::ranges::unique(parser_subcommands);
        parser_subcommands.erase(first, last);
    }
 
    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 option_end_identifier{"--"};
 
    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_tdl,
                 detail::format_copyright>
        format{detail::format_short_help{}};
 
    std::unordered_set<detail::id_pair> used_option_ids{{'h', "help"},
                                                        {'\0' /*hh*/, "advanced-help"},
                                                        {'\0', "hh"},
                                                        {'\0', "export-help"},
                                                        {'\0', "version"},
                                                        {'\0', "copyright"}};
 
    std::vector<std::string> format_arguments{};
 
    std::vector<std::string> arguments{};
 
    std::vector<std::string> executable_name{};
 
    std::unordered_set<std::string> options{};
 
    std::vector<std::function<void()>> operations;
 
    void determine_format_and_subcommand()
    {
        assert(!arguments.empty());
 
        auto it = arguments.begin();
        std::string_view arg{*it};
 
        executable_name.emplace_back(arg);
 
        // Helper function for reading the next argument. This makes it more obvious that we are
        // incrementing `it` (version-check, and export-help).
        auto read_next_arg = [this, &it, &arg]() -> bool
        {
            assert(it != arguments.end());
 
            if (++it == arguments.end())
                return false;
 
            arg = *it;
            return true;
        };
 
        // Helper function for finding and processing subcommands.
        auto found_subcommand = [this, &it, &arg]() -> bool
        {
            if (subcommands.empty())
                return false;
 
            auto copy_metadata_to_subparser = [this](parser & sub_parser)
            {
                sub_parser.info.version = info.version;
                sub_parser.info.author = info.author;
                sub_parser.info.email = info.email;
                sub_parser.info.date = info.date;
                sub_parser.info.url = info.url;
                sub_parser.info.short_copyright = info.short_copyright;
                sub_parser.info.long_copyright = info.long_copyright;
                sub_parser.info.citation = info.citation;
            };
 
            if (std::ranges::find(subcommands, arg) != subcommands.end())
            {
                sub_parser = std::make_unique<parser>(info.app_name + "-" + arg.data(),
                                                      std::vector<std::string>{it, arguments.end()},
                                                      update_notifications::off);
                copy_metadata_to_subparser(get_sub_parser());
 
                // Add the original calls to the front, e.g. ["raptor"],
                // s.t. ["raptor", "build"] will be the list after constructing the subparser
                sub_parser->executable_name.insert(sub_parser->executable_name.begin(),
                                                   executable_name.begin(),
                                                   executable_name.end());
                return true;
            }
            else
            {
                // Positional options are forbidden by design.
                // Flags and options, which both start with '-', are allowed for the top-level parser.
                // Otherwise, this is an unknown subcommand.
                if (!arg.starts_with('-'))
                {
                    std::string message = "You specified an unknown subcommand! Available subcommands are: [";
                    for (std::string const & command : subcommands)
                        message += command + ", ";
                    message.replace(message.size() - 2, 2, "]. Use -h/--help for more information.");
 
                    throw user_input_error{message};
                }
            }
 
            return false;
        };
 
        // Process the arguments.
        for (; read_next_arg();)
        {
            // The argument is a known option.
            if (options.contains(std::string{arg}))
            {
                // No futher checks are needed.
                format_arguments.emplace_back(arg);
 
                // Consume the next argument (the option value) if possible.
                if (read_next_arg())
                {
                    format_arguments.emplace_back(arg);
                    continue;
                }
                else // Too few arguments. This is handled by format_parse.
                {
                    break;
                }
            }
 
            // If we have a subcommand, all further arguments are passed to the subparser.
            if (found_subcommand())
                break;
 
            if (arg == "-h" || arg == "--help")
            {
                format = detail::format_help{subcommands, version_check_dev_decision, false};
            }
            else if (arg == "-hh" || arg == "--advanced-help")
            {
                format = detail::format_help{subcommands, version_check_dev_decision, true};
            }
            else if (arg == "--version")
            {
                format = detail::format_version{};
            }
            else if (arg == "--copyright")
            {
                format = detail::format_copyright{};
            }
            else if (arg == "--export-help" || arg.starts_with("--export-help="))
            {
                arg.remove_prefix(std::string_view{"--export-help"}.size());
 
                // --export-help man
                if (arg.empty())
                {
                    if (!read_next_arg())
                        throw too_few_arguments{"Option --export-help must be followed by a value."};
                }
                else // --export-help=man
                {
                    arg.remove_prefix(1u);
                }
 
                if (arg == "html")
                    format = detail::format_html{subcommands, version_check_dev_decision};
                else if (arg == "man")
                    format = detail::format_man{subcommands, version_check_dev_decision};
                else if (arg == "ctd")
                    format = detail::format_tdl{detail::format_tdl::FileFormat::CTD};
                else if (arg == "cwl")
                    format = detail::format_tdl{detail::format_tdl::FileFormat::CWL};
                else
                    throw validation_error{"Validation failed for option --export-help: "
                                           "Value must be one of "
                                           + detail::supported_exports + "."};
            }
            else if (arg == "--version-check")
            {
                if (!read_next_arg())
                    throw too_few_arguments{"Option --version-check must be followed by a value."};
 
                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)."};
            }
            else
            {
                // Flags, positional options, options using an alternative syntax (--optionValue, --option=value), etc.
                format_arguments.emplace_back(arg);
            }
        }
 
        // A special format was set. We do not need to parse the format_arguments.
        if (!std::holds_alternative<detail::format_short_help>(format))
            return;
 
        // All special options have been handled. If there are arguments left or we have a subparser,
        // we call format_parse. Oterhwise, we print the short help (default variant).
        if (!format_arguments.empty() || sub_parser)
            format = detail::format_parse(format_arguments);
    }
 
    void verify_identifiers(char const short_id, std::string const & long_id)
    {
        auto is_valid = [](char const c) -> bool
        {
            return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || (c >= '0' && c <= '9') // alphanumeric
                || c == '@' || c == '_' || c == '-';                                          // additional characters
        };
 
        if (short_id == '\0' && long_id.empty())
            throw design_error{"Short and long identifiers may not both be empty."};
 
        if (short_id != '\0')
        {
            if (short_id == '-' || !is_valid(short_id))
                throw design_error{"Short identifiers may only contain alphanumeric characters, '_', or '@'."};
            if (detail::id_pair::contains(used_option_ids, short_id))
                throw design_error{"Short identifier '" + std::string(1, short_id) + "' was already used before."};
        }
 
        if (!long_id.empty())
        {
            if (long_id.size() == 1)
                throw design_error{"Long identifiers must be either empty or longer than one character."};
            if (long_id[0] == '-')
                throw design_error{"Long identifiers may not use '-' as first character."};
            if (!std::ranges::all_of(long_id, is_valid))
                throw design_error{"Long identifiers may only contain alphanumeric characters, '_', '-', or '@'."};
            if (detail::id_pair::contains(used_option_ids, long_id))
                throw design_error{"Long identifier '" + long_id + "' was already used before."};
        }
 
        used_option_ids.emplace(short_id, long_id);
    }
 
    template <typename validator_t>
    void verify_option_config(config<validator_t> const & config)
    {
        verify_identifiers(config.short_id, config.long_id);
 
        if (config.short_id != '\0')
            options.emplace(std::string{"-"} + config.short_id);
        if (!config.long_id.empty())
            options.emplace(std::string{"--"} + config.long_id);
 
        if (config.required && !config.default_message.empty())
            throw design_error{"A required option cannot have a default message."};
    }
 
    template <typename validator_t>
    void verify_flag_config(config<validator_t> 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`."};
    }
 
    template <typename validator_t>
    void verify_positional_option_config(config<validator_t> 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 (!subcommands.empty())
            throw design_error{"You may only specify flags and options 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."};
    }
 
    inline void check_parse_not_called(std::string_view const function_name) const
    {
        if (parse_was_called)
            throw design_error{detail::to_string(function_name.data(), " may only be used before calling parse().")};
    }
 
    inline void verify_app_and_subcommand_names() const
    {
        // Before creating the detail::version_checker, we have to make sure that
        // malicious code cannot be injected through the app name.
        if (!std::regex_match(info.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_-]+$\")."};
            }
        }
    }
 
    inline void run_version_check()
    {
        detail::version_checker app_version{info.app_name, info.version, info.url};
 
        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));
        }
    }
 
    inline void parse_format()
    {
        auto format_parse_fn = [this]<typename format_t>(format_t & f)
        {
            if constexpr (std::same_as<format_t, detail::format_tdl>)
                f.parse(info, executable_name);
            else
                f.parse(info);
        };
 
        std::visit(std::move(format_parse_fn), format);
    }
};
 
} // namespace sharg