This HowTo shows you how to write an argument parser with subcommand like git push
using SeqAn.
Motivation
A common use case for command line tools, e.g. git
, is to have multiple subcommands, e.g. git fetch
or git push
. Each subcommand has its own set of options and its own help page. This HowTo explains how this can be done with the seqan3::argument_parser and serves as a copy'n'paste source. If you are new to SeqAn, we recommend to do the basic argument parser tutorial before you read further.
A subcommand argument parser
In order to keep parsing with subcommands straightforward and simple, the seqan3::argument_parser provides an advanced interface that internally takes care of the correct input parsing.
You simply need to specify the names of the subcommands when constructing your top-level argument parser:
The SeqAn command line parser.
Definition argument_parser.hpp:145
@ on
Automatic update notifications should be enabled.
- Attention
- You can still add flags to your top-level parser if needed but no (positional) options. This avoids ambiguous parsing (e.g. subcommand fasta given file extension fasta
./myfasta_parser --filext fasta fasta ...
).
After calling seqan3::argument_parser::parse() on your top-level parser, you can then access the sub-parser via the function seqan3::argument_parser::get_sub_parser():
argument_parser & get_sub_parser()
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
Definition argument_parser.hpp:436
The sub-parser's seqan3::argument_parser::info::app_name will be set to the user chosen sub command. For example, if the user calls
then the sub-parser will be named mygit-push
and will be instantiated with all arguments followed by the keyword push
which in this case triggers printing the help page (-h
).
That's it. Here is a full example of a subcommand argument parser you can try and adjust to your needs:
struct pull_arguments
{
bool progress{false};
};
{
pull_arguments args{};
try
{
}
{
return -1;
}
seqan3::debug_stream <<
"Git pull with repository " << args.repository <<
" and branch " << args.branch <<
'\n';
return 0;
}
struct push_arguments
{
bool push_all{false};
};
{
push_arguments args{};
parser.
add_positional_option(args.branches,
"The branch names to push (if none are given, push current).");
try
{
}
{
return -1;
}
seqan3::debug_stream <<
"Git push with repository " << args.repository <<
" and branches " << args.branches <<
'\n';
return 0;
}
int main(int argc, char const ** argv)
{
top_level_parser.add_flag(flag, 'f', "flag", "some flag");
try
{
top_level_parser.parse();
}
{
return -1;
}
return run_git_pull(sub_parser);
return run_git_push(sub_parser);
else
return 0;
}
Meta-header for the Argument Parser module .
Argument parser exception that is thrown whenever there is an error while parsing the command line ar...
Definition exceptions.hpp:37
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
argument_parser_meta_data info
Aggregates all parser related meta data (see seqan3::argument_parser_meta_data struct).
Definition argument_parser.hpp:634
void parse()
Initiates the actual command line parsing.
Definition argument_parser.hpp:402
Provides seqan3::debug_stream and related types.
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:37
@ flag
The alignment flag (bit information), uint16_t value.