Loading...
Searching...
No Matches
Argument Parser

## Classes

class | seqan3::argument_parser
| The SeqAn command line parser. More...
interface | argument_parser_compatible_option
| Checks whether the the type can be used in an add_(positional_)option call on the argument parser. More...
class | seqan3::argument_parser_error
| Argument parser exception that is thrown whenever there is an error while parsing the command line arguments. More...
struct | seqan3::argument_parser_meta_data
| Stores all parser related meta information of the seqan3::argument_parser. More...
struct | seqan3::custom::argument_parsing< t >
| A type that can be specialised to provide customisation point implementations for the seqan3::argument_parser such that third party types may be adapted. More...
class | seqan3::arithmetic_range_validator< option_value_t >
| A validator that checks whether a number is inside a given range. More...
struct | seqan3::enumeration_printer< enum_t >
| A type (e.g. an enum) can be made debug streamable by customizing the seqan3::enumeration_names. More...
class | seqan3::file_validator_base
| An abstract base class for the file and directory validators. More...
class | seqan3::input_directory_validator
| A validator that checks if a given path is a valid input directory. More...
class | seqan3::input_file_validator< file_t >
| A validator that checks if a given path is a valid input file. More...
interface | named_enumeration
| Checks whether the free function seqan3::enumeration_names can be called on the type. More...
class | seqan3::option_declared_multiple_times
| Argument parser exception thrown when a non-list option is declared multiple times. More...
class | seqan3::output_directory_validator
| A validator that checks if a given path is a valid output directory. More...
class | seqan3::output_file_validator< file_t >
| A validator that checks if a given path is a valid output file. More...
class | seqan3::regex_validator
| A validator that checks if a matches a regular expression pattern. More...
class | seqan3::required_option_missing
| Argument parser exception thrown when a required option is missing. More...
class | seqan3::too_few_arguments
| Argument parser exception thrown when too few arguments are provided. More...
class | seqan3::too_many_arguments
| Argument parser exception thrown when too many arguments are provided. More...
class | seqan3::unknown_option
| Argument parser exception thrown when encountering unknown option. More...
class | seqan3::user_input_error
| Argument parser exception thrown when an incorrect argument is given as (positional) option value. More...
class | seqan3::validation_error
| Argument parser exception thrown when an argument could not be casted to the according type. More...
interface | validator
| The concept for option validators passed to add_option/positional_option. More...
class | seqan3::value_list_validator< option_value_t >
| A validator that checks whether a value is inside a list of valid values. More...

## Enumerations

enum | seqan3::option_spec { seqan3::standard = 0 , seqan3::required = 1 , seqan3::advanced = 2 , seqan3::hidden = 4 }
| Used to further specify argument_parser options/flags. More...

## Functions

template<validator validator1_type, validator validator2_type> requires std::common_with<typename std::remove_reference_t<validator1_type>::option_value_type, typename std::remove_reference_t<validator2_type>::option_value_type>
auto | seqan3::operator| (validator1_type &&vali1, validator2_type &&vali2)
| Enables the chaining of validators.

## Customisation Points

template<typename option_type>
auto const | seqan3::enumeration_names = detail::adl_only::enumeration_names_cpo<option_type>{}()
| Return a conversion map from std::string_view to option_type.

## Detailed Description

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

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

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

# Argument Validation

The SeqAn 3 Argument Parser offers a validation mechanism for (positional_)options via callables. You can pass any functor that fulfils the seqan3::validator 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:

- seqan3::regex_validator
- seqan3::value_list_validator
- seqan3::arithmetic_range_validator
- seqan3::input_file_validator
- seqan3::output_file_validator
- seqan3::input_directory_validator
- seqan3::output_directory_validator

## Enumeration Type Documentation

## option_spec

enum seqan3::option_spec

Used to further specify argument_parser options/flags.

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

// 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 const ** argv)
{
seqan3::argument_parser myparser{"Test", argc, argv};
std::string myvar{"Example"};
myparser.add_option(myvar, 's', "special-op", "You know what you doin'?", seqan3::option_spec::advanced);
}
seqan3::advanced
@ advanced
Definition auxiliary.hpp:256

Remarks
  For a complete overview, take a look at Argument Parser

Enumerator
standard | 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.

## Function Documentation

## operator|()

template<validator validator1_type, validator validator2_type>
requires std::common_with<typename std::remove_reference_t<validator1_type>::option_value_type, typename std::remove_reference_t<validator2_type>::option_value_type>

auto seqan3::operator| | ( | validator1_type && | vali1,
|  | validator2_type && | vali2 )

Enables the chaining of validators.

Template Parameters

  validator1_type | The type of the fist validator; Must satisfy the seqan3::validator and the same option_value_type as the second validator type.
  validator2_type | The type of the second validator; Must satisfy the seqan3::validator and the same option_value_type as the fist validator type.

Parameters

  [in] | vali1 | The first validator to chain.
  [in] | vali2 | The 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::input_file_validator like this:

