Class ArgumentParser
Parse the command line.

Defined in <seqan/arg_parse.h>
Signature class ArgumentParser;

Member Function Overview

Interface Function Overview

Detailed Description

Options are stored as ArgParseOption and ArgParseArgument objects.

Remarks

See the documentation of ToolDoc on how to format text. Wherever possible, formatting is added automatically for you. You have to use formatting in the following places: (1) usage lines, (2) option help texts, (3) description and additional text sections.

Examples

The following gives a simple example of how to use the ArgumentParser class.

#include <iostream>

#include <seqan/basic.h>
#include <seqan/sequence.h>
#include <seqan/stream.h>      // For printing SeqAn Strings.

#include <seqan/arg_parse.h>

using namespace seqan;

int main(int argc, char const ** argv)
{
    // Initialize ArgumentParser.
    ArgumentParser parser("arg_parse_demo");
    setCategory(parser, "Demo");
    setShortDescription(parser, "Just a demo of the new ArgumentParser!");
    setVersion(parser, "0.1");
    setDate(parser, "Mar 2012");

    // Add use and description lines.
    addUsageLine(parser, "[\\fIOPTIONS\\fP] \\fIIN\\fP \\fIOUT\\fP ");

    addDescription(
        parser,
        "This is just a little demo to show what ArgumentParser is "
        "able to do.  \\fIIN\\fP is a multi-FASTA input file.  \\fIOUT\\fP is a "
        "txt output file.");

    // Add positional arguments and set their valid file types.
    addArgument(parser, ArgParseArgument(ArgParseArgument::INPUT_FILE, "IN"));
    addArgument(parser, ArgParseArgument(ArgParseArgument::OUTPUT_FILE, "OUT"));
    setValidValues(parser, 0, "FASTA fa");
    setValidValues(parser, 1, "txt");

    // Add a section with some options.
    addSection(parser, "Important Tool Parameters");
    addOption(parser, ArgParseOption("", "id", "Sequence identity between [0.0:1.0]",
                                     ArgParseArgument::DOUBLE, "ID"));
    setRequired(parser, "id", true);
    setMinValue(parser, "id", "0.0");
    setMaxValue(parser, "id", "1.0");

    // Adding a verbose and a hidden option.
    addSection(parser, "Miscellaneous");
    addOption(parser, ArgParseOption("v", "verbose", "Turn on verbose output."));
    addOption(parser, ArgParseOption("H", "hidden", "Super mysterious flag that will not be shown in "
                                                    "the help screen or man page."));
    hideOption(parser, "H");

    // Add a Reference section.
    addTextSection(parser, "References");
    addText(parser, "http://www.seqan.de");

    // Parse the arguments.
    ArgumentParser::ParseResult res = parse(parser, argc, argv);
    // Return if there was an error or a built-in command was triggered (e.g. help).
    if (res != ArgumentParser::PARSE_OK)
        return res == ArgumentParser::PARSE_ERROR;  // 1 on errors, 0 otherwise

    // Extract and print the options.
    bool verbose = false;
    getOptionValue(verbose, parser, "verbose");
    std::cout << "Verbose:     " << (verbose ? "on" : "off") << std::endl;

    double identity = -1.0;
    getOptionValue(identity, parser, "id");
    std::cout << "Identity:    " << identity << std::endl;

    CharString inputFile, outputFile;
    getArgumentValue(inputFile, parser, 0);
    getArgumentValue(outputFile, parser, 1);

    std::cout << "Input-File:  " << inputFile << std::endl;
    std::cout << "Output-File: " << outputFile << std::endl;

    return 0;
}
$ demo_arg_parse_argument_parser in.fa out.txt --id 0
Built target seqan_core
Built target demo_arg_parse
Verbose:     off
Identity:    0
Input-File:  in.fa
Output-File: out.txt

See Also

Member Functions Detail

ArgumentParser::ArgumentParser([appName]);

Constructor

Parameters

appName The name of the application (std::string), defaults to argv[0].

