This document provides example recipes on how to carry out particular tasks using the Sharg functionalities in C++. Please note that these recipes are not ordered. You can use the links in the table of contents or the search function of your browser to navigate them.
It will take some time, but we hope to expand this document into containing numerous great examples. If you have suggestions for how to improve the Cookbook and/or examples you would like included, please feel free to contact us.
Constructing a basic parser
{
std::cerr <<
"reference_file_path: " << reference_path <<
'\n';
std::cerr <<
"index_path " << index_path <<
'\n';
}
struct cmd_arguments
{
};
void initialise_parser(
sharg::parser & parser, cmd_arguments & args)
{
.long_id = "reference",
.description = "The path to the reference.",
.required = true,
.validator = sharg::input_file_validator{{"fa", "fasta"}}});
args.index_path,
.long_id = "output",
.description = "The output index file path.",
.validator =
sharg::output_file_validator{sharg::output_file_open_options::create_new, {"index"}}});
}
int main(int argc, char const ** argv)
{
cmd_arguments args{};
initialise_parser(parser, args);
try
{
parser.parse();
}
{
return -1;
}
run_program(args.reference_path, args.index_path);
return 0;
}
Meta-header for the Parser module .
Parser exception that is thrown whenever there is an error while parsing the command line arguments.
Definition exceptions.hpp:40
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
parser_meta_data info
Aggregates all parser related meta data (see sharg::parser_meta_data struct).
Definition parser.hpp:713
Option struct that is passed to the sharg::parser::add_option() function.
Definition config.hpp:43
Constructing a subcommand parser
struct pull_arguments
{
bool progress{false};
};
{
pull_arguments args{};
try
{
}
{
return -1;
}
std::cerr <<
"Git pull with repository " << args.repository <<
" and branch " << args.branch <<
'\n';
return 0;
}
struct push_arguments
{
bool push_all{false};
};
{
push_arguments args{};
try
{
}
{
return -1;
}
std::cerr <<
"Git push with repository " << args.repository <<
" and branches ";
for (auto && branch : args.branches)
std::cerr << branch <<
' ';
return 0;
}
int main(int argc, char const ** argv)
{
bool flag{false};
top_level_parser.add_flag(flag,
sharg::config{.
short_id =
'f', .long_id =
"flag", .description =
"some flag"});
try
{
top_level_parser.parse();
}
{
return -1;
}
return run_git_pull(sub_parser);
return run_git_push(sub_parser);
else
return 0;
}
void add_positional_option(option_type &value, config< validator_type > const &config)
Adds a positional option to the sharg::parser.
Definition parser.hpp:325
void parse()
Initiates the actual command line parsing.
Definition parser.hpp:414
parser & get_sub_parser()
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
Definition parser.hpp:448
@ on
Automatic update notifications should be enabled.
char short_id
The short identifier for the option (e.g. 'a', making the option callable via -a).
Definition config.hpp:53
Write a custom validator
This recipe implements a validator that checks whether a numeric argument is an integral square (i.e. 0, 1, 4, 9...). Invalid values throw a sharg::validation_error.
struct custom_validator
{
using option_value_type = double;
void operator()(option_value_type const & val) const
{
{
}
}
{
return "Value must be the square of an integral number.";
}
};
All Sharg documentation snippets
The following lists all snippets that appear in our documentation. Search for keywords with Strg + F.
{
git_parser.add_subcommands({"remote"});
git_parser.parse();
{
auto & pull_parser = sub_parser;
pull_parser.parse();
}
{
auto & push_parser = sub_parser;
push_parser.parse();
}
{
auto & remote_parser = sub_parser;
remote_parser.parse();
{
auto & set_url_parser = recursive_sub_parser;
set_url_parser.add_positional_option(repository,
sharg::config{});
set_url_parser.parse();
}
{
auto & show_parser = recursive_sub_parser;
}
}
}
int main(int argc, char ** argv)
{
try
{
run({argv, argv + argc});
}
{
}
return 0;
}
void add_subcommands(std::vector< std::string > const &subcommands)
Adds subcommands to the parser.
Definition parser.hpp:652
@ off
Automatic update notifications should be disabled.
int main(int argc, char const ** argv)
{
}
namespace foo
{
enum class bar
{
one,
two,
three
};
auto enumeration_names(bar)
{
}
}
int main(int argc, char const * argv[])
{
foo::bar value{};
value,
sharg::config{.
short_id =
'f', .long_id =
"foo", .description =
"Give me a value for foo.", .validator = vali});
try
{
}
{
return -1;
}
}
A validator that checks whether a value is inside a list of valid values.
Definition validators.hpp:175
namespace sharg::custom
{
template <>
struct parsing<
std::errc>
{
{"timed_out", std::errc::timed_out},
{"invalid_argument", std::errc::invalid_argument},
{"io_error", std::errc::io_error}};
};
}
int main(int argc, char const * argv[])
{
.long_id = "errc",
.description = "Give me a std::errc value.",
.validator = validator});
try
{
}
{
return -1;
}
return 0;
}
auto const enumeration_names
Return a conversion map from std::string_view to option_type.
Definition enumeration_names.hpp:214
int main(int argc, char ** argv)
{
int a{3};
try
{
myparser.parse();
}
{
return -1;
}
if (myparser.is_option_set('a'))
std::cerr <<
"The user set option -a on the command line.\n";
if (myparser.is_option_set("awesome-parameter"))
std::cerr <<
"The user set option --awesome-parameter on the command line.\n";
return 0;
}
int main(int argc, char ** argv)
{
bool bonus{false};
myparser.add_option(name,
sharg::config{.
short_id =
'n', .long_id =
"name", .description =
"Your name please."});
myparser.add_flag(bonus,
sharg::config{.
short_id =
'b', .long_id =
"bonus", .description =
"Got a bonus?."});
try
{
myparser.parse();
}
{
return -1;
}
if (bonus)
grades.push_back(1.0);
double avg{0};
for (auto g : grades)
avg += g;
avg = avg / grades.size();
std::cerr << name <<
" has an average grade of " << avg <<
'\n';
return 0;
}
std::string description
The description to be shown on any (exported) help page.
Definition config.hpp:68
int main(int argc, char ** argv)
{
int age{30};
try
{
myparser.parse();
}
{
std::cerr <<
"The-Age-App - [PARSER ERROR] " << ext.
what() <<
'\n';
return -1;
}
std::cerr <<
"integer given by user: " << age <<
'\n';
return 0;
}
int main(int argc, char ** argv)
{
myparser.info.date = "12.01.2017";
myparser.info.short_description = "Organize your penguin parade";
myparser.info.description.
push_back(
"First Paragraph.");
myparser.info.description.push_back("Second Paragraph.");
myparser.info.examples.push_back("./penguin_parade Skipper Kowalski Rico Private -d 10 -m 02 -y 2017");
int d{01};
int m{01};
int y{2050};
myparser.add_option(d,
sharg::config{.
short_id =
'd', .long_id =
"day", .description =
"Your preferred day."});
myparser.add_option(m,
sharg::config{.
short_id =
'm', .long_id =
"month", .description =
"Your preferred month."});
myparser.add_option(y,
sharg::config{.
short_id =
'y', .long_id =
"year", .description =
"Your preferred year."});
try
{
myparser.parse();
}
{
return -1;
}
return 0;
}
#define main test
int main(int argc, char ** argv)
{
int val{};
return 0;
}
#undef main
int main()
{
return test(argv.size(), argv.data());
}
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
int main()
{
sharg::detail::safe_filesystem_entry file_guard{my_file};
file_guard.remove();
}
Provides sharg::detail::safe_filesystem_entry.
T temp_directory_path(T... args)
int main(int argc, char const ** argv)
{
int myint;
myparser.add_option(myint,
.long_id = "integer",
.description = "Give me a number.",
.validator = my_validator});
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"integer given by user passed validation: " << myint <<
"\n";
return 0;
}
A validator that checks whether a number is inside a given range.
Definition validators.hpp:79
int main(int argc, char const ** argv)
{
int myint;
myparser.add_option(myint,
.long_id = "integer",
.description = "Give me a number.",
.validator = my_validator});
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"integer given by user passed validation: " << myint <<
"\n";
return 0;
}
int main(int argc, char const ** argv)
{
myparser.add_option(
myfile,
sharg::config{.
short_id =
'f', .long_id =
"file", .description =
"Give me a filename.", .validator = vali});
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"filename given by user passed validation: " << myfile <<
"\n";
return 0;
}
int main(int argc, char const ** argv)
{
myparser.add_option(my_string,
.long_id = "str",
.description = "Give me a string.",
.validator = my_validator});
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"email address given by user passed validation: " << my_string <<
"\n";
return 0;
}
A validator that checks if a matches a regular expression pattern.
Definition validators.hpp:976
int main(int argc, char const ** argv)
{
myparser.add_option(file_name,
.long_id = "file",
.description = "Give me a file name with an absolute path.",
.validator = absolute_path_validator | my_file_ext_validator});
try
{
myparser.parse();
}
{
return -1;
}
std::cout <<
"filename given by user passed validation: " << file_name <<
"\n";
return 0;
}
int main(int argc, char const ** argv)
{
myparser.add_option(mydir,
.long_id = "dir",
.description = "The directory containing the input files.",
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"directory given by user passed validation: " << mydir <<
"\n";
return 0;
}
int main(int argc, char const ** argv)
{
myparser.add_option(myfile,
.long_id = "file",
.description = "The input file containing the sequences.",
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"filename given by user passed validation: " << myfile <<
"\n";
return 0;
}
int main()
{
std::cerr << validator1.get_help_page_message() <<
'\n';
std::cerr << validator2.get_help_page_message() <<
'\n';
return 0;
}
Provides some standard validators for (positional) options.
int main(int argc, char const ** argv)
{
myparser.add_option(mydir,
.long_id = "dir",
.description = "The output directory for storing the files.",
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"directory given by user passed validation: " << mydir <<
"\n";
return 0;
}
A validator that checks if a given path is a valid output directory.
Definition validators.hpp:878
int main(int argc, char const ** argv)
{
myparser.add_option(
myfile,
.long_id = "file",
.description = "Output file containing the processed sequences.",
{"fa", "fasta"}}});
myparser.add_option(myfile,
.long_id = "file2",
.description = "Output file containing the processed sequences.",
try
{
myparser.parse();
}
{
return -1;
}
std::cerr <<
"filename given by user passed validation: " << myfile <<
"\n";
return 0;
}
A validator that checks if a given path is a valid output file.
Definition validators.hpp:640
int main()
{
std::cerr << validator1.get_help_page_message() <<
'\n';
std::cerr << validator2.get_help_page_message() <<
'\n';
std::cerr << validator3.get_help_page_message() <<
'\n';
std::cerr << validator4.get_help_page_message() <<
'\n';
return 0;
}
1.10.0