Класс QCommandLineParser

Класс 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.

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

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

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

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

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

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

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

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

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

QCommandLineParser::QCommandLineParser()

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

QCommandLineParser::~QCommandLineParser()

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

QCommandLineOption QCommandLineParser::addHelpOption()

Добавляет опцию справки (-h, --help и -? на Windows). Эта опция обрабатывается автоматически объектом 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.

Добавление опции не удастся, если к опции не присвоено имя или имя опции совпадает с именем ранее добавленной опции.

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 если был вызван addHelpOption.

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

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

void QCommandLineParser::process(const QCoreApplication &app)

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

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

void QCommandLineParser::setApplicationDescription(const QString &description)

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

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

void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(OptionsAfterPositionalArgumentsMode parsingMode)

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

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

void QCommandLineParser::setSingleDashWordOptionMode(SingleDashWordOptionMode singleDashWordOptionMode)

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

void QCommandLineParser::showHelp(int exitCode = 0)

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

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

void QCommandLineParser::showVersion()

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

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

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

QStringList QCommandLineParser::unknownOptionNames() const

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

Этот список будет содержать как длинные, так и короткие имена параметров, которые не были распознаны. Для любых длинных параметров, имеющих вид {--option=value}, часть 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().