QCommandLineParser Class

Dokumentation der Mitgliedsfunktionen

QCommandLineParser::QCommandLineParser()

Konstruiert ein Kommandozeilen-Parser-Objekt.

[noexcept] QCommandLineParser::~QCommandLineParser()

Zerstört das Kommandozeilen-Parser-Objekt.

QCommandLineOption QCommandLineParser::addHelpOption()

Fügt dem Befehlszeilenparser Hilfeoptionen hinzu.

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

Diese Optionen werden automatisch von QCommandLineParser behandelt.

Denken Sie daran, setApplicationDescription() zu verwenden, um die Anwendungsbeschreibung zu setzen, die angezeigt wird, wenn diese Option verwendet 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, die für den Aufruf von isSet() verwendet 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 kein Name an die Option angehängt ist oder die Option einen Namen hat, der mit einem zuvor hinzugefügten Optionsnamen kollidiert.

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

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

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

In der Dokumentation zu addOption() ist beschrieben, wann diese Funktion fehlschlagen kann.

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

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

Die Argumente name und description werden unter dem Abschnitt Arguments: in der Hilfe erscheinen. 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 / --version hinzu, die den Versionsstring der Anwendung anzeigt.

Diese Option wird automatisch von QCommandLineParser behandelt.

Sie können die aktuelle Versionszeichenfolge mit QCoreApplication::setApplicationVersion() setzen.

Gibt die Optionsinstanz zurück, die für den Aufruf von isSet() verwendet werden kann.

QString QCommandLineParser::applicationDescription() const

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

Siehe auch setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Löscht die Definitionen von zusätzlichen Argumenten aus dem Hilfetext.

Dies ist nur für den speziellen Fall von Werkzeugen erforderlich, die mehrere Befehle mit unterschiedlichen Optionen unterstützen. Sobald der eigentliche Befehl identifiziert ist, können die Optionen für diesen Befehl definiert werden, und der Hilfetext für den Befehl kann 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. Dies sollte nur aufgerufen werden, wenn parse() false zurückgibt.

QString QCommandLineParser::helpText() const

Gibt eine Zeichenkette mit den vollständigen Hilfeinformationen zurück.

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 langer oder kurzer Name einer beliebigen Option sein, die mit addOption() hinzugefügt wurde. Alle Optionsnamen werden als gleichwertig behandelt. Wenn der Name nicht erkannt wird oder die Option nicht vorhanden war, wird false zurückgegeben.

Beispiel:

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

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

Dies ist eine überladene Funktion.

Prüft, ob die option an die Anwendung übergeben wurde.

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

Dies ist der empfohlene Weg, um nach Optionen ohne Werte zu suchen.

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 Optionsnamen zurück, die gefunden wurden.

Gibt eine Liste aller erkannten Optionsnamen zurück, die vom Parser gefunden wurden, und zwar in der Reihenfolge, in der sie gefunden wurden. Bei langen Optionen in der Form {-option=wert} wurde der Wertteil weggelassen.

Die Namen in dieser Liste enthalten nicht die vorangestellten Bindestriche. Namen können mehrfach in dieser Liste erscheinen, wenn sie vom Parser mehr als einmal gefunden wurden.

Jeder Eintrag in der Liste kann mit value() oder mit values() verwendet werden, um alle relevanten Optionswerte zu erhalten.

bool QCommandLineParser::parse(const QStringList &arguments)

Analysiert die Befehlszeile arguments.

Die meisten Programme brauchen dies nicht aufzurufen, ein einfacher Aufruf von process() ist ausreichend.

parse() ist eher auf niedriger Ebene angesiedelt und führt nur das Parsing durch. Die Anwendung muss sich um die Fehlerbehandlung kümmern und errorText() verwenden, wenn parse() false zurückgibt. Dies kann zum Beispiel 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, denn weitere Optionsdefinitionen werden später (abhängig von einem der Argumente) bereitgestellt, bevor process() aufgerufen wird.

Vergessen Sie nicht, dass arguments mit dem Namen der ausführbaren Datei beginnen muss (wird aber ignoriert).

Gibt false zurück, wenn ein Parse-Fehler vorliegt (unbekannte Option oder fehlender Wert); andernfalls wird true zurückgegeben.

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 Befehlszeile arguments.

Zusätzlich zum Parsen der Optionen (wie parse()) behandelt diese Funktion auch die eingebauten Optionen und behandelt Fehler.

Die eingebauten Optionen sind --version, wenn addVersionOption aufgerufen wurde, und --help / --help-all, wenn addHelpOption aufgerufen wurde.

Wenn eine dieser Optionen aufgerufen wird oder ein Fehler auftritt (z. B. wenn eine unbekannte Option übergeben wurde), wird der aktuelle Prozess mit der Funktion exit() beendet.

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

void QCommandLineParser::process(const QCoreApplication &app)

Dies ist eine überladene Funktion.

Die Befehlszeile wird von der Instanz QCoreApplication app bezogen.

void QCommandLineParser::setApplicationDescription(const QString &description)

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

Siehe auch applicationDescription().

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

Setzt den Parsing-Modus auf parsingMode. Dies muss vor process() oder parse() aufgerufen werden.

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

Setzt den Parsing-Modus auf singleDashWordOptionMode. Dieser Aufruf muss vor process() oder parse() erfolgen.

void QCommandLineParser::showHelp(int exitCode = 0)

Zeigt die Hilfeinformationen 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 sehen wollte, und auf einen beliebigen anderen Wert im Falle eines Fehlers.

Siehe auch helpText().

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 der unbekannten Optionsnamen zurück.

Diese Liste enthält sowohl Optionen mit langem als auch mit kurzem Namen, die nicht erkannt wurden. Bei langen Optionen, die in der Form {-option=wert} vorlagen, wurde der Wertteil weggelassen und nur der lange Name hinzugefügt.

Die Namen in dieser Liste enthalten nicht die vorangestellten Bindestriche. Namen können mehrfach in dieser Liste erscheinen, wenn sie vom Parser mehr als einmal angetroffen wurden.

Siehe auch optionNames().

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

Gibt den Optionswert zurück, der für den angegebenen Optionsnamen optionName gefunden wurde, oder einen leeren String, wenn er nicht gefunden wurde.

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

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

Wenn die Option keinen Wert annimmt, 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

Dies ist eine überladene Funktion.

Gibt den Optionswert zurück, der für die angegebene option gefunden wurde, oder einen leeren String, wenn er nicht gefunden wurde.

Bei Optionen, die vom Parser gefunden wurden, wird der letzte für diese Option gefundene Wert zurückgegeben. Wenn die Option nicht in der Befehlszeile angegeben wurde, 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 Optionswerte zurück, die für den angegebenen Optionsnamen optionName gefunden wurden, oder eine leere Liste, falls nicht gefunden.

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

Bei 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 in der Befehlszeile angegeben, werden die Standardwerte zurückgegeben.

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

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

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

Dies ist eine überladene Funktion.

Gibt eine Liste der Optionswerte zurück, die für die angegebene option gefunden wurden, oder eine leere Liste, wenn sie nicht gefunden wurde.

Bei 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. 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 annimmt.

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