Data Races

Thread safety unknown!

Interface Functions Detail

void addArgument(parser, arg);

Adds an ArgParseArgument to an ArgumentParser.

Parameters

parser The ArgumentParser to add the argument to.
arg The ArgParseArgument to add to parser.

Data Races

Thread safety unknown!

void addDefaultValue(parser, name, v);

Add/append a value to the default values for an option in an ArgumentParser.

Parameters

parser The ArgumentParser to append the default value to.
name The short or long name of the argument (std::string).
v The value to append (template parameter, must be streamable into a std::stringstream).

Data Races

Thread safety unknown!

void addDescription(parser, description);

Appends a description paragraph to the ArgumentParser documentation.

Parameters

parser The ArgumentParser to add the line to.
description The description text, a std::string.

Data Races

Thread safety unknown!

void addLine(parser, line);

Adds a line of text to the help output of the ArgumentParser.

Parameters

parser The ArgumentParser to add the line to.
line The line of text to add, StringConcept of char.

The line of text will be added to the block of the options.

Data Races

Thread safety unknown!

void addListItem(parser, item, description);

Appends a list item to the ArgumentParser

Parameters

parser The ArgumentParser to add the list item to.
item The item to add, std::string.
description The item to add, std::string.

Data Races

Thread safety unknown!

void addOption(parser, option);

Adds an ArgParseOption to an ArgumentParser.

Parameters

parser The ArgumentParser to add the option to.
option The ArgParseOption to add to parser.

Data Races

Thread safety unknown!

void addSection(parser, title);

Begins a new section of the option block of the ArgumentParser help output.

Parameters

parser The ArgumentParser to add the line to.
title The title to add, StringConcept of char.
ArgumentParser parser;

[...] // init parser

addSection(parser, "In-/Output-Options");
addOption("i", ... );
addOption("o", ... );

addSection(parser, "Other Options");
addOption("x", ... );

Data Races

Thread safety unknown!

void addText(parser, text);

Add text to an ArgumentParser.

Parameters

parser ArgumentParser to add text to.
text The std::string to add to the parser.

Data Races

Thread safety unknown!

void addTextSection(parser, title);

Add a text section to the ArgumentParser.

Parameters

parser The ArgumentParser to add the text section title to.
title The section title to add, std::string.

Data Races

Thread safety unknown!

void addTextSubSection(parser, title);

Add a text sub section to the ArgumentParser.

Parameters

parser The ArgumentParser add the subsection title to of.
title The sub section title to add, std::string.

Data Races

Thread safety unknown!

void addUsageLine(parser, line);

Adds a line of text to the usage output of the ArgumentParser.

Parameters

parser The ArgumentParser to add the line to.
line The line to add, a std::string.

Data Races

Thread safety unknown!

TCharStringRef getAppName(parser);

Return program name of ArgumentParser.

Parameters

parser The ArgumentParser to get the app name for.

Returns

TCharStringRef The app name, const-ref to CharString.

Data Races

Thread safety unknown!

TArgument getArgument(parser, pos);

Returns a reference to the given positional argument.

Parameters

parser The ArgumentParser to query.
pos The position of the argument to return (unsigned, starting at 0).

Returns

TArgument Reference to the ArgParseArgument with the given position.

Data Races

Thread safety unknown!

std::string argumentFileExtension(parser, pos[, argNo]);

Retrieve the file extension of a file argument.

Parameters

parser The ArgumentParser to get the value from.
pos The position of the argument to query (unsigned).
argNo Optional position for multi-value options (unsigned, defaults to 0).

Returns

std::string The extension of the argument if any.

Overriding File Extensions on the Command Line

For each argument with type INPUT_FILE and OUTPUT_FILE, an option with the index arg-${idx}-file-ext is automatically added to the ArgumentParser (where ${idx} is the index of the original option). The extension can be overridden by specifying the argument. Thus, the user of the program could give the value "file.ext" to the parameter "0" and override the extension on the command line to "ext2" as follows:

