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} の形式の長いオプションについては、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 に対して見つかったオプション値のリストを返します。見つからない場合は空のリストを返します。

パーサーによって検出されたオプションの場合、このリストには、パーサーがそのオプションを検出するたびに1つのエントリが含まれます。コマンドラインでオプションが指定されていない場合は、デフォルト値が返されます。

オプションに値が指定されない場合は、空のリストが返されます。

value()、QCommandLineOption::setDefaultValue()、およびQCommandLineOption::setDefaultValues()も参照してください 。