Class
ArgumentParserParse 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. -
TCharStringRef getCitation(parser);
Returns the citation string. -
TVector getFormatExtension(tag);, TVector getFormatExtension(tagList);, TVector getFormatExtension(tagSelector);
Returns file format extension given a format tag. -
TCharStringRef getLongCopyright(parser);
Returns the long copyright string. -
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. -
TCharStringRef getShortCopyright(parser);
Returns the short copyright string. -
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, showAdvancedOptions);
Prints the help message for the parser. -
void printLongCopyright(parser, stream);
Prints the long copyright information of the parser to a stream. -
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 setAdvanced(parser, name[, required]).
Sets whether or not the option with the givne name is advanced. -
void setAppName(parser, name);
Sets application name of ArgumentParser. -
void setCategory(parser, category);
Sets category of ArgumentParser. -
void setCitation(parser, citation);
Sets citation 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 setLongCopyright(parser, long copyright);
Sets long copyright of ArgumentParser. -
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 setShortCopyright(parser, short copyright);
Sets short copyright of ArgumentParser. -
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_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]);
Parameters
appName
|
The name of the application (std::string), defaults to argv[0]. |
---|
Data Races
Interface Functions Detail
void addArgument(parser, arg);
Parameters
parser
|
The ArgumentParser to add the argument to. |
---|---|
arg
|
The ArgParseArgument to add to parser. |
Data Races
void addDefaultValue(parser, name, v);
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
void addDescription(parser, description);
Parameters
parser
|
The ArgumentParser to add the line to. |
---|---|
description
|
The description text, a std::string. |
Data Races
void addLine(parser, line);
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
void addListItem(parser, item, description);
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
void addOption(parser, option);
Parameters
parser
|
The ArgumentParser to add the option to. |
---|---|
option
|
The ArgParseOption to add to parser. |
Data Races
void addSection(parser, title);
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
void addText(parser, text);
Parameters
parser
|
ArgumentParser to add text to. |
---|---|
text
|
The std::string to add to the parser. |
Data Races
void addTextSection(parser, title);
Parameters
parser
|
The ArgumentParser to add the text section title to. |
---|---|
title
|
The section title to add, std::string. |
Data Races
void addTextSubSection(parser, title);
Parameters
parser
|
The ArgumentParser add the subsection title to of. |
---|---|
title
|
The sub section title to add, std::string. |
Data Races
void addUsageLine(parser, line);
Parameters
parser
|
The ArgumentParser to add the line to. |
---|---|
line
|
The line to add, a std::string. |
Data Races
TCharStringRef getAppName(parser);
Parameters
parser
|
The ArgumentParser to get the app name for. |
---|
Returns
TCharStringRef |
The app name, const-ref to CharString. |
---|
Data Races
TArgument getArgument(parser, pos);
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
std::string argumentFileExtension(parser, pos[, argNo]);
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
See Also
bool getArgumentValue(dest, parser, pos[, no]);
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
unsigned getArgumentValueCount(parser, pos);
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
TVector getArgumentValues(parser, pos);
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
TCharStringRef getCategory(parser);
Parameters
parser
|
The ArgumentParser to get the category from. |
---|
Returns
TCharString |
A const-ref to a CharString with the category. |
---|
Data Races
TCharStringRef getCitation(parser);
Parameters
parser
|
The ArgumentParser to get the citation string from. |
---|
Returns
TCharString |
A const-ref to a CharString with the citation string. |
---|
Data Races
TVector getFormatExtension(tag);
TVector getFormatExtension(tagList);
TVector getFormatExtension(tagSelector);
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
TCharStringRef getLongCopyright(parser);
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
TOption getOption(parser, name);
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
std::string getOptionFileExtension(parser, name[, pos]);
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
See Also
bool getOptionValue(dest, parser, name[, pos]);
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
unsigned getOptionValueCount(parser, name);
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
TVector getOptionValues(parser, name);
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
TCharStringRef getShortCopyright(parser);
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
CharString getShortDescription(parser);
Parameters
parser
|
The ArgumentParser to get short description for. |
---|
Returns
CharString |
A CharString with the short description. |
---|
Data Races
TCharStringRef getVersion(parser);
Parameters
parser
|
The ArgumentParser to get the version string from. |
---|
Returns
TCharString |
A const-ref to a CharString with the version string. |
---|
Data Races
bool hasDefault(parser, name);
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
bool hasOption(parser, name);
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
void hideOption(parser, name[, hide]).
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
bool isSet(parser, name);
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
TResult parse(parser, argc, argv[, outStream[, errStream]]);
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
void printHelp(parser, out, format, showAdvancedOptions);
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
void printLongCopyright(parser, stream);
Parameters
parser
|
The ArgumenParser to print for. |
---|---|
stream
|
The std::ostream to print to. |
Data Races
void printShortHelp(parser, out);
Parameters
parser
|
The ArgumentParser to print help for. |
---|---|
out
|
The std::ostream to print help to. |
Data Races
void printVersion(parser, stream);
Parameters
parser
|
The ArgumenParser to print for. |
---|---|
stream
|
The std::ostream to print to. |
Data Races
void setAdvanced(parser, name[, required]).
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
void setAppName(parser, name);
Parameters
parser
|
The ArgumentParser to set the name of. |
---|---|
name
|
The application name, std::string. |
Data Races
void setCategory(parser, category);
Parameters
parser
|
The ArgumentParser to set the category of. |
---|---|
category
|
The category to set, std::string. |
Data Races
void setCitation(parser, citation);
Parameters
parser
|
The ArgumentParser to set the citation of. |
---|---|
citation
|
The citation string to set, std::string. |
Data Races
void setDate(parser, date);
Parameters
parser
|
The ArgumentParser to set the date string of. |
---|---|
date
|
The date string to set, std::string. |
Data Races
void setDefaultValue(parser, name, v);
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
void setHelpText(parser, name, text);
void setHelpText(parser, pos, text);
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
void setLongCopyright(parser, long copyright);
Parameters
parser
|
The ArgumentParser to set the long copyright of. |
---|---|
long
|
copyright The long copyright string to set, std::string. |
Data Races
void setMaxValue(parser, name, v);
void setMaxValue(parser, pos, v);
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
void setMinValue(parser, name, v);
void setMinValue(parser, pos, v);
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
void setRequired(parser, name[, required]).
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
void setShortCopyright(parser, short copyright);
Parameters
parser
|
The ArgumentParser to set the short copyright of. |
---|---|
short
|
copyright The short copyright string to set, std::string. |
Data Races
void setShortDescription(parser, desc);
Parameters
parser
|
The ArgumentParser to set the short description of. |
---|---|
desc
|
The short description, std::string. |
Data Races
void setValidValues(parser, name, values);
void setValidValues(parser, pos, values);
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
void setVersion(parser, version);
Parameters
parser
|
The ArgumentParser to set the version of. |
---|---|
version
|
The version string to set, std::string. |
Data Races
bool writeCTD(parser[, stream]);
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. |
---|