SeqAn3
Argument Parser

The Argument Parser Module. More...

Classes

class  seqan3::argument_parser
 The SeqAn command line parser. More...
 
struct  seqan3::argument_parser_meta_data
 Stores all parser related meta information of the seqan3::argument_parser. More...
 
class  seqan3::file_existance_validator
 A validator that checks if a file exists. More...
 
class  seqan3::file_ext_validator
 A validator that checks if a filenames has one of the valid extensions. More...
 
class  seqan3::integral_range_validator< option_value_type >
 A validator that checks whether a number is inside a given range. More...
 
class  seqan3::regex_validator< std::string >
 A validator that checks if a matches a regular expression pattern. More...
 
class  seqan3::regex_validator< std::vector< std::string > >
 A validator that checks if each value in a container satisfies a regex expression. More...
 
interface  seqan3::validator_concept
 The concept for option validators passed to add_option/positional_option. More...
 
class  seqan3::value_list_validator< option_value_type >
 A validator that checks whether a value is inside a list of valid values. More...
 
class  seqan3::value_list_validator< option_value_type >
 A validator that checks if each value in a container appears in a list of valid values. More...
 

Enumerations

enum  seqan3::option_spec { seqan3::DEFAULT = 0, seqan3::REQUIRED = 1, seqan3::ADVANCED = 2, seqan3::HIDDEN = 4 }
 Used to further specify argument_parser options/flags. More...
 

Functions

template<validator_concept validator1_type, validator_concept validator2_type>
auto seqan3::operator| (validator1_type &&vali1, validator2_type &&vali2)
 Enables the chaining of validators. ! More...
 

Detailed Description

The Argument Parser Module.

The Argument Parser Class

The seqan3::argument_parser is a general purpose argument parser that provides convenient access to the command line arguments passed to the program. It automatically generates a help page and can export manual-pages as well as HTML documentation.

Furthermore common tool descriptor (CTD) files can be exported (soon) and a server be queried for available application updates.

Terminology

Since the terms option and arguments are frequently used in different contexts we want to first clarify our usage:

Add/get options, flags or positional Options

Adding an option is done in a single call. You simply need to provide a predeclared variable and some additional information like the identifier, description or advanced restrictions. To actually retrieve the value from the command line and enable every other mechanism you need to call the seqan3::argument_parser::parse function in the end.

int main(int argc, char ** argv)
{
seqan3::argument_parser myparser("Grade-Average", argc, argv); // initialize
std::string name{"Max Muster"}; // define default values directly in the variable.
bool bonus{false};
std::vector<double> grades{}; // you can also specify a vector that is treated as a list option.
myparser.add_option(name, 'n', "name", "Please specify your name.");
myparser.add_flag(bonus, 'b', "bonus", "Please specify if you got the bonus.");
myparser.add_positional_option(grades, "Please specify your grades.");
try
{
myparser.parse();
}
catch (seqan3::parser_invalid_argument const & ext) // the user did something wrong
{
std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
return -1;
}
catch (seqan3::parser_interruption const &) // expected behaviour on special requests (e.g. `--help`)
{
return 0;
}
if (bonus)
grades.push_back(1.0); // extra good grade
double avg{0};
for (auto g : grades)
avg += g;
avg = avg / grades.size();
seqan3::debug_stream << name << " has an average grade of " << avg << std::endl;
return 0;
}

Now you can call your application via the command line:

MaxMuster% ./grade_avg_app -n Peter --bonus 1.0 2.0 1.7
Peter has an average grade of 1.425

You can also display the help page automatically:

MaxMuster% ./grade_avg_app --help
Grade-Average
=============
POSITIONAL ARGUMENTS
ARGUMENT-1 List of DOUBLE's
Please specify your grades.
OPTIONS
-n, --name STRING
Please specify your name.
-b, --bonus
Please specify if you got the bonus.
VERSION
Last update:
Grade-Average version:
SeqAn version: 3.0.0

Errors that are caught by the argument_parser

There are two different kinds of errors: Developer errors and user errors.

Developer errors are those that violate the seqan3::argument_parser design (e.g. calling the seqan3::argument_parser::parse function twice or specifying two different options with the same identifier.) In this case, a seqan3::parser_design_error is thrown.

The second kind are user errors, due to invalid command line calls. In this case a seqan3::parser_invalid_argument is thrown.

For example:

MaxMuster% ./grade_avg_app -n Peter 2.0 abc 1.7
[PARSER ERROR] Value cast failed for positional option 2: Argument abc could not be casted to type DOUBLE.

See the seqan3::argument_parser::parse documentation for a detailed list of which exceptions are caught.

Parsing Command Line Arguments

Attention
The function must be called at the very end of all parser related code and should be enclosed in a try catch block.
Exceptions
seqan3::option_declared_multiple_timesif an option that is not a list was declared multiple times.
seqan3::overflow_error_on_conversionif the numeric argument would cause an overflow error when converted into the expected type.
seqan3::parser_interruptionon special user request (e.g. –help or –version).
seqan3::parser_invalid_argumentif the user provided wrong arguments.
seqan3::required_option_missingif the user did not provide a required option.
seqan3::too_many_argumentsif the command line call contained more arguments than expected.
seqan3::too_few_argumentsif the command line call contained too few arguments than expected.
seqan3::type_conversion_failedif the argument value could not be converted into the expected type.
seqan3::validation_failedif the argument was not excepted by the provided validator.

