Qt：QCommandLineParser类

QCommandLineParser类提供了一种处理命令行选项的方法

头文件：

#include <QCommandLineParser>

cmake:

find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core)

qmake:

QT += core

引入：

Qt 5.2

详细说明

QCoreApplication以简单的字符串列表的形式提供命令行参数。QCommandLineParser提供了定义一组选项、解析命令行参数、存储实际使用的选项以及选项值的能力。

任何不是选项的参数(即不以a -开头)都被存储为“位置参数”。

解析器处理短名称，长名称，相同选项的多个名称以及选项值。

命令行上的选项被识别为以一个或两个-字符开头。选项-（仅单破折号）是一种特殊情况，通常表示标准输入，而不是选项。解析器会将选项–（双破折号）之后的所有内容都视为位置参数。

短选项是单个字母。该选项v将通过-v在命令行上传递来指定。在默认的解析模式下，短选项可以紧凑的形式编写，例如-abc等效于-a -b -c。可以将的解析模式设置为ParseAsLongOptions，在这种情况下，-abc将解析为long选项abc。

长选项超过一个字母长，不能一起压缩。long选项verbose将作为–verbose或传递-verbose。

可以使用赋值运算符：-v=value --verbose=value或空格：将值传递给选项-v value --verbose value，即，将下一个参数用作值（即使它以开头-）。

解析器不支持可选值-如果将选项设置为需要一个值，则必须存在一个。如果这样的选项放在最后并且没有任何值，则该选项将被视为未指定。

解析器不自动支持使用–disable-option或格式否定或禁用长选项–no-option。但是，可以通过使用no-option其名称之一作为选项并显式处理该选项来显式处理这种情况。

例子：

成员函数

QCommandLineParser

QCommandLineParser::QCommandLineParser()

构造一个命令行解析器对象。

~QCommandLineParser

QCommandLineParser::~QCommandLineParser()

销毁命令行解析器对象。

addHelpOption

QCommandLineOption QCommandLineParser::addHelpOption()

添加帮助选项(-h，–help和-?)在Windows上)以及一个选项——help-all，以在输出中包含qt特定的选项。

这些选项由QCommandLineParser自动处理。

记住使用setApplicationDescription来设置应用程序描述，使用此选项时将显示该描述。

返回可用于调用isSet()的选项实例。

addOption

bool QCommandLineParser::addOption(const QCommandLineOption &option)

添加在解析时查找的选项选项。

如果添加选项成功，则返回true;否则返回false。

如果该选项没有附加名称，或者该选项的名称与前面添加的选项名称冲突，则添加该选项失败。

addOptions

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

添加解析时查找的选项。这些选项由参数选项指定。

如果添加所有选项都成功，则返回true;否则返回false。

当这个函数可能失败时，请参阅文档addOption()。

这个函数是在Qt 5.4中引入的。

addPositionalArgument

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

为应用程序定义一个额外的参数，以便使用帮助文本。

参数名称和描述将出现在帮助的参数:部分。如果指定了语法，它将被追加到Usage行，否则名称将被追加。

例子:

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

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>
#include <QDir>
#include <QCommandLineParser>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    QCoreApplication::setApplicationName("my-copy-program");  // 应用名称
    QCoreApplication::setApplicationVersion("1.0");   // 应用版本号

    QCommandLineParser parser;
    parser.setApplicationDescription("Test helper");
    parser.addHelpOption();  // 添加帮助选项 （"-h" 或 "--help"）
    parser.addVersionOption();   // 添加版本选项 ("-v" 或 "--version")
    parser.addPositionalArgument("source", QCoreApplication::translate("main", "Source file to copy."));
    parser.addPositionalArgument("destination", QCoreApplication::translate("main", "Destination directory."));


	parser.process(a);
	
    return a.exec();
}

addVersionOption

QCommandLineOption QCommandLineParser::addVersionOption()

添加-v /–version选项，用于显示应用程序的版本字符串。

该选项由QCommandLineParser自动处理。

您可以使用QCoreApplication::setApplicationVersion()来设置实际的版本字符串。

返回可用于调用isSet()的选项实例。

#include <QCoreApplication>
#include <QSettings>
#include <QDebug>
#include <QDir>
#include <QCommandLineParser>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    QCoreApplication::setApplicationName("my-copy-program");  // 应用名称
    QCoreApplication::setApplicationVersion("1.0");   // 应用版本号

    QCommandLineParser parser;
    parser.setApplicationDescription("Test helper");
    parser.addHelpOption();  // 添加帮助选项 （"-h" 或 "--help"）
    parser.addVersionOption();   // 添加版本选项 ("-v" 或 "--version")

	parser.process(a);
	
    return a.exec();
}

applicationDescription

QString QCommandLineParser::applicationDescription() const

返回setApplicationDescription()中设置的应用程序描述。

参见setApplicationDescription()。

clearPositionalArguments

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.
*/

errorText

QString QCommandLineParser::errorText() const

为用户返回经过翻译的错误文本。只有当parse()返回false时才会调用这个函数。

helpText

QString QCommandLineParser::helpText() const

返回包含完整帮助信息的字符串。

参见showHelp()。

isSet

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

检查是否将选项名称传递给应用程序。

如果设置了选项名，则返回true，否则返回false。

所提供的名称可以是使用addOption()添加的任何选项的任意长或短名称。所有的选项名称都被视为等价的。如果无法识别该名称或该选项不存在，则返回false。

例子:

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

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

这是一个重载函数。

检查是否将选项传递给应用程序。

如果设置了该选项则返回true，否则返回false。

