Класс QCommandLineParser

Класс QCommandLineParser предоставляет способ обработки параметров командной строки. Подробнее...

• Список всех членов, включая унаследованные члены

Открытые типы

Открытые функции

Подробное описание

QCoreApplication предоставляет аргументы командной строки в виде простого списка строк. QCommandLineParser предоставляет возможность определить набор опций, разобрать аргументы командной строки и сохранить, какие опции были фактически использованы, а также значения опций.

Любой аргумент, который не является опцией (то есть не начинается с - ), сохраняется как «позиционный аргумент».

Парсер обрабатывает короткие имена, длинные имена, более одного имени для одной и той же опции и значения опций.

Опции в командной строке распознаются по наличию одного или двух - символа(ов) в начале. Опция - (один дефис) является специальным случаем, часто означающим стандартный ввод, и не рассматривается как опция. Парсер будет рассматривать всё после опции -- (два дефиса) как позиционные аргументы.

Короткие опции представляют собой одиночные буквы. Опция v будет задана передачей -v в командной строке. В режиме обработки по умолчанию короткие опции могут быть записаны в компактной форме, например, -abc эквивалентно -a -b -c. Режим обработки можно установить на ParseAsLongOptions, в этом случае -abc будет распознан как длинная опция abc.

Длинные опции имеют длину более одной буквы и не могут быть объединены. Длинная опция verbose будет передана как --verbose или -verbose.

Передача значений опциям может быть выполнена с использованием оператора присваивания: -v=value --verbose=value, или пробелом: -v value --verbose value, т.е. следующий аргумент используется как значение (даже если он начинается с -).

Парсер не поддерживает необязательные значения — если опция должна иметь значение, оно должно быть указано. Если такая опция находится в конце и не имеет значения, она будет обрабатываться так, как будто она не была указана.

Парсер не автоматически поддерживает отмену или отключение длинных опций с помощью формата --disable-option или --no-option. Однако можно явно обработать такой случай, сделав опцию с no-option в качестве одного из своих имен и обработав опцию явно.

Пример:

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

Если ваш компилятор поддерживает стандарт C++11, три вызова addOption() в приведенном выше примере можно упростить:

    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")},
    });

Известное ограничение: обработка опций Qt внутри QCoreApplication и подклассов происходит до создания QCommandLineParser, поэтому он не может их учесть. Это означает, что любое значение опции, которое выглядит как встроенная опция Qt, будет обработано QCoreApplication как встроенная опция Qt. Пример: --profile -reverse приведет к тому, что QGuiApplication увидит установленную опцию -reverse и удалит её из QCoreApplication::arguments() до того, как QCommandLineParser определит опцию profile и обработает командную строку.

Как использовать QCommandLineParser в сложных приложениях

На практике необходимо выполнять дополнительную проверку позиционных аргументов и значений опций. Например, нужно проверять диапазоны чисел.

Затем рекомендуется ввести функцию для обработки командной строки, которая принимает структуру или класс, принимающий значения опций, и возвращает перечисление, представляющее результат. Пример dnslookup из модуля QtNetwork демонстрирует это:

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;
}

В функции main должно выводиться справка в стандартный вывод, если была передана опция справки, и приложение должно возвращать код завершения 0.

Если была обнаружена ошибка, сообщение об ошибке должно быть выведено в стандартный поток ошибок, а приложение должно вернуть код выхода, отличный от 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();
    }

Особый случай следует рассмотреть для GUI-приложений на Windows и мобильных платформах. Эти приложения могут не использовать стандартные каналы вывода или ошибок, так как вывод либо отбрасывается, либо недоступен.

В Windows QCommandLineParser использует диалоговые окна сообщений для отображения информации об использовании и ошибок, если окно консоли получить не удается.

Для других платформ рекомендуется отображать подсказки и сообщения об ошибках с помощью QMessageBox. Для сохранения форматирования подсказки необходимо использовать форматированный текст с <pre> элементами:

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;
}

Однако это не относится к примеру dnslookup, так как это консольное приложение.

См. также QCommandLineOption и QCoreApplication.

Документация по типам членов

[since 5.6] перечисление QCommandLineParser::OptionsAfterPositionalArgumentsMode

Это перечисление описывает способ, которым парсер интерпретирует параметры, которые следуют после позиционных аргументов.

Это перечисление было добавлено или изменено в Qt 5.6.

См. также setOptionsAfterPositionalArgumentsMode().

перечисление QCommandLineParser::SingleDashWordOptionMode

Это перечисление описывает способ, которым парсер интерпретирует параметры командной строки, использующие один дефис, за которым следуют несколько букв, как -abc.

См. также setSingleDashWordOptionMode().

