QCommandLineParser Class

Dokumentation der Member-Funktionen

QCommandLineParser::QCommandLineParser()

Erstellt ein Objekt für die Befehlszeilenauswertung.

[noexcept] QCommandLineParser::~QCommandLineParser()

Löscht das Befehlszeilen-Parser-Objekt.

QCommandLineOption QCommandLineParser::addHelpOption()

Fügt dem Befehlszeilen-Parser Hilfeoptionen hinzu.

Die für diese Befehlszeile angegebenen Optionen werden unter -h oder --help beschrieben. Unter Windows wird auch die alternative Option -? unterstützt. Die Option --help-all erweitert dies dahingehend, dass generische Qt-Optionen, die nicht durch diesen Befehl definiert sind, in die Ausgabe aufgenommen werden.

Diese Optionen werden von QCommandLineParser automatisch verarbeitet.

Denken Sie daran, setApplicationDescription() zu verwenden, um die Anwendungsbeschreibung festzulegen, die bei Verwendung dieser Option angezeigt wird.

Beispiel:

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);
    // ...
}

Gibt die Optionsinstanz zurück, mit der ` isSet()` aufgerufen werden kann.

bool QCommandLineParser::addOption(const QCommandLineOption &option)

Fügt die Option „ option “ hinzu, nach der beim Parsen gesucht werden soll.

Gibt „ true “ zurück, wenn das Hinzufügen der Option erfolgreich war; andernfalls wird „ false “ zurückgegeben.

Das Hinzufügen der Option schlägt fehl, wenn der Option kein Name zugewiesen ist oder wenn der Name der Option mit dem Namen einer zuvor hinzugefügten Option kollidiert.

bool QCommandLineParser::addOptions(const QList<QCommandLineOption> &options)

Fügt die Optionen hinzu, nach denen beim Parsen gesucht werden soll. Die Optionen werden über den Parameter „ options “ angegeben.

Gibt ` true ` zurück, wenn das Hinzufügen aller Optionen erfolgreich war; andernfalls wird ` false` zurückgegeben.

Informationen dazu, unter welchen Umständen diese Funktion fehlschlagen kann, finden Sie in der Dokumentation zu ` addOption()`.

void QCommandLineParser::addPositionalArgument(const QString &name, const QString &description, const QString &syntax = QString())

Definiert ein zusätzliches Argument für die Anwendung, das für den Hilfetext verwendet wird.

Die Argumente „ name “ und „ description “ werden im Abschnitt „ Arguments: “ der Hilfe angezeigt. Wenn „ syntax “ angegeben ist, wird es an die Zeile „Usage“ angehängt, andernfalls wird „ name “ angehängt.

Beispiel:

// 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."));

Siehe auch addHelpOption() und helpText().

QCommandLineOption QCommandLineParser::addVersionOption()

Fügt die Option „ -v “ bzw. „ --version “ hinzu, die die Versionszeichenfolge der Anwendung anzeigt.

Diese Option wird automatisch von QCommandLineParser verarbeitet.

Sie können die tatsächliche Versionszeichenfolge mithilfe von ` QCoreApplication::setApplicationVersion()` festlegen.

Gibt die Optionsinstanz zurück, mit der ` isSet()` aufgerufen werden kann.

QString QCommandLineParser::applicationDescription() const

Gibt die in setApplicationDescription() festgelegte Anwendungsbeschreibung zurück.

Siehe auch setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Löscht die Definitionen zusätzlicher Argumente aus dem Hilfetext.

Dies ist nur im Sonderfall von Tools erforderlich, die mehrere Befehle mit unterschiedlichen Optionen unterstützen. Sobald der eigentliche Befehl identifiziert wurde, können die Optionen für diesen Befehl definiert und der Hilfetext für den Befehl entsprechend angepasst werden.

Beispiel:

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.
*/

QString QCommandLineParser::errorText() const

