QCommandLineParser 类
QCommandLineParser 类提供了处理命令行选项的方法。 更多...
头文件 | #include <QCommandLineParser> |
CMake | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake | QT += core |
公共类型
枚举 | OptionsAfterPositionalArgumentsMode { ParseAsOptions, ParseAsPositionalArguments } |
枚举 | SingleDashWordOptionMode { ParseAsCompactedShortOptions, ParseAsLongOptions } |
公共函数
QCommandLineParser() | |
~QCommandLineParser() | |
QCommandLineOption | addHelpOption() |
bool | addOption(const QCommandLineOption &option) |
bool | addOptions(const QList<QCommandLineOption> &options) |
void | addPositionalArgument(const QString &name, const QString &description, const QString &syntax = QString()) |
QCommandLineOption | addVersionOption() |
QString | applicationDescription() const |
void | clearPositionalArguments() |
QString | errorText() const |
QString | helpText() const |
bool | isSet(const QString &name) const |
bool | isSet(const QCommandLineOption &option) const |
QStringList | optionNames() const |
bool | parse(const QStringList &arguments) |
QStringList | positionalArguments() const |
void | process(const QStringList &arguments) |
void | process(const QCoreApplication &app) |
void | setApplicationDescription(const QString &description) |
void | setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode) |
void | setSingleDashWordOptionMode(QCommandLineParser::SingleDashWordOptionMode singleDashWordOptionMode) |
void | showHelp(int exitCode = 0) |
void | showVersion() |
QStringList | unknownOptionNames() const |
QString | value(const QString &optionName) const |
QString | value(const QCommandLineOption &option) const |
QStringList | values(const QString &optionName) const |
QStringList | values(const QCommandLineOption &option) const |
详细描述
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); // ... }
上述示例中的三个 addOption() 调用可以更紧凑地通过使用 addOptions() 来实现。
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")}, });
已知限制:在 QCoreApplication 和其子类中,Qt 选项的解析发生在 QCommandLineParser 存在之前,因此它不能将其考虑在内。这意味着任何看起来像内置 Qt 选项的选项值都将被 QCoreApplication 视为内置 Qt 选项。例如:--profile -reverse
将导致 QGuiApplication 将 -reverse 选项设为已设置,并在 QCommandLineParser 定义 profile
选项并解析命令行之前,从 QCoreApplication::arguments() 中删除它。
在复杂应用程序中使用 QCommandLineParser 的方法
实际上,需要对定位参数和选项值执行额外的错误检查。例如,应检查数字的范围。
此外,建议引入一个函数来执行命令行解析,它接收一个结构体或类,该类接收选项值并返回一个表示结果的对象。QtNetwork 模块的 dnslookup 示例说明了这一点。
struct DnsQuery { DnsQuery() : type(QDnsLookup::A) {} QDnsLookup::Type type; QHostAddress nameServer; QString name; }; struct CommandLineParseResult { enum class Status { Ok, Error, VersionRequested, HelpRequested }; Status statusCode = Status::Ok; std::optional<QString> errorString = std::nullopt; }; CommandLineParseResult parseCommandLine(QCommandLineParser &parser, DnsQuery *query) { using Status = CommandLineParseResult::Status; 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())) return { Status::Error, parser.errorText() }; if (parser.isSet(versionOption)) return { Status::VersionRequested }; if (parser.isSet(helpOption)) return { Status::HelpRequested }; if (parser.isSet(nameServerOption)) { const QString nameserver = parser.value(nameServerOption); query->nameServer = QHostAddress(nameserver); if (query->nameServer.isNull() || query->nameServer.protocol() == QAbstractSocket::UnknownNetworkLayerProtocol) { return { Status::Error, u"Bad nameserver address: %1"_s.arg(nameserver) }; } } if (parser.isSet(typeOption)) { const QString typeParameter = parser.value(typeOption); if (std::optional<QDnsLookup::Type> type = typeFromParameter(typeParameter)) query->type = *type; else return { Status::Error, u"Bad record type: %1"_s.arg(typeParameter) }; } const QStringList positionalArguments = parser.positionalArguments(); if (positionalArguments.isEmpty()) return { Status::Error, u"Argument 'name' missing."_s }; if (positionalArguments.size() > 1) return { Status::Error, u"Several 'name' arguments specified."_s }; query->name = positionalArguments.first(); return { Status::Ok }; }
在主函数中,如果传递了帮助选项,则应将帮助信息打印到标准输出,并使应用程序返回退出码 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; using Status = CommandLineParseResult::Status; CommandLineParseResult parseResult = parseCommandLine(parser, &query); switch (parseResult.statusCode) { case Status::Ok: break; case Status::Error: std::fputs(qPrintable(parseResult.errorString.value_or(u"Unknown error occurred"_s)), stderr); std::fputs("\n\n", stderr); std::fputs(qPrintable(parser.helpText()), stderr); return 1; case Status::VersionRequested: parser.showVersion(); Q_UNREACHABLE_RETURN(0); case Status::HelpRequested: parser.showHelp(); Q_UNREACHABLE_RETURN(0); }
这里需要考虑的一个特殊情况是在 Windows 和移动平台上的 GUI 应用程序。由于输出可能被丢弃或无法访问,这些应用程序可能不会使用标准输出或错误通道。
在 Windows 上,如果无法获取控制台窗口,QCommandLineParser 使用消息框来显示使用信息和错误。
对于其他平台,建议使用 QMessageBox 来显示帮助文本和错误消息。为保留帮助文本的格式,应使用包含 <pre>
元素的富文本
switch (parseResult.statusCode) { case Status::Ok: break; case Status::Error: { QString errorMessage = parseResult.errorString.value_or(u"Unknown error occurred"_qs); QMessageBox::warning(0, QGuiApplication::applicationDisplayName(), "<html><head/><body><h2>" + errorMessage + "</h2><pre>" + parser.helpText() + "</pre></body></html>"); return 1; } case Status::VersionRequested: QMessageBox::information(0, QGuiApplication::applicationDisplayName(), QGuiApplication::applicationDisplayName() + ' ' + QCoreApplication::applicationVersion()); return 0; case Status::HelpRequested: QMessageBox::warning(0, QGuiApplication::applicationDisplayName(), "<html><head/><body><pre>" + parser.helpText() + "</pre></body></html>"); return 0; }
然而,这并不适用于 dnslookup 示例,因为它是一个控制台应用程序。
另请参阅QCommandLineOption 和 QCoreApplication。
成员类型文档
enum QCommandLineParser::OptionsAfterPositionalArgumentsMode
此枚举描述了解析器解释在位置参数之后出现的选项的方式。
常量 | 值 | 描述 |
---|---|---|
QCommandLineParser::ParseAsOptions | 0 | application argument --opt -t 是解释为设置选项 opt 和 t ,就像 application --opt -t argument 所做的那样。这是默认解析模式。为了指定 --opt 和 -t 是位置参数,用户可以使用 -- ,如 application argument -- --opt -t 。 |
QCommandLineParser::ParseAsPositionalArguments | 1 | application argument --opt 被解释为有两个位置参数,分别是 argument 和 --opt 。这种模式对于旨在启动其他可执行文件的程序(例如包装器、调试工具等)或支持内部命令后跟选项的程序很有用。 argument 是命令的名称,所有在它之后出现的选项都可以被另一个命令行解析器收集和解析,可能是在另一个可执行文件中。 |
另请参阅setOptionsAfterPositionalArgumentsMode。
enum QCommandLineParser::SingleDashWordOptionMode
此枚举描述了解析器解释使用单一短横线加多个字母的命令行选项的方式,如 -abc
。
常量 | 值 | 描述 |
---|---|---|
QCommandLineParser::ParseAsCompactedShortOptions | 0 | -abc 被解释为 -a -b -c ,即作为命令行上压缩的三个短选项,如果没有选项带有值。如果 a 带有值,则它被解释为 -a bc ,即短选项 a 后跟值 bc 。这是默认解析模式。建议新应用程序使用此模式。 |
QCommandLineParser::ParseAsLongOptions | 1 | -abc 被解释为 --abc ,即名为 abc 的长选项。这是 Qt 自身工具(uic、rcc 等)一直使用的参数解析方式。在此方式解析参数的应用程序中,应该使用此模式以保持兼容性。如果 a 选项设置了 QCommandLineOption::ShortOptionStyle 标志,则它仍然被解释为 -a bc 。 |
成员函数文档
QCommandLineParser::QCommandLineParser()
构建一个命令行解析器对象。
[noexcept]
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
。
如果选项没有附加名称,或者选项的名称与之前添加的选项名称冲突,添加选项将失败。
bool QCommandLineParser::addOptions(const QList<QCommandLineOption> &options)
添加要解析时寻找的选项列表。选项通过参数 options 指定。
如果所有选项添加成功返回 true
;否则返回 false
。
请参阅 addOption() 文档了解函数可能失败的情况。
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() 设置的应用程序描述。
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 选项传递给应用程序。
如果 name 选项已被设置,则返回 true
;否则返回 false
。
提供的名称可以是使用 addOption() 添加的任何选项的任何长名或短名。所有选项名称都被视为等效。如果该名称未被识别或该选项不存在,则返回 false
。
示例
bool verbose = parser.isSet("verbose");
bool QCommandLineParser>::isSet(const QCommandLineOption &option) const
这是一个重载函数。
检查是否将 option 传递给应用程序。
如果 option 已设置,则返回 true
;否则返回 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() 函数较底层,仅进行解析。应用程序需要处理错误,如果在 parse() 返回 false
时使用 errorText()。这可以用于在图形程序中显示图形错误消息。
相对于 process(),调用 parse() 也可以有助于暂时忽略未知选项,因为之后还会提供更多的选项定义(依赖于一些参数),在调用 process() 之前。
请不要忘记,参数 必须以可执行文件名开头(将被忽略)。
如果出现解析错误(未知选项或缺失值),返回 false
;否则返回 true
。
另请参阅 process。
QStringList QCommandLineParser::positionalArguments() const
返回一个位置参数的列表。
这些都是没有被识别为选项的部分参数。
void QCommandLineParser::process(const QStringList &arguments)
处理命令行参数 arguments。
除了解析选项(如 parse()),此函数还处理内置选项和处理错误。
内置的选项是 --version
如果调用了 addVersionOption,以及如果调用了 addHelpOption 则是 --help
/ --help-all
。
当调用这些选项之一或发生错误(例如未知选项)时,当前进程将停止,使用 exit() 函数。
另请参阅 QCoreApplication::arguments() 和 parse。
void QCommandLineParser::process(const QCoreApplication &app)
这是一个重载函数。
从 QCoreApplication 实例 app 获取命令行。
void QCommandLineParser::setApplicationDescription(const QString &description)
设置由 helpText 显示的应用程序 描述。
另请参阅 applicationDescription。
void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(QCommandLineParser::OptionsAfterPositionalArgumentsMode parsingMode)
设置解析模式为 parsingMode。必须在 process() 或 parse() 调用之前调用。
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)。
另请参阅 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()。
© 2024 Qt公司有限公司。本文件中的文档贡献均为原作者的版权。本文件中的文档是根据自由软件基金会发布的《GNU自由文档许可协议第1.3版》许可提供的。Qt及其相关标志为芬兰和其他国家的Qt公司商标。所有其他商标归其各自所有者所有。