QCommandLineOption、QCommandLineParser

QCommandLineOption

一、描述

此类用于描述命令行的选项。

二、类型成员

1、enum QCommandLineOption::Flag

• HiddenFromHelp：在用户可见的帮助输出中隐藏此选项。默认情况下，所有选项都可见。为特定选项设置此标志使其成为内部选项，即不在帮助输出中列出。
• ShortOptionStyle：无论 QCommandLineParser::setSingleDashWordOptionMode() 设置了什么，该选项始终被认为是短选项。

三、构造函数

1、QCommandLineOption(const QStringList &names, const QString &description, const QString &valueName = QString(), const QString &defaultValue = QString())

      QCommandLineOption(const QString &name, const QString &description, const QString &valueName = QString(), const QString &defaultValue = QString())

      QCommandLineOption(const QStringList &names)

      QCommandLineOption(const QString &name)

使用给定的参数构造命令行选项对象。

选项的名称为 names。名称可以是短名称或长名称。names 列表中任何长度为一个字符的名称都是短名称。选项名称不能以破折号（—）或斜杠字符开头，不能包含=，并且不能重复。

description 为描述。通常在描述的末尾添加一个“.”。

如果选项需要值，则设置为 valueName。

如果选项有默认值，则设置为 defaultValue。

---

QCommandLineParser

一、描述

QCoreApplication 将命令行参数作为简单的字符串列表提供。此类提供了处理命令行选项的方法，包括定义一组选项、解析命令行参数以及存储实际使用的选项和选项值等功能。

命令行上的选项被识别为以单个或双字符开头。选项 -（单破折号）是一种特殊情况，通常表示标准输入，不作为选项处理。

1.1、短选项

短选项是单个字母。如选项 v 将通过在命令行上传递 -v 来指定。

1.2、长选项

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

1.3、选项赋值

将值传递给选项可以使用：

• 赋值运算符：-v=value --verbose=value
• 空格： -v value --verbose value。即下一个参数用作值（即使它以-开头）。

此类不支持可选值，选项设置必须存在一个值。如果这样的选项放在最后且没有值，则该选项将被忽略。

1.4、禁用长选项

此类不支持使用：--disable 或 --no 来禁用或否定长选项。但可以通过将 no-option 作为其名称的一部分来显式来禁用或否定长选项。

二、类型成员

1、enum QCommandLineParser::OptionsAfterPositionalArgumentsMode：此枚举描述解析器解释参数之后出现的选项的方式。

• ParseAsOptions：默认的解析模式。[参数] --opt-t 被解释为设置选项 opt 和 t。
• ParseAsPositionalArguments：[参数] --opt 被解释为两部分，[参数] 和 --opt。

2、enum QCommandLineParser::SingleDashWordOptionMode：此枚举描述了解析器解释一个短划线后跟多个字母（如 -abc）这类命令行选项的方式。

• ParseAsCompactedShortOptions：-a-bc 等同于 -a-b-c。
• ParseAsLongOptions：-abc 将被解析为长选项 abc。如果a选项设置了QCommandLineOption::ShortOptionStyle 标志，则会出现异常，在这种情况下，它被解释为：-a bc。

三、成员函数

1、QCommandLineOption addHelpOption()

添加帮助选项（Windows上的：-h、--help、-?）以及选项：--help-all。

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

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("测试");
    QCoreApplication::setApplicationVersion("1.0");
 
    QCommandLineParser parser;
    parser.setApplicationDescription("这是程序的帮助文本");
    parser.addHelpOption();
    parser.process(app);
}

2、bool addOption(const QCommandLineOption &option)

      bool addOptions(const QList<QCommandLineOption> &options)

添加解析时要查找的选项。返回是否添加选项成功。

      QString value(const QCommandLineOption &option)

      QString value(const QString &optionName)

      QStringList values(const QCommandLineOption &option)

      QStringList values(const QString &optionName)

返回为 optionName 找到的选项值。

3、bool isSet(const QString &name)

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

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("复制文件");
    QCoreApplication::setApplicationVersion("1.0");
 
    QCommandLineParser parser;
    parser.setApplicationDescription("这是程序的帮助文本");
    parser.addHelpOption();
 
    QCommandLineOption showProgressOption("p","复制期间显示进度.");
    parser.addOption(showProgressOption);
    parser.process(app);
 
    if(parser.isSet("p"))
    {
        qDebug()<<"复制期间显示进度";
    }
}

      bool isSet(const QCommandLineOption &option)

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

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("复制文件");
    QCoreApplication::setApplicationVersion("1.0");
 
    QCommandLineParser parser;
    parser.setApplicationDescription("这是程序的帮助文本");
    parser.addHelpOption();
 
    //具有单个名称（-p）的布尔选项
    QCommandLineOption showProgressOption("p","复制期间显示进度.");
    parser.addOption(showProgressOption);
 
    //具有多个名称的布尔选项（-f，--force）
    QCommandLineOption forceOption(QStringList() << "f" << "force","覆盖现有文件.");
    parser.addOption(forceOption);
 
    //具有值的选项
    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory","将所有源文件复制到 .","./defaultPath");
    parser.addOption(targetDirectoryOption);
    parser.process(app);
 
    if(parser.isSet(showProgressOption))
    {
        qDebug()<<"将在复制期间显示进度";
    }
 
    if(parser.isSet(forceOption))
    {
        qDebug()<<"复制将覆盖现有文件";
    }
 
    if(parser.isSet(targetDirectoryOption))
    {
        qDebug()<<"将文件复制到："<value("target-directory");
    }
}

4、void addPositionalArgument(const QString &name, const QString &description, const QString &syntax = QString())

为应用程序定义一个附加参数，以便用于帮助文本。参数名称和描述将出现在帮助的 Arguments: 部分下。

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("复制文件");
    QCoreApplication::setApplicationVersion("1.0");
 
    QCommandLineParser parser;
    parser.setApplicationDescription("这是程序的帮助文本");
    parser.addHelpOption();
    parser.addVersionOption();
 
    parser.addPositionalArgument("source", "要复制的源文件.");
    parser.addPositionalArgument("destination", "目标目录.");
 
    parser.process(app);
    const QStringList args = parser.positionalArguments();
    qDebug()<<"参数："<
}

      QStringList positionalArguments()

返回附加参数列表。

      void clearPositionalArguments()

从帮助文本中清除其他参数的定义。

此函数仅适用于支持具有不同选项的多个命令的特殊情况。一旦确定了实际的命令，就可以定义该命令的选项，并且可以相应地调整该命令的帮助文本。

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCommandLineParser parser;
 
    parser.addPositionalArgument("command", "The command to execute.");
    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 [resize_options]");
        QCommandLineOption option("size", "新的大小.", "new_size");
        parser.addOption(option);
        parser.process(app);
        if(parser.isSet(option))
        {
            qDebug()<<"新的大小："<value("size");
        }
    }
}

5、QCommandLineOption addVersionOption()

添加 -v / --version 选项，该选项显示应用程序的版本字符串。可以使用 QCoreApplication::setApplicationVersio() 设置实际版本字符串。

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("复制文件");
//    QCoreApplication::setApplicationVersion("1.0");
    QCoreApplication::setApplicationVersion("版本号：1.2.3.001");
 
    QCommandLineParser parser;
    parser.addVersionOption();
    parser.process(app);
}

6、QString errorText()

返回错误文本。仅当 parse() 返回 false 时调用此函数才有意义。

7、QString helpText()

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

8、QStringList optionNames()

返回解析器找到的所有已识别选项名称的列表，按的找到顺序排列。

对于形式为｛--option=value｝的长选项，value 部分将被删除。

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    QCoreApplication::setApplicationName("复制文件");
    QCoreApplication::setApplicationVersion("1.0");
 
    QCommandLineParser parser;
    parser.setApplicationDescription("这是程序的帮助文本");
    parser.addHelpOption();
 
    //具有单个名称（-p）的布尔选项
    QCommandLineOption showProgressOption("p","复制期间显示进度.");
    parser.addOption(showProgressOption);
 
    //具有多个名称的布尔选项（-f，--force）
    QCommandLineOption forceOption(QStringList() << "f" << "force","覆盖现有文件.");
    parser.addOption(forceOption);
 
    //具有值的选项
    QCommandLineOption targetDirectoryOption(QStringList() << "t" << "target-directory","将所有源文件复制到 .","./defaultPath");
    parser.addOption(targetDirectoryOption);
    parser.process(app);
 
    if(parser.isSet(showProgressOption))
    {
        qDebug()<<"将在复制期间显示进度";
    }
 
    if(parser.isSet(forceOption))
    {
        qDebug()<<"复制将覆盖现有文件";
    }
 
    if(parser.isSet(targetDirectoryOption))
    {
        qDebug()<<"将文件复制到："<value("target-directory");
    }
 
    qDebug()<optionNames();
}

9、bool parse(const QStringList &arguments)

分析命令行参数。大多数程序不需要调用此函数，只需调用 process() 就足够了。

10、void process(const QStringList &arguments)

处理命令行参数。除了解析选项（parse()），该函数还处理内置选项和错误。

内置选项为 --version（如果调用了 addVersionOption()）和 --help / --help all（如果调用了 addHelpOption()）。

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

      void process(const QCoreApplication &app)

命令行从 QCoreApplication 实例获得。

11、void setApplicationDescription(const QString &description) 

设置 helpText() 显示的应用程序说明。

12、void showHelp(int exitCode = 0)

显示帮助信息，然后退出应用程序。

这由 --help 选项自动触发，但也可以用于在用户没有正确调用应用程序时显示帮助。

退出代码设置为 exitCode。如果用户请求查看帮助，则应将其设置为0，如果出现错误，则应设置为任何其他值。

13、void showVersion()

显示 QCoreApplication::applicationVersion() 中的版本信息，然后退出应用程序。

这由 --version 选项自动触发，但也可以用于在不使用 process() 时显示版本。

退出代码设置为 exit_SUCCESS（等于 0）。

14、QStringList unknownOptionNames()

返回未知选项名称的列表。

对于形式为｛--option=value｝的长选项，value部分将被删除，只添加长名称。