When no specific key words are supplied, the seqan3::argument_parser starts to process the command line for specified options, flags and positional options.

The parser behaves differently when the given command line (argv) contains the following keywords (in order of checking) :

For example you can call your application binary like this:

MaxMuster$ ./my_app --export-help html > my_app.html

Note: We throw a parser_interruption exception to ensure that the application/program is not executed when the user requests special behaviour. You should therefore enclose this function into a try catch block, customizing the behaviour of your application parser:

int main(int argc, char ** argv)
{
seqan3::argument_parser myparser("The-Age-App", argc, argv); // initialize
int age{30}; // define default values directly in the variable
myparser.add_option(age, 'a', "user-age", "Please specify your age.");
try
{
myparser.parse();
}
catch (seqan3::parser_invalid_argument const & ext) // the user did something wrong
{
std::cerr << "The-Age-App - [PARSER ERROR] " << ext.what() << "\n"; // customize your error message
return -1;
}
catch (seqan3::parser_interruption const &) // expected behaviour on special requests (e.g. `--help`)
{
seqan3::debug_stream << std::endl << "Thanks for using The-Age-App!" << std::endl; // customize
return 0;
}
seqan3::debug_stream << "integer given by user: " << age << std::endl;
return 0;
}

For example a help call gives the following output:

MaxMuster$ ./age_app --help
The-Age-App
===========
OPTIONS
-a, --user-age INT (32 bit)
Please specify your age.
VERSION
Last update:
The-Age-App version:
SeqAn version: 3.0.0
Thanks for using The-Age-App!

If the user does something wrong, it looks like this:

MaxMuster$ ./age_app --foo
The Age App - [PARSER ERROR] Unknown option --foo. Please see -h/--help for more information.
MaxMuster$
MaxMuster$ ./age_app -a abc
The Age App - [PARSER ERROR] Value cast failed for option -a: Argument abc
could not be casted to type INT (32 bit).

Argument Validation

The SeqAn 3 Argument Parser offers a validation mechanism for (positional_)options via callables. You can pass any functor that fulfills the seqan3::validator_concept and takes the value passed to the add_(positional_)option function call as a parameter. We provide some commonly used functor that might come in handy:

Enumeration Type Documentation

◆ option_spec

Used to further specify argument_parser options/flags.

All options and flags are set to option_spec::DEFAULT unless specified otherwise by the developer, e.g. when calling argument_parser::add_option().

argument_parser myparser("Test", argc, argv);
std::string myvar{"Example"};
myparser.add_option(myvar, 's', "special-op", "You know what you doin'?",
Enumerator
DEFAULT 

The default were no checking or special displaying is happening.

REQUIRED 

Set an option as required if you want to enforce that the user supplies this option when calling the program via the command line. If the option is missing, the argument_parser will automatically detect this and throw a invalid_argument exception.

ADVANCED 

Set an option/flag to advanced if you do not want the option to be displayed in the normal help page (-h/--help). Instead, the advanced options are only displayed when calling -hh/--advanced-help

HIDDEN 

Set an option/flag to hidden, if you want to completely hide it from the user. It will never appear on the help page nor any export format. For example, this can be useful for debugging reasons. (e.g. "A tool for mapping reads to the genome").

Function Documentation

◆ operator|()

template<validator_concept validator1_type, validator_concept validator2_type>
auto seqan3::operator| ( validator1_type &&  vali1,
validator2_type &&  vali2 
)

Enables the chaining of validators. !

Template Parameters
validator1_typeThe type of the fist validator; Must satisfy the seqan3::validator_concept and the same value_type as the second validator type.
validator2_typeThe type of the second validator; Must satisfy the seqan3::validator_concept and the same value_type as the fist validator type.
Parameters
[in]vali1The first validator to chain.
[in]vali2The second validator to chain.
Returns
A new validator that tests a value for both vali1 and vali2.

The pipe operator is the AND operation for two validators, which means that a value must pass both validators in order to be accepted by the new validator.

For example you may want a file name that only accepts absolute paths but also must have one out of some given file extensions. For this purpose you can chain a seqan3::regex_validator to a seqan3::file_ext_validator like this:

int main(int argc, const char ** argv)
{
seqan3::argument_parser myparser("Test", argc, argv); // initialize
std::string file_name;
seqan3::regex_validator<std::string> absolute_path_validator("(/[^/]+)+/.*\\.[^/\\.]+$");
seqan3::file_ext_validator my_file_ext_validator({"sa", "so"});
myparser.add_option(file_name, 'f', "file","Give me a file name/path.",
seqan3::option_spec::DEFAULT, absolute_path_validator | my_file_ext_validator);
// an exception will be thrown if the user specifies a file name
// that is not an absolute path or does not have one of the file extension [sa,so]
try
{
myparser.parse();
}
catch (seqan3::parser_invalid_argument const & ext) // the user did something wrong
{
std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
return -1;
}
catch (seqan3::parser_interruption const &) // expected behaviour on special requests (e.g. `--help`)
{
return 0;
}
std::cout << "filename given by user passed validation: " << file_name << "\n";
return 0;
}

You can chain as many validators as you want which will be evaluated one after the other from left to right (first to last).