Gibt einen übersetzten Fehlertext für den Benutzer zurück. Diese Funktion sollte nur aufgerufen werden, wenn parse() den Wert „ false “ zurückgibt.

QString QCommandLineParser::helpText() const

Gibt eine Zeichenkette zurück, die die vollständigen Hilfeinformationen enthält.

Siehe auch ` showHelp()`.

bool QCommandLineParser::isSet(const QString &name) const

Prüft, ob die Option „ name “ an die Anwendung übergeben wurde.

Gibt „ true “ zurück, wenn die Option „ name “ gesetzt wurde, andernfalls „false“.

Der angegebene Name kann ein beliebiger Lang- oder Kurzname einer Option sein, die mit ` addOption()` hinzugefügt wurde. Alle Optionsnamen werden als gleichwertig behandelt. Wird der Name nicht erkannt oder war die Option nicht vorhanden, wird `false` zurückgegeben.

Beispiel:

bool verbose = parser.isSet("verbose");

bool QCommandLineParser::isSet(const QCommandLineOption &option) const

Prüft, ob der Parameter „ option “ an die Anwendung übergeben wurde.

Gibt „ true “ zurück, wenn „ option “ gesetzt wurde, andernfalls „false“.

Dies ist die empfohlene Methode, um Optionen ohne Werte zu prüfen.

Beispiel:

QCoreApplication app(argc, argv);
QCommandLineParser parser;
QCommandLineOption verboseOption("verbose");
parser.addOption(verboseOption);
parser.process(app);
bool verbose = parser.isSet(verboseOption);

QStringList QCommandLineParser::optionNames() const

Gibt eine Liste der gefundenen Optionsnamen zurück.

Dies gibt eine Liste aller vom Parser erkannten Optionsnamen in der Reihenfolge zurück, in der sie gefunden wurden. Bei langen Optionen, die die Form {–option=value} hatten, wurde der Wertteil weggelassen.

Die Namen in dieser Liste enthalten keine vorangestellten Bindestriche. Namen können in dieser Liste mehrmals vorkommen, wenn sie vom Parser mehr als einmal gefunden wurden.

Jeder Eintrag in der Liste kann mit ` value()` oder mit ` values()` verwendet werden, um die entsprechenden Optionswerte abzurufen.

bool QCommandLineParser::parse(const QStringList &arguments)

Analysiert die Befehlszeile „ arguments “.

Die meisten Programme müssen diese Funktion nicht aufrufen; ein einfacher Aufruf von ` process()` reicht aus.

`parse()` ist eher auf niedrigerer Ebene angesiedelt und führt lediglich die Analyse durch. Die Anwendung muss sich um die Fehlerbehandlung kümmern und ` errorText()` verwenden, falls `parse()` ` false` zurückgibt. Dies kann beispielsweise nützlich sein, um in grafischen Programmen eine grafische Fehlermeldung anzuzeigen.

Der Aufruf von `parse()` anstelle von ` process()` kann auch nützlich sein, um unbekannte Optionen vorübergehend zu ignorieren, da später (abhängig von einem der Argumente) weitere Optionsdefinitionen bereitgestellt werden, bevor ` process()` aufgerufen wird.

Beachten Sie, dass „ arguments “ mit dem Namen der ausführbaren Datei beginnen muss (der jedoch ignoriert wird).

Gibt im Falle eines Parsing-Fehlers (unbekannte Option oder fehlender Wert) „ false “ zurück; andernfalls „ true “.

Siehe auch process().

QStringList QCommandLineParser::positionalArguments() const

Gibt eine Liste von Positionsargumenten zurück.

Dies sind alle Argumente, die nicht als Teil einer Option erkannt wurden.

void QCommandLineParser::process(const QStringList &arguments)

Verarbeitet die Befehlszeilen arguments.

Neben der Auswertung der Optionen (wie bei ` parse()`) verarbeitet diese Funktion auch die integrierten Optionen und behandelt Fehler.

