174 char const *
const *
const argv,
177 version_check_dev_decision{version_updates},
178 subcommands{
std::move(subcommands)}
182 throw design_error{(
"The application name must only contain alpha-numeric characters or '_' and '-' "
183 "(regex: \"^[a-zA-Z0-9_-]+$\").")};
186 for (
auto & sub : this->subcommands)
190 throw design_error{
"The subcommand name must only contain alpha-numeric characters or '_' and '-' "
191 "(regex: \"^[a-zA-Z0-9_-]+$\")."};
204 if (version_check_future.
valid())
232 template <
typename option_type, val
idator val
idator_type = detail::default_val
idator<option_type>>
235 && std::invocable<validator_type, option_type>
241 validator_type option_validator = validator_type{})
243 if (sub_parser !=
nullptr)
244 throw design_error{
"You may only specify flags for the top-level parser."};
246 verify_identifiers(short_id, long_id);
250 [=, &value](
auto & f)
252 f.add_option(value, short_id, long_id, desc, spec, option_validator);
275 throw design_error(
"A flag's default value must be false.");
277 verify_identifiers(short_id, long_id);
281 [=, &value](
auto & f)
283 f.add_flag(value, short_id, long_id, desc, spec);
308 template <
typename option_type, val
idator val
idator_type = detail::default_val
idator<option_type>>
311 && std::invocable<validator_type, option_type>
314 validator_type option_validator = validator_type{})
316 if (sub_parser !=
nullptr)
317 throw design_error{
"You may only specify flags for the top-level parser."};
319 if (has_positional_list_option)
320 throw design_error{
"You added a positional option with a list value before so you cannot add "
321 "any other positional options."};
323 if constexpr (detail::is_container_option<option_type>)
324 has_positional_list_option =
true;
329 [=, &value](
auto & f)
331 f.add_positional_option(value, desc, option_validator);
404 if (parse_was_called)
405 throw design_error(
"The function parse() must only be called once!");
409 if (std::holds_alternative<detail::format_parse>(format) && !subcommands.
empty() && sub_parser ==
nullptr)
411 throw too_few_arguments{detail::to_string(
"You either forgot or misspelled the subcommand! Please specify"
412 " which sub-program you want to use: one of ",
414 ". Use -h/--help for more information.")};
417 if (app_version.decide_if_check_is_performed(version_check_dev_decision, version_check_user_decision))
421 version_check_future = app_version_prom.
get_future();
422 app_version(std::move(app_version_prom));
431 parse_was_called =
true;
438 if (sub_parser ==
nullptr)
440 throw design_error(
"No subcommand was provided at the construction of the argument parser!");
472 template <
typename id_type>
473 requires std::same_as<id_type, char> || std::constructible_from<std::string, id_type>
476 if (!parse_was_called)
477 throw design_error{
"You can only ask which options have been set after calling the function `parse()`."};
481 char_or_string_t short_or_long_id = {
id};
483 if constexpr (!std::same_as<id_type, char>)
485 if (short_or_long_id.size() == 1)
487 throw design_error{
"Long option identifiers must be longer than one character! If " + short_or_long_id
488 +
"' was meant to be a short identifier, please pass it as a char ('') not a string"
494 throw design_error{
"You can only ask for option identifiers that you added with add_option() before."};
497 auto end_of_options =
std::find(cmd_arguments.
begin(), cmd_arguments.
end(), end_of_options_indentifier);
498 auto option_it = detail::format_parse::find_option_id(cmd_arguments.
begin(), end_of_options, short_or_long_id);
499 return option_it != end_of_options;
516 f.add_section(title, spec);
532 f.add_subsection(title, spec);
551 f.add_line(text, is_paragraph, spec);
580 f.add_list_item(key, desc, spec);
638 bool parse_was_called{
false};
641 bool has_positional_list_option{
false};
650 friend struct ::seqan3::detail::test_accessor;
656 std::regex app_name_regex{
"^[a-zA-Z0-9_-]+$"};
676 detail::format_short_help,
677 detail::format_version,
680 detail::format_copyright
681> format{detail::format_help{{},
false}};
684 std::set<std::string> used_option_ids{
"h",
"hh",
"help",
"advanced-help",
"export-help",
"version",
"copyright"};
721 void init(
int argc,
char const *
const *
const argv)
725 format = detail::format_short_help{};
729 bool special_format_was_set{
false};
731 for (
int i = 1, argv_len = argc; i < argv_len; ++i)
737 sub_parser = std::make_unique<argument_parser>(
info.
app_name +
"-" + arg,
744 if (arg ==
"-h" || arg ==
"--help")
746 format = detail::format_help{subcommands,
false};
747 init_standard_options();
748 special_format_was_set =
true;
750 else if (arg ==
"-hh" || arg ==
"--advanced-help")
752 format = detail::format_help{subcommands,
true};
753 init_standard_options();
754 special_format_was_set =
true;
756 else if (arg ==
"--version")
758 format = detail::format_version{};
759 special_format_was_set =
true;
761 else if (arg.substr(0, 13) ==
"--export-help")
767 export_format = arg.
substr(14);
771 if (argv_len <= i + 1)
772 throw too_few_arguments{
"Option --export-help must be followed by a value."};
773 export_format = argv[i + 1];
776 if (export_format ==
"html")
777 format = detail::format_html{subcommands};
778 else if (export_format ==
"man")
779 format = detail::format_man{subcommands};
784 throw validation_error{
"Validation failed for option --export-help: "
785 "Value must be one of [html, man]"};
786 init_standard_options();
787 special_format_was_set =
true;
789 else if (arg ==
"--copyright")
791 format = detail::format_copyright{};
792 special_format_was_set =
true;
794 else if (arg ==
"--version-check")
797 throw too_few_arguments{
"Option --version-check must be followed by a value."};
801 if (arg ==
"1" || arg ==
"true")
802 version_check_user_decision =
true;
803 else if (arg ==
"0" || arg ==
"false")
804 version_check_user_decision =
false;
806 throw validation_error{
"Value for option --version-check must be true (1) or false (0)."};
817 if (!special_format_was_set)
818 format = detail::format_parse(argc, cmd_arguments);
822 void init_standard_options()
825 add_list_item(
"\fB-h\fP, \fB--help\fP",
"Prints the help page.");
826 add_list_item(
"\fB-hh\fP, \fB--advanced-help\fP",
"Prints the help page including advanced options.");
827 add_list_item(
"\fB--version\fP",
"Prints the version information.");
828 add_list_item(
"\fB--copyright\fP",
"Prints the copyright/license information.");
830 "Export the help page information. Value must be one of [html, man].");
833 "Whether to check for the newest app version. Default: true.");
841 template <
typename id_type>
842 bool id_exists(id_type
const &
id)
844 if (detail::format_parse::is_empty_id(
id))
858 void verify_identifiers(
char const short_id,
std::string const & long_id)
862 if (id_exists(short_id))
863 throw design_error(
"Option Identifier '" +
std::string(1, short_id) +
"' was already used before.");
864 if (id_exists(long_id))
865 throw design_error(
"Option Identifier '" + long_id +
"' was already used before.");
866 if (long_id.
length() == 1)
867 throw design_error(
"Long IDs must be either empty, or longer than one character.");
868 if (!allowed(short_id) && !
is_char<
'\0'>(short_id))
869 throw design_error(
"Option identifiers may only contain alphanumeric characters, '_', or '@'.");
870 if (long_id.
size() > 0 &&
is_char<
'-'>(long_id[0]))
871 throw design_error(
"First character of long ID cannot be '-'.");
877 if (!(allowed(c) || is_char<
'-'>(c)))
879 "Long identifiers may only contain alphanumeric characters, '_', '-', or '@'.");
881 if (detail::format_parse::is_empty_id(short_id) && detail::format_parse::is_empty_id(long_id))
882 throw design_error(
"Option Identifiers cannot both be empty.");
The SeqAn command line parser.
Definition argument_parser.hpp:145
void add_positional_option(option_type &value, std::string const &desc, validator_type option_validator=validator_type{})
Adds a positional option to the seqan3::argument_parser.
Definition argument_parser.hpp:312
void add_flag(bool &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const spec=option_spec::standard)
Adds a flag to the seqan3::argument_parser.
Definition argument_parser.hpp:268
bool is_option_set(id_type const &id) const
Checks whether the option identifier (id) was set on the command line by the user.
Definition argument_parser.hpp:474
argument_parser(argument_parser const &)=delete
Deleted. Holds std::future.
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::standard, validator_type option_validator=validator_type{})
Adds an option to the seqan3::argument_parser.
Definition argument_parser.hpp:236
argument_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={})
Initializes an seqan3::argument_parser object from the command line arguments.
Definition argument_parser.hpp:172
argument_parser & operator=(argument_parser &&)=default
Defaulted.
~argument_parser()
The destructor.
Definition argument_parser.hpp:201
argument_parser & operator=(argument_parser const &)=delete
Deleted. Holds std::future.
argument_parser_meta_data info
Aggregates all parser related meta data (see seqan3::argument_parser_meta_data struct).
Definition argument_parser.hpp:634
argument_parser(argument_parser &&)=default
Defaulted.
void parse()
Initiates the actual command line parsing.
Definition argument_parser.hpp:402
argument_parser()=delete
Deleted.
void add_line(std::string const &text, bool is_paragraph=false, option_spec const spec=option_spec::standard)
Adds an help page text line to the seqan3::argument_parser.
Definition argument_parser.hpp:546
void add_list_item(std::string const &key, std::string const &desc, option_spec const spec=option_spec::standard)
Adds an help page list item (key-value) to the seqan3::argument_parser.
Definition argument_parser.hpp:575
void add_section(std::string const &title, option_spec const spec=option_spec::standard)
Adds an help page section to the seqan3::argument_parser.
Definition argument_parser.hpp:511
void add_subsection(std::string const &title, option_spec const spec=option_spec::standard)
Adds an help page subsection to the seqan3::argument_parser.
Definition argument_parser.hpp:527
argument_parser & get_sub_parser()
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
Definition argument_parser.hpp:436
Argument parser exception that is thrown whenever there is an design error directed at the developer ...
Definition exceptions.hpp:148
Argument parser exception thrown when too few arguments are provided.
Definition exceptions.hpp:76
option_spec
Used to further specify argument_parser options/flags.
Definition auxiliary.hpp:247
@ standard
The default were no checking or special displaying is happening.
Definition auxiliary.hpp:248
constexpr auto is_alnum
Checks whether c is a alphanumeric character.
Definition predicate.hpp:194
constexpr auto is_char
Checks whether a given letter is the same as the template non-type argument.
Definition predicate.hpp:60
Checks whether the the type can be used in an add_(positional_)option call on the argument parser.
The main SeqAn3 namespace.
Definition aligned_sequence_concept.hpp:26
update_notifications
Indicates whether application allows automatic update notifications by the seqan3::argument_parser.
Definition auxiliary.hpp:266
@ off
Automatic update notifications should be disabled.
@ on
Automatic update notifications should be enabled.
SeqAn specific customisations in the standard namespace.
Checks if program is run interactively and retrieves dimensions of terminal (Transferred from seqan2)...
Forward declares seqan3::detail::test_accessor.
Auxiliary for pretty printing of exception messages.
Provides the version check functionality.