 |
Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
|
Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
|
The QCommandLineParser class provides a means for handling the command line options. More...
#include <qcommandlineparser.h>
Collaboration diagram for QCommandLineParser:Public Types | |
| enum | SingleDashWordOptionMode { ParseAsCompactedShortOptions , ParseAsLongOptions } |
This enum describes the way the parser interprets command-line options that use a single dash followed by multiple letters, as | |
| enum | OptionsAfterPositionalArgumentsMode { ParseAsOptions , ParseAsPositionalArguments } |
| This enum describes the way the parser interprets options that occur after positional arguments. More... | |
Public Member Functions | |
| QCommandLineParser () | |
| Constructs a command line parser object. | |
| ~QCommandLineParser () | |
| Destroys the command line parser object. | |
| void | setSingleDashWordOptionMode (SingleDashWordOptionMode parsingMode) |
| Sets the parsing mode to singleDashWordOptionMode. | |
| void | setOptionsAfterPositionalArgumentsMode (OptionsAfterPositionalArgumentsMode mode) |
| Sets the parsing mode to parsingMode. | |
| bool | addOption (const QCommandLineOption &commandLineOption) |
| Adds the option option to look for while parsing. | |
| bool | addOptions (const QList< QCommandLineOption > &options) |
| QCommandLineOption | addVersionOption () |
Adds the | |
| QCommandLineOption | addHelpOption () |
| Adds help options to the command-line parser. | |
| void | setApplicationDescription (const QString &description) |
| Sets the application description shown by helpText(). | |
| QString | applicationDescription () const |
| Returns the application description set in setApplicationDescription(). | |
| void | addPositionalArgument (const QString &name, const QString &description, const QString &syntax=QString()) |
| Defines an additional argument to the application, for the benefit of the help text. | |
| void | clearPositionalArguments () |
| Clears the definitions of additional arguments from the help text. | |
| void | process (const QStringList &arguments) |
| Processes the command line arguments. | |
| void | process (const QCoreApplication &app) |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.The command line is obtained from the QCoreApplication instance app. | |
| bool | parse (const QStringList &arguments) |
| Parses the command line arguments. | |
| QString | errorText () const |
| Returns a translated error text for the user. | |
| bool | isSet (const QString &name) const |
| Checks whether the option name was passed to the application. | |
| QString | value (const QString &name) const |
| Returns the option value found for the given option name optionName, or an empty string if not found. | |
| QStringList | values (const QString &name) const |
| Returns a list of option values found for the given option name optionName, or an empty list if not found. | |
| bool | isSet (const QCommandLineOption &option) const |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Checks whether the option was passed to the application. | |
| QString | value (const QCommandLineOption &option) const |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns the option value found for the given option, or an empty string if not found. | |
| QStringList | values (const QCommandLineOption &option) const |
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns a list of option values found for the given option, or an empty list if not found. | |
| QStringList | positionalArguments () const |
| Returns a list of positional arguments. | |
| QStringList | optionNames () const |
| Returns a list of option names that were found. | |
| QStringList | unknownOptionNames () const |
| Returns a list of unknown option names. | |
| Q_NORETURN void | showVersion () |
| Displays the version information from QCoreApplication::applicationVersion(), and exits the application. | |
| Q_NORETURN void | showHelp (int exitCode=0) |
| Displays the help information, and exits the application. | |
| QString | helpText () const |
| Returns a string containing the complete help information. | |
The QCommandLineParser class provides a means for handling the command line options.
\inmodule QtCore
QCoreApplication provides the command-line arguments as a simple list of strings. QCommandLineParser provides the ability to define a set of options, parse the command-line arguments, and store which options have actually been used, as well as option values.
Any argument that isn't an option (i.e. doesn't start with a {-}) is stored as a "positional argument".
The parser handles short names, long names, more than one name for the same option, and option values.
Options on the command line are recognized as starting with one or two {-} characters, followed by the option name. The option {-} (single dash alone) is a special case, often meaning standard input, and is not treated as an option. The parser will treat everything after the option {–} (double dash) as positional arguments.
Short options are single letters. The option {v} would be specified by passing {-v} on the command line. In the default parsing mode, short options can be written in a compact form, for instance {-abc} is equivalent to {-a -b -c}. The parsing mode can be changed to ParseAsLongOptions, in which case {-abc} will be parsed as the long option {abc}.
Long options are more than one letter long and cannot be compacted together. The long option {verbose} would be passed as {–verbose} or {-verbose}.
Passing values to options can be done by using the assignment operator ({-v=value}, {–verbose=value}), or with a space ({-v value}, {–verbose value}). This works even if the the value starts with a {-}.
The parser does not support optional values - if an option is set to require a value, one must be present. If such an option is placed last and has no value, the option will be treated as if it had not been specified.
The parser does not automatically support negating or disabling long options by using the format {–disable-option} or {–no-option}. However, it is possible to handle this case explicitly by making an option with {no-option} as one of its names, and handling the option explicitly.
Example:
The three addOption() calls in the above example can be made more compact by using addOptions():
Known limitation: the parsing of Qt options inside QCoreApplication and subclasses happens before QCommandLineParser exists, so it can't take it into account. This means any option value that looks like a builtin Qt option will be treated by QCoreApplication as a builtin Qt option. Example: {–profile -reverse} will lead to QGuiApplication seeing the -reverse option set, and removing it from QCoreApplication::arguments() before QCommandLineParser defines the {profile} option and parses the command line.
Definition at line 19 of file qcommandlineparser.h.
This enum describes the way the parser interprets options that occur after positional arguments.
\value ParseAsOptions {application argument –opt -t} is interpreted as setting the options {opt} and {t}, just like {application –opt -t argument} would do. This is the default parsing mode. In order to specify that {–opt} and {-t} are positional arguments instead, the user can use {–}, as in {application argument – –opt -t}.
\value ParseAsPositionalArguments {application argument –opt} is interpreted as having two positional arguments, {argument} and {–opt}. This mode is useful for executables that aim to launch other executables (e.g. wrappers, debugging tools, etc.) or that support internal commands followed by options for the command. {argument} is the name of the command, and all options occurring after it can be collected and parsed by another command line parser, possibly in another executable.
| Enumerator | |
|---|---|
| ParseAsOptions | |
| ParseAsPositionalArguments | |
Definition at line 32 of file qcommandlineparser.h.
This enum describes the way the parser interprets command-line options that use a single dash followed by multiple letters, as {-abc}.
\value ParseAsCompactedShortOptions {-abc} is interpreted as {-a -b -c}, i.e. as three short options that have been compacted on the command-line, if none of the options take a value. If {a} takes a value, then it is interpreted as {-a bc}, i.e. the short option {a} followed by the value {bc}. This is typically used in tools that behave like compilers, in order to handle options such as {-DDEFINE=VALUE} or {-I/include/path}. This is the default parsing mode. New applications are recommended to use this mode.
\value ParseAsLongOptions {-abc} is interpreted as {–abc}, i.e. as the long option named {abc}. This is how Qt's own tools (uic, rcc...) have always been parsing arguments. This mode should be used for preserving compatibility in applications that were parsing arguments in such a way. There is an exception if the {a} option has the QCommandLineOption::ShortOptionStyle flag set, in which case it is still interpreted as {-a bc}.
| Enumerator | |
|---|---|
| ParseAsCompactedShortOptions | |
| ParseAsLongOptions | |
Definition at line 26 of file qcommandlineparser.h.
| QCommandLineParser::QCommandLineParser | ( | ) |
Constructs a command line parser object.
Definition at line 239 of file qcommandlineparser.cpp.
| QCommandLineParser::~QCommandLineParser | ( | ) |
Destroys the command line parser object.
Definition at line 247 of file qcommandlineparser.cpp.
| QCommandLineOption QCommandLineParser::addHelpOption | ( | ) |
Adds help options to the command-line parser.
The options specified for this command-line are described by {-h} or {–help}. On Windows, the alternative {-?} is also supported. The option {–help-all} extends that to include generic Qt options, not defined by this command, in the output.
These options are handled automatically by QCommandLineParser.
Remember to use setApplicationDescription() to set the application description, which will be displayed when this option is used.
Example:
Returns the option instance, which can be used to call isSet().
Definition at line 409 of file qcommandlineparser.cpp.
References addOption(), QCommandLineParserPrivate::builtinHelpOption, opt, QStringLiteral, and tr.
Referenced by main(), main(), parseArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:| bool QCommandLineParser::addOption | ( | const QCommandLineOption & | option | ) |
Adds the option option to look for while parsing.
Returns true if adding the option was successful; otherwise returns false.
Adding the option fails if there is no name attached to the option, or the option has a name that clashes with an option name added before.
Definition at line 330 of file qcommandlineparser.cpp.
References QList< T >::append(), QCommandLineParserPrivate::commandLineOptionList, QHash< Key, T >::contains(), QHash< Key, T >::insert(), QCommandLineParserPrivate::nameHash, optionNames(), qWarning, and QList< T >::size().
Referenced by addHelpOption(), addOptions(), addVersionOption(), main(), main(), main(), parseArguments(), parseEarlyArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:| bool QCommandLineParser::addOptions | ( | const QList< QCommandLineOption > & | options | ) |
Adds the options to look for while parsing. The options are specified by the parameter options.
Returns true if adding all of the options was successful; otherwise returns false.
See the documentation for addOption() for when this function may fail.
Definition at line 365 of file qcommandlineparser.cpp.
References addOption(), and it.
Here is the call graph for this function:| void QCommandLineParser::addPositionalArgument | ( | const QString & | name, |
| const QString & | description, | ||
| const QString & | syntax = QString() ) |
Defines an additional argument to the application, for the benefit of the help text.
The argument name and description will appear under the {Arguments:} section of the help. If syntax is specified, it will be appended to the Usage line, otherwise the name will be appended.
Example:
Definition at line 453 of file qcommandlineparser.cpp.
References arg, QString::isEmpty(), and QCommandLineParserPrivate::positionalArgumentDefinitions.
Referenced by main(), main(), parseArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:| QCommandLineOption QCommandLineParser::addVersionOption | ( | ) |
Adds the {-v} / {–version} option, which displays the version string of the application.
This option is handled automatically by QCommandLineParser.
You can set the actual version string by using QCoreApplication::setApplicationVersion().
Returns the option instance, which can be used to call isSet().
Definition at line 383 of file qcommandlineparser.cpp.
References addOption(), QCommandLineParserPrivate::builtinVersionOption, opt, QStringLiteral, and tr.
Referenced by main(), main(), parseArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:| QString QCommandLineParser::applicationDescription | ( | ) | const |
Returns the application description set in setApplicationDescription().
Definition at line 436 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::description.
| void QCommandLineParser::clearPositionalArguments | ( | ) |
Clears the definitions of additional arguments from the help text.
This is only needed for the special case of tools which support multiple commands with different options. Once the actual command has been identified, the options for this command can be defined, and the help text for the command can be adjusted accordingly.
Example:
Definition at line 473 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::positionalArgumentDefinitions.
Referenced by main().
Here is the caller graph for this function:| QString QCommandLineParser::errorText | ( | ) | const |
Returns a translated error text for the user.
This should only be called when parse() returns false.
Definition at line 506 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::errorText, QString::isEmpty(), QStringLiteral, tr, and QCommandLineParserPrivate::unknownOptionNames.
Referenced by parseArguments(), and process().
Here is the call graph for this function: Here is the caller graph for this function:| QString QCommandLineParser::helpText | ( | ) | const |
Returns a string containing the complete help information.
Definition at line 1035 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::helpText().
Here is the call graph for this function:| bool QCommandLineParser::isSet | ( | const QCommandLineOption & | option | ) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Checks whether the option was passed to the application.
Returns true if the option was set, false otherwise.
This is the recommended way to check for options with no values.
Example:
Definition at line 890 of file qcommandlineparser.cpp.
References isSet().
Here is the call graph for this function:| bool QCommandLineParser::isSet | ( | const QString & | name | ) | const |
Checks whether the option name was passed to the application.
Returns true if the option name was set, false otherwise.
The name provided can be any long or short name of any option that was added with addOption(). All the options names are treated as being equivalent. If the name is not recognized or that option was not present, false is returned.
Example:
Definition at line 797 of file qcommandlineparser.cpp.
References aliases(), QCommandLineParserPrivate::aliases(), QCommandLineParserPrivate::checkParsed(), and QCommandLineParserPrivate::optionNames.
Referenced by QQmlToolingUtils::getAndWarnForInvalidDirsFromOption(), isSet(), main(), main(), parseArguments(), parseEarlyArguments(), parseExclusiveOptions(), process(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:| QStringList QCommandLineParser::optionNames | ( | ) | const |
Returns a list of option names that were found.
This returns a list of all the recognized option names found by the parser, in the order in which they were found. For any long options that were in the form {–option=value}, the value part will have been dropped.
The names in this list do not include the preceding dash characters. Names may appear more than once in this list if they were encountered more than once by the parser.
Any entry in the list can be used with value() or with values() to get any relevant option values.
Definition at line 962 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::checkParsed(), and QCommandLineParserPrivate::optionNames.
Referenced by addOption().
Here is the call graph for this function: Here is the caller graph for this function:| bool QCommandLineParser::parse | ( | const QStringList & | arguments | ) |
Parses the command line arguments.
Most programs don't need to call this, a simple call to process() is enough.
parse() is more low-level, and only does the parsing. The application will have to take care of the error handling, using errorText() if parse() returns false. This can be useful for instance to show a graphical error message in graphical programs.
Calling parse() instead of process() can also be useful in order to ignore unknown options temporarily, because more option definitions will be provided later on (depending on one of the arguments), before calling process().
Don't forget that arguments must start with the name of the executable (ignored, though).
Returns false in case of a parse error (unknown option or missing value); returns true otherwise.
Definition at line 497 of file qcommandlineparser.cpp.
References arguments, and QCommandLineParserPrivate::parse().
Referenced by main(), parseArguments(), and parseEarlyArguments().
Here is the call graph for this function: Here is the caller graph for this function:| QStringList QCommandLineParser::positionalArguments | ( | ) | const |
Returns a list of positional arguments.
These are all of the arguments that were not recognized as part of an option.
Definition at line 940 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::checkParsed(), and QCommandLineParserPrivate::positionalArgumentList.
Referenced by main(), main(), parseArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), runUic(), and searchStringOrError().
Here is the call graph for this function: Here is the caller graph for this function:| void QCommandLineParser::process | ( | const QCoreApplication & | app | ) |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.The command line is obtained from the QCoreApplication instance app.
Definition at line 590 of file qcommandlineparser.cpp.
References app, QCoreApplication::arguments(), process(), and Q_UNUSED.
Here is the call graph for this function:| void QCommandLineParser::process | ( | const QStringList & | arguments | ) |
Processes the command line arguments.
In addition to parsing the options (like parse()), this function also handles the builtin options and handles errors.
The builtin options are {–version} if addVersionOption was called and {–help} / {–help-all} if addHelpOption was called.
When invoking one of these options, or when an error happens (for instance an unknown option was passed), the current process will then stop, using the exit() function.
Definition at line 567 of file qcommandlineparser.cpp.
References QCoreApplication::applicationName, arguments, QCommandLineParserPrivate::builtinHelpOption, QCommandLineParserPrivate::builtinVersionOption, ErrorMessage, errorText(), isSet(), QCommandLineParserPrivate::parse(), QStringLiteral, qt_call_post_routines(), QCommandLineParserPrivate::showHelp(), showParserMessage(), and showVersion().
Referenced by main(), main(), process(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:Sets the application description shown by helpText().
Definition at line 428 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::description.
Referenced by main(), main(), parseArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the caller graph for this function:| void QCommandLineParser::setOptionsAfterPositionalArgumentsMode | ( | QCommandLineParser::OptionsAfterPositionalArgumentsMode | parsingMode | ) |
Sets the parsing mode to parsingMode.
This must be called before process() or parse().
Definition at line 317 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::optionsAfterPositionalArgumentsMode.
| void QCommandLineParser::setSingleDashWordOptionMode | ( | QCommandLineParser::SingleDashWordOptionMode | singleDashWordOptionMode | ) |
Sets the parsing mode to singleDashWordOptionMode.
This must be called before process() or parse().
Definition at line 282 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::singleDashWordOptionMode.
Referenced by main(), parseArguments(), parseEarlyArguments(), runMoc(), runRcc(), and runUic().
Here is the caller graph for this function:| Q_NORETURN void QCommandLineParser::showHelp | ( | int | exitCode = 0 | ) |
Displays the help information, and exits the application.
This is automatically triggered by the –help option, but can also be used to display the help when the user is not invoking the application correctly. The exit code is set to exitCode. It should be set to 0 if the user requested to see the help, and to any other value in case of an error.
Definition at line 1018 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::showHelp().
Referenced by main(), runMoc(), and runRcc().
Here is the call graph for this function: Here is the caller graph for this function:| Q_NORETURN void QCommandLineParser::showVersion | ( | ) |
Displays the version information from QCoreApplication::applicationVersion(), and exits the application.
This is automatically triggered by the –version option, but can also be used to display the version when not using process(). The exit code is set to EXIT_SUCCESS (0).
Definition at line 998 of file qcommandlineparser.cpp.
References QCoreApplication::applicationName, QCoreApplication::applicationVersion, qt_call_post_routines(), showParserMessage(), and UsageMessage.
Referenced by process().
Here is the call graph for this function: Here is the caller graph for this function:| QStringList QCommandLineParser::unknownOptionNames | ( | ) | const |
Returns a list of unknown option names.
This list will include both long an short name options that were not recognized. For any long options that were in the form {–option=value}, the value part will have been dropped and only the long name is added.
The names in this list do not include the preceding dash characters. Names may appear more than once in this list if they were encountered more than once by the parser.
Definition at line 982 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::checkParsed(), and QCommandLineParserPrivate::unknownOptionNames.
Here is the call graph for this function:| QString QCommandLineParser::value | ( | const QCommandLineOption & | option | ) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns the option value found for the given option, or an empty string if not found.
For options found by the parser, the last value found for that option is returned. If the option wasn't specified on the command line, the default value is returned.
An empty string is returned if the option does not take a value.
Definition at line 910 of file qcommandlineparser.cpp.
Returns the option value found for the given option name optionName, or an empty string if not found.
The name provided can be any long or short name of any option that was added with addOption(). All the option names are treated as being equivalent. If the name is not recognized or that option was not present, an empty string is returned.
For options found by the parser, the last value found for that option is returned. If the option wasn't specified on the command line, the default value is returned.
If the option does not take a value, a warning is printed, and an empty string is returned.
Definition at line 828 of file qcommandlineparser.cpp.
References QCommandLineParserPrivate::checkParsed().
Referenced by main(), main(), parseArguments(), parseEarlyArguments(), QDBusXmlToCpp::run(), runMoc(), runRcc(), and runUic().
Here is the call graph for this function: Here is the caller graph for this function:| QStringList QCommandLineParser::values | ( | const QCommandLineOption & | option | ) | const |
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Returns a list of option values found for the given option, or an empty list if not found.
For options found by the parser, the list will contain an entry for each time the option was encountered by the parser. If the option wasn't specified on the command line, the default values are returned.
An empty list is returned if the option does not take a value.
Definition at line 928 of file qcommandlineparser.cpp.
| QStringList QCommandLineParser::values | ( | const QString & | optionName | ) | const |
Returns a list of option values found for the given option name optionName, or an empty list if not found.
The name provided can be any long or short name of any option that was added with addOption(). All the options names are treated as being equivalent. If the name is not recognized or that option was not present, an empty list is returned.
For options found by the parser, the list will contain an entry for each time the option was encountered by the parser. If the option wasn't specified on the command line, the default values are returned.
An empty list is returned if the option does not take a value.
Definition at line 857 of file qcommandlineparser.cpp.
References QList< T >::at(), QHash< Key, T >::cend(), QCommandLineParserPrivate::checkParsed(), QCommandLineParserPrivate::commandLineOptionList, QHash< Key, T >::constFind(), it, QCommandLineParserPrivate::nameHash, QCommandLineParserPrivate::optionValuesHash, qUtf16Printable, qWarning, and QHash< Key, T >::value().
Referenced by QQmlToolingUtils::getAndWarnForInvalidDirsFromOption(), parseArguments(), QDBusXmlToCpp::run(), and runMoc().
Here is the call graph for this function: Here is the caller graph for this function:
1.10.0