Класс QCommandLineParser

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

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

Типы public

Функции public

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

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

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().