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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void addOption(parser, option);
Parameters
parser
|
The ArgumentParser to add the option to. |
option
|
The ArgParseOption to add to parser. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
bool getArgumentValue(dest, parser, pos[, no]);
Retrieves the value of an argument given by its position.
Parameters
dest
|
The variable to write the result to (the type is a template parameter and the value type of the
argument must be convertible in the type of dest for the retrieval to work, also see
result value). |
parser
|
The ArgumentParser to get the value from. |
pos
|
The position of the argument to get the value of. |
no
|
Optional position for multi-value arguments (unsigned, defaults to 0). |
Returns
bool |
true if the retrieval was successful, false otherwise. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
TCharStringRef getCitation(parser);
Returns the citation string.
Parameters
parser
|
The ArgumentParser to get the citation string from. |
Returns
TCharString |
A const-ref to a CharString with the citation string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
TCharStringRef getLongCopyright(parser);
Returns the long copyright string.
Parameters
parser
|
The ArgumentParser to get the long copyright string from. |
Returns
TCharString |
A const-ref to a CharString with the long copyright string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
See Also
bool getOptionValue(dest, parser, name[, pos]);
Retrieve the value of an option.
Parameters
dest
|
The variable to write the result to (the type is a template parameter and the value type of the
option must be convertible in the type of dest for the retrieval to work, also see
result value). |
parser
|
The ArgumentParser to get the value from. |
name
|
The short or long name of the option (std::string). |
pos
|
Optional position for multi-value options (unsigned, defaults to 0). |
Returns
bool |
true if the requested option was given on the command line and could be coverted to the type of
dest. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
TCharStringRef getShortCopyright(parser);
Returns the short copyright string.
Parameters
parser
|
The ArgumentParser to get the short copyright string from. |
Returns
TCharString |
A const-ref to a CharString with the short copyright string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
TCharStringRef getUrl(parser);
Parameters
parser
|
The ArgumentParser to get the url string from. |
Returns
TCharString |
A const-ref to a CharString with the url string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
This function must be called before retrieving any options or arguments from the parser.
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void printHelp(parser, out, format, showAdvancedOptions);
Prints the help message for the parser.
Parameters
parser
|
The ArgumentParser print the help for. |
out
|
The output stream to print to (std::ostream). |
format
|
The format to print, one of "html", "man", and "txt". |
showAdvancedOptions
|
Also show advanced options to user (default = false). |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void printLongCopyright(parser, stream);
Prints the long copyright information of the parser to a stream.
Parameters
parser
|
The ArgumenParser to print for. |
stream
|
The std::ostream to print to. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void setAdvanced(parser, name[, required]).
Sets whether or not the option with the givne name is advanced.
Parameters
parser
|
The ArgumentParser to set the flag of. |
name
|
The short or long name of the option (std::string). |
required
|
Whether or not the option is required (bool, default to true). |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void setCitation(parser, citation);
Sets citation of ArgumentParser.
Parameters
parser
|
The ArgumentParser to set the citation of. |
citation
|
The citation string to set, std::string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void setLongCopyright(parser, long copyright);
Sets long copyright of ArgumentParser.
Parameters
parser
|
The ArgumentParser to set the long copyright of. |
long
|
copyright The long copyright string to set, std::string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void setShortCopyright(parser, short copyright);
Sets short copyright of ArgumentParser.
Parameters
parser
|
The ArgumentParser to set the short copyright of. |
short
|
copyright The short copyright string to set, std::string. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
void setUrl(parser, url);
Sets url of ArgumentParser.
Parameters
parser
|
The ArgumentParser to set the url of. |
url
|
The url string to set, CharString. |
Data Races
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.
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
If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.