Документация по функциям членов

QCommandLineParser::QCommandLineParser()

Конструирует объект парсера командной строки.

QCommandLineParser::~QCommandLineParser()

Удаляет объект парсера командной строки.

QCommandLineOption QCommandLineParser::addHelpOption()

Добавляет параметр справки (-h, --help и -? в Windows), а также параметр --help-all для включения специфичных для Qt параметров в вывод.

Эти параметры автоматически обрабатываются QCommandLineParser.

Не забудьте использовать setApplicationDescription для задания описания приложения, которое будет отображено при использовании этого параметра.

Пример:

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

Возвращает экземпляр параметра, который можно использовать для вызова isSet().

bool QCommandLineParser::addOption(const QCommandLineOption &option)

Добавляет параметр option для поиска во время парсинга.

Возвращает true , если добавление параметра прошло успешно; в противном случае возвращает false.

Добавление параметра завершается неудачно, если к параметру не присвоено имя или параметр имеет имя, которое совпадает с именем параметра, добавленного ранее.

[since 5.4] bool QCommandLineParser::addOptions(const QList<QCommandLineOption> &options)

Добавляет параметры для поиска во время парсинга. Параметры задаются параметром options.

Возвращает true , если добавление всех параметров прошло успешно; в противном случае возвращает false.

См. документацию addOption() для случаев, когда эта функция может завершиться неудачно.

Эта функция была добавлена в Qt 5.4.

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

Определяет дополнительный аргумент для приложения для помощи в тексте справки.

Аргумент name и description будут отображаться в разделе Arguments: справки. Если syntax задан, он будет добавлен к строке Использование, в противном случае будет добавлен name.

Пример:

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

См. также addHelpOption() и helpText().

QCommandLineOption QCommandLineParser::addVersionOption()

Добавляет параметр -v / --version , который отображает строку версии приложения.

Этот параметр автоматически обрабатывается QCommandLineParser.

Вы можете установить фактическую строку версии, используя QCoreApplication::setApplicationVersion().

Возвращает экземпляр параметра, который можно использовать для вызова isSet().

QString QCommandLineParser::applicationDescription() const

Возвращает описание приложения, заданное в setApplicationDescription().

См. также setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Очищает определения дополнительных аргументов из текста справки.

Это необходимо только в специальном случае инструментов, которые поддерживают несколько команд с различными параметрами. После того, как фактическая команда будет идентифицирована, параметры для этой команды могут быть определены, и текст справки для команды может быть соответствующим образом скорректирован.

Пример:

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

Возвращает переведенный текст ошибки для пользователя. Это следует вызывать только тогда, когда parse() возвращает false.

QString QCommandLineParser::helpText() const

Возвращает строку, содержащую полную справочную информацию.

См. также showHelp().

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

Проверяет, был ли параметр name передан в приложение.

Возвращает true , если параметр name был задан, в противном случае возвращает false.

Указанное имя может быть любым длинным или коротким именем любого параметра, который был добавлен с помощью addOption(). Все имена параметров считаются эквивалентными. Если имя не распознано или этот параметр отсутствовал, возвращается false.

Пример:

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

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

Это перегруженная функция.

Проверяет, был ли параметр option передан в приложение.

Возвращает true , если параметр option был задан, в противном случае возвращает false.

Это рекомендуемый способ проверки параметров без значений.

Пример:

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

QStringList QCommandLineParser::optionNames() const

Возвращает список имен опций, которые были найдены.

Это возвращает список всех распознанных имён опций, найденных парсером, в порядке их обнаружения. Для любых длинных опций, которые имели вид {--option=value}, часть со значением была удалена.

Имена в этом списке не включают предшествующие символы тире. Имена могут появляться в этом списке более одного раза, если они были встречены парсером более одного раза.

Любой элемент в списке может быть использован с value() или с values() для получения соответствующих значений опций.

bool QCommandLineParser::parse(const QStringList &arguments)

Парсит командную строку arguments.

Большинству программ не нужно вызывать этот метод, достаточно простого вызова process().

parse() — более низкоуровневый метод, выполняющий только парсинг. Приложение должно позаботиться об обработке ошибок, используя errorText(), если parse() возвращает false. Это может быть полезно, например, для отображения графического сообщения об ошибке в графических программах.

Вызов parse() вместо process() также может быть полезен для временного игнорирования неизвестных опций, поскольку более подробные определения опций могут быть предоставлены позже (в зависимости от одного из аргументов) перед вызовом process().

Не забудьте, что arguments должны начинаться с имени исполняемого файла (он игнорируется).

Возвращает false в случае ошибки парсинга (неизвестная опция или недостающее значение); в противном случае возвращает true.

