Skip to content

PythonQt.Qt.QCommandLineParser

QCommandLineParser

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

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 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 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 with no-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 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.

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.

Source: https://doc.qt.io/archives/qt-5.15/qcommandlineparser.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
OptionsAfterPositionalArgumentsMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ParseAsCompactedShortOptions attribute Any (shared captured text)
ParseAsLongOptions attribute Any (shared captured text)
ParseAsOptions attribute Any (shared captured text)
ParseAsPositionalArguments attribute Any (shared captured text)
SingleDashWordOptionMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
addHelpOption function (self) -> Any X.addHelpOption() -> PythonQt.QtCore.QCommandLineOption (shared captured text)
addOption function (self, commandLineOption: Any) -> bool X.addOption(commandLineOption) -> bool (shared captured text)
addOptions function (self, options: Any) -> bool X.addOptions(options) -> bool (shared captured text)
addPositionalArgument function (self, name: str, description: str, syntax: str) -> None X.addPositionalArgument(name, description, syntax) (shared captured text)
addVersionOption function (self) -> Any X.addVersionOption() -> PythonQt.QtCore.QCommandLineOption (shared captured text)
applicationDescription function (self) -> str X.applicationDescription() -> str (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
clearPositionalArguments function (self) -> None Clears the definitions of additional arguments from the help text. (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
errorText function (self) -> str X.errorText() -> str (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
helpText function (self) -> str X.helpText() -> str (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
isSet function (self, option: Any) -> bool X.isSet(option) -> bool (shared captured text)
optionNames function (self) -> tuple X.optionNames() -> tuple (shared captured text)
parse function (self, arguments: Any) -> bool X.parse(arguments) -> bool (shared captured text)
positionalArguments function (self) -> tuple X.positionalArguments() -> tuple (shared captured text)
process function (self, app: Any) -> None Processes the command line arguments. (shared captured text)
setApplicationDescription function (self, description: str) -> None Sets the application description shown by [helpText](https://doc.qt.io/archives/qt-5.15/qcommandlineparser.html#helpText)(). (shared captured text)
setOptionsAfterPositionalArgumentsMode function (self, mode: Any) -> None Sets the parsing mode to parsingMode. (shared captured text)
setSingleDashWordOptionMode function (self, parsingMode: Any) -> None Sets the parsing mode to singleDashWordOptionMode. (shared captured text)
showHelp function (self, exitCode: int) -> None Displays the help information, and exits the application. (shared captured text)
showVersion function (self) -> None Displays the version information from [QCoreApplication::applicationVersion](https://doc.qt.io/archives/qt-5.15/qcoreapplication.html#applicationVersion-prop)(), and exits the application. (shared captured text)
tr function (self, sourceText: Any, disambiguation: Any, n: Any) -> str X.tr(sourceText, disambiguation, n) -> str (shared captured text)
trUtf8 function (self, sourceText: Any, disambiguation: Any, n: Any) -> str X.trUtf8(sourceText, disambiguation, n) -> str (shared captured text)
unknownOptionNames function (self) -> tuple X.unknownOptionNames() -> tuple (shared captured text)
value function (self, option: Any) -> str X.value(option) -> str (shared captured text)
values function (self, option: Any) -> tuple X.values(option) -> tuple (shared captured text)