Medical Imaging Interaction Toolkit
2016.11.0
Medical Imaging Interaction Toolkit
|
#include <mitkCommandLineParser.h>
Public Types | |
enum | Type { String, Bool, StringList, Int, Float, InputDirectory, InputFile, OutputDirectory, OutputFile, InputImage } |
typedef std::vector< std::string > | StringContainerType |
Public Member Functions | |
mitkCommandLineParser () | |
~mitkCommandLineParser () | |
std::map< std::string, us::Any > | parseArguments (const StringContainerType &arguments, bool *ok=nullptr) |
std::map< std::string, us::Any > | parseArguments (int argc, char **argv, bool *ok=nullptr) |
std::string | errorString () const |
const StringContainerType & | unparsedArguments () const |
bool | argumentAdded (const std::string &argument) const |
bool | argumentParsed (const std::string &argument) const |
void | addArgument (const std::string &longarg, const std::string &shortarg, Type type, const std::string &argLabel, const std::string &argHelp=std::string(), const us::Any &defaultValue=us::Any(), bool optional=true, bool ignoreRest=false, bool deprecated=false) |
void | addDeprecatedArgument (const std::string &longarg, const std::string &shortarg, const std::string &argLabel, const std::string &argHelp) |
bool | setExactMatchRegularExpression (const std::string &argument, const std::string &expression, const std::string &exactMatchFailedMessage) |
std::string::size_type | fieldWidth () const |
std::string | helpText () const |
void | setArgumentPrefix (const std::string &longPrefix, const std::string &shortPrefix) |
void | beginGroup (const std::string &description) |
void | endGroup () |
void | setStrictModeEnabled (bool strictMode) |
void | generateXmlOutput () |
void | setTitle (std::string title) |
void | setContributor (std::string contributor) |
void | setCategory (std::string category) |
void | setDescription (std::string description) |
void | changeParameterGroup (std::string name, std::string tooltip) |
The MITK command line parser, based on the CTK command line parser.
Use this class to add information about the command line arguments your program understands and to easily parse them from a given list of strings.
This parser provides the following features:
The main difference between the MITK command line parser and the CTK command line parser is that the former does not depend on Qt. Apart from that an image type was added and XML output improved for automatic GUI generation.
std::out is used for output to keep dependencies to a minimum.
Definition at line 77 of file mitkCommandLineParser.h.
typedef std::vector<std::string> mitkCommandLineParser::StringContainerType |
Definition at line 94 of file mitkCommandLineParser.h.
Enumerator | |
---|---|
String | |
Bool | |
StringList | |
Int | |
Float | |
InputDirectory | |
InputFile | |
OutputDirectory | |
OutputFile | |
InputImage |
Definition at line 80 of file mitkCommandLineParser.h.
mitkCommandLineParser::mitkCommandLineParser | ( | ) |
Definition at line 337 of file mitkCommandLineParser.cpp.
mitkCommandLineParser::~mitkCommandLineParser | ( | ) |
Definition at line 349 of file mitkCommandLineParser.cpp.
void mitkCommandLineParser::addArgument | ( | const std::string & | longarg, |
const std::string & | shortarg, | ||
Type | type, | ||
const std::string & | argLabel, | ||
const std::string & | argHelp = std::string() , |
||
const us::Any & | defaultValue = us::Any() , |
||
bool | optional = true , |
||
bool | ignoreRest = false , |
||
bool | deprecated = false |
||
) |
Adds a command line argument. An argument can have a long name (like –long-argument-name), a short name (like -l), or both. The type of the argument can be specified by using the type
parameter. The following types are supported:
Type | # of parameters | Default regular expr | Example |
us::Any::String | 1 | .* | –test-string StringParameter |
us::Any::Bool | 0 | does not apply | –enable-something |
us::Any::StringList | -1 | .* | –test-list string1 string2 |
us::Any::Int | 1 | -?[0-9]+ | –test-int -5 |
The regular expressions are used to validate the parameters of command line arguments. You can restrict the valid set of parameters by calling setExactMatchRegularExpression()
for your argument.
Optionally, a help string and a default value can be provided for the argument. If the us::Any type of the default value does not match type
, an exception is thrown. Arguments with default values are always returned by parseArguments()
.
You can also declare an argument deprecated, by setting deprecated
to true
. Alternatively you can add a deprecated argument by calling addDeprecatedArgument()
.
If the long or short argument has already been added, or if both are empty strings, the method call has no effect.
longarg | The long argument name. |
shortarg | The short argument name. |
type | The argument type (see the list above for supported types). |
argLabel | The label of this argument, when auto generated interface is used. |
argHelp | A help string describing the argument. |
defaultValue | A default value for the argument. |
ignoreRest | All arguments after the current one will be ignored. |
deprecated | Declares the argument deprecated. |
std::logic_error | If the us::Any type of defaultValue does not match type , a std::logic_error is thrown. |
Definition at line 664 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
void mitkCommandLineParser::addDeprecatedArgument | ( | const std::string & | longarg, |
const std::string & | shortarg, | ||
const std::string & | argLabel, | ||
const std::string & | argHelp | ||
) |
Adds a deprecated command line argument. If a deprecated argument is provided on the command line, argHelp
is displayed in the console and processing continues with the next argument.
Deprecated arguments are grouped separately at the end of the help text returned by helpText()
.
longarg | The long argument name. |
shortarg | The short argument name. |
argHelp | A help string describing alternatives to the deprecated argument. |
Definition at line 730 of file mitkCommandLineParser.cpp.
bool mitkCommandLineParser::argumentAdded | ( | const std::string & | argument | ) | const |
Checks if the given argument has been added via a call to addArgument()
.
argument | The argument to be checked. |
true
if the argument was added, false
otherwise. Definition at line 808 of file mitkCommandLineParser.cpp.
bool mitkCommandLineParser::argumentParsed | ( | const std::string & | argument | ) | const |
Checks if the given argument has been parsed successfully by a previous call to parseArguments()
.
argument | The argument to be checked. |
true
if the argument was parsed, false
otherwise. Definition at line 814 of file mitkCommandLineParser.cpp.
void mitkCommandLineParser::beginGroup | ( | const std::string & | description | ) |
Begins a new group for documenting arguments. All newly added arguments via addArgument()
will be put in the new group. You can close the current group by calling endGroup()
or be opening a new group.
Note that groups cannot be nested and all arguments which do not belong to a group will be listed at the top of the text created by helpText()
.
description | The description of the group |
Definition at line 745 of file mitkCommandLineParser.cpp.
void mitkCommandLineParser::changeParameterGroup | ( | std::string | name, |
std::string | tooltip | ||
) |
Is used to group several Parameters in one groupbox in the auto generated interface. Default name is "Parameters", with the tooltip: "Groupbox containing parameters."
To change the group of several arguments, call this method before the arguments are added.
name | The name of the groupbox. |
tooltip | The tooltip of the groupbox. |
Definition at line 953 of file mitkCommandLineParser.cpp.
Referenced by main().
void mitkCommandLineParser::endGroup | ( | ) |
Ends the current group.
Definition at line 751 of file mitkCommandLineParser.cpp.
string mitkCommandLineParser::errorString | ( | ) | const |
Returns a detailed error description if a call to parseArguments()
failed.
Definition at line 652 of file mitkCommandLineParser.cpp.
std::string::size_type mitkCommandLineParser::fieldWidth | ( | ) | const |
The field width for the argument names without the help text.
Definition at line 739 of file mitkCommandLineParser.cpp.
void mitkCommandLineParser::generateXmlOutput | ( | ) |
Is used to generate an XML output for any commandline program.
Definition at line 835 of file mitkCommandLineParser.cpp.
References Bool, Float, InputDirectory, InputFile, InputImage, Int, OutputDirectory, OutputFile, String, and StringList.
string mitkCommandLineParser::helpText | ( | ) | const |
Creates a help text containing properly formatted argument names and help strings provided by calls to addArgument()
. The arguments can be grouped by using beginGroup()
and endGroup()
.
charPad | The padding character. |
Definition at line 757 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), and main().
map< string, us::Any > mitkCommandLineParser::parseArguments | ( | const StringContainerType & | arguments, |
bool * | ok = nullptr |
||
) |
Parse a given list of command line arguments.
This method parses a list of string elements considering the known arguments added by calls to addArgument()
. If any one of the argument values does not match the corresponding regular expression, ok
is set to false and an empty map object is returned.
The keys in the returned map object correspond to the long argument string, if it is not empty. Otherwise, the short argument string is used as key. The us::Any values can safely be converted to the type specified in the addArgument()
method call.
arguments | A StringContainerType containing command line arguments. |
ok | A pointer to a boolean variable. Will be set to true if all regular expressions matched, false otherwise. |
Definition at line 355 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
map< string, us::Any > mitkCommandLineParser::parseArguments | ( | int | argc, |
char ** | argv, | ||
bool * | ok = nullptr |
||
) |
Convenient method allowing to parse a given list of command line arguments.
Definition at line 640 of file mitkCommandLineParser.cpp.
void mitkCommandLineParser::setArgumentPrefix | ( | const std::string & | longPrefix, |
const std::string & | shortPrefix | ||
) |
Sets the argument prefix for long and short argument names. This can be used to create native command line arguments without changing the calls to addArgument()
. For example on Unix-based systems, long argument names start with "--" and short names with "-", while on Windows argument names always start with "/".
Note that all methods in mitkCommandLineParser which take an argument name expect the name as it was supplied to addArgument
.
Example usage:
longPrefix | The prefix for long argument names. |
shortPrefix | The prefix for short argument names. |
Definition at line 823 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
void mitkCommandLineParser::setCategory | ( | std::string | category | ) |
Is used to categorize the apps in the commandline module.
category | The category of the app. |
Definition at line 943 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
void mitkCommandLineParser::setContributor | ( | std::string | contributor | ) |
Is used to set the contributor for the help view in the auto generated interface.
contributor | Contributor of the app. |
Definition at line 938 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
void mitkCommandLineParser::setDescription | ( | std::string | description | ) |
Is used as the help text in the auto generated interface.
description | A short description for the app. |
Definition at line 948 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
bool mitkCommandLineParser::setExactMatchRegularExpression | ( | const std::string & | argument, |
const std::string & | expression, | ||
const std::string & | exactMatchFailedMessage | ||
) |
Sets a custom regular expression for validating argument parameters. The method errorString()
can be used the get the last error description.
argument | The previously added long or short argument name. |
expression | A regular expression which the arugment parameters must match. |
exactMatchFailedMessage | An error message explaining why the parameter did not match. |
true
if the argument was found and the regular expression was set, false
otherwise.void mitkCommandLineParser::setStrictModeEnabled | ( | bool | strictMode | ) |
Can be used to teach the parser to stop parsing the arguments and return False when an unknown argument is encountered. By default StrictMode
is disabled.
Definition at line 830 of file mitkCommandLineParser.cpp.
void mitkCommandLineParser::setTitle | ( | std::string | title | ) |
Is used to set the title of the auto generated interface.
title | The title of the app. |
Definition at line 934 of file mitkCommandLineParser.cpp.
Referenced by ExtractImageStatistics(), FiberJoin(), main(), StartPeakExtraction(), and StartShConversion().
const mitkCommandLineParser::StringContainerType & mitkCommandLineParser::unparsedArguments | ( | ) | const |
This method returns all unparsed arguments, i.e. all arguments for which no long or short name has been registered via a call to addArgument()
.
Definition at line 658 of file mitkCommandLineParser.cpp.