См. также process().

QStringList QCommandLineParser::positionalArguments() const

Возвращает список позиционных аргументов.

Это все аргументы, которые не были распознаны как часть опции.

void QCommandLineParser::process(const QStringList &arguments)

Обрабатывает аргументы командной строки arguments.

В дополнение к парсингу опций (как в parse()), эта функция также обрабатывает встроенные опции и ошибки.

Встроенные опции — --version если был вызван addVersionOption и --help / --help-all если был вызван addHelpOption.

При вызове одной из этих опций или при возникновении ошибки (например, была передана неизвестная опция), текущий процесс завершится с использованием функции exit().

См. также QCoreApplication::arguments() и parse().

void QCommandLineParser::process(const QCoreApplication &app)

Это перегруженный метод.

Командная строка получается из экземпляра QCoreApplication app.

void QCommandLineParser::setApplicationDescription(const QString &description)

Устанавливает описание приложения description, отображаемое методом helpText().

См. также applicationDescription().

[since 5.6] void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode)

Устанавливает режим парсинга в parsingMode. Этот метод должен быть вызван до process() или parse().

Этот метод был добавлен в Qt 5.6.

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

Устанавливает режим парсинга в singleDashWordOptionMode. Этот метод должен быть вызван до process() или parse().

void QCommandLineParser::showHelp(int exitCode = 0)

Отображает информацию о помощи и завершает приложение. Это автоматически запускается опцией --help, но также может быть использовано для отображения справки, если пользователь неправильно вызывает приложение. Код возврата устанавливается в exitCode. Он должен быть установлен в 0, если пользователь запросил отображение справки, и в любом другом значении в случае ошибки.

См. также helpText().

[since 5.4] void QCommandLineParser::showVersion()

Отображает информацию о версии из QCoreApplication::applicationVersion() и завершает приложение. Это автоматически запускается опцией --version, но также может быть использовано для отображения версии без использования process(). Код возврата устанавливается в EXIT_SUCCESS (0).

Этот метод был добавлен в Qt 5.4.

См. также addVersionOption().

QStringList QCommandLineParser::unknownOptionNames() const

Возвращает список неизвестных имён опций.

Этот список будет содержать как длинные, так и короткие имена опций, которые не были распознаны. Для любых длинных опций, имеющих вид {--option=value}, часть со значением была удалена, и добавлено только длинное имя.

Имена в этом списке не включают предшествующие символы тире. Имена могут появляться в этом списке более одного раза, если они были встречены парсером более одного раза.

См. также optionNames().

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

Возвращает значение опции, найденное для данного имени опции optionName, или пустую строку, если не найдено.

Указанное имя может быть любым длинным или коротким именем любой опции, которая была добавлена с помощью addOption(). Все имена опций рассматриваются как эквивалентные. Если имя не распознано или опция отсутствовала, возвращается пустая строка.

Для опций, найденных парсером, возвращается последнее найденное значение для этой опции. Если опция не была указана в командной строке, возвращается значение по умолчанию.

Возвращается пустая строка, если опция не принимает значение.

См. также values(), QCommandLineOption::setDefaultValue() и QCommandLineOption::setDefaultValues().

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

Это перегруженный метод.

Возвращает значение опции, найденное для данной option, или пустую строку, если не найдено.

Для опций, найденных парсером, возвращается последнее найденное значение для этой опции. Если опция не была указана в командной строке, возвращается значение по умолчанию.

Возвращается пустая строка, если опция не принимает значение.

См. также values(), QCommandLineOption::setDefaultValue() и QCommandLineOption::setDefaultValues().

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

Возвращает список значений опции, найденных для данного имени опции optionName, или пустой список, если не найдено.

Указанное имя может быть любым длинным или коротким именем любой опции, которая была добавлена с помощью addOption(). Все имена опций рассматриваются как эквивалентные. Если имя не распознано или опция отсутствовала, возвращается пустой список.

Для опций, найденных парсером, список будет содержать запись для каждого случая, когда опция была встречена парсером. Если опция не была указана в командной строке, возвращаются значения по умолчанию.

Возвращается пустой список, если опция не принимает значение.

См. также value(), QCommandLineOption::setDefaultValue() и QCommandLineOption::setDefaultValues().

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

Это перегруженный метод.

Возвращает список значений опции, найденных для данной option, или пустой список, если не найдено.

Для опций, найденных парсером, список будет содержать запись для каждого случая, когда опция была встречена парсером. Если опция не была указана в командной строке, возвращаются значения по умолчанию.

Возвращается пустой список, если опция не принимает значение.

См. также value(), QCommandLineOption::setDefaultValue() и QCommandLineOption::setDefaultValues().