# program_name file.ext --arg-0-file-ext ext2

Data Races

Thread safety unknown!

See Also

bool getArgumentValue(dest, parser, pos[, no]);

Retrieves the value of an argument given by its position.

Parameters

dest The variable to write the result to (the type is a template parameter and the value type of the argument must be convertible in the type of dest for the retrieval to work, also see result value).
parser The ArgumentParser to get the value from.
pos The position of the argument to get the value of.
no Optional position for multi-value arguments (unsigned, defaults to 0).

Returns

bool true if the retrieval was successful, false otherwise.

Data Races

Thread safety unknown!

unsigned getArgumentValueCount(parser, pos);

Query number of values stored for the specified argument.

Parameters

parser The ArgumentParser to query.
name The position of the argument (unsigned, 0-based).

Returns

unsigned The number of values for the argument with the given position.

Data Races

Thread safety unknown!

TVector getArgumentValues(parser, pos);

Returns all values of an argument given on the command line.

Parameters

parser The ArgumentParser to query.
pos The position of the argument (unsigned, 0-based).

Returns

TVector The resulting values (std::vector<std::string>).

Data Races

Thread safety unknown!

TCharStringRef getCategory(parser);

Returns the category.

Parameters

parser The ArgumentParser to get the category from.

Returns

TCharString A const-ref to a CharString with the category.

Data Races

Thread safety unknown!

TCharStringRef getCitation(parser);

Returns the citation string.

Parameters

parser The ArgumentParser to get the citation string from.

Returns

TCharString A const-ref to a CharString with the citation string.

Data Races

Thread safety unknown!

TVector getFormatExtension(tag); TVector getFormatExtension(tagList); TVector getFormatExtension(tagSelector);

Returns file format extension given a format tag.

Parameters

tag A single file foramt, e.g. Fastq().
tagList A list of file format (TagList).
tagSelector A file format selector (TagSelector).

Returns

TVector A std::vector<std::string> with the allowed file format extensions.

Data Races

Thread safety unknown!

TCharStringRef getLongCopyright(parser);

Returns the long copyright string.

Parameters

parser The ArgumentParser to get the long copyright string from.

Returns

TCharString A const-ref to a CharString with the long copyright string.

Data Races

Thread safety unknown!

TOption getOption(parser, name);

Returns a reference to the specified option.

Parameters

parser The parser to query.
name The short or long name of the option (std::string).

Returns

TOption Reference to the ArgParseOption with the given short or long name.

Data Races

Thread safety unknown!

std::string getOptionFileExtension(parser, name[, pos]);

Retrieve the file extension of a file option.

Parameters

parser The ArgumentParser to get the value from.
name The short or long name of the option (std::string).
pos Optional position for multi-value options (unsigned, defaults to 0).

Returns

std::string The extension of the option. Empty if not set or no extension.

Overriding File Extension on the Command Line

For each option with type INPUT_FILE and OUTPUT_FILE, an option with the name ${name}-file-ext is automatically added to the ArgumentParser (where ${name} is the name of the original option). The extension can be overridden by specifying the argument. Thus, the user of the program could give the value "file.ext" to the parameter "fname" and override the extension on the command line to "ext2" as follows:

# program_name --fname file.ext --fname-file-ext ext2

Data Races

Thread safety unknown!

See Also

bool getOptionValue(dest, parser, name[, pos]);

Retrieve the value of an option.

Parameters

dest The variable to write the result to (the type is a template parameter and the value type of the option must be convertible in the type of dest for the retrieval to work, also see result value).
parser The ArgumentParser to get the value from.
name The short or long name of the option (std::string).
pos Optional position for multi-value options (unsigned, defaults to 0).

Returns

bool true if the requested option was given on the command line and could be coverted to the type of dest.

Data Races

Thread safety unknown!

unsigned getOptionValueCount(parser, name);

Query number of values stored for the specified option.

Parameters

parser The ArgumentParser to query.
name The short or long name of the option (string).

