argument_parser.hpp

Go to the documentation of this file.

// -----------------------------------------------------------------------------------------------------
// Copyright (c) 2006-2020, Knut Reinert & Freie Universität Berlin
// Copyright (c) 2016-2020, 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/seqan3/blob/master/LICENSE.md
// -----------------------------------------------------------------------------------------------------
 
#pragma once
 
#include <future>
#include <iostream>
#include <set>
#include <sstream>
#include <string>
#include <variant>
#include <vector>
#include <regex>
 
// #include <seqan3/argument_parser/detail/format_ctd.hpp>
#include <seqan3/argument_parser/detail/format_help.hpp>
#include <seqan3/argument_parser/detail/format_html.hpp>
#include <seqan3/argument_parser/detail/format_man.hpp>
#include <seqan3/argument_parser/detail/format_parse.hpp>
#include <seqan3/argument_parser/detail/version_check.hpp>
#include <seqan3/core/char_operations/predicate.hpp>
#include <seqan3/core/detail/terminal.hpp>
#include <seqan3/core/detail/test_accessor.hpp>
#include <seqan3/core/detail/to_string.hpp>
#include <seqan3/io/stream/concept.hpp>
 
namespace seqan3
{
 
class argument_parser
{
public:
    argument_parser() = delete;                                     
    argument_parser(argument_parser const &) = default;             
    argument_parser & operator=(argument_parser const &) = default; 
    argument_parser(argument_parser &&) = default;                  
    argument_parser & operator=(argument_parser &&) = default;      
 
    argument_parser(std::string const app_name,
                    int const argc,
                    char const * const * const  argv,
                    bool version_check = true,
                    std::vector<std::string> subcommands = {}) :
        version_check_dev_decision{version_check}
    {
        if (!std::regex_match(app_name, app_name_regex))
            throw parser_design_error{"The application name must only contain alpha-numeric characters "
                                               "or '_' and '-' (regex: \"^[a-zA-Z0-9_-]+$\")."};
        for (auto & sub : subcommands)
            if (!std::regex_match(sub, std::regex{"^[a-zA-Z0-9_]+$"}))
                throw parser_design_error{"The subcommand name must only contain alpha-numeric characters or '_'."};
 
        info.app_name = std::move(app_name);
        init(argc, argv, std::move(subcommands));
    }
 
    ~argument_parser()
    {
        // wait for another 3 seconds
        if (version_check_future.valid())
            version_check_future.wait_for(std::chrono::seconds(3));
    }
 
    template <typename option_type, validator validator_type = detail::default_validator<option_type>>
        requires (argument_parser_compatible_option<option_type> ||
                  argument_parser_compatible_option<std::ranges::range_value_t<option_type>>) &&
                  std::invocable<validator_type, option_type>
    void add_option(option_type & value,
                    char const short_id,
                    std::string const & long_id,
                    std::string const & desc,
                    option_spec const & spec = option_spec::DEFAULT,
                    validator_type validator = validator_type{}) // copy to bind rvalues
    {
        if (sub_parser != nullptr)
            throw parser_design_error{"You may only specify flags for the top-level parser."};
 
        verify_identifiers(short_id, long_id);
        // copy variables into the lambda because the calls are pushed to a stack
        // and the references would go out of scope.
        std::visit([=, &value] (auto & f) { f.add_option(value, short_id, long_id, desc, spec, validator); }, format);
    }
 
    void add_flag(bool & value,
                  char const short_id,
                  std::string const & long_id,
                  std::string const & desc,
                  option_spec const & spec = option_spec::DEFAULT)
    {
        verify_identifiers(short_id, long_id);
        // copy variables into the lambda because the calls are pushed to a stack
        // and the references would go out of scope.
        std::visit([=, &value] (auto & f) { f.add_flag(value, short_id, long_id, desc, spec); }, format);
    }
 
    template <typename option_type, validator validator_type = detail::default_validator<option_type>>
        requires (argument_parser_compatible_option<option_type> ||
                  argument_parser_compatible_option<std::ranges::range_value_t<option_type>>) &&
                  std::invocable<validator_type, option_type>
    void add_positional_option(option_type & value,
                               std::string const & desc,
                               validator_type validator = validator_type{}) // copy to bind rvalues
    {
        if (sub_parser != nullptr)
            throw parser_design_error{"You may only specify flags for the top-level parser."};
 
        if (has_positional_list_option)
            throw parser_design_error{"You added a positional option with a list value before so you cannot add "
                                      "any other positional options."};
 
        if constexpr (sequence_container<option_type> && !std::same_as<option_type, std::string>)
            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] (auto & f) { f.add_positional_option(value, desc, validator); }, format);
    }
 
    void parse()
    {
        if (parse_was_called)
            throw parser_design_error("The function parse() must only be called once!");
 
        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));
        }
 
        std::visit([this] (auto & f) { f.parse(info); }, format);
        parse_was_called = true;
    }
 
    argument_parser & get_sub_parser()
    {
        if (sub_parser == nullptr)
        {
            throw parser_design_error("You did not enable subcommand parsing on construction "
                                      "so you cannot access the sub-parser!");
        }
 
        return *sub_parser;
    }
 
 
    void add_section(std::string const & title)
    {
        std::visit([&] (auto & f) { f.add_section(title); }, format);
    }
 
    void add_subsection(std::string const & title)
    {
        std::visit([&] (auto & f) { f.add_subsection(title); }, format);
    }
 
    void add_line(std::string const & text, bool line_is_paragraph = false)
    {
        std::visit([&] (auto & f) { f.add_line(text, line_is_paragraph); }, format);
    }
 
    void add_list_item(std::string const & key, std::string const & desc)
    {
        std::visit([&] (auto & f) { f.add_list_item(key, desc); }, format);
    }
 
    argument_parser_meta_data info;
 
private:
    bool parse_was_called{false};
 
    bool has_positional_list_option{false};
 
    bool version_check_dev_decision{};
 
    std::optional<bool> version_check_user_decision;
 
    friend struct ::seqan3::detail::test_accessor;
 
    std::future<bool> version_check_future;
 
    std::regex app_name_regex{"^[a-zA-Z0-9_-]+$"};
 
    std::unique_ptr<argument_parser> sub_parser{nullptr};
 
    void init(int argc, char const * const * const argv, std::vector<std::string> const & subcommands)
    {
        // cash command line input, in case --version-check is specified but shall not be passed to format_parse()
        std::vector<std::string> argv_new{};
 
        if (argc <= 1) // no arguments provided
        {
            format = detail::format_short_help{};
            return;
        }
 
        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::ranges::find(subcommands, arg) != subcommands.end())
            {
                sub_parser = std::make_unique<argument_parser>(info.app_name + "-" + arg, argc - i, argv + i, false);
                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 parser_invalid_argument{"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_failed{"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 parser_invalid_argument{"Option --version-check must be followed by a value."};
 
                arg = argv[i];
 
                if (arg == "1")
                    version_check_user_decision = true;
                else if (arg == "0")
                    version_check_user_decision = false;
                else
                    throw parser_invalid_argument{"Value for option --version-check must be 1 or 0."};
 
                argc -= 2;
            }
            else
            {
                argv_new.push_back(std::move(arg));
            }
        }
 
        if (!special_format_was_set)
        {
            if (!subcommands.empty() && sub_parser == nullptr)
            {
                throw parser_invalid_argument{detail::to_string("Please specify which sub program you want to use ",
                                              "(one of ", subcommands, "). Use -h/--help for more information.")};
            }
 
            format = detail::format_parse(argc, std::move(argv_new));
        }
    }
 
    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)
            add_list_item("\\fB--version-check\\fP (bool)", "Whether to to check for the newest app version. Default: 1.");
        add_subsection(""); // add a new line (todo smehringer) add a add_newline() function
    }
 
    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)
    {
        auto constexpr allowed = is_alnum || is_char<'_'> || is_char<'@'>;
 
        if (id_exists(short_id))
            throw parser_design_error("Option Identifier '" + std::string(1, short_id) + "' was already used before.");
        if (id_exists(long_id))
            throw parser_design_error("Option Identifier '" + long_id + "' was already used before.");
        if (long_id.length() == 1)
            throw parser_design_error("Long IDs must be either empty, or longer than one character.");
        if (!allowed(short_id) && !is_char<'\0'>(short_id))
            throw parser_design_error("Option identifiers may only contain alphanumeric characters, '_', or '@'.");
        if (long_id.size() > 0 && is_char<'-'>(long_id[0]))
            throw parser_design_error("First character of long ID cannot be '-'.");
 
        std::for_each(long_id.begin(), long_id.end(), [&allowed] (char c)
                      {
                          if (!(allowed(c) || is_char<'-'>(c)))
                              throw parser_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 parser_design_error("Option Identifiers cannot both be empty.");
    }
 
    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"};
};
 
} // namespace seqan3