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

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

enum QCommandLineParser::OptionsAfterPositionalArgumentsMode

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

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

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

enum 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}, часть значения будет опущена, и в список будет добавлено только длинное имя.

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

См. также 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().