Die integrierten Optionen sind „ --version “, wenn „ addVersionOption “ aufgerufen wurde, sowie „ --help “ bzw. „ --help-all “, wenn „ addHelpOption “ aufgerufen wurde.

Beim Aufruf einer dieser Optionen oder wenn ein Fehler auftritt (z. B. wenn eine unbekannte Option übergeben wurde), wird der aktuelle Prozess mithilfe der Funktion `exit()` beendet.

Siehe auch QCoreApplication::arguments() und parse().

void QCommandLineParser::process(const QCoreApplication &app)

Die Befehlszeile wird von der Instanz „ QCoreApplication “ abgerufen: app.

void QCommandLineParser::setApplicationDescription(const QString &description)

Legt die Anwendungs description fest, die von helpText() angezeigt wird.

Siehe auch ` applicationDescription()`.

void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode)

Stellt den Parsing-Modus auf „ parsingMode “ ein. Diese Funktion muss vor dem Aufruf von „ process()“ oder „ parse()“ aufgerufen werden.

void QCommandLineParser::setSingleDashWordOptionMode(QCommandLineParser::SingleDashWordOptionMode singleDashWordOptionMode)

Stellt den Parsing-Modus auf „ singleDashWordOptionMode “ ein. Diese Funktion muss vor dem Aufruf von „ process()“ oder „ parse()“ aufgerufen werden.

void QCommandLineParser::showHelp(int exitCode = 0)

Zeigt die Hilfe an und beendet die Anwendung. Dies wird automatisch durch die Option „–help“ ausgelöst, kann aber auch verwendet werden, um die Hilfe anzuzeigen, wenn der Benutzer die Anwendung nicht korrekt aufruft. Der Exit-Code wird auf „ exitCode “ gesetzt. Er sollte auf 0 gesetzt werden, wenn der Benutzer die Hilfe angefordert hat, und auf einen beliebigen anderen Wert im Falle eines Fehlers.

Siehe auch „ helpText()“ und „ showMessageAndExit()“.

[static, since 6.9] void QCommandLineParser::showMessageAndExit(QCommandLineParser::MessageType type, const QString &message, int exitCode = 0)

Zeigt eine „ message “ an und beendet die Anwendung mit der angegebenen „ exitCode “.

Die Meldung „ message “ wird in der Regel entsprechend der angegebenen Option „ type “ direkt an „ stdout “ oder „ stderr “ ausgegeben, oder die Meldung wird bei Bedarf unter Windows in einem Meldungsfeld angezeigt, wobei je nach der angegebenen Option „ type “ ein Informations- oder Fehlersymbol erscheint (setzen Sie die Umgebungsvariable „ QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES “, wenn Sie das Meldungsfeld nicht wünschen).

Es handelt sich um dieselbe Methode zur Anzeige von Meldungen, die auch von „ showHelp “, „ showVersion “ und den integrierten Optionen verwendet wird (--version, wenn „ addVersionOption “ aufgerufen wurde, und --help / --help-all, wenn „ addHelpOption “ aufgerufen wurde).

Diese Funktion wurde in Qt 6.9 eingeführt.

Siehe auch addVersionOption(), showHelp(), showVersion() und QCommandLineParser::MessageType.

void QCommandLineParser::showVersion()

Zeigt die Versionsinformationen von QCoreApplication::applicationVersion() an und beendet die Anwendung. Dies wird automatisch durch die Option –version ausgelöst, kann aber auch verwendet werden, um die Version anzuzeigen, wenn process() nicht verwendet wird. Der Exit-Code wird auf EXIT_SUCCESS (0) gesetzt.

Siehe auch addVersionOption().

QStringList QCommandLineParser::unknownOptionNames() const

Gibt eine Liste unbekannter Optionsnamen zurück.

