Loading...
Searching...
No Matches
seqan3::argument_parser Class Reference
Argument Parser

The SeqAn command line parser. More...

`#include <seqan3/argument_parser/argument_parser.hpp>`

## Public Member Functions

argument_parser & | get_sub_parser ()
| Returns a reference to the sub-parser instance if subcommand parsing was enabled.
template<typename id_type> requires std::same_as<id_type, char> || std::constructible_from<std::string, id_type>
bool | is_option_set (id_type const &id) const
| Checks whether the option identifier (id) was set on the command line by the user.
void | parse ()
| Initiates the actual command line parsing.
Constructors, destructor and assignment
| argument_parser ()=delete
| Deleted.
| argument_parser (argument_parser const &)=delete
| Deleted. Holds std::future.
argument_parser & | operator= (argument_parser const &)=delete
| Deleted. Holds std::future.
| 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, update_notifications version_updates=update_notifications::on, std::vector< std::string > subcommands={})
| Initializes an seqan3::argument_parser object from the command line arguments.
| ~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>> requires (argument_parser_compatible_option<option_type> || argument_parser_compatible_option<std::ranges::range_value_t<option_type>>) && std::invocable<validator_type, 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::standard, validator_type option_validator=validator_type{})
| Adds an option to the seqan3::argument_parser.
void | add_flag (bool &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const spec=option_spec::standard)
| Adds a flag to the seqan3::argument_parser.
template<typename option_type, validator validator_type = detail::default_validator<option_type>> requires (argument_parser_compatible_option<option_type> || argument_parser_compatible_option<std::ranges::range_value_t<option_type>>) && std::invocable<validator_type, option_type>
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.
Structuring the Help Page
void | add_section (std::string const &title, option_spec const spec=option_spec::standard)
| Adds an help page section to the seqan3::argument_parser.
void | add_subsection (std::string const &title, option_spec const spec=option_spec::standard)
| Adds an help page subsection to the seqan3::argument_parser.
void | add_line (std::string const &text, bool is_paragraph=false, option_spec const spec=option_spec::standard)
| Adds an help page text line to the seqan3::argument_parser.
void | add_list_item (std::string const &key, std::string const &desc, option_spec const spec=option_spec::standard)
| Adds an help page list item (key-value) to the seqan3::argument_parser.

## Public Attributes

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

## 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.

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#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::argument_parser_error 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 << '\n';
return 0;
}
all.hpp
Meta-header for the Argument Parser module .
std::string
std::cerr
seqan3::argument_parser_error
Argument parser exception that is thrown whenever there is an error while parsing the command line ar...
Definition exceptions.hpp:39
seqan3::argument_parser
The SeqAn command line parser.
Definition argument_parser.hpp:147
seqan3::argument_parser::add_positional_option
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:314
seqan3::argument_parser::add_flag
void add_flag(bool &value, char const short_id, std::string const &long_id, std::string const &desc, option_spec const spec=option_spec::standard)
Adds a flag to the seqan3::argument_parser.
Definition argument_parser.hpp:270
seqan3::argument_parser::add_option
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::standard, validator_type option_validator=validator_type{})
Adds an option to the seqan3::argument_parser.
Definition argument_parser.hpp:238
seqan3::argument_parser::parse
void parse()
Initiates the actual command line parsing.
Definition argument_parser.hpp:404
debug_stream.hpp
Provides seqan3::debug_stream and related types.
seqan3::debug_stream
debug_stream_type debug_stream
A global instance of seqan3::debug_stream_type.
Definition debug_stream.hpp:38
std::vector::push_back
T push_back(T... args)
std::vector
std::runtime_error::what
T what(T... args)

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::design_error is thrown.

The second kind are user errors, due to invalid command line calls. In this case a seqan3::argument_parser_error 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.

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 false/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,
|  | update_notifications | version_updates = update_notifications::on,
|  | std::vector< std::string > | subcommands = {} )

inline

Initializes an seqan3::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_updates | Notify users about version updates (default seqan3::update_notifications::on).
  [in] | subcommands | A list of subcommands (see subcommand parsing ).

Exceptions

  seqan3::design_error | if the application name contains illegal characters.

The application name must only contain alpha-numeric characters, _ or -, i.e. the following regex must evaluate to true: "^[a-zA-Z0-9_-]+$".

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::standard )

inline

Adds a flag to the seqan3::argument_parser.

Parameters

  [in,out] | value | The variable which shows whether the flag is turned off (default) or on.
  [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.

Exceptions

  seqan3::design_error | if value is true.

## add_line()

void seqan3::argument_parser::add_line | ( | std::string const & | text,
|  | bool | is_paragraph = false,
|  | option_spec const | spec = option_spec::standard )

inline

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

Parameters

  [in] | text | The text to print.
  [in] | is_paragraph | Whether to insert as paragraph or just a line (Default: false).
  [in] | spec | Whether to always display this line (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).

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,
|  | option_spec const | spec = option_spec::standard )

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.
  [in] | spec | Whether to always display this list item (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).

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>>
requires (argument_parser_compatible_option<option_type> || argument_parser_compatible_option<std::ranges::range_value_t<option_type>>) && std::invocable<validator_type, 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::standard,
|  | validator_type | option_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 model seqan3::validator.

