185 version_check_dev_decision{version_updates},
195 char const *
const *
const argv,
198 parser{app_name,
std::vector<
std::string>{argv, argv + argc}, version_updates, std::move(subcommands)}
205 if (version_check_future.valid())
238 template <
typename option_type,
typename val
idator_type>
243 check_parse_not_called(
"add_option");
244 verify_option_config(
config);
246 auto operation = [
this, &value,
config]()
248 auto visit_fn = [&value, &
config](
auto & f)
250 f.add_option(value,
config);
256 operations.push_back(std::move(operation));
272 template <
typename val
idator_type>
276 check_parse_not_called(
"add_flag");
277 verify_flag_config(
config);
280 throw design_error(
"A flag's default value must be false.");
282 auto operation = [
this, &value,
config]()
284 auto visit_fn = [&value, &
config](
auto & f)
286 f.add_flag(value,
config);
292 operations.push_back(std::move(operation));
322 template <
typename option_type,
typename val
idator_type>
327 check_parse_not_called(
"add_positional_option");
328 verify_positional_option_config(
config);
330 if constexpr (detail::is_container_option<option_type>)
331 has_positional_list_option =
true;
333 auto operation = [
this, &value,
config]()
335 auto visit_fn = [&value, &
config](
auto & f)
337 f.add_positional_option(value,
config);
343 operations.push_back(std::move(operation));
416 if (parse_was_called)
417 throw design_error(
"The function parse() must only be called once!");
419 parse_was_called =
true;
422 verify_app_and_subcommand_names();
425 determine_format_and_subcommand();
428 for (
auto & operation : operations)
450 if (sub_parser ==
nullptr)
452 throw design_error(
"No subcommand was provided at the construction of the argument parser!");
488 template <
typename id_type>
493 if (!parse_was_called)
494 throw design_error{
"You can only ask which options have been set after calling the function `parse()`."};
498 char_or_string_t short_or_long_id = {
id};
502 if (short_or_long_id.size() == 1)
504 throw design_error{
"Long option identifiers must be longer than one character! If " + short_or_long_id
505 +
"' was meant to be a short identifier, please pass it as a char ('') not a string"
511 throw design_error{
"You can only ask for option identifiers that you added with add_option() before."};
514 auto option_end =
std::find(format_arguments.begin(), format_arguments.end(), option_end_identifier);
515 auto option_it = detail::format_parse::find_option_id(format_arguments.begin(), option_end, short_or_long_id);
516 return option_it != option_end;
534 check_parse_not_called(
"add_section");
536 auto operation = [
this, title, advanced_only]()
538 auto visit_fn = [&title, advanced_only](
auto & f)
540 f.add_section(title, advanced_only);
546 operations.push_back(std::move(operation));
561 check_parse_not_called(
"add_subsection");
563 auto operation = [
this, title, advanced_only]()
565 auto visit_fn = [&title, advanced_only](
auto & f)
567 f.add_subsection(title, advanced_only);
573 operations.push_back(std::move(operation));
589 check_parse_not_called(
"add_line");
591 auto operation = [
this, text, is_paragraph, advanced_only]()
593 auto visit_fn = [&text, is_paragraph, advanced_only](
auto & f)
595 f.add_line(text, is_paragraph, advanced_only);
601 operations.push_back(std::move(operation));
626 check_parse_not_called(
"add_list_item");
628 auto operation = [
this, key, desc, advanced_only]()
630 auto visit_fn = [&key, &desc, advanced_only](
auto & f)
632 f.add_list_item(key, desc, advanced_only);
638 operations.push_back(std::move(operation));
654 auto & parser_subcommands = this->subcommands;
655 parser_subcommands.
insert(parser_subcommands.end(), subcommands.
cbegin(), subcommands.
cend());
659 parser_subcommands.erase(first, last);
717 bool parse_was_called{
false};
720 bool has_positional_list_option{
false};
729 friend struct ::sharg::detail::test_accessor;
735 std::regex app_name_regex{
"^[a-zA-Z0-9_-]+$"};
755 detail::format_short_help,
756 detail::format_version,
760 detail::format_copyright>
761 format{detail::format_short_help{}};
808 void determine_format_and_subcommand()
810 assert(!arguments.empty());
812 auto it = arguments.begin();
815 executable_name.emplace_back(arg);
819 auto read_next_arg = [
this, &it, &arg]() ->
bool
821 assert(it != arguments.end());
823 if (++it == arguments.end())
831 auto found_subcommand = [
this, &it, &arg]() ->
bool
833 if (subcommands.empty())
844 sub_parser->executable_name.insert(sub_parser->executable_name.begin(),
845 executable_name.begin(),
846 executable_name.end());
854 if (!arg.starts_with(
'-'))
856 std::string message =
"You specified an unknown subcommand! Available subcommands are: [";
858 message += command +
", ";
859 message.
replace(message.
size() - 2, 2,
"]. Use -h/--help for more information.");
861 throw user_input_error{message};
869 for (; read_next_arg();)
875 format_arguments.emplace_back(arg);
880 format_arguments.emplace_back(arg);
890 if (found_subcommand())
893 if (arg ==
"-h" || arg ==
"--help")
895 format = detail::format_help{subcommands, version_check_dev_decision,
false};
897 else if (arg ==
"-hh" || arg ==
"--advanced-help")
899 format = detail::format_help{subcommands, version_check_dev_decision,
true};
901 else if (arg ==
"--version")
903 format = detail::format_version{};
905 else if (arg ==
"--copyright")
907 format = detail::format_copyright{};
909 else if (arg ==
"--export-help" || arg.starts_with(
"--export-help="))
916 if (!read_next_arg())
917 throw too_few_arguments{
"Option --export-help must be followed by a value."};
921 arg.remove_prefix(1u);
925 format = detail::format_html{subcommands, version_check_dev_decision};
926 else if (arg ==
"man")
927 format = detail::format_man{subcommands, version_check_dev_decision};
928 else if (arg ==
"ctd")
929 format = detail::format_tdl{detail::format_tdl::FileFormat::CTD};
930 else if (arg ==
"cwl")
931 format = detail::format_tdl{detail::format_tdl::FileFormat::CWL};
933 throw validation_error{
"Validation failed for option --export-help: "
934 "Value must be one of "
935 + detail::supported_exports +
"."};
937 else if (arg ==
"--version-check")
939 if (!read_next_arg())
940 throw too_few_arguments{
"Option --version-check must be followed by a value."};
942 if (arg ==
"1" || arg ==
"true")
943 version_check_user_decision =
true;
944 else if (arg ==
"0" || arg ==
"false")
945 version_check_user_decision =
false;
947 throw validation_error{
"Value for option --version-check must be true (1) or false (0)."};
952 format_arguments.emplace_back(arg);
962 if (!format_arguments.empty() || sub_parser)
963 format = detail::format_parse(format_arguments);
971 template <
typename id_type>
972 bool id_exists(id_type
const &
id)
974 if (detail::format_parse::is_empty_id(
id))
976 return (!(used_ids.insert(
std::string({id}))).second);
988 void verify_identifiers(
char const short_id,
std::string const & long_id)
990 auto is_valid = [](
char const c) ->
bool
992 return (c >=
'a' && c <=
'z') || (c >=
'A' && c <=
'Z') || (c >=
'0' && c <=
'9')
993 || c ==
'@' || c ==
'_' || c ==
'-';
996 if (short_id ==
'\0' && long_id.
empty())
997 throw design_error{
"Short and long identifiers may not both be empty."};
999 if (short_id !=
'\0')
1001 if (short_id ==
'-' || !is_valid(short_id))
1002 throw design_error{
"Short identifiers may only contain alphanumeric characters, '_', or '@'."};
1003 if (id_exists(short_id))
1004 throw design_error{
"Short identifier '" +
std::string(1, short_id) +
"' was already used before."};
1007 if (!long_id.
empty())
1009 if (long_id.
size() == 1)
1010 throw design_error{
"Long identifiers must be either empty or longer than one character."};
1011 if (long_id[0] ==
'-')
1012 throw design_error{
"Long identifiers may not use '-' as first character."};
1014 throw design_error{
"Long identifiers may only contain alphanumeric characters, '_', '-', or '@'."};
1015 if (id_exists(long_id))
1016 throw design_error{
"Long identifier '" + long_id +
"' was already used before."};
1021 template <
typename val
idator_t>
1022 void verify_option_config(config<validator_t>
const & config)
1024 verify_identifiers(config.short_id, config.long_id);
1026 if (config.short_id !=
'\0')
1027 options.emplace(
std::string{
"-"} + config.short_id);
1028 if (!config.long_id.empty())
1029 options.emplace(
std::string{
"--"} + config.long_id);
1031 if (config.required && !config.default_message.empty())
1032 throw design_error{
"A required option cannot have a default message."};
1036 template <
typename val
idator_t>
1037 void verify_flag_config(config<validator_t>
const & config)
1039 verify_identifiers(config.short_id, config.long_id);
1041 if (!config.default_message.empty())
1042 throw design_error{
"A flag may not have a default message because the default is always `false`."};
1046 template <
typename val
idator_t>
1047 void verify_positional_option_config(config<validator_t>
const & config)
const
1049 if (config.short_id !=
'\0' || config.long_id !=
"")
1050 throw design_error{
"Positional options are identified by their position on the command line. "
1051 "Short or long ids are not permitted!"};
1053 if (config.advanced || config.hidden)
1054 throw design_error{
"Positional options are always required and therefore cannot be advanced nor hidden!"};
1056 if (!subcommands.empty())
1057 throw design_error{
"You may only specify flags and options for the top-level parser."};
1059 if (has_positional_list_option)
1060 throw design_error{
"You added a positional option with a list value before so you cannot add "
1061 "any other positional options."};
1063 if (!config.default_message.empty())
1064 throw design_error{
"A positional option may not have a default message because it is always required."};
1076 inline void check_parse_not_called(
std::string_view const function_name)
const
1078 if (parse_was_called)
1079 throw design_error{detail::to_string(function_name.
data(),
" may only be used before calling parse().")};
1089 inline void verify_app_and_subcommand_names()
const
1095 throw design_error{(
"The application name must only contain alpha-numeric characters or '_' and '-' "
1096 "(regex: \"^[a-zA-Z0-9_-]+$\").")};
1099 for (
auto & sub : this->subcommands)
1103 throw design_error{
"The subcommand name must only contain alpha-numeric characters or '_' and '-' "
1104 "(regex: \"^[a-zA-Z0-9_-]+$\")."};
1114 inline void run_version_check()
1118 if (app_version.decide_if_check_is_performed(version_check_dev_decision, version_check_user_decision))
1122 version_check_future = app_version_prom.
get_future();
1123 app_version(std::move(app_version_prom));
1137 inline void parse_format()
1139 auto format_parse_fn = [
this]<
typename format_t>(format_t & f)
1142 f.parse(info, executable_name);
1147 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:241
void add_flag(bool &value, config< validator_type > const &config)
Adds a flag to the sharg::parser.
Definition parser.hpp:274
void add_subsection(std::string const &title, bool const advanced_only=false)
Adds an help page subsection to the sharg::parser.
Definition parser.hpp:559
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:490
void add_subcommands(std::vector< std::string > const &subcommands)
Adds subcommands to the parser.
Definition parser.hpp:652
void add_positional_option(option_type &value, config< validator_type > const &config)
Adds a positional option to the sharg::parser.
Definition parser.hpp:325
parser_meta_data info
Aggregates all parser related meta data (see sharg::parser_meta_data struct).
Definition parser.hpp:713
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:181
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:193
parser(parser &&)=default
Defaulted.
void parse()
Initiates the actual command line parsing.
Definition parser.hpp:414
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:624
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:532
~parser()
The destructor.
Definition parser.hpp:202
parser & get_sub_parser()
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
Definition parser.hpp:448
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:587
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.