Diese Liste enthält sowohl lange als auch kurze Optionsnamen, die nicht erkannt wurden. Bei langen Optionen in der Form {–option=value} wurde der Wert-Teil weggelassen und nur der lange Name hinzugefügt.

Die Namen in dieser Liste enthalten keine vorangestellten Bindestriche. Namen können in dieser Liste mehrmals vorkommen, wenn sie vom Parser mehr als einmal erkannt wurden.

Siehe auch ` optionNames()`.

QString QCommandLineParser::value(const QString &optionName) const

Gibt den für den angegebenen Optionsnamen optionName gefundenen Optionswert zurück oder eine leere Zeichenkette, falls dieser nicht gefunden wurde.

Der angegebene Name kann ein beliebiger langer oder kurzer Name einer Option sein, die mit ` addOption()` hinzugefügt wurde. Alle Optionsnamen werden als gleichwertig behandelt. Wird der Name nicht erkannt oder war die Option nicht vorhanden, wird eine leere Zeichenkette zurückgegeben.

Für Optionen, die vom Parser gefunden wurden, wird der zuletzt für diese Option gefundene Wert zurückgegeben. Wenn die Option nicht auf der Befehlszeile angegeben wurde, wird der Standardwert zurückgegeben.

Wenn die Option keinen Wert akzeptiert, wird eine Warnung ausgegeben und eine leere Zeichenkette zurückgegeben.

Siehe auch values(), QCommandLineOption::setDefaultValue() und QCommandLineOption::setDefaultValues().

QString QCommandLineParser::value(const QCommandLineOption &option) const

Gibt den für die angegebene Option „ option “ gefundenen Wert zurück oder eine leere Zeichenkette, falls keine Option gefunden wurde.

Bei Optionen, die vom Parser gefunden wurden, wird der zuletzt gefundene Wert für diese Option zurückgegeben. Wurde die Option nicht über die Befehlszeile angegeben, wird der Standardwert zurückgegeben.

Eine leere Zeichenkette wird zurückgegeben, wenn die Option keinen Wert annimmt.

Siehe auch ` values()`, ` QCommandLineOption::setDefaultValue()` und ` QCommandLineOption::setDefaultValues()`.

QStringList QCommandLineParser::values(const QString &optionName) const

Gibt eine Liste der für den angegebenen Optionsnamen optionName gefundenen Optionswerte zurück oder eine leere Liste, falls keine gefunden wurden.

Der angegebene Name kann ein beliebiger Lang- oder Kurzname einer Option sein, die mit ` addOption()` hinzugefügt wurde. Alle Optionsnamen werden als gleichwertig behandelt. Wird der Name nicht erkannt oder war die Option nicht vorhanden, wird eine leere Liste zurückgegeben.

Für Optionen, die vom Parser gefunden wurden, enthält die Liste einen Eintrag für jedes Mal, wenn der Parser auf die Option gestoßen ist. Wurde die Option nicht auf der Befehlszeile angegeben, werden die Standardwerte zurückgegeben.

Es wird eine leere Liste zurückgegeben, wenn die Option keinen Wert annimmt.

Siehe auch value(), QCommandLineOption::setDefaultValue() und QCommandLineOption::setDefaultValues().

QStringList QCommandLineParser::values(const QCommandLineOption &option) const

Gibt eine Liste der für die angegebene Option „ option “ gefundenen Optionswerte zurück oder eine leere Liste, falls keine gefunden wurden.

Für Optionen, die vom Parser gefunden wurden, enthält die Liste einen Eintrag für jedes Mal, wenn die Option vom Parser erkannt wurde. Wenn die Option nicht in der Befehlszeile angegeben wurde, werden die Standardwerte zurückgegeben.

Eine leere Liste wird zurückgegeben, wenn die Option keinen Wert akzeptiert.

Siehe auch ` value()`, ` QCommandLineOption::setDefaultValue()` und ` QCommandLineOption::setDefaultValues()`.