# Class ArgumentParser
Parse the command line.

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

## Member Function Overview

- `ArgumentParser::ArgumentParser([appName]);`
  Constructor

## Interface Function Overview

- `void addArgument(parser, arg);`
  Adds an ArgParseArgument to an ArgumentParser.
- `void addDefaultValue(parser, name, v);`
  Add/append a value to the default values for an option in an ArgumentParser.
- `void addDescription(parser, description);`
  Appends a description paragraph to the ArgumentParser documentation.
- `void addLine(parser, line);`
  Adds a line of text to the help output of the ArgumentParser.
- `void addListItem(parser, item, description);`
  Appends a list item to the ArgumentParser
- `void addOption(parser, option);`
  Adds an ArgParseOption to an ArgumentParser.
- `void addSection(parser, title);`
  Begins a new section of the option block of the ArgumentParser help output.
- `void addText(parser, text);`
  Add text to an ArgumentParser.
- `void addTextSection(parser, title);`
  Add a text section to the ArgumentParser.
- `void addTextSubSection(parser, title);`
  Add a text sub section to the ArgumentParser.
- `void addUsageLine(parser, line);`
  Adds a line of text to the usage output of the ArgumentParser.
- `TCharStringRef getAppName(parser);`
  Return program name of ArgumentParser.
- `TArgument getArgument(parser, pos);`
  Returns a reference to the given positional argument.
- `std::string argumentFileExtension(parser, pos[, argNo]);`
  Retrieve the file extension of a file argument.
- `bool getArgumentValue(dest, parser, pos[, no]);`
  Retrieves the value of an argument given by its position.
- `unsigned getArgumentValueCount(parser, pos);`
  Query number of values stored for the specified argument.
- `TVector getArgumentValues(parser, pos);`
  Returns all values of an argument given on the command line.
- `TCharStringRef getCategory(parser);`
  Returns the category.
- `TVector getFormatExtension(tag);, TVector getFormatExtension(tagList);, TVector getFormatExtension(tagSelector);`
  Returns file format extension given a format tag.
- `TOption getOption(parser, name);`
  Returns a reference to the specified option.
- `std::string getOptionFileExtension(parser, name[, pos]);`
  Retrieve the file extension of a file option.
- `bool getOptionValue(dest, parser, name[, pos]);`
  Retrieve the value of an option.
- `unsigned getOptionValueCount(parser, name);`
  Query number of values stored for the specified option.
- `TVector getOptionValues(parser, name);`
  Returns all values of an option given on the command line.
- `CharString getShortDescription(parser);`
  Returns the short description.
- `TCharStringRef getVersion(parser);`
  Returns the version string.
- `bool hasDefault(parser, name);`
  Query whether an option has a default value.
- `bool hasOption(parser, name);`
  Query whether a certain option is registered in the parser.
- `void hideOption(parser, name[, hide]).`
  Hides the ArgParseOption with the given name.
- `bool isSet(parser, name);`
  Query whether an option was set on the command line.
- `TResult parse(parser, argc, argv[, outStream[, errStream]]);`
  Parse command line parameters.
- `void printHelp(parser, out, format);`
  Prints the complete help message for the parser.
- `void printShortHelp(parser, out);`
  Prints a short help message for the parser to a stream.
- `void printVersion(parser, stream);`
  Prints the version information of the parser to a stream.
- `void setAppName(parser, name);`
  Sets application name of ArgumentParser.
- `void setCategory(parser, category);`
  Sets category of ArgumentParser.
- `void setDate(parser, date);`
  Sets date string of ArgumentParser.
- `void setDefaultValue(parser, name, v);`
  Set the default value of an option of an ArgumentParser.
- `void setHelpText(parser, name, text);, void setHelpText(parser, pos, text);`
  Set the help text of an option or argument.
- `void setMaxValue(parser, name, v);, void setMaxValue(parser, pos, v);`
  Set largest allowed value for an option or argument of an ArgumentParser.
- `void setMinValue(parser, name, v);, void setMinValue(parser, pos, v);`
  Set smallest allowed value for an option or argument of an ArgumentParser.
- `void setRequired(parser, name[, required]).`
  Sets whether or not the option with the givne name is mandatory.
- `void setShortDescription(parser, desc);`
  Sets shortDescription of ArgumentParser.
- `void setValidValues(parser, name, values);, void setValidValues(parser, pos, values);`
  Set valid values for an argumetn or option of an ArgumentParser.
- `void setVersion(parser, version);`
  Sets version of ArgumentParser.
- `bool writeCTD(parser[, stream]);`
  Export the app's interface description to a .ctd file.

## 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: demos/dox/arg_parse/argument_parser.cpp

    $ 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

- ArgParseArgument
- ArgParseOption
- ToolDoc

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

- getOptionFileExtension

### `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!

### `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!

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

- getArgumentFileExtension

### `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!

### `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);`

Prints the complete 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".

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

#### Dox Sources

    /*!
     * @class ArgumentParser
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Parse the command line.
     *
     * @signature class ArgumentParser;
     *
     * Options are stored as @link ArgParseOption @endlink and @link
     * ArgParseArgument @endlink objects.
     *
     * @section Remarks
     *
     * See the documentation of @link ToolDoc @endlink 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.
     *
     * @section Examples
     *
     * The following gives a simple example of how to use the ArgumentParser class.
     *
     * @include demos/dox/arg_parse/argument_parser.cpp
     *
     * @code{.console}
     * $ 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
     * @endcode
     *
     *
     * @see ArgParseArgument
     * @see ArgParseOption
     * @see ToolDoc
     *
     * @fn ArgumentParser::ArgumentParser
     *
     * @brief Constructor
     *
     * @signature ArgumentParser::ArgumentParser([appName]);
     *
     * @param[in] appName The name of the application (<tt>std::string</tt>),
     *                    defaults to <tt>argv[0]</tt>.
     *
     * @fn ArgumentParser#writeCTD
     *
     * @headerfile <seqan/arg_parse.h>\
     *
     * @brief Export the app's interface description to a .ctd file.
     *
     * @signature bool writeCTD(parser[, stream]);
     *
     * @param[in] parser The ArgumentParser to write the CTD file for.
     * @param[out] stream A <tt>std::ostream</tt> to write to. If omitted an output
     *                    file with the name form the "write-ctd" parameter of the
     *                    parser is used.
     *
     * @return bool <tt>true</tt> on success, <tt>false</tt> on failure.
     *
     * @fn ArgumentParser#getAppName
     *
     * @brief Return program name of ArgumentParser.
     *
     * @signature TCharStringRef getAppName(parser);
     *
     * @param[in] parser The ArgumentParser to get the app name for.
     *
     * @return TCharStringRef The app name, const-ref to @link CharString @endlink.
     *
     * @fn ArgumentParser#addLine
     *
     * @brief Adds a line of text to the help output of the ArgumentParser.
     *
     * @signature void addLine(parser, line);
     *
     * @param[in,out] parser The ArgumentParser to add the line to.
     * @param[in] line The line of text to add, @link StringConcept @endlink of
     *                 <tt>char</tt>.
     *
     * The line of text will be added to the block of the options.
     *
     * @fn ArgumentParser#addSection
     *
     * @brief Begins a new section of the option block of the ArgumentParser help
     *        output.
     *
     * @signature void addSection(parser, title);
     *
     * @param[in,out] parser The ArgumentParser to add the line to.
     * @param[in] title The title to add, @link StringConcept @endlink of
     *                  <tt>char</tt>.
     *
     * @code{.cpp}
     * ArgumentParser parser;
     *
     * [...] // init parser
     *
     * addSection(parser, "In-/Output-Options");
     * addOption("i", ... );
     * addOption("o", ... );
     *
     * addSection(parser, "Other Options");
     * addOption("x", ... );
     * @endcode
     *
     *
     * @fn ArgumentParser#addUseLine
     *
     * @brief Adds a line of text to the usage output of the ArgumentParser.
     *
     * @signature void addUsageLine(parser, line);
     *
     * @param[in,out] parser The ArgumentParser to add the line to.
     * @param[in] line The line to add, a <tt>std::string</tt>.
     *
     * @fn ArgumentParser#addDescription
     *
     * @brief Appends a description paragraph to the ArgumentParser documentation.
     *
     * @signature void addDescription(parser, description);
     *
     * @param[in,out] parser The ArgumentParser to add the line to.
     * @param[in] description The description text, a <tt>std::string</tt>.
     *
     * @fn ArgumentParser#setAppName
     *
     * @brief Sets application name of ArgumentParser.
     *
     * @signature void setAppName(parser, name);
     *
     * @param[in,out] parser The ArgumentParser to set the name of.
     * @param[in] name The application name, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#setShortDescription
     *
     * @brief Sets shortDescription of ArgumentParser.
     *
     * @signature void setShortDescription(parser, desc);
     *
     * @param[in,out] parser The ArgumentParser to set the short description of.
     * @param[in] desc The short description, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#getShortDescription
     *
     * @brief Returns the short description.
     *
     * @signature CharString getShortDescription(parser);
     *
     * @param[in,out] parser The ArgumentParser to get short description for.
     *
     * @return CharString A @link CharString @endlink with the short description.
     *
     * @fn ArgumentParser#setVersion
     *
     * @brief Sets version of ArgumentParser.
     *
     * @signature void setVersion(parser, version);
     *
     * @param[in,out] parser The ArgumentParser to set the version of.
     * @param[in] version The version string to set, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#getVersion
     *
     * @brief Returns the version string.
     *
     * @signature TCharStringRef getVersion(parser);
     *
     * @param[in,out] parser The ArgumentParser to get the version string from.
     *
     * @return TCharString A const-ref to a @link CharString @endlink with the
     *                     version string.
     *
     * @fn ArgumentParser#setCategory
     *
     * @brief Sets category of ArgumentParser.
     *
     * @signature void setCategory(parser, category);
     *
     * @param[in,out] parser The ArgumentParser to set the category of.
     * @param[in] category The category to set, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#getCategory
     *
     * @brief Returns the category.
     *
     * @signature TCharStringRef getCategory(parser);
     *
     * @param[in,out] parser The ArgumentParser to get the category from.
     *
     * @return TCharString A const-ref to a @link CharString @endlink with the
     *                     category.
     *
     * @fn ArgumentParser#setDate
     *
     * @brief Sets date string of ArgumentParser.
     *
     * @signature void setDate(parser, date);
     *
     * @param[in,out] parser The ArgumentParser to set the date string of.
     * @param[in] date The date string to set, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#addTextSection
     *
     * @brief Add a text section to the ArgumentParser.
     *
     * @signature void addTextSection(parser, title);
     *
     * @param[in,out] parser The ArgumentParser to add the text section title to.
     * @param[in] title The section title to add, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#addTextSubSection
     *
     * @brief Add a text sub section to the ArgumentParser.
     *
     * @signature void addTextSubSection(parser, title);
     *
     * @param[in,out] parser The ArgumentParser add the subsection title to of.
     * @param[in] title The sub section title to add, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#addText
     *
     * @brief Add text to an ArgumentParser.
     *
     * @signature void addText(parser, text);
     *
     * @param[in,out] parser ArgumentParser to add text to.
     * @param[in] text The <tt>std::string</tt> to add to the parser.
     *
     * @fn ArgumentParser#addListItem
     *
     * @brief Appends a list item to the ArgumentParser
     *
     * @signature void addListItem(parser, item, description);
     *
     * @param[in,out] parser The ArgumentParser to add the list item to.
     * @param[in] item The item to add, <tt>std::string</tt>.
     * @param[in] description The item to add, <tt>std::string</tt>.
     *
     * @fn ArgumentParser#printShortHelp
     *
     * @brief Prints a short help message for the parser to a stream.
     *
     * @signature void printShortHelp(parser, out);
     *
     * @param[in,out] parser The ArgumentParser to print help for.
     * @param[in,out] out The <tt>std::ostream</tt> to print help to.
     *
     * @fn ArgumentParser#printVersion
     *
     * @brief Prints the version information of the parser to a stream.
     *
     * @signature void printVersion(parser, stream);
     *
     * @param[in,out] parser The ArgumenParser to print for.
     * @param[in,out] stream The <tt>std::ostream</tt> to print to.
     *
     * @fn ArgumentParser#printHelp
     *
     * @brief Prints the complete help message for the parser.
     *
     * @signature void printHelp(parser, out, format);
     *
     * @param[in,out] parser The ArgumentParser print the help for.
     * @param[out] out The output stream to print to (<tt>std::ostream</tt>).
     * @param[in] format The format to print, one of "html", "man", and "txt".
     *
     * @fn ArgumentParser#parse
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Parse command line parameters.
     *
     * @signature TResult parse(parser, argc, argv[, outStream[, errStream]]);
     *
     * @param[in,out] parser The ArgumentParser to use for parsing and for storing
     *                       parse results.
     * @param[in] argc The number of arguments (<tt>int</tt>).
     * @param[in] argv The arguments (<tt>const char * argv[]</tt>).
     * @param[in,out] outStream The <tt>std::ostream</tt> to use for output.
     * @param[in,out] errStream The <tt>std::ostream</tt> to use for error output.
     *
     * @return TResult The parse result, of type @link ArgumentParser::ParseResult
     *                 @endlink.
     *
     * This function must be called before retrieving any options or arguments from
     * the parser.
     *
     * @fn ArgumentParser#hasOption
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Query whether a certain option is registered in the parser.
     *
     * @signature bool hasOption(parser, name);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] name The name to query for (<tt>std::string</tt>).
     *
     * @return bool <tt>true</tt> if there is such an option, <tt>false</tt>
     *              otherwise.
     *
     * @fn ArgumentParser#addOption
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Adds an @link ArgParseOption @endlink to an ArgumentParser.
     *
     * @signature void addOption(parser, option);
     *
     * @param[in,out] parser The ArgumentParser to add the option to.
     * @param[in] option The ArgParseOption to add to <tt>parser</tt>.
     *
     * @fn ArgumentParser#addArgument
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Adds an @link ArgParseArgument @endlink to an ArgumentParser.
     *
     * @signature void addArgument(parser, arg);
     *
     * @param[in,out] parser The ArgumentParser to add the argument to.
     * @param[in] arg The ArgParseArgument to add to <tt>parser</tt>.
     *
     * @fn ArgumentParser#getOption
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns a reference to the specified option.
     *
     * @signature TOption getOption(parser, name);
     *
     * @param[in] parser The parser to query.
     * @param[in] name The short or long name of the option (<tt>std::string</tt>).
     *
     * @return TOption Reference to the @link ArgParseOption @endlink with the given
     *                 short or long name.
     *
     * @fn ArgumentParser#setRequired
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Sets whether or not the option with the givne name is mandatory.
     *
     * @signature void setRequired(parser, name[, required]).
     *
     * @param[in,out] parser The ArgumentParser to set the flag of.
     * @param[in] name The short or long name of the option (<tt>std::string</tt>).
     * @param[in] required Whether or not the option is required (<tt>bool</tt>,
     *                     default to <tt>true</tt>).
     *
     * @fn ArgumentParser#hideOption
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Hides the ArgParseOption with the given name.
     *
     * @signature void hideOption(parser, name[, hide]).
     *
     * @param[in,out] parser The ArgParseOption to the the hidden flag of.
     * @param[in] name The short or long name of the option to modify.
     * @param[in] hide Whether or not to hide the flag (<tt>bool</tt>, defaults to
     *                 <tt>true</tt>).
     *
     * @fn ArgumentParser#getArgument
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns a reference to the given positional argument.
     *
     * @signature TArgument getArgument(parser, pos);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] pos The position of the argument to return (<tt>unsigned</tt>,
     *                starting at 0).
     *
     * @return TArgument Reference to the @link ArgParseArgument @endlink with the
     *                   given position.
     *
     * @fn ArgumentParser#isSet
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Query whether an option was set on the command line.
     *
     * @signature bool isSet(parser, name);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] name The short or long name of the option (<tt>std::string</tt>).
     *
     * @return bool Whether or not the option was set on the command line or not.
     *
     * @fn ArgumentParser#hasDefault
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Query whether an option has a default value.
     *
     * @signature bool hasDefault(parser, name);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] name The short or long name of the option (<tt>std::string</tt>).
     *
     * @return bool Whether or not the option has a default value.
     *
     * @fn ArgumentParser#getOptionValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Retrieve the value of an option.
     *
     * @signature bool getOptionValue(dest, parser, name[, pos]);
     *
     * @param[in] 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 <tt>dest</tt> for the retrieval to
     *                 work, also see result value).
     * @param[in] parser The ArgumentParser to get the value from.
     * @param[in] name The short or long name of the option (<tt>std::string</tt>).
     * @param[in] pos Optional position for multi-value options (<tt>unsigned</tt>,
     *                defaults to 0).
     *
     * @return bool <tt>true</tt> if the requested option was given on the command
     *              line and could be coverted to the type of <tt>dest</tt>.
     *
     * @fn ArgumentParser#getOptionFileExtension
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Retrieve the file extension of a file option.
     *
     * @signature std::string getOptionFileExtension(parser, name[, pos]);
     *
     * @param[in] parser The ArgumentParser to get the value from.
     * @param[in] name The short or long name of the option (<tt>std::string</tt>).
     * @param[in] pos Optional position for multi-value options (<tt>unsigned</tt>,
     *                defaults to 0).
     *
     * @return std::string The extension of the option. Empty if not set or no
     *                     extension.
     *
     * @section Overriding File Extension on the Command Line
     *
     * For each option with type <tt>INPUT_FILE</tt> and <tt>OUTPUT_FILE</tt>, an
     * option with the name <tt>${name}-file-ext</tt> is automatically added to the
     * ArgumentParser (where <tt>${name}</tt> 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:
     *
     * @code{.console}
     * # program_name --fname file.ext --fname-file-ext ext2
     * @endcode
     *
     *
     * @see ArgumentParser#getArgumentFileExtension
     *
     * @fn ArgumentParser#getOptionValueCount
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Query number of values stored for the specified option.
     *
     * @signature unsigned getOptionValueCount(parser, name);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] name The short or long name of the option (<tt>string</tt>).
     *
     * @return unsigned The number of values for the option with the given name.
     *
     * @fn ArgumentParser#getArgumentValueCount
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Query number of values stored for the specified argument.
     *
     * @signature unsigned getArgumentValueCount(parser, pos);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] name The position of the argument (<tt>unsigned</tt>, 0-based).
     *
     * @return unsigned The number of values for the argument with the given
     *                  position.
     *
     * @fn ArgumentParser#getArgumentValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Retrieves the value of an argument given by its position.
     *
     * @signature bool getArgumentValue(dest, parser, pos[, no]);
     *
     * @param[in] 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 <tt>dest</tt> for the retrieval to
     *                 work, also see result value).
     * @param[in] parser The ArgumentParser to get the value from.
     * @param[in] pos The position of the argument to get the value of.
     * @param[in] no Optional position for multi-value arguments (<tt>unsigned</tt>,
     *               defaults to 0).
     *
     * @return bool <tt>true</tt> if the retrieval was successful, <tt>false</tt>
     *              otherwise.
     *
     * @fn ArgumentParser#getArgumentFileExtension
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Retrieve the file extension of a file argument.
     *
     * @signature std::string argumentFileExtension(parser, pos[, argNo]);
     *
     * @param[in] parser The ArgumentParser to get the value from.
     * @param[in] pos The position of the argument to query (<tt>unsigned</tt>).
     * @param[in] argNo Optional position for multi-value options
     *                  (<tt>unsigned</tt>, defaults to 0).
     *
     * @return std::string The extension of the argument if any.
     *
     * @section Overriding File Extensions on the Command Line
     *
     * For each argument with type <tt>INPUT_FILE</tt> and <tt>OUTPUT_FILE</tt>, an
     * option with the index <tt>arg-${idx}-file-ext</tt> is automatically added to
     * the ArgumentParser (where <tt>${idx}</tt> 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:
     *
     * @code{.console}
     * # program_name file.ext --arg-0-file-ext ext2
     * @endcode
     *
     *
     * @see ArgumentParser#getOptionFileExtension
     *
     * @fn ArgumentParser#getOptionValues
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns all values of an option given on the command line.
     *
     * @signature TVector getOptionValues(parser, name);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] name The short or long name of the option to get
     *                 (<tt>std::string</tt>).
     *
     * @return TVector The resulting values
     *                 (<tt>std::vector&lt;std::string&gt;</tt>).
     *
     * @fn ArgumentParser#getArgumentValues
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns all values of an argument given on the command line.
     *
     * @signature TVector getArgumentValues(parser, pos);
     *
     * @param[in] parser The ArgumentParser to query.
     * @param[in] pos The position of the argument (<tt>unsigned</tt>, 0-based).
     *
     * @return TVector The resulting values
     *                 (<tt>std::vector&lt;std::string&gt;</tt>).
     *
     * @fn ArgumentParser#setDefaultValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the default value of an option of an ArgumentParser.
     *
     * @signature void setDefaultValue(parser, name, v);
     *
     * @param[in] parser The ArgumentParser to set the default value to.
     * @param[in] name The short or long name of the argument
     *                 (<tt>std::string</tt>).
     * @param[in] v The value to set (template parameter, must be streamable into a
     *              <tt>std::stringstream</tt>).
     *
     * @fn ArgumentParser#addDefaultValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Add/append a value to the default values for an option in an
     *        ArgumentParser.
     *
     * @signature void addDefaultValue(parser, name, v);
     *
     * @param[in,out] parser The ArgumentParser to append the default value to.
     * @param[in] name The short or long name of the argument
     *                 (<tt>std::string</tt>).
     * @param[in] v The value to append (template parameter, must be streamable into
     *              a <tt>std::stringstream</tt>).
     *
     * @fn ArgumentParser#setMinValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set smallest allowed value for an option or argument of an
     *        ArgumentParser.
     *
     * @signature void setMinValue(parser, name, v);
     * @signature void setMinValue(parser, pos, v);
     *
     * @param[in,out] parser The ArgumentParser to set the minimal value for.
     * @param[in] name The name of the option to set the minimal value for
     *                 (<tt>std::string</tt>).
     * @param[in] pos The position of the argument to set the minimal value for
     *                (<tt>unsigned</tt>, 0-based).
     * @param[in] v The minimal value to set (<tt>std::string</tt>).
     *
     * @section Remarks
     *
     * The option/argument must have an integer or double type.
     *
     * @fn ArgumentParser#setMaxValue
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set largest allowed value for an option or argument of an
     *        ArgumentParser.
     *
     * @signature void setMaxValue(parser, name, v);
     * @signature void setMaxValue(parser, pos, v);
     *
     * @param[in,out] parser The ArgumentParser to set the maximal value for.
     * @param[in] name The name of the option to set the maximal value for
     *                 (<tt>std::string</tt>).
     * @param[in] pos The position of the argument to set the maximal value for
     *                (<tt>unsigned</tt>, 0-based).
     * @param[in] v The maximal value to set (<tt>std::string</tt>).
     *
     * @section Remarks
     *
     * The option/argument must have an integer or double type.
     *
     * @fn ArgumentParser#setValidValues
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set valid values for an argumetn or option of an ArgumentParser.
     *
     * @signature void setValidValues(parser, name, values);
     * @signature void setValidValues(parser, pos, values);
     *
     * @param[in,out] parser The ArgumentParser to set the default values to.
     * @param[in] name The name of the option (<tt>std::string</tt>).
     * @param[in] pos The position of the argument (<tt>unsigned</tt>, 0-based).
     * @param[in] values The values to set. Either a <tt>std::string</tt> with the
     *                   values as space-separated list or a
     *                   <tt>std::vector&lt;std::string&gt;</tt> with the values.
     *
     * @fn ArgumentParser#setHelpText
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the help text of an option or argument.
     *
     * @signature void setHelpText(parser, name, text);
     * @signature void setHelpText(parser, pos, text);
     *
     * @param[in,out] parser The ArgumentParser object.
     * @param[in] name The name of the option to set the help text for
     *                 (<tt>std::string</tt>).
     * @param[in] pos The position of the argument to set the help text for.
     * @param[in] text The string to use for the help text (<tt>std::string</tt>).
     *
     * @fn ArgumentParser#getFileExtensions
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Returns file format extension given a format tag.
     *
     * @signature TVector getFormatExtension(tag);
     * @signature TVector getFormatExtension(tagList);
     * @signature TVector getFormatExtension(tagSelector);
     *
     * @param[in] tag A single file foramt, e.g. <tt>Fastq()</tt>.
     * @param[in] tagList A list of file format (@link TagList @endlink).
     * @param[in] tagSelector A file format selector (@link TagSelector @endlink).
     *
     * @return TVector A <tt>std::vector&lt;std::string&gt;</tt> with the allowed
     *                 file format extensions.
     */