这是检查没有值的选项的推荐方法。

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

optionNames

QStringList QCommandLineParser::optionNames() const

返回找到的选项名的列表。

这将返回解析器找到的所有可识别选项名称的列表，这些名称按照找到它们的顺序排列。对于任何形式为{–option=value}的长选项，value部分将被删除。

此列表中的名称不包括前面的破折号字符。如果解析器多次遇到名称，则名称可能在此列表中出现多次。

列表中的任何条目都可以与value()或values()一起使用，以获得任何相关的选项值。

parse

bool QCommandLineParser::parse(const QStringList &arguments)

解析命令行参数。

大多数程序不需要调用这个函数，简单地调用process()就足够了。

parse()更低级，只执行解析。应用程序必须处理错误处理，如果parse()返回false，则使用errorText()。这对于在图形程序中显示图形错误信息是很有用的。

为了暂时忽略未知选项，调用parse()而不是process()也很有用，因为稍后将在调用process()之前提供更多的选项定义(取决于其中一个参数)。

不要忘记参数必须以可执行文件的名称开头(不过会被忽略)。

在解析错误的情况下返回false(未知选项或缺失值);否则返回true。

参见process()。

positionalArguments

QStringList QCommandLineParser::positionalArguments() const

返回位置参数列表。

这些都是没有被认为是选项的一部分的所有参数。

process

void QCommandLineParser::process(const QStringList &arguments)

处理命令行参数。

除了解析选项(如parse())之外，这个函数还处理内置选项和处理错误。

内置选项是–version(如果addVersionOption被调用)和–help /–help-all(如果addHelpOption被调用)。

当调用这些选项中的一个时，或者发生错误时(例如传递了未知选项)，当前进程将使用exit()函数停止。

参见QCoreApplication::arguments()和parse()。

void QCommandLineParser::process(const QCoreApplication &app)

这是一个重载函数。

命令行是从QCoreApplication实例应用程序获取的。

setApplicationDescription

void QCommandLineParser::setApplicationDescription(const QString &description)

设置由helpText()显示的应用程序描述。

参见applicationDescription()。

setOptionsAfterPositionalArgumentsMode

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

设置解析模式为parsingMode。这个必须在process()或parse()之前调用。

这个函数是在Qt 5.6中引入的。

setSingleDashWordOptionMode

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

设置解析模式为singleDashWordOptionMode。这个必须在process()或parse()之前调用。

showHelp

void QCommandLineParser::showHelp(int exitCode = 0)

显示帮助信息，并退出应用程序。这是由–help选项自动触发的，但也可以用于在用户没有正确调用应用程序时显示帮助。退出码设置为exitCode。如果用户请求查看帮助，则应将其设置为0，如果出现错误，则将其设置为任何其他值。

参见helpText()。

showVersion

[since 5.4]void QCommandLineParser::showVersion()

显示来自QCoreApplication::applicationVersion()的版本信息，并退出应用程序。这是由–version选项自动触发的，但在不使用process()时也可以用来显示版本。退出码设置为EXIT_SUCCESS(0)。

这个函数是在Qt 5.4中引入的。

参见addVersionOption()。

unknownOptionNames

QStringList QCommandLineParser::unknownOptionNames() const

返回未知选项名的列表。

此列表将包括未被识别的长名称和短名称选项。对于任何形式为{–option=value}的长选项，value部分将被删除，只添加长名称。

此列表中的名称不包括前面的破折号字符。如果解析器多次遇到名称，则名称可能在此列表中出现多次。

参见optionNames()。

value

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

返回为给定选项名找到的选项值optionName，如果没有找到，则返回一个空字符串。

所提供的名称可以是使用addOption()添加的任何选项的任意长或短名称。所有的选项名都被视为等价的。如果无法识别名称或该选项不存在，则返回空字符串。

对于解析器找到的选项，将返回为该选项找到的最后一个值。如果在命令行上没有指定该选项，则返回默认值。

如果该选项不带值，则返回空字符串。

参见values()， QCommandLineOption::setDefaultValue()和QCommandLineOption::setDefaultValues()。

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

这是一个重载函数。

返回为给定选项找到的选项值，如果没有找到则返回空字符串。

对于解析器找到的选项，将返回为该选项找到的最后一个值。如果在命令行上没有指定该选项，则返回默认值。

如果该选项不带值，则返回空字符串。

参见values()， QCommandLineOption::setDefaultValue()和QCommandLineOption::setDefaultValues()。

values

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

返回为给定选项名optionName找到的选项值列表，如果没有找到，则返回一个空列表。

所提供的名称可以是使用addOption()添加的任何选项的任意长或短名称。所有的选项名称都被视为等价的。如果无法识别该名称或该选项不存在，则返回一个空列表。

对于解析器找到的选项，该列表将包含解析器每次遇到该选项时的一个条目。如果在命令行上没有指定该选项，则返回默认值。

如果该选项不接受值，则返回空列表。

参见value()， QCommandLineOption::setDefaultValue()和QCommandLineOption::setDefaultValues()。

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

这是一个重载函数。

返回为给定选项找到的选项值列表，如果没有找到，则返回空列表。

对于解析器找到的选项，该列表将包含解析器每次遇到该选项时的一个条目。如果在命令行上没有指定该选项，则返回默认值。

如果该选项不接受值，则返回空列表。

参见value()， QCommandLineOption::setDefaultValue()和QCommandLineOption::setDefaultValues()。

例子

我们可以在qtcreator下加入执行参数

当然我们也可以在windos下的dos命令行下执行，前提是把程序需要用到的qt库拷贝到执行目录：