seqan3::argument_parser Class Reference

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&l