Returns

unsigned The number of values for the option with the given name.

Data Races

Thread safety unknown!

TVector getOptionValues(parser, name);

Returns all values of an option given on the command line.

Parameters

parser The ArgumentParser to query.
name The short or long name of the option to get (std::string).

Returns

TVector The resulting values (std::vector<std::string>).

Data Races

Thread safety unknown!

TCharStringRef getShortCopyright(parser);

Returns the short copyright string.

Parameters

parser The ArgumentParser to get the short copyright string from.

Returns

TCharString A const-ref to a CharString with the short copyright string.

Data Races

Thread safety unknown!

CharString getShortDescription(parser);

Returns the short description.

Parameters

parser The ArgumentParser to get short description for.

Returns

CharString A CharString with the short description.

Data Races

Thread safety unknown!

TCharStringRef getVersion(parser);

Returns the version string.

Parameters

parser The ArgumentParser to get the version string from.

Returns

TCharString A const-ref to a CharString with the version string.

Data Races

Thread safety unknown!

bool hasDefault(parser, name);

Query whether an option has a default value.

Parameters

parser The ArgumentParser to query.
name The short or long name of the option (std::string).

Returns

bool Whether or not the option has a default value.

Data Races

Thread safety unknown!

bool hasOption(parser, name);

Query whether a certain option is registered in the parser.

Parameters

parser The ArgumentParser to query.
name The name to query for (std::string).

Returns

bool true if there is such an option, false otherwise.

Data Races

Thread safety unknown!

void hideOption(parser, name[, hide]).

Hides the ArgParseOption with the given name.

Parameters

parser The ArgParseOption to the the hidden flag of.
name The short or long name of the option to modify.
hide Whether or not to hide the flag (bool, defaults to true).

Data Races

Thread safety unknown!

bool isSet(parser, name);

Query whether an option was set on the command line.

Parameters

parser The ArgumentParser to query.
name The short or long name of the option (std::string).

Returns

bool Whether or not the option was set on the command line or not.

Data Races

Thread safety unknown!

TResult parse(parser, argc, argv[, outStream[, errStream]]);

Parse command line parameters.

Parameters

parser The ArgumentParser to use for parsing and for storing parse results.
argc The number of arguments (int).
argv The arguments (const char * argv[]).
outStream The std::ostream to use for output.
errStream The std::ostream to use for error output.

Returns

TResult The parse result, of type ArgumentParser::ParseResult.

This function must be called before retrieving any options or arguments from the parser.

Data Races

Thread safety unknown!

void printHelp(parser, out, format, showAdvancedOptions);

Prints the help message for the parser.

Parameters

parser The ArgumentParser print the help for.
out The output stream to print to (std::ostream).
format The format to print, one of "html", "man", and "txt".
showAdvancedOptions Also show advanced options to user (default = false).

Data Races

Thread safety unknown!

void printLongCopyright(parser, stream);

Prints the long copyright information of the parser to a stream.

Parameters

parser The ArgumenParser to print for.
stream The std::ostream to print to.

Data Races

Thread safety unknown!

void printShortHelp(parser, out);

Prints a short help message for the parser to a stream.

Parameters

parser The ArgumentParser to print help for.
out The std::ostream to print help to.

Data Races

Thread safety unknown!

void printVersion(parser, stream);

Prints the version information of the parser to a stream.

Parameters

parser The ArgumenParser to print for.
stream The std::ostream to print to.

Data Races

Thread safety unknown!

void setAdvanced(parser, name[, required]).

Sets whether or not the option with the givne name is advanced.

Parameters

parser The ArgumentParser to set the flag of.
name The short or long name of the option (std::string).
required Whether or not the option is required (bool, default to true).

Data Races

Thread safety unknown!

void setAppName(parser, name);

Sets application name of ArgumentParser.

Parameters

parser The ArgumentParser to set the name of.
name The application name, std::string.

Data Races

Thread safety unknown!

void setCategory(parser, category);

Sets category of ArgumentParser.

Parameters

parser The ArgumentParser to set the category of.
category The category to set, std::string.

Data Races

Thread safety unknown!

void setCitation(parser, citation);

Sets citation of ArgumentParser.

Parameters

parser The ArgumentParser to set the citation of.
citation The citation string to set, std::string.

Data Races

Thread safety unknown!

void setDate(parser, date);

Sets date string of ArgumentParser.

Parameters

parser The ArgumentParser to set the date string of.
date The date string to set, std::string.

Data Races

Thread safety unknown!

void setDefaultValue(parser, name, v);

Set the default value of an option of an ArgumentParser.

Parameters

parser The ArgumentParser to set the default value to.
name The short or long name of the argument (std::string).
v The value to set (template parameter, must be streamable into a std::stringstream).

Data Races

Thread safety unknown!

void setHelpText(parser, name, text); void setHelpText(parser, pos, text);

Set the help text of an option or argument.

Parameters

parser The ArgumentParser object.
name The name of the option to set the help text for (std::string).
pos The position of the argument to set the help text for.
text The string to use for the help text (std::string).

Data Races

Thread safety unknown!

void setLongCopyright(parser, long copyright);

Sets long copyright of ArgumentParser.

Parameters

parser The ArgumentParser to set the long copyright of.
long copyright The long copyright string to set, std::string.

Data Races

Thread safety unknown!

void setMaxValue(parser, name, v); void setMaxValue(parser, pos, v);

Set largest allowed value for an option or argument of an ArgumentParser.

Parameters

parser The ArgumentParser to set the maximal value for.
name The name of the option to set the maximal value for (std::string).
pos The position of the argument to set the maximal value for (unsigned, 0-based).
v The maximal value to set (std::string).

Remarks

The option/argument must have an integer or double type.

Data Races

Thread safety unknown!

void setMinValue(parser, name, v); void setMinValue(parser, pos, v);

Set smallest allowed value for an option or argument of an ArgumentParser.

Parameters

parser The ArgumentParser to set the minimal value for.
name The name of the option to set the minimal value for (std::string).
pos The position of the argument to set the minimal value for (unsigned, 0-based).
v The minimal value to set (std::string).

Remarks

The option/argument must have an integer or double type.

Data Races

Thread safety unknown!

void setRequired(parser, name[, required]).

Sets whether or not the option with the givne name is mandatory.

Parameters

parser The ArgumentParser to set the flag of.
name The short or long name of the option (std::string).
required Whether or not the option is required (bool, default to true).

Data Races

Thread safety unknown!

void setShortCopyright(parser, short copyright);

Sets short copyright of ArgumentParser.

Parameters

parser The ArgumentParser to set the short copyright of.
short copyright The short copyright string to set, std::string.

Data Races

Thread safety unknown!

void setShortDescription(parser, desc);

Sets shortDescription of ArgumentParser.

Parameters

parser The ArgumentParser to set the short description of.
desc The short description, std::string.

Data Races

Thread safety unknown!

void setValidValues(parser, name, values); void setValidValues(parser, pos, values);

Set valid values for an argumetn or option of an ArgumentParser.

Parameters

parser The ArgumentParser to set the default values to.
name The name of the option (std::string).
pos The position of the argument (unsigned, 0-based).
values The values to set. Either a std::string with the values as space-separated list or a std::vector<std::string> with the values.

Data Races

Thread safety unknown!

void setVersion(parser, version);

Sets version of ArgumentParser.

Parameters

parser The ArgumentParser to set the version of.
version The version string to set, std::string.

Data Races

Thread safety unknown!

bool writeCTD(parser[, stream]);

Export the app's interface description to a .ctd file.

Parameters

parser The ArgumentParser to write the CTD file for.
stream A std::ostream to write to. If omitted an output file with the name form the "write-ctd" parameter of the parser is used.

Returns

bool true on success, false on failure.

Data Races

Thread safety unknown!