The SeqAn command line parser. More...

#include <seqan3/argument_parser/argument_parser.hpp>

Public Member Functions
void	parse ()
	Initiates the actual command line parsing. More...

Constructors, destructor and assignment
	argument_parser ()=delete
	Deleted.

	argument_parser (argument_parser const &)=default
	Defaulted.

argument_parser &	operator= (argument_parser const &)=default
	Defaulted.

	argument_parser (argument_parser &&)=default
	Defaulted.

argument_parser &	operator= (argument_parser &&)=default
	Defaulted.

	argument_parser (std::string const app_name, int const argc, char const const const argv, bool version_check=true)
	Initializes an argument_parser object from the command line arguments. More...

	~argument_parser ()
	The destructor.

Adding options
Add (positional) options and flags to the parser.
template<typename option_type , Validator validator_type = detail::default_validator<option_type>>
void	add_option (option_type &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const &spec=option_spec::DEFAULT, validator_type validator=validator_type{})
	Adds an option to the seqan3::argument_parser. More...

void	add_flag (bool &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const &spec=option_spec::DEFAULT)
	Adds a flag to the seqan3::argument_parser. More...

template<typename option_type , Validator validator_type = detail::default_validator<option_type>>
void	add_positional_option (option_type &value, std::string const &desc, validator_type validator=validator_type{})
	Adds a positional option to the seqan3::argument_parser. More...

Structuring the Help Page
void	add_section (std::string const &title)
	Adds an help page section to the seqan3::argument_parser. More...

void	add_subsection (std::string const &title)
	Adds an help page subsection to the seqan3::argument_parser. More...

void	add_line (std::string const &text, bool line_is_paragraph=false)
	Adds an help page text line to the seqan3::argument_parser. More...

void	add_list_item (std::string const &key, std::string const &desc)
	Adds an help page list item (key-value) to the seqan3::argument_parser. More...

Public Attributes
argument_parser_meta_data	info
	Aggregates all parser related meta data (see seqan3::argument_parser_meta_data struct). More...

Detailed Description

The SeqAn command line parser.

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:

options [e.g. -i myfile, --infile myfile] refer to key-value pairs. The key is either a short indentifier, restricted to a single character -i, or a long identifier --infile.
positional options [e.g. arg1] refers to command line arguments that are specified without an identifier/key, are always required and are identified by their position.
flags [e.g. -b] refers to identifiers that are not followed by a value (booleans) and therefore only indicate whether they are set or not.

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.

#include <seqan3/argument_parser/all.hpp>
#include <seqan3/core/debug_stream.hpp>
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;
    }
    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.

Update Notifications

SeqAn applications that are using the seqan3::argument_parser can check SeqAn servers for version updates. The functionality helps getting new versions out to users faster. It is also used to inform application developers of new versions of the SeqAn library which means that applications ship with less bugs. For privacy implications, please see: https://github.com/seqan/seqan3/wiki/Update-Notifications.

Developers that wish to disable this feature permanently can pass an extra constructor argument:

#include <seqan3/argument_parser/all.hpp>
using namespace seqan3;
int main(int argc, char ** argv)
{
    argument_parser myparser{"Game of Parsing", argc, argv, false};
    // disable version checks permanently --------------------^
}

Users of applications that have this feature activated can opt-out, by either:

disabling it for a specific application simply by setting the option --version-check 0 or
disabling it for all applications by setting the SEQAN3_NO_VERSION_CHECK environment variable.

Note that in case there is no --version-check option (display available options with -h/--help), then the developer already disabled the version check functionality.

Constructor & Destructor Documentation

◆ argument_parser()

seqan3::argument_parser::argument_parser	(	std::string const	app_name,
		int const	argc,
		char const const const	argv,
		bool	version_check = `true`
	)

inline

Initializes an argument_parser object from the command line arguments.

Parameters

[in]	app_name	The name of the app that is displayed on the help page.
[in]	argc	The number of command line arguments.
[in]	argv	The command line arguments to parse.
[in]	version_check	Notify users about app version updates (default true).

See the argument parser tutorial for more information about the version check functionality.

Member Function Documentation

◆ add_flag()

