187 version_check_dev_decision{version_updates},
188 subcommands{
std::move(subcommands)},
197 char const *
const *
const argv,
200 parser{app_name,
std::vector<
std::string>{argv, argv + argc}, version_updates, std::move(subcommands)}
207 if (version_check_future.valid())
240 template <
typename option_type,
typename val
idator_type>
245 check_parse_not_called(
"add_option");
246 verify_option_config(
config);
248 auto operation = [
this, &value,
config]()
250 auto visit_fn = [&value, &
config](
auto & f)
252 f.add_option(value,
config);
258 operations.push_back(std::move(operation));
274 template <
typename val
idator_type>
278 check_parse_not_called(
"add_flag");
279 verify_flag_config(
config);
282 throw design_error(
"A flag's default value must be false.");
284 auto operation = [
this, &value,
config]()
286 auto visit_fn = [&value, &
config](
auto & f)
288 f.add_flag(value,
config);
294 operations.push_back(std::move(operation));
324 template <
typename option_type,
typename val
idator_type>
329 check_parse_not_called(
"add_positional_option");
330 verify_positional_option_config(
config);
332 if constexpr (detail::is_container_option<option_type>)
333 has_positional_list_option =
true;
335 auto operation = [
this, &value,
config]()
337 auto visit_fn = [&value, &
config](
auto & f)
339 f.add_positional_option(value,
config);
345 operations.push_back(std::move(operation));
418 if (parse_was_called)
419 throw design_error(
"The function parse() must only be called once!");
421 parse_was_called =
true;
424 verify_app_and_subcommand_names();
427 determine_format_and_subcommand();
430 for (
auto & operation : operations)
452 if (sub_parser ==
nullptr)
454 throw design_error(
"No subcommand was provided at the construction of the argument parser!");
490 template <
typename id_type>
495 if (!parse_was_called)
496 throw design_error{
"You can only ask which options have been set after calling the function `parse()`."};
500 char_or_string_t short_or_long_id = {
id};
504 if (short_or_long_id.size() == 1)
506 throw design_error{
"Long option identifiers must be longer than one character! If " + short_or_long_id
507 +
"' was meant to be a short identifier, please pass it as a char ('') not a string"
513 throw design_error{
"You can only ask for option identifiers that you added with add_option() before."};
516 auto option_end =
std::find(format_arguments.begin(), format_arguments.end(), option_end_identifier);
517 auto option_it = detail::format_parse::find_option_id(format_arguments.begin(), option_end, short_or_long_id);
518 return option_it != option_end;
536 check_parse_not_called(
"add_section");
538 auto operation = [
this, title, advanced_only]()
540 auto visit_fn = [&title, advanced_only](
auto & f)
542 f.add_section(title, advanced_only);
548 operations.push_back(std::move(operation));
563 check_parse_not_called(
"add_subsection");
565 auto operation = [
this, title, advanced_only]()
567 auto visit_fn = [&title, advanced_only](
auto & f)
569 f.add_subsection(title, advanced_only);
575 operations.push_back(std::move(operation));
591 check_parse_not_called(
"add_line");
593 auto operation = [
this, text, is_paragraph, advanced_only]()
595 auto visit_fn = [&text, is_paragraph, advanced_only](
auto & f)
597 f.add_line(text, is_paragraph, advanced_only);
603 operations.push_back(std::move(operation));
628 check_parse_not_called(
"add_list_item");
630 auto operation = [
this, key, desc, advanced_only]()
632 auto visit_fn = [&key, &desc, advanced_only](
auto & f)
634 f.add_list_item(key, desc, advanced_only);
640 operations.push_back(std::move(operation));
698 bool parse_was_called{
false};
701 bool has_positional_list_option{
false};
710 friend struct ::sharg::detail::test_accessor;
716 std::regex app_name_regex{
"^[a-zA-Z0-9_-]+$"};
736 detail::format_short_help,
737 detail::format_version,
741 detail::format_copyright>
742 format{detail::format_short_help{}};
789 void determine_format_and_subcommand()
791 assert(!arguments.empty());
793 auto it = arguments.begin();
796 executable_name.emplace_back(arg);
800 auto read_next_arg = [
this, &it, &arg]() ->
bool
802 assert(it != arguments.end());
804 if (++it == arguments.end())
812 auto found_subcommand = [
this, &it, &arg]() ->
bool
814 if (subcommands.empty())
825 sub_parser->executable_name.insert(sub_parser->executable_name.begin(),
826 executable_name.begin(),
827 executable_name.end());
835 if (!arg.starts_with(
'-'))
837 std::string message =
"You specified an unknown subcommand! Available subcommands are: [";
839 message += command +
", ";
840 message.
replace(message.
size() - 2, 2,
"]. Use -h/--help for more information.");
842 throw user_input_error{message};
850 for (; read_next_arg();)
856 format_arguments.emplace_back(arg);
861 format_arguments.emplace_back(arg);
871 if (found_subcommand())
874 if (arg ==
"-h" || arg ==
"--help")
876 format = detail::format_help{subcommands, version_check_dev_decision,
false};
878 else if (arg ==
"-hh" || arg ==
"--advanced-help")
880 format = detail::format_help{subcommands, version_check_dev_decision,
true};
882 else if (arg ==
"--version")
884 format = detail::format_version{};
886 else if (arg ==
"--copyright")
888 format = detail::format_copyright{};
890 else if (arg ==
"--export-help" || arg.starts_with(
"--export-help="))
897 if (!read_next_arg())
898 throw too_few_arguments{
"Option --export-help must be followed by a value."};
902 arg.remove_prefix(1u);
906 format = detail::format_html{subcommands, version_check_dev_decision};
907 else if (arg ==
"man")
908 format = detail::format_man{subcommands, version_check_dev_decision};
909 else if (arg ==
"ctd")
910 format = detail::format_tdl{detail::format_tdl::FileFormat::CTD};
911 else if (arg ==
"cwl")
912 format = detail::format_tdl{detail::format_tdl::FileFormat::CWL};
914 throw validation_error{
"Validation failed for option --export-help: "
915 "Value must be one of "
916 + detail::supported_exports +
"."};
918 else if (arg ==
"--version-check")
920 if (!read_next_arg())
921 throw too_few_arguments{
"Option --version-check must be followed by a value."};
923 if (arg ==
"1" || arg ==
"true")
924 version_check_user_decision =
true;
925 else if (arg ==
"0" || arg ==
"false")
926 version_check_user_decision =
false;
928 throw validation_error{
"Value for option --version-check must be true (1) or false (0)."};
933 format_arguments.emplace_back(arg);
943 if (!format_arguments.empty() || sub_parser)
944 format = detail::format_parse(format_arguments);
952 template <
typename id_type>
953 bool id_exists(id_type
const &
id)
955 if (detail::format_parse::is_empty_id(
id))
957 return (!(used_ids.insert(
std::string({id}))).second);
969 void verify_identifiers(
char const short_id,
std::string const & long_id)
971 auto is_valid = [](
char const c) ->
bool
973 return (c >=
'a' && c <=
'z') || (c >=
'A' && c <=
'Z') || (c >=
'0' && c <=
'9')
974 || c ==
'@' || c ==
'_' || c ==
'-';
977 if (short_id ==
'\0' && long_id.
empty())
978 throw design_error{
"Short and long identifiers may not both be empty."};
980 if (short_id !=
'\0')
982 if (short_id ==
'-' || !is_valid(short_id))
983 throw design_error{
"Short identifiers may only contain alphanumeric characters, '_', or '@'."};
984 if (id_exists(short_id))
985 throw design_error{
"Short identifier '" +
std::string(1, short_id) +
"' was already used before."};
988 if (!long_id.
empty())
990 if (long_id.
size() == 1)
991 throw design_error{
"Long identifiers must be either empty or longer than one character."};
992 if (long_id[0] ==
'-')
993 throw design_error{
"Long identifiers may not use '-' as first character."};
995 throw design_error{
"Long identifiers may only contain alphanumeric characters, '_', '-', or '@'."};
996 if (id_exists(long_id))
997 throw design_error{
"Long identifier '" + long_id +
"' was already used before."};
1002 template <
typename val
idator_t>
1003 void verify_option_config(config<validator_t>
const & config)
1005 verify_identifiers(config.short_id, config.long_id);
1007 if (config.short_id !=
'\0')
1008 options.emplace(
std::string{
"-"} + config.short_id);
1009 if (!config.long_id.empty())
1010 options.emplace(
std::string{
"--"} + config.long_id);
1012 if (config.required && !config.default_message.empty())
1013 throw design_error{
"A required option cannot have a default message."};
1017 template <
typename val
idator_t>
1018 void verify_flag_config(config<validator_t>
const & config)
1020 verify_identifiers(config.short_id, config.long_id);
1022 if (!config.default_message.empty())
1023 throw design_error{
"A flag may not have a default message because the default is always `false`."};
1027 template <
typename val
idator_t>
1028 void verify_positional_option_config(config<validator_t>
const & config)
const
1030 if (config.short_id !=
'\0' || config.long_id !=
"")
1031 throw design_error{
"Positional options are identified by their position on the command line. "
1032 "Short or long ids are not permitted!"};
1034 if (config.advanced || config.hidden)
1035 throw design_error{
"Positional options are always required and therefore cannot be advanced nor hidden!"};
1037 if (!subcommands.empty())
1038 throw design_error{
"You may only specify flags and options for the top-level parser."};
1040 if (has_positional_list_option)
1041 throw design_error{
"You added a positional option with a list value before so you cannot add "
1042 "any other positional options."};
1044 if (!config.default_message.empty())
1045 throw design_error{
"A positional option may not have a default message because it is always required."};
1057 inline void check_parse_not_called(
std::string_view const function_name)
const
1059 if (parse_was_called)
1060 throw design_error{detail::to_string(function_name.
data(),
" may only be used before calling parse().")};
1070 inline void verify_app_and_subcommand_names()
const
1076 throw design_error{(
"The application name must only contain alpha-numeric characters or '_' and '-' "
1077 "(regex: \"^[a-zA-Z0-9_-]+$\").")};
1080 for (
auto & sub : this->subcommands)
1084 throw design_error{
"The subcommand name must only contain alpha-numeric characters or '_' and '-' "
1085 "(regex: \"^[a-zA-Z0-9_-]+$\")."};
1095 inline void run_version_check()
1099 if (app_version.decide_if_check_is_performed(version_check_dev_decision, version_check_user_decision))
1103 version_check_future = app_version_prom.
get_future();
1104 app_version(std::move(app_version_prom));
1118 inline void parse_format()
1120 auto format_parse_fn = [
this]<
typename format_t>(format_t & f)
1123 f.parse(info, executable_name);
1128 std::visit(std::move(format_parse_fn), format);
Parser exception that is thrown whenever there is an design error directed at the developer of the ap...
Definition exceptions.hpp:207
The Sharg command line parser.
Definition parser.hpp:154
void add_option(option_type &value, config< validator_type > const &config)
Adds an option to the sharg::parser.
Definition parser.hpp:243
void add_flag(bool &value, config< validator_type > const &config)
Adds a flag to the sharg::parser.
Definition parser.hpp:276
void add_subsection(std::string const &title, bool const advanced_only=false)
Adds an help page subsection to the sharg::parser.
Definition parser.hpp:561
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 parser.hpp:492
void add_positional_option(option_type &value, config< validator_type > const &config)
Adds a positional option to the sharg::parser.
Definition parser.hpp:327
parser_meta_data info
Aggregates all parser related meta data (see sharg::parser_meta_data struct).
Definition parser.hpp:694
parser(std::string const &app_name, std::vector< std::string > const &arguments, update_notifications version_updates=update_notifications::on, std::vector< std::string > subcommands={})
Initializes an sharg::parser object from the command line arguments.
Definition parser.hpp:183
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={})
This is an overloaded member function, provided for convenience. It differs from the above function o...
Definition parser.hpp:195
parser(parser &&)=default
Defaulted.
void parse()
Initiates the actual command line parsing.
Definition parser.hpp:416
parser & operator=(parser const &)=delete
Deleted.
parser(parser const &)=delete
Deleted.
void add_list_item(std::string const &key, std::string const &desc, bool const advanced_only=false)
Adds an help page list item (key-value) to the sharg::parser.
Definition parser.hpp:626
parser & operator=(parser &&)=default
Defaulted.
void add_section(std::string const &title, bool const advanced_only=false)
Adds an help page section to the sharg::parser.
Definition parser.hpp:534
~parser()
The destructor.
Definition parser.hpp:204
parser & get_sub_parser()
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
Definition parser.hpp:450
void add_line(std::string const &text, bool is_paragraph=false, bool const advanced_only=false)
Adds an help page text line to the sharg::parser.
Definition parser.hpp:589
Checks whether the the type can be used in an add_(positional_)option call on the parser.
Definition concept.hpp:91
Provides sharg::config class.
update_notifications
Indicates whether application allows automatic update notifications by the sharg::parser.
Definition auxiliary.hpp:26
@ off
Automatic update notifications should be disabled.
@ on
Automatic update notifications should be enabled.
Option struct that is passed to the sharg::parser::add_option() function.
Definition config.hpp:43
Provides the version check functionality.