Loading...
Searching...
No Matches
How to write an argument parser with subcommands

This HowTo shows you how to write an argument parser with subcommand like git push using SeqAn.

Difficulty | Easy
Duration | 15 min
Prerequisite tutorials | Parsing command line arguments with Sharg
Recommended reading |

# Motivation

A common use case for command line tools, e.g. git, is to have multiple subcommands, e.g. git fetch or git push. Each subcommand has its own set of options and its own help page. This HowTo explains how this can be done with the seqan3::argument_parser and serves as a copy'n'paste source. If you are new to SeqAn, we recommend to do the basic argument parser tutorial before you read further.

# A subcommand argument parser

In order to keep parsing with subcommands straightforward and simple, the seqan3::argument_parser provides an advanced interface that internally takes care of the correct input parsing.

You simply need to specify the names of the subcommands when constructing your top-level argument parser:

seqan3::argument_parser top_level_parser{"mygit", argc, argv, seqan3::update_notifications::on, {"push", "pull"}};

Attention
  You can still add flags to your top-level parser if needed but no (positional) options. This avoids ambiguous parsing (e.g. subcommand fasta given file extension fasta ./myfasta_parser --filext fasta fasta ...).

After calling seqan3::argument_parser::parse() on your top-level parser, you can then access the sub-parser via the function seqan3::argument_parser::get_sub_parser():

seqan3::argument_parser & sub_parser = top_level_parser.get_sub_parser(); // hold a reference to the sub_parser

The sub-parser's seqan3::argument_parser::info::app_name will be set to the user chosen sub command. For example, if the user calls

max$ ./mygit push -h

then the sub-parser will be named mygit-push and will be instantiated with all arguments followed by the keyword push which in this case triggers printing the help page (-h).

That's it. Here is a full example of a subcommand argument parser you can try and adjust to your needs:

// 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>
// =====================================================================================================================
// pull
// =====================================================================================================================
struct pull_arguments
{
std::string repository{};
std::string branch{};
bool progress{false};
};
int run_git_pull(seqan3::argument_parser & parser)
{
pull_arguments args{};
parser.add_positional_option(args.repository, "The repository name to pull from.");
parser.add_positional_option(args.branch, "The branch name to pull from.");
try
{
parser.parse();
}
catch (seqan3::argument_parser_error const & ext)
{
seqan3::debug_stream << "[Error git pull] " << ext.what() << "\n";
return -1;
}
seqan3::debug_stream << "Git pull with repository " << args.repository << " and branch " << args.branch << '\n';
return 0;
}
// =====================================================================================================================
// push
// =====================================================================================================================
struct push_arguments
{
std::string repository{};
std::vector<std::string> branches{};
bool push_all{false};
};
int run_git_push(seqan3::argument_parser & parser)
{
push_arguments args{};
parser.add_positional_option(args.repository, "The repository name to push to.");
parser.add_positional_option(args.branches, "The branch names to push (if none are given, push current).");
try
{
parser.parse();
}
catch (seqan3::argument_parser_error const & ext)
{
seqan3::debug_stream << "[Error git push] " << ext.what() << "\n";
return -1;
}
seqan3::debug_stream << "Git push with repository " << args.repository << " and branches " << args.branches << '\n';
return 0;
}
// =====================================================================================================================
// main
// =====================================================================================================================
int main(int argc, char const ** argv)
{
seqan3::argument_parser top_level_parser{"mygit", argc, argv, seqan3::update_notifications::on, {"push", "pull"}};
// Add information and flags, but no (positional) options to your top-level parser.
// Because of ambiguity, we do not allow any (positional) options for the top-level parser.
top_level_parser.info.description.push_back("You can push or pull from a remote repository.");
// A flag's default value must be false.
bool flag{false};
top_level_parser.add_flag(flag, 'f', "flag", "some flag");
try
{
top_level_parser.parse(); // trigger command line parsing
}
catch (seqan3::argument_parser_error const & ext) // catch user errors
{
seqan3::debug_stream << "[Error] " << ext.what() << "\n"; // customise your error message
return -1;
}
seqan3::argument_parser & sub_parser = top_level_parser.get_sub_parser(); // hold a reference to the sub_parser
std::cout << "Proceed to sub parser.\n";
if (sub_parser.info.app_name == std::string_view{"mygit-pull"})
return run_git_pull(sub_parser);
else if (sub_parser.info.app_name == std::string_view{"mygit-push"})
return run_git_push(sub_parser);
else
std::cout << "Unhandled subparser named " << sub_parser.info.app_name << '\n';
// Note: Arriving in this else branch means you did not handle all sub_parsers in the if branches above.
return 0;
}
all.hpp
Meta-header for the Argument Parser module .
std::string
std::string_view
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::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::parse
void parse()
Initiates the actual command line parsing.
Definition argument_parser.hpp:404
seqan3::argument_parser::get_sub_parser
argument_parser & get_sub_parser()
Returns a reference to the sub-parser instance if subcommand parsing was enabled.
Definition argument_parser.hpp:438
std::cout
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
seqan3::field::flag
@ flag
The alignment flag (bit information), uint16_t value.
Definition record.hpp:84
seqan3::update_notifications::on
@ on
Automatic update notifications should be enabled.
Definition auxiliary.hpp:269
std::vector::push_back
T push_back(T... args)
seqan3::argument_parser_meta_data::app_name
std::string app_name
The application name that will be displayed on the help page.
Definition auxiliary.hpp:293
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
std::runtime_error::what
T what(T... args)
Hide me