![]() |
CTK
0.1.0
The Common Toolkit is a community effort to provide support code for medical image analysis, surgical navigation, and related projects.
|
#include <Libs/Core/ctkCommandLineParser.h>
Public Types | |
typedef QObject | Superclass |
Public Member Functions | |
void | addArgument (const QString &longarg, const QString &shortarg, QVariant::Type type, const QString &argHelp=QString(), const QVariant &defaultValue=QVariant(), bool ignoreRest=false, bool deprecated=false) |
void | addDeprecatedArgument (const QString &longarg, const QString &shortarg, const QString &argHelp) |
Q_INVOKABLE bool | argumentAdded (const QString &argument) const |
Q_INVOKABLE bool | argumentParsed (const QString &argument) const |
void | beginGroup (const QString &description) |
ctkCommandLineParser (QObject *newParent=0) | |
ctkCommandLineParser (QSettings *settings, QObject *newParent=0) | |
void | enableSettings (const QString &disableLongArg="", const QString &disableShortArg="") |
void | endGroup () |
QString | errorString () const |
int | fieldWidth () const |
QString | helpText (const char charPad=' ') const |
void | mergeSettings (bool merge) |
QHash< QString, QVariant > | parseArguments (const QStringList &arguments, bool *ok=0) |
QHash< QString, QVariant > | parseArguments (int argc, char **argv, bool *ok=0) |
void | setArgumentPrefix (const QString &longPrefix, const QString &shortPrefix) |
bool | setExactMatchRegularExpression (const QString &argument, const QString &expression, const QString &exactMatchFailedMessage) |
void | setStrictModeEnabled (bool strictMode) |
bool | settingsEnabled () const |
const QStringList & | unparsedArguments () const |
~ctkCommandLineParser () | |
Properties | |
QString | errorString |
bool | settingsEnabled |
QStringList | unparsedArguments |
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:
Here is an example how to use this class inside a main function:
Definition at line 62 of file ctkCommandLineParser.h.
typedef QObject ctkCommandLineParser::Superclass |
Definition at line 71 of file ctkCommandLineParser.h.
ctkCommandLineParser::ctkCommandLineParser | ( | QObject * | newParent = 0 | ) |
Constructs a parser instance.
If QSettings support is enabled by a call to enableSettings()
a default constructed QSettings instance will be used when parsing the command line arguments. Make sure to call QCoreApplication::setOrganizationName()
and QCoreApplication::setApplicationName()
before using default constructed QSettings objects.
newParent | The QObject parent. |
ctkCommandLineParser::ctkCommandLineParser | ( | QSettings * | settings, |
QObject * | newParent = 0 |
||
) |
Constructs a parser instance.
If QSettings support is enabled by a call to enableSettings()
the provided QSettings instance will be used. If the QSettings instance is zero, a default constructed QSettings instance will be used when parsing the command line arguments. Using a default constructed instance is usually what you want, if you have called QCoreApplication::setOrganizationName()
and QCoreApplication::setApplicationName()
.
settings | A QSettings instance which should be used. |
newParent | The QObject parent. |
ctkCommandLineParser::~ctkCommandLineParser | ( | ) |
void ctkCommandLineParser::addArgument | ( | const QString & | longarg, |
const QString & | shortarg, | ||
QVariant::Type | type, | ||
const QString & | argHelp = QString() , |
||
const QVariant & | defaultValue = QVariant() , |
||
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 |
QVariant::String | 1 | .* | –test-string StringParameter |
QVariant::Bool | 0 | does not apply | –enable-something |
QVariant::StringList | -1 | .* | –test-list string1 string2 |
QVariant::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 QVariant 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). |
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 QVariant type of defaultValue does not match type , a std::logic_error is thrown. |
void ctkCommandLineParser::addDeprecatedArgument | ( | const QString & | longarg, |
const QString & | shortarg, | ||
const QString & | 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. |
Q_INVOKABLE bool ctkCommandLineParser::argumentAdded | ( | const QString & | 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. Q_INVOKABLE bool ctkCommandLineParser::argumentParsed | ( | const QString & | 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. void ctkCommandLineParser::beginGroup | ( | const QString & | 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 |
void ctkCommandLineParser::enableSettings | ( | const QString & | disableLongArg = "" , |
const QString & | disableShortArg = "" |
||
) |
Enables QSettings support in ctkCommandLineParser. If an argument name is found in the QSettings instance with a valid QVariant, the value is considered as a default value and overwrites default values registered with addArgument()
. User supplied values on the command line overwrite values in the QSettings instance, except for arguments with multiple parameters which are merged with QSettings values. Call mergeSettings(false)
to disable merging.
See ctkCommandLineParser(QSettings*)
for information about how to supply a QSettings instance.
Additionally, a long and short argument name can be specified which will disable QSettings support if supplied on the command line. The argument name must be registered as a regular argument via addArgument()
.
disableLongArg | Long argument name. |
disableShortArg | Short argument name. |
void ctkCommandLineParser::endGroup | ( | ) |
Ends the current group.
QString ctkCommandLineParser::errorString | ( | ) | const |
Returns a detailed error description if a call to parseArguments()
failed.
int ctkCommandLineParser::fieldWidth | ( | ) | const |
The field width for the argument names without the help text.
QString ctkCommandLineParser::helpText | ( | const char | charPad = ' ' | ) | 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. |
void ctkCommandLineParser::mergeSettings | ( | bool | merge | ) |
Controlls the merging behavior of user values and QSettings values.
If merging is on (the default), user supplied values for an argument which can take more than one parameter are merged with values stored in the QSettings instance. If merging is off, the user values overwrite the QSettings values.
merge | true enables QSettings merging, false disables it. |
QHash<QString, QVariant> ctkCommandLineParser::parseArguments | ( | const QStringList & | arguments, |
bool * | ok = 0 |
||
) |
Parse a given list of command line arguments.
This method parses a list of QString 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 QHash object is returned.
The keys in the returned QHash object correspond to the long argument string, if it is not empty. Otherwise, the short argument string is used as key. The QVariant values can safely be converted to the type specified in the addArgument()
method call.
arguments | A QStringList containing command line arguments. Usually given by QCoreApplication::arguments() . |
ok | A pointer to a boolean variable. Will be set to true if all regular expressions matched, false otherwise. |
QHash<QString, QVariant> ctkCommandLineParser::parseArguments | ( | int | argc, |
char ** | argv, | ||
bool * | ok = 0 |
||
) |
Convenient method allowing to parse a given list of command line arguments.
void ctkCommandLineParser::setArgumentPrefix | ( | const QString & | longPrefix, |
const QString & | 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 ctkCommandLineParser 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. |
bool ctkCommandLineParser::setExactMatchRegularExpression | ( | const QString & | argument, |
const QString & | expression, | ||
const QString & | 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 ctkCommandLineParser::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.
bool ctkCommandLineParser::settingsEnabled | ( | ) | const |
Can be used to check if QSettings support has been enabled by a call to enableSettings()
.
true
if QSettings support is enabled, false
otherwise. const QStringList& ctkCommandLineParser::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()
.
|
read |
Definition at line 1 of file ctkCommandLineParser.h.
|
read |
Definition at line 1 of file ctkCommandLineParser.h.
|
read |
Definition at line 1 of file ctkCommandLineParser.h.