Parameters

  [in,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] | option_validator | A seqan3::validator that verifies the value after parsing (callable).

Exceptions

  seqan3::design_error |

## add_positional_option()

template<typename option_type, validator validator_type = detail::default_validator<option_type>>
requires (argument_parser_compatible_option<option_type> || argument_parser_compatible_option<std::ranges::range_value_t<option_type>>) && std::invocable<validator_type, option_type>

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

inline

Adds a positional 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 model seqan3::validator.

Parameters

  [in,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] | option_validator | A seqan3::validator that verifies the value after parsing (callable).

Exceptions

  seqan3::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,
|  | option_spec const | spec = option_spec::standard )

inline

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

Parameters

  [in] | title | The title of the section.
  [in] | spec | Whether to always display this section title (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).

This only affects the help page and other output formats.

## add_subsection()

void seqan3::argument_parser::add_subsection | ( | std::string const & | title,
|  | option_spec const | spec = option_spec::standard )

inline

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

Parameters

  [in] | title | The title of the subsection.
  [in] | spec | Whether to always display this subsection title (seqan3::option_spec::standard), only when showing the advanced help page (seqan3::option_spec::advanced) or never (seqan3::option_spec::hidden).

This only affects the help page and other output formats.

## is_option_set()

template<typename id_type>
requires std::same_as<id_type, char> || std::constructible_from<std::string, id_type>

bool seqan3::argument_parser::is_option_set | ( | id_type const & | id | ) | const

inline

Checks whether the option identifier (id) was set on the command line by the user.

Template Parameters

  id_type | Either type char or a type that a std::string is constructible from.

Parameters

  [in] | id | The short (char) or long (std::string) option identifier to search for.

Returns
  true if option identifier id was set on the command line by the user.

Exceptions

  seqan3::design_error | if the function is used incorrectly (see details below).

You can only ask for option identifiers that were added to the parser beforehand via seqan3::argument_parser::add_option. As in the seqan3::argument_parser::add_option call, pass short identifiers as a char and long identifiers as a std::string or a type that a std::string is constructible from (e.g. a const char *).

### Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#include <seqan3/argument_parser/all.hpp>
#include <seqan3/core/debug_stream.hpp>
int main(int argc, char ** argv)
{
seqan3::argument_parser myparser{"awesome-app", argc, argv}; // initialize
int a{3};
myparser.add_option(a, 'a', "awesome-parameter", "Please specify an integer.");
try
{
myparser.parse();
}
catch (seqan3::argument_parser_error const & ext) // the user did something wrong
{
std::cerr << "[PARSER ERROR] " << ext.what() << '\n'; // customize your error message
return -1;
}
if (myparser.is_option_set('a'))
seqan3::debug_stream << "The user set option -a on the command line.\n";
if (myparser.is_option_set("awesome-parameter"))
seqan3::debug_stream << "The user set option --awesome-parameter on the command line.\n";
// Asking for an option identifier that was not used before throws an error:
// myparser.is_option_set("foo"); // throws seqan3::design_error
return 0;
}
seqan3::argument_parser::is_option_set
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 argument_parser.hpp:476

### Exceptions

This function throws a seqan3::design_error if

- seqan3::argument_parser::parse() was not called before.
- a long identifier was passed (e.g. a std::string) that only consists of a single character. If you mean to pass a short identifier, please pass it as a char not a std::string.
- the option identifier cannot be found in the list of valid option identifiers that were added to the parser via seqan3::argument_parser::add_option() calls beforehand.

## 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 as the argument parser may throw.

Exceptions

  seqan3::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::user_input_error | if an incorrect argument is given as (positional) option value.
  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::validation_error | 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 false/0/true/1 Disable/enable update notifications.

Example:

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#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::argument_parser_error 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 << '\n';
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)

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
#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::argument_parser_error const & ext) // the user did something wrong
{
std::cerr << ext.what() << "\n";
return -1;
}
// organize ...
return 0;
}
seqan3::argument_parser::info
argument_parser_meta_data info
Aggregates all parser related meta data (see seqan3::argument_parser_meta_data struct).
Definition argument_parser.hpp:636
seqan3::argument_parser_meta_data::date
std::string date
The date that the application was last updated. Keep this updated, ! since it will tell your users th...
Definition auxiliary.hpp:305
seqan3::argument_parser_meta_data::version
std::string version
The version information MAJOR.MINOR.PATH (e.g. 3.1.3).
Definition auxiliary.hpp:295
seqan3::argument_parser_meta_data::short_description
std::string short_description
A short description of the application (e.g. "A tool for mapping reads to the genome").
Definition auxiliary.hpp:297
seqan3::argument_parser_meta_data::description
std::vector< std::string > description
A more detailed description that is displayed on the help page in the section "DESCRIPTION"....
Definition auxiliary.hpp:327
seqan3::argument_parser_meta_data::examples
std::vector< std::string > examples
Provide some examples on how to use your tool and what standard parameters might be appropriate in di...
Definition auxiliary.hpp:336

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:

- argument_parser.hpp

Hide me