// 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 <filesystem>
#include <seqan3/argument_parser/all.hpp>
int main(int argc, char const ** argv)
{
seqan3::argument_parser myparser{"Test", argc, argv}; // initialize
std::string file_name;
seqan3::regex_validator absolute_path_validator{"(/[^/]+)+/.*\\.[^/\\.]+$"};
seqan3::input_file_validator my_file_ext_validator{{"sa", "so"}};
myparser.add_option(file_name,
'f',
"file",
"Give me a file name with an absolute path.",
seqan3::option_spec::standard,
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::argument_parser_error const & ext) // the user did something wrong
{
std::cerr << "[PARSER ERROR] " << ext.what() << "\n"; // customize your error message
return -1;
}
std::cout << "filename given by user passed validation: " << file_name << "\n";
return 0;
}
seqan3::input_file_validator
A validator that checks if a given path is a valid input file.
Definition validators.hpp:517
seqan3::regex_validator
A validator that checks if a matches a regular expression pattern.
Definition validators.hpp:931
std::cout
filesystem
seqan3::standard
@ standard
The default were no checking or special displaying is happening.
Definition auxiliary.hpp:250

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

Remarks
  For a complete overview, take a look at Argument Parser

## Variable Documentation

## enumeration_names

template<typename option_type>

auto const seqan3::enumeration_names = detail::adl_only::enumeration_names_cpo<option_type>{}()

inline

Return a conversion map from std::string_view to option_type.

Template Parameters

  your_type | Type of the value to retrieve the conversion map for.

Parameters

  value | The value is not used, just its type.

Returns
  A std::unordered_map<std::string_view, your_type> that maps a string identifier to a value of your_type.

This is a function object. Invoke it with the parameter(s) specified above.

It acts as a wrapper and looks for two possible implementations (in this order):

1. A static member enumeration_names in seqan3::custom::argument_parsing<your_type> that is of type std::unordered_map<std::string_view, your_type>>.
2. A free function enumeration_names(your_type const a) in the namespace of your type (or as friend) which returns a std::unordered_map<std::string_view, your_type>>.

### Example

If you are working on a type in your own namespace, you should implement a free function like this:

// 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>
namespace foo
{
enum class bar
{
one,
two,
three
};
// Specialise a mapping from an identifying string to the respective value of your type bar.
auto enumeration_names(bar)
{
return std::unordered_map<std::string_view, bar>{{"one", bar::one}, {"two", bar::two}, {"three", bar::three}};
}
} // namespace foo
int main(int argc, char const * argv[])
{
foo::bar value{};
seqan3::argument_parser parser{"my_program", argc, argv};
// Because of the enumeration_names function
// you can now add an option that takes a value of type bar:
parser.add_option(value,
'f',
"foo",
"Give me a foo value.",
seqan3::option_spec::standard,
seqan3::value_list_validator{(seqan3::enumeration_names<foo::bar> | std::views::values)});
try
{
parser.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;
}
}
seqan3::value_list_validator
A validator that checks whether a value is inside a list of valid values.
Definition validators.hpp:199
seqan3::enumeration_names
auto const enumeration_names
Return a conversion map from std::string_view to option_type.
Definition auxiliary.hpp:162
std::unordered_map

Only if you cannot access the namespace of your type to customize you may specialize the seqan3::custom::argument_parsing struct like this:

// 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 <ranges>
#include <system_error>
#include <seqan3/argument_parser/all.hpp>
namespace seqan3::custom
{
// Specialise the seqan3::custom::argument_parsing data structure to enable parsing of std::errc.
template <>
struct argument_parsing<std::errc>
{
// Specialise a mapping from an identifying string to the respective value of your type Foo.
static inline std::unordered_map<std::string_view, std::errc> const enumeration_names{
{"no_error", std::errc{}},
{"timed_out", std::errc::timed_out},
{"invalid_argument", std::errc::invalid_argument},
{"io_error", std::errc::io_error}};
};
} // namespace seqan3::custom
int main(int argc, char const * argv[])
{
std::errc value{};
seqan3::argument_parser parser{"my_program", argc, argv};
// Because of the argument_parsing struct and
// the static member function enumeration_names
// you can now add an option that takes a value of type std::errc:
parser.add_option(value,
'e',
"errc",
"Give me a std::errc value.",
seqan3::option_spec::standard,
seqan3::value_list_validator{(seqan3::enumeration_names<std::errc> | std::views::values)});
try
{
parser.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;
}
return 0;
}
std::errc
seqan3::custom
A namespace for third party and standard library specialisations of SeqAn customisation points.
Definition char.hpp:40
std
SeqAn specific customisations in the standard namespace.
system_error

Remarks
  For a complete overview, take a look at Argument Parser

### Customisation point

This is a customisation point (see Customisation). To specify the behaviour for your own type, simply provide one of the two functions specified above.

Hide me