QCommandLineParser Class

The QCommandLineParser class provides a means for handling the command line options. More…

List of all members, including inherited members

Public Types

Public Functions

Detailed Description

Describe the options with QCommandLineOption, add them with addOption(), then call process() or parse() with the arguments. Afterwards use isSet(), value(), values() and positionalArguments() to read the result.

QCoreApplication app(argc, argv);
QCoreApplication::setApplicationVersion("1.0");

QCommandLineParser parser;
parser.setApplicationDescription("Copies files");
parser.addHelpOption();
parser.addVersionOption();
parser.addPositionalArgument("source", "File to copy.");
QCommandLineOption force({"f", "force"}, "Overwrite existing files.");
parser.addOption(force);

parser.process(app);
bool overwrite = parser.isSet(force);

Supported forms are --name, --name=value, --name value, -n, -nvalue, -n value and compacted short options such as -abc. A -- argument ends option processing.

See also QCommandLineOption and QCoreApplication.

Differences from Qt

Member Type Documentation

enum QCommandLineParser::OptionsAfterPositionalArgumentsMode

Controls how arguments that look like options are treated after the first positional argument.

enum QCommandLineParser::SingleDashWordOptionMode

Controls how an argument with a single dash and several characters, such as -abc or -name, is parsed.

Member Function Documentation

QCommandLineParser::QCommandLineParser()

Constructs a command line parser.

QCommandLineParser::~QCommandLineParser()

Destroys the command line parser.

QCommandLineOption QCommandLineParser::addHelpOption()

Adds the option -h, --help that displays the help text and returns it. The option is acted on by process().

See also addVersionOption() and showHelp().

bool QCommandLineParser::addOption(const QCommandLineOption &option)

Adds option to the parser and returns true on success. Returns false, without adding it, if the option has no valid names or one of its names is already defined.

See also addOptions(), addHelpOption() and addVersionOption().

bool QCommandLineParser::addOptions(const QList<QCommandLineOption> &options)

Adds each option in options and returns true if all were added. Options that cannot be added are skipped.

See also addOption().

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

Describes a positional argument called name with the help text description. The argument is shown in the usage line as syntax, or as name if syntax is empty. This only affects helpText(); positional arguments are not validated.

See also positionalArguments() and clearPositionalArguments().

QCommandLineOption QCommandLineParser::addVersionOption()

Adds the option -v, --version that displays the application name and version, set with QCoreApplication::setApplicationVersion(), and returns it. The option is acted on by process().

See also addHelpOption() and showVersion().

QString QCommandLineParser::applicationDescription() const

Returns the description of the application shown in the help text.

See also setApplicationDescription().

void QCommandLineParser::clearPositionalArguments()

Removes the positional arguments described with addPositionalArgument(). Parsed positional arguments are not affected.

QString QCommandLineParser::errorText() const

Returns the error text of the last failed parse(), or an empty string if it succeeded.

See also parse().

QString QCommandLineParser::helpText() const

Returns the help text: a usage line, the application description, the options that are not hidden and the positional arguments added with addPositionalArgument(). Descriptions are wrapped at 79 columns.

See also showHelp() and QCommandLineOption::HiddenFromHelp.

bool QCommandLineParser::isSet(const QString &name) const

Returns true if the option called name was given on the command line; otherwise returns false. Prints a warning and returns false if no option has that name.

See also value() and values().

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

This is an overloaded function.

Returns true if option was given, looking it up by its first name.

QStringList QCommandLineParser::optionNames() const

Returns the names of the options found by the last parse(), in the order given and as written on the command line, with repeats.

See also isSet().

bool QCommandLineParser::parse(const QStringList &arguments)

Parses arguments, whose first entry is the program name, and stores the result. Returns true on success; returns false if an option is unknown, a value is missing or unexpected, and sets errorText().

Unknown options are listed by unknownOptionNames(). Anything after --, and arguments that are not options, are positional.

See also process() and errorText().

QStringList QCommandLineParser::positionalArguments() const

Returns the positional arguments found by the last parse(), in order. The program name is not included.

See also addPositionalArgument().

void QCommandLineParser::process(const QStringList &arguments)

Parses arguments, whose first entry is the program name, and handles the common cases. On a parse error it prints the application name and errorText() to standard error and exits the process with a failure status. If the version or help option added with addVersionOption() or addHelpOption() was given, it prints that text and exits successfully.

See also parse(), showHelp() and showVersion().

void QCommandLineParser::process(const QCoreApplication &app)

This is an overloaded function.

Processes the command line of app, as returned by QCoreApplication::arguments().

void QCommandLineParser::setApplicationDescription(const QString &description)

Sets the description of the application shown in the help text to description.

See also applicationDescription().

void QCommandLineParser::setOptionsAfterPositionalArgumentsMode(OptionsAfterPositionalArgumentsMode mode)

Sets how arguments after the first positional argument are parsed to mode. The default is ParseAsOptions.

See also OptionsAfterPositionalArgumentsMode.

void QCommandLineParser::setSingleDashWordOptionMode(SingleDashWordOptionMode mode)

Sets how single-dash words are parsed to mode. The default is ParseAsCompactedShortOptions.

See also SingleDashWordOptionMode.

void QCommandLineParser::showHelp(int exitCode = 0)

Prints helpText() and exits the process with exitCode. The text goes to standard output if exitCode is 0, otherwise to standard error. This function does not return.

See also helpText() and addHelpOption().

void QCommandLineParser::showVersion()

Prints the application name and version to standard output and exits the process with a success status. This function does not return.

See also addVersionOption() and QCoreApplication::setApplicationVersion().

QStringList QCommandLineParser::unknownOptionNames() const

Returns the names of options found by the last parse() that are not defined, without leading dashes.

See also errorText().

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

Returns the last value given for the option called name, or the last of its default values if it was not given. Returns an empty string if there is none.

See also values() and isSet().

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

This is an overloaded function.

Returns the last value of option, looking it up by its first name.

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

Returns every value given for the option called name, in command-line order, or the option's default values if it was not given. Prints a warning and returns an empty list if no option has that name.

See also value() and isSet().

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

This is an overloaded function.

Returns every value of option, looking it up by its first name.