void seqan3::argument_parser::add_flag	(	bool &	value,
		char const	short_id,
		std::string const &	long_id,
		std::string const &	desc,
		option_spec const &	spec = `option_spec::DEFAULT`
	)

inline

Adds a flag to the seqan3::argument_parser.

Parameters

[out]	value	The variable in which to store the given command line argument.
[in]	short_id	The short identifier for the flag (e.g. 'i').
[in]	long_id	The long identifier for the flag (e.g. "integer").
[in]	desc	The description of the flag to be shown in the help page.
[in]	spec	Advanced flag specification, see seqan3::option_spec.

◆ add_line()

void seqan3::argument_parser::add_line	(	std::string const &	text,
		bool	line_is_paragraph = `false`
	)

inline

Adds an help page text line to the seqan3::argument_parser.

Parameters

[in]	text	The text to print.
[in]	line_is_paragraph	Whether to insert as paragraph or just a line (Default: false).

If the line is not a paragraph (false), only one line break is appended, otherwise two line breaks are appended. This only affects the help page and other output formats.

◆ add_list_item()

void seqan3::argument_parser::add_list_item	(	std::string const &	key,
		std::string const &	desc
	)

inline

Adds an help page list item (key-value) to the seqan3::argument_parser.

Parameters

[in]	key	The key of the key-value pair of the list item.
[in]	desc	The value of the key-value pair of the list item.

Note: This only affects the help page and other output formats.

A list item is composed of a key (key) and value (desc) and usually used for option identifier-description-pairs. E.g.:

-a, --age LONG

Super important integer for age.

◆ add_option()

template<typename option_type , Validator validator_type = detail::default_validator<option_type>>

void seqan3::argument_parser::add_option	(	option_type &	value,
		char const	short_id,
		std::string const &	long_id,
		std::string const &	desc,
		option_spec const &	spec = `option_spec::DEFAULT`,
		validator_type	validator = `validator_type{}`
	)

inline

Adds an option to the seqan3::argument_parser.

Template Parameters

option_type	Must have a formatted input function (stream >> value). If option_type is a container, its value type must have the formatted input function (exception: std::string is not regarded as a container). See FormattedInputFunction .
validator_type	The type of validator to be applied to the option value. Must satisfy seqan3::Validator.

Parameters

[out]	value	The variable in which to store the given command line argument.
[in]	short_id	The short identifier for the option (e.g. 'a').
[in]	long_id	The long identifier for the option (e.g. "age").
[in]	desc	The description of the option to be shown in the help page.
[in]	spec	Advanced option specification, see seqan3::option_spec.
[in]	validator	The validator applied to the value after parsing (callable).

◆ add_positional_option()

template<typename option_type , Validator validator_type = detail::default_validator<option_type>>

void seqan3::argument_parser::add_positional_option	(	option_type &	value,
		std::string const &	desc,
		validator_type	validator = `validator_type{}`
	)

inline

Adds a positional option to the seqan3::argument_parser.

Template Parameters

option_type	Must have a formateted input function (stream >> value). If option_type is a container, its value type must have the formateted input function (exception: std::string is not regarded as a container). See FormattedInputFunction .
validator_type	The type of validator to be applied to the option value. Must satisfy seqan3::Validator.

Parameters

[out]	value	The variable in which to store the given command line argument.
[in]	desc	The description of the positional option to be shown in the help page.
[in]	validator	The validator applied to the value after parsing (callable).

Exceptions

seqan3::parser_design_error

The validator must be applicable to the given output variable (value).

◆ add_section()

void seqan3::argument_parser::add_section ( std::string const & title )

inline

Adds an help page section to the seqan3::argument_parser.

Parameters

[in] title The title of the section.

This only affects the help page and other output formats.

◆ add_subsection()

void seqan3::argument_parser::add_subsection ( std::string const & title )

inline

Adds an help page subsection to the seqan3::argument_parser.

Parameters

[in] title The title of the subsection.

This only affects the help page and other output formats.

◆ parse()

void seqan3::argument_parser::parse ( )

inline

