argument_parser.hpp

Go to the documentation of this file.

// -----------------------------------------------------------------------------------------------------
// Copyright (c) 2006-2019, Knut Reinert & Freie Universität Berlin
// Copyright (c) 2016-2019, 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 <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/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) :
        version_check_dev_decision{version_check}
    {
        info.app_name = std::move(app_name);
        init(argc, argv);
    }

    ~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 (IStream<std::istringstream, option_type> ||
                  IStream<std::istringstream, typename option_type::value_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
    {
        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 (IStream<std::istringstream, option_type> ||
                  IStream<std::istringstream, typename option_type::value_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
    {
        // 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;
    }


    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 version_check_dev_decision{};

    std::optional<bool> version_check_user_decision;

    std::future<bool> version_check_future;

    void init(int argc, char const * const * const argv)
    {
        // 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;
        }

        for(int i = 1, argv_len = argc; i < argv_len; ++i) // start at 1 to skip binary name
        {
            std::string arg{argv[i]};

            if (arg == "-h" || arg == "--help")
            {
                format = detail::format_help{false};
                init_standard_options();
                return;
            }
            else if (arg == "-hh" || arg == "--advanced-help")
            {
                format = detail::format_help{true};
                init_standard_options();
                return;
            }
            else if (arg == "--version")
            {
                format = detail::format_version{};
                return;
            }
            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{};
                else if (export_format == "man")
                    format = detail::format_man{};
                // 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();
                return;
            }
            else if (arg == "--copyright")
            {
                format = detail::format_copyright{};
                return;
            }
            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));
            }
        }

        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(0)};

    std::set<std::string> used_option_ids{"h", "hh", "help", "advanced-help", "export-help", "version", "copyright"};
};

} // namespace seqan3