QCommandLineParser¶
The
QCommandLineParser
class provides a means for handling the command line options. More…
New in version 5.2.
Synopsis¶
Functions¶
def
addHelpOption
()def
addOption
(commandLineOption)def
addOptions
(options)def
addPositionalArgument
(name, description[, syntax=””])def
addVersionOption
()def
applicationDescription
()def
clearPositionalArguments
()def
errorText
()def
helpText
()def
isSet
(name)def
isSet
(option)def
optionNames
()def
parse
(arguments)def
positionalArguments
()def
process
(app)def
process
(arguments)def
setApplicationDescription
(description)def
setOptionsAfterPositionalArgumentsMode
(mode)def
setSingleDashWordOptionMode
(parsingMode)def
showHelp
([exitCode=0])def
showVersion
()def
unknownOptionNames
()def
value
(name)def
value
(option)def
values
(name)def
values
(option)
Detailed Description¶
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 a single or double
-
character(s). The option-
(single dash alone) is a special case, often meaning standard input, and 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 for can be set toParseAsLongOptions
, in which case-abc
will be parsed as the long optionabc
.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 using the assignment operator:
-v=value
--verbose=value
, or a space:-v value
--verbose value
, i.e. the next argument is used as value (even if it 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 withno-option
as one of its names, and handling the option explicitly.Example:
int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); QCoreApplication::setApplicationName("my-copy-program"); QCoreApplication::setApplicationVersion("1.0"); QCommandLineParser parser; parser.setApplicationDescription("Test helper"); parser.addHelpOption(); parser.addVersionOption(); parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy.")); parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory.")); // A boolean option with a single name (-p) QCommandLineOption showProgressOption("p", QCoreApplication::translate("main", "Show progress during copy")); parser.addOption(showProgressOption); // A boolean option with multiple names (-f, --force) QCommandLineOption forceOption(QStringList() << "f" << "force", QCoreApplication::translate("main", "Overwrite existing files.")); parser.addOption(forceOption); // An option with a value QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory", QCoreApplication::translate("main", "Copy all source files into <directory>."), QCoreApplication::translate("main", "directory")); parser.addOption(targetDirectoryOption); // Process the actual command line arguments given by the user parser.process(app); const QStringList args = parser.positionalArguments(); // source is args.at(0), destination is args.at(1) bool showProgress = parser.isSet(showProgressOption); bool force = parser.isSet(forceOption); QString targetDir = parser.value(targetDirectoryOption); // ... }If your compiler supports the C++11 standard, the three
addOption()
calls in the above example can be simplified:parser.addOptions({ // A boolean option with a single name (-p) {"p", QCoreApplication::translate("main", "Show progress during copy")}, // A boolean option with multiple names (-f, --force) {{"f", "force"}, QCoreApplication::translate("main", "Overwrite existing files.")}, // An option with a value {{"t", "target-directory"}, QCoreApplication::translate("main", "Copy all source files into <directory>."), QCoreApplication::translate("main", "directory")}, });Known limitation: the parsing of Qt options inside
QCoreApplication
and subclasses happens beforeQCommandLineParser
exists, so it can’t take it into account. This means any option value that looks like a builtin Qt option, will be treated byQCoreApplication
as a builtin Qt option. Example:--profile -reverse
will lead toQGuiApplication
seeing the -reverse option set, and removing it fromarguments()
beforeQCommandLineParser
defines theprofile
option and parses the command line.
How to Use QCommandLineParser in Complex Applications¶
In practice, additional error checking needs to be performed on the positional arguments and option values. For example, ranges of numbers should be checked.
It is then advisable to introduce a function to do the command line parsing which takes a struct or class receiving the option values returning an enumeration representing the result. The dnslookup example of the QtNetwork module illustrates this:
struct DnsQuery { DnsQuery() : type(QDnsLookup::A) {} QDnsLookup::Type type; QHostAddress nameServer; QString name; }; enum CommandLineParseResult { CommandLineOk, CommandLineError, CommandLineVersionRequested, CommandLineHelpRequested }; CommandLineParseResult parseCommandLine(QCommandLineParser &parser, DnsQuery *query, QString *errorMessage) { parser.setSingleDashWordOptionMode(QCommandLineParser::ParseAsLongOptions); const QCommandLineOption nameServerOption("n", "The name server to use.", "nameserver"); parser.addOption(nameServerOption); const QCommandLineOption typeOption("t", "The lookup type.", "type"); parser.addOption(typeOption); parser.addPositionalArgument("name", "The name to look up."); const QCommandLineOption helpOption = parser.addHelpOption(); const QCommandLineOption versionOption = parser.addVersionOption(); if (!parser.parse(QCoreApplication::arguments())) { *errorMessage = parser.errorText(); return CommandLineError; } if (parser.isSet(versionOption)) return CommandLineVersionRequested; if (parser.isSet(helpOption)) return CommandLineHelpRequested; if (parser.isSet(nameServerOption)) { const QString nameserver = parser.value(nameServerOption); query->nameServer = QHostAddress(nameserver); if (query->nameServer.isNull() || query->nameServer.protocol() == QAbstractSocket::UnknownNetworkLayerProtocol) { *errorMessage = "Bad nameserver address: " + nameserver; return CommandLineError; } } if (parser.isSet(typeOption)) { const QString typeParameter = parser.value(typeOption); const int type = typeFromParameter(typeParameter.toLower()); if (type < 0) { *errorMessage = "Bad record type: " + typeParameter; return CommandLineError; } query->type = static_cast<QDnsLookup::Type>(type); } const QStringList positionalArguments = parser.positionalArguments(); if (positionalArguments.isEmpty()) { *errorMessage = "Argument 'name' missing."; return CommandLineError; } if (positionalArguments.size() > 1) { *errorMessage = "Several 'name' arguments specified."; return CommandLineError; } query->name = positionalArguments.first(); return CommandLineOk; }In the main function, help should be printed to the standard output if the help option was passed and the application should return the exit code 0.
If an error was detected, the error message should be printed to the standard error output and the application should return an exit code other than 0.
QCoreApplication::setApplicationVersion(QT_VERSION_STR); QCoreApplication::setApplicationName(QCoreApplication::translate("QDnsLookupExample", "DNS Lookup Example")); QCommandLineParser parser; parser.setApplicationDescription(QCoreApplication::translate("QDnsLookupExample", "An example demonstrating the class QDnsLookup.")); DnsQuery query; QString errorMessage; switch (parseCommandLine(parser, &query, &errorMessage)) { case CommandLineOk: break; case CommandLineError: fputs(qPrintable(errorMessage), stderr); fputs("\n\n", stderr); fputs(qPrintable(parser.helpText()), stderr); return 1; case CommandLineVersionRequested: printf("%s %s\n", qPrintable(QCoreApplication::applicationName()), qPrintable(QCoreApplication::applicationVersion())); return 0; case CommandLineHelpRequested: parser.showHelp(); Q_UNREACHABLE(); }A special case to consider here are GUI applications on Windows and mobile platforms. These applications may not use the standard output or error channels since the output is either discarded or not accessible.
On Windows,
QCommandLineParser
uses message boxes to display usage information and errors if no console window can be obtained.For other platforms, it is recommended to display help texts and error messages using a
QMessageBox
. To preserve the formatting of the help text, rich text with<pre>
elements should be used:switch (parseCommandLine(parser, &query, &errorMessage)) { case CommandLineOk: break; case CommandLineError: QMessageBox::warning(0, QGuiApplication::applicationDisplayName(), "<html><head/><body><h2>" + errorMessage + "</h2><pre>" + parser.helpText() + "</pre></body></html>"); return 1; case CommandLineVersionRequested: QMessageBox::information(0, QGuiApplication::applicationDisplayName(), QGuiApplication::applicationDisplayName() + ' ' + QCoreApplication::applicationVersion()); return 0; case CommandLineHelpRequested: QMessageBox::warning(0, QGuiApplication::applicationDisplayName(), "<html><head/><body><pre>" + parser.helpText() + "</pre></body></html>"); return 0; }However, this does not apply to the dnslookup example, because it is a console application.
See also
- class PySide2.QtCore.QCommandLineParser¶
Constructs a command line parser object.
- PySide2.QtCore.QCommandLineParser.SingleDashWordOptionMode¶
This enum describes the way the parser interprets command-line options that use a single dash followed by multiple letters, as as
-abc
.Constant
Description
QCommandLineParser.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. Ifa
takes a value, then it is interpreted as-a bc
, i.e. the short optiona
followed by the valuebc
. 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.QCommandLineParser.ParseAsLongOptions
-abc
is interpreted as--abc
, i.e. as the long option namedabc
. 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 thea
option has theShortOptionStyle
flag set, in which case it is still interpreted as-a bc
.See also
- PySide2.QtCore.QCommandLineParser.OptionsAfterPositionalArgumentsMode¶
This enum describes the way the parser interprets options that occur after positional arguments.
Constant
Description
QCommandLineParser.ParseAsOptions
application argument --opt -t
is interpreted as setting the optionsopt
andt
, just likeapplication --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 inapplication argument -- --opt -t
.QCommandLineParser.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.
New in version 5.6.
- PySide2.QtCore.QCommandLineParser.addHelpOption()¶
- Return type:
Adds the help option (
-h
,--help
and-?
on Windows) as well as an option--help-all
to include Qt-specific options 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:
int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); QCoreApplication::setApplicationName("my-copy-program"); QCoreApplication::setApplicationVersion("1.0"); QCommandLineParser parser; parser.setApplicationDescription("Test helper"); parser.addHelpOption(); parser.addVersionOption(); parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy.")); parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory.")); // A boolean option with a single name (-p) QCommandLineOption showProgressOption("p", QCoreApplication::translate("main", "Show progress during copy")); parser.addOption(showProgressOption); // A boolean option with multiple names (-f, --force) QCommandLineOption forceOption(QStringList() << "f" << "force", QCoreApplication::translate("main", "Overwrite existing files.")); parser.addOption(forceOption); // An option with a value QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory", QCoreApplication::translate("main", "Copy all source files into <directory>."), QCoreApplication::translate("main", "directory")); parser.addOption(targetDirectoryOption); // Process the actual command line arguments given by the user parser.process(app); const QStringList args = parser.positionalArguments(); // source is args.at(0), destination is args.at(1) bool showProgress = parser.isSet(showProgressOption); bool force = parser.isSet(forceOption); QString targetDir = parser.value(targetDirectoryOption); // ... }
Returns the option instance, which can be used to call
isSet()
.
- PySide2.QtCore.QCommandLineParser.addOption(commandLineOption)¶
- Parameters:
commandLineOption –
PySide2.QtCore.QCommandLineOption
- Return type:
bool
Adds the option
option
to look for while parsing.Returns
true
if adding the option was successful; otherwise returnsfalse
.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.
- PySide2.QtCore.QCommandLineParser.addOptions(options)¶
- Parameters:
options –
- Return type:
bool
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 returnsfalse
.See the documentation for
addOption()
for when this function may fail.
- PySide2.QtCore.QCommandLineParser.addPositionalArgument(name, description[, syntax=""])¶
- Parameters:
name – str
description – str
syntax – str
Defines an additional argument to the application, for the benefit of the help text.
The argument
name
anddescription
will appear under theArguments:
section of the help. Ifsyntax
is specified, it will be appended to the Usage line, otherwise thename
will be appended.Example:
// Usage: image-editor file // // Arguments: // file The file to open. parser.addPositionalArgument("file", QCoreApplication::translate("main", "The file to open.")); // Usage: web-browser [urls...] // // Arguments: // urls URLs to open, optionally. parser.addPositionalArgument("urls", QCoreApplication::translate("main", "URLs to open, optionally."), "[urls...]"); // Usage: cp source destination // // Arguments: // source Source file to copy. // destination Destination directory. parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy.")); parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));
See also
- PySide2.QtCore.QCommandLineParser.addVersionOption()¶
- Return type:
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
setApplicationVersion()
.Returns the option instance, which can be used to call
isSet()
.
- PySide2.QtCore.QCommandLineParser.applicationDescription()¶
- Return type:
str
Returns the application description set in
setApplicationDescription()
.See also
- PySide2.QtCore.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:
QCoreApplication app(argc, argv); QCommandLineParser parser; parser.addPositionalArgument("command", "The command to execute."); // Call parse() to find out the positional arguments. parser.parse(QCoreApplication::arguments()); const QStringList args = parser.positionalArguments(); const QString command = args.isEmpty() ? QString() : args.first(); if (command == "resize") { parser.clearPositionalArguments(); parser.addPositionalArgument("resize", "Resize the object to a new size.", "resize [resize_options]"); parser.addOption(QCommandLineOption("size", "New size.", "new_size")); parser.process(app); // ... } /* This code results in context-dependent help: $ tool --help Usage: tool command Arguments: command The command to execute. $ tool resize --help Usage: tool resize [resize_options] Options: --size <size> New size. Arguments: resize Resize the object to a new size. */
- PySide2.QtCore.QCommandLineParser.errorText()¶
- Return type:
str
Returns a translated error text for the user. This should only be called when
parse()
returnsfalse
.
- PySide2.QtCore.QCommandLineParser.helpText()¶
- Return type:
str
Returns a string containing the complete help information.
See also
- PySide2.QtCore.QCommandLineParser.isSet(option)¶
- Parameters:
option –
PySide2.QtCore.QCommandLineOption
- Return type:
bool
- PySide2.QtCore.QCommandLineParser.isSet(name)
- Parameters:
name – str
- Return type:
bool
- PySide2.QtCore.QCommandLineParser.optionNames()¶
- Return type:
list of strings
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 withvalues()
to get any relevant option values.
- PySide2.QtCore.QCommandLineParser.parse(arguments)¶
- Parameters:
arguments – list of strings
- Return type:
bool
Parses the command line
arguments
.Most programs don’t need to call this, a simple call to
process()
is enough.is more low-level, and only does the parsing. The application will have to take care of the error handling, using
errorText()
if returnsfalse
. This can be useful for instance to show a graphical error message in graphical programs.Calling 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 callingprocess()
.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); returnstrue
otherwise.See also
- PySide2.QtCore.QCommandLineParser.positionalArguments()¶
- Return type:
list of strings
Returns a list of positional arguments.
These are all of the arguments that were not recognized as part of an option.
- PySide2.QtCore.QCommandLineParser.process(app)¶
- Parameters:
- PySide2.QtCore.QCommandLineParser.process(arguments)
- Parameters:
arguments – list of strings
- PySide2.QtCore.QCommandLineParser.setApplicationDescription(description)¶
- Parameters:
description – str
Sets the application
description
shown byhelpText()
.See also
- PySide2.QtCore.QCommandLineParser.setOptionsAfterPositionalArgumentsMode(mode)¶
- Parameters:
Sets the parsing mode to
parsingMode
. This must be called beforeprocess()
orparse()
.
- PySide2.QtCore.QCommandLineParser.setSingleDashWordOptionMode(parsingMode)¶
- Parameters:
parsingMode –
SingleDashWordOptionMode
Sets the parsing mode to
singleDashWordOptionMode
. This must be called beforeprocess()
orparse()
.
- PySide2.QtCore.QCommandLineParser.showHelp([exitCode=0])¶
- Parameters:
exitCode – int
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.See also
- PySide2.QtCore.QCommandLineParser.showVersion()¶
Displays the version information from
applicationVersion()
, and exits the application. This is automatically triggered by the –version option, but can also be used to display the version when not usingprocess()
. The exit code is set to EXIT_SUCCESS (0).See also
- PySide2.QtCore.QCommandLineParser.unknownOptionNames()¶
- Return type:
list of strings
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.
See also
- PySide2.QtCore.QCommandLineParser.value(option)¶
- Parameters:
option –
PySide2.QtCore.QCommandLineOption
- Return type:
str
- PySide2.QtCore.QCommandLineParser.value(name)
- Parameters:
name – str
- Return type:
str
- PySide2.QtCore.QCommandLineParser.values(option)¶
- Parameters:
option –
PySide2.QtCore.QCommandLineOption
- Return type:
list of strings
- PySide2.QtCore.QCommandLineParser.values(name)
- Parameters:
name – str
- Return type:
list of strings
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.