Initiates the actual command line parsing.

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::parser_design_error	if this function was already called before.
seqan3::option_declared_multiple_times	if an option that is not a list was declared multiple times.
seqan3::overflow_error_on_conversion	if the numeric argument would cause an overflow error when converted into the expected type.
seqan3::parser_invalid_argument	if the user provided wrong arguments.
seqan3::required_option_missing	if the user did not provide a required option.
seqan3::too_many_arguments	if the command line call contained more arguments than expected.
seqan3::too_few_arguments	if the command line call contained less arguments than expected.
seqan3::type_conversion_failed	if the argument value could not be converted into the expected type.
seqan3::validation_failed	if 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.

If the given command line input (argv) contains the following keywords (in order of checking), the parser will exit (std::exit) with error code 0 after doing the following:

-h/--help Prints the help page.
-hh/--advanced-help Prints the help page including advanced options.
--version Prints the version information.
--export-help [format] Prints the application description in the given format (html/man/ctd).
--version-check 0/1 Disable/enable update notifications.

Example:

Note: Since the argument parser may throw, you should always wrap parse() into a try-catch block.

#include <seqan3/argument_parser/all.hpp>
#include <seqan3/core/debug_stream.hpp>
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;
    }
    seqan3::debug_stream << "integer given by user: " << age << std::endl;
    return 0;
}

The code above gives the following output when calling --help:

MaxMuster$ ./age_app --help
The-Age-App
===========
OPTIONS
    -a, --user-age (signed 32 bit integer)
          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$ ./age_app -a abc
The Age App - [PARSER ERROR] Value cast failed for option -a: Argument abc
                             could not be casted to type (signed 32 bit integer).

Member Data Documentation

◆ info

argument_parser_meta_data seqan3::argument_parser::info

Aggregates all parser related meta data (see seqan3::argument_parser_meta_data struct).

Attention: You should supply as much information as possible to help users of the application.

The meta information is assembled in a struct to provide a central access point that can be easily extended.

You can access the members directly: (see seqan3::argument_parser_meta_data for a list of the info members)

#include <seqan3/argument_parser/all.hpp>
int main(int argc, char ** argv)
{
    seqan3::argument_parser myparser{"Penguin_Parade", argc, argv}; // initialize
    myparser.info.version = "2.0.0";
    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};   // day
    int m{01};   // month
    int y{2050}; // year
    myparser.add_option(d, 'd', "day", "Please specify your preferred day.");
    myparser.add_option(m, 'm', "month", "Please specify your preferred month.");
    myparser.add_option(y, 'y', "year", "Please specify your preferred year.");
    std::vector<std::string> penguin_names;
    myparser.add_positional_option(penguin_names, "Specify the names of the penguins.");
    try
    {
        myparser.parse();
    }
    catch (seqan3::parser_invalid_argument const & ext) // the user did something wrong
    {
        std::cerr << ext.what() << "\n";
        return -1;
    }
    // organize ...
    return 0;
}

This will produce a nice help page when the user calls -h or --help:

MaxMuster% ./penguin_app --help
Penguin_Parade - Organize your penguin parade
=============================================
DESCRIPTION
    First Paragraph.
    Second Paragraph.
POSITIONAL ARGUMENTS
    ARGUMENT-1 List of STRING's
          Specify the names of the penguins.
OPTIONS
    -d, --day (signed 32 bit integer)
          Please specify your preferred day.
    -m, --month (signed 32 bit integer)
          Please specify your preferred month.
    -y, --year (signed 32 bit integer)
          Please specify your preferred year.
EXAMPLES
    ./penguin_parade Skipper Kowalski Rico Private -d 10 -m 02 -y 2017
VERSION
    Last update: 12.01.2017
    Penguin_Parade version: 2.0.0
    SeqAn version: 3.0.0

The documentation for this class was generated from the following file:

seqan3/argument_parser/argument_parser.hpp

Public Member Functions

Public Attributes

Detailed Description

Terminology

Add/get options, flags or positional Options

Errors that are caught by the argument_parser

Update Notifications

Constructor & Destructor Documentation

◆ argument_parser()

Member Function Documentation

◆ add_flag()

◆ add_line()

◆ add_list_item()

◆ add_option()

◆ add_positional_option()

◆ add_section()

◆ add_subsection()

◆ parse()

Member Data Documentation

◆ info