QCommandLineParser Class

멤버 함수 문서

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 가 지정되면 'Usage' 줄에 이 인수가 추가되며, 그렇지 않은 경우 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 옵션이 애플리케이션에 전달되었는지 확인합니다.

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 부분이 제거됩니다.

이 리스트에 포함된 이름에는 앞의 대시 문자가 포함되지 않습니다. 파서가 동일한 이름을 두 번 이상 발견한 경우, 해당 이름이 리스트에 여러 번 나타날 수 있습니다.

목록에 포함된 항목은 value() 또는 values()와 함께 사용하여 관련 옵션 값을 가져올 수 있습니다.

bool QCommandLineParser::parse(const QStringList &arguments)

명령줄 arguments 을 구문 분석합니다.

대부분의 프로그램은 이 함수를 호출할 필요가 없으며, process()를 간단히 호출하는 것으로 충분합니다.

parse()는 더 저수준이며, 오직 구문 분석만 수행합니다. parse()가 false 을 반환할 경우, 응용 프로그램은 errorText()를 사용하여 오류 처리를 직접 처리해야 합니다. 이는 예를 들어 그래픽 프로그램에서 그래픽 오류 메시지를 표시하는 데 유용할 수 있습니다.

process() 대신 parse()를 호출하는 것은, process()를 호출하기 전에 (인수 중 하나에 따라) 나중에 더 많은 옵션 정의가 제공될 예정이므로, 알 수 없는 옵션을 일시적으로 무시하는 데에도 유용할 수 있습니다.

arguments 는 실행 파일의 이름으로 시작해야 한다는 점을 잊지 마십시오(비록 무시되지만).

구문 분석 오류(알 수 없는 옵션 또는 누락된 값)가 발생한 경우 false 을 반환하고, 그렇지 않은 경우 true 을 반환합니다.

process()도 참조하십시오 .

QStringList QCommandLineParser::positionalArguments() const

위치 매개변수 목록을 반환합니다.

이들은 옵션의 일부로 인식되지 않은 모든 인자입니다.

void QCommandLineParser::process(const QStringList &arguments)

명령줄 arguments 을 처리합니다.

이 함수는 옵션(예: parse())을 구문 분석하는 것 외에도 내장 옵션을 처리하고 오류를 처리합니다.

내장 옵션은 addVersionOption 가 호출된 경우 --version 이며, addHelpOption 가 호출된 경우 --help / --help-all 입니다.

이러한 옵션 중 하나를 호출하거나 오류가 발생하면(예: 알 수 없는 옵션이 전달된 경우), 현재 프로세스는 exit() 함수를 사용하여 중지됩니다.

QCoreApplication::arguments() 및 parse()도 참조하십시오 .

void QCommandLineParser::process(const QCoreApplication &app)

명령줄은 QCoreApplication 인스턴스 app 에서 가져옵니다.

void QCommandLineParser::setApplicationDescription(const QString &description)

helpText() 함수에 의해 표시되는 애플리케이션 description 을 설정합니다.

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() 및 showMessageAndExit()도 참조하십시오 .

[static, since 6.9] void QCommandLineParser::showMessageAndExit(QCommandLineParser::MessageType type, const QString &message, int exitCode = 0)

message 를 표시하고, 지정된 exitCode 로 애플리케이션을 종료합니다.

message 는 일반적으로 지정된 type 에 따라 stdout 또는 stderr 로 직접 출력되거나, 필요한 경우 Windows에서 지정된 type 에 따라 정보 아이콘이나 오류 아이콘과 함께 메시지 상자에 표시될 수 있습니다(메시지 상자를 표시하지 않으려면 QT_COMMAND_LINE_PARSER_NO_GUI_MESSAGE_BOXES 환경 변수를 설정하십시오).

이는 showHelp, showVersion 및 내장 옵션( addVersionOption 이 호출된 경우--version, addHelpOption 이 호출된 경우 --help / --help-all )에서 사용되는 것과 동일한 메시지 표시 방식입니다.

이 함수는 Qt 6.9에서 도입되었습니다.

addVersionOption(), showHelp(), showVersion(), QCommandLineParser::MessageType도 참조하십시오 .

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()도 참조하십시오 .