/*!
* @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#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#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<std::string></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<std::string></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<std::string></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<std::string></tt> with the allowed
* file format extensions.
*
* @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#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.
*/