Provides a way to process command line options. More...

Public Types
enum	SingleDashWordOptionMode

Public Methods
	QCommandLineParser ()

	~QCommandLineParser ()

QCommandLineOption	addHelpOption ()

bool	addOption (const QCommandLineOption &option)

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

QCommandLineOption	addVersionOption ()

QString	applicationDescription () const

void	clearPositionalArguments ()

QString	errorText () const

QString	helpText () const

bool	isSet (const QCommandLineOption &option) const

bool	isSet (const QString &name) const

QStringList	optionNames () const

bool	parse (const QStringList &arguments)

QStringList	positionalArguments () const

void	process (const QCoreApplication &app)

void	process (const QStringList &arguments)

void	setApplicationDescription (const QString &description)

void	setSingleDashWordOptionMode (SingleDashWordOptionMode parsingMode)

void	showHelp (int exitCode=0)

QStringList	unknownOptionNames () const

QString	value (const QCommandLineOption &option) const

QString	value (const QString &optionName) const

QStringList	values (const QCommandLineOption &option) const

QStringList	values (const QString &optionName) const

Detailed Description

The QCommandLineParser class provides a way to process command line options.

QCoreApplication provides the command line arguments as a simple list of strings. QCommandLineParser provides the ability to define a set of options, parse the command-line arguments, and store which options have actually been used, as well as option values.

Any argument that does not start with a dash is stored as a "positional argument". The parser handles short names, long names, more than one name for the same option, and option values.

Options on the command line are recognized as starting with a single or double dash.

The parser will treat everything after the double dash as positional arguments.

A dash followed by a space or nothing is not treated as an option. This is typically interpreted by the application to indicate that instead of reading some input from a file, it should read from the standard input stream.

Short options are single letters. The option v would be specified by passing -v on the command line. In the default parsing mode, short options can be written in a compact form, for instance -abc is equivalent to -a -b -c. The parsing mode for can be set to ParseAsLongOptions, in which case -abc will be parsed as the long option abc.

Long options are more than one letter long and can not be compacted together. The long option verbose would be passed as –verbose or -verbose.

Passing values for options can be done using an equal sign or a space.

-v=value --verbose=value // equal sign

-v value --verbose value // space

The parser does not support optional values - if an option is set to require a value, one must be present. If such an option is placed last and has no value, the option will be treated as if it had not been specified.

The parser does not automatically support negating or disabling long options by using the format –disable-option or –no-option. However, it is possible to handle this case explicitly by making an option with no-option as one of its names, and handling the option explicitly.

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."));
 
   // boolean option with a single name (-p)
   QCommandLineOption showProgressOption("p",  QCoreApplication::translate("main", "Show progress during copy"));
   parser.addOption(showProgressOption);
 
   // boolean option with multiple names (-f, --force)
   QCommandLineOption forceOption(QStringList() << "f" << "force",
         QCoreApplication::translate("main", "Overwrite existing files."));
 
   parser.addOption(forceOption);
 
   // 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);
 
   // first two values for args are the source and destination
   const QStringList args = parser.positionalArguments();
 
   bool showProgress = parser.isSet(showProgressOption);
   bool force = parser.isSet(forceOption);
   QString targetDir = parser.value(targetDirectoryOption);
 
   // ...
}

The parsing of CopperSpice options inside QCoreApplication and subclasses happens before QCommandLineParser exists, so it can not take it into account. This means any option value that looks like a builtin option, will be treated by QCoreApplication as a builtin CopperSpice option.

--profile -reverse

The previous example will lead to QApplication seeing the -reverse option set, and removing it from QCoreApplication::arguments() before QCommandLineParser defines the profile option and parses the command line.

How to Use QCommandLineParser in Complex Applications

In practice, additional error checking needs to be performed on the positional arguments and option values. For example, ranges of numbers should be checked.

It is then advisable to introduce a function to do the command line parsing which takes a struct or class receiving the option values returning an enumeration representing the result. The dnslookup example of the CsNetwork library illustrates the following.

struct DnsQuery {
    DnsQuery() : type(QDnsLookup::A) {}
 
    QDnsLookup::Type type;
    QHostAddress nameServer;
    QString name;
};
 
enum CommandLineParseResult {
    CommandLineOk,
    CommandLineError,
    CommandLineVersionRequested,
    CommandLineHelpRequested
};
 
CommandLineParseResult parseCommandLine(QCommandLineParser &parser, DnsQuery *query, QString *errorMessage) {
   parser.setSingleDashWordOptionMode(QCommandLineParser::ParseAsLongOptions);
   const QCommandLineOption nameServerOption("n", "The name server to use.", "nameserver");
   parser.addOption(nameServerOption);
 
   const QCommandLineOption typeOption("t", "The lookup type.", "type");
   parser.addOption(typeOption);
   parser.addPositionalArgument("name", "The name to look up.");
 
   const QCommandLineOption helpOption = parser.addHelpOption();
   const QCommandLineOption versionOption = parser.addVersionOption();
 
   if (! parser.parse(QCoreApplication::arguments())) {
     *errorMessage = parser.errorText();
     return CommandLineError;
   }
 
   if (parser.isSet(versionOption)) {
     return CommandLineVersionRequested;
   }
 
   if (parser.isSet(helpOption)) }
     return CommandLineHelpRequested;
   }
 
   if (parser.isSet(nameServerOption)) {
      const QString nameserver = parser.value(nameServerOption);
      query->nameServer = QHostAddress(nameserver);
 
      if (query->nameServer.isNull() || query->nameServer.protocol() == QAbstractSocket::UnknownNetworkLayerProtocol) {
         *errorMessage = "Bad nameserver address: " + nameserver;
         return CommandLineError;
      }
   }
 
   if (parser.isSet(typeOption)) {
      const QString typeParameter = parser.value(typeOption);
      const int type = typeFromParameter(typeParameter.toLower());
 
      if (type < 0) {
         *errorMessage = "Bad record type: " + typeParameter;
         return CommandLineError;
      }
 
      query->type = static_cast<QDnsLookup::Type>(type);
   }
 
   const QStringList positionalArguments = parser.positionalArguments();
   if (positionalArguments.isEmpty()) {
      *errorMessage = "Argument 'name' is missing.";
      return CommandLineError;
   }
 
   if (positionalArguments.size() > 1) {
      *errorMessage = "Several 'name' arguments were specified.";
      return CommandLineError;
   }
 
   query->name = positionalArguments.first();
 
   return CommandLineOk;
}

In the main function, help should be printed to the standard output if the help option was passed and the application should return the exit code 0. If an error was detected, the error message should be printed to the standard error output and the application should return an exit code other than 0.

QCoreApplication::setApplicationVersion(CS_VERSION_STR);
QCoreApplication::setApplicationName(QCoreApplication::translate("QDnsLookupExample", "DNS Lookup Example"));
 
QCommandLineParser parser;
parser.setApplicationDescription(QCoreApplication::translate("QDnsLookupExample",
      "Example demonstrating the class QDnsLookup."));
 
DnsQuery query;
QString errorMessage;
 
switch (parseCommandLine(parser, &query, &errorMessage)) {
   case CommandLineOk:
      break;
 
   case CommandLineError:
      fputs(csPrintable(errorMessage), stderr);
      fputs("\n\n", stderr);
 
      fputs(csPrintable(parser.helpText()), stderr);
      return 1;
 
   case CommandLineVersionRequested:
      printf("%s %s\n", csPrintable(QCoreApplication::applicationName()), csPrintable(QCoreApplication::applicationVersion()));
      return 0;
 
   case CommandLineHelpRequested:
      parser.showHelp();
 
}

A special case to consider is a GUI application for Windows or mobile platforms. These applications should not use the standard output or error channels since the output is either discarded or not accessible. Instead it is recommended to display help texts and error messages using a QMessageBox.

To preserve the formatting of the help text, use rich text format with <pre> elements.

    switch (parseCommandLine(parser, &query, &errorMessage)) {
       case CommandLineOk:
           break;
 
       case CommandLineError:
 
#ifdef Q_OS_WIN
         QMessageBox::warning(nullptr, QApplication::applicationDisplayName(),
            "<html><head/><body><h2>" + errorMessage + "</h2><pre>" + parser.helpText() + "</pre></body></html>");
 
#else
           fputs(csPrintable(errorMessage), stderr);
           fputs("\n\n", stderr);
           fputs(csPrintable(parser.helpText()), stderr);
#endif
 
           return 1;
 
       case CommandLineVersionRequested:
 
#ifdef Q_OS_WIN
           QMessageBox::information(nullptr, QApplication::applicationDisplayName(),
                     QApplication::applicationDisplayName() + ' ' + QCoreApplication::applicationVersion());
#else
           printf("%s %s\n", QApplication::applicationDisplayName(), csPrintable(QCoreApplication::applicationVersion()));
#endif
 
           return 0;
 
       case CommandLineHelpRequested:
 
#ifdef Q_OS_WIN
           QMessageBox::warning(nullptr, QApplication::applicationDisplayName(),
                     "<html><head/><body><pre>" + parser.helpText() + "</pre></body></html>");
           return 0;
#else
 
           parser.showHelp();
#endif
   }

See also: QCommandLineOption, QCoreApplication

Member Enumeration Documentation

enum QCommandLineParser::SingleDashWordOptionMode

This enum describes the way the parser interprets command line options that use a single dash followed by multiple letters, as in "-abc".

Constant	Value	Description
`QCommandLineParser::ParseAsCompactedShortOptions`	`0`	`-abc` is interpreted as `-a -b -c`, i.e. as three short options that have been compacted on the command-line, if none of the options take a value. If `a` takes a value, then it is interpreted as `-a bc`, i.e. the short option `a` followed by the value `bc`. This is typically used in tools that behave like compilers, in order to handle options such as `-DDEFINE=VALUE` or `-I/include/path`. This is the default parsing mode. New applications are recommended to use this mode.
`QCommandLineParser::ParseAsLongOptions`	`1`	`-abc` is interpreted as `–abc`, i.e. as the long option named `abc`. This is how the CopperSpice tools (uic, rcc...) have always been parsing arguments. This mode should be used for preserving compatibility in applications that were parsing arguments in such a way.

See also: setSingleDashWordOptionMode()

Constructor & Destructor Documentation

QCommandLineParser::QCommandLineParser ( )

Constructs a command line parser object.

QCommandLineParser::~QCommandLineParser ( )

Destroys the command line parser object.

Method Documentation

QCommandLineOption QCommandLineParser::addHelpOption ( )

Adds the help options -h and –help. On Windows and additional option for -? will be added. These options will be processed automatically by QCommandLineParser.

Use setApplicationDescription() to add change the application description, which is displayed when the user asks for help.

bool QCommandLineParser::addOption ( const QCommandLineOption & option )

Adds the option to look for while parsing. Returns true if adding the option was successful, otherwise returns false.

Adding the option fails if there is no name attached to the option, or the option has a name that clashes with an option name added before.

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

Defines an additional argument to the application, for the benefit of the help text.

The argument name and description will appear under the Arguments: section of the help. If syntax is specified, it will be appended to the Usage line, otherwise the name will be appended.

// 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."));

See also: addHelpOption(), helpText()

QCommandLineOption QCommandLineParser::addVersionOption ( )

Adds the -v / –version option, which displays the version string of the application. This option is handled automatically by QCommandLineParser.

You can set the actual version string by using QCoreApplication::setApplicationVersion().

Returns the option instance which can be used to call isSet().

QString QCommandLineParser::applicationDescription ( ) const

Returns the application description set in setApplicationDescription().

See also: setApplicationDescription()

void QCommandLineParser::clearPositionalArguments ( )

Clears the definitions of additional arguments from the help text.

This is only needed for the special case of tools which support multiple commands with different options. Once the actual command has been identified, the options for this command can be defined, and the help text for the command can be adjusted accordingly.

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

Returns a translated error text for the user. This should only be called when parse() returns false.

QString QCommandLineParser::helpText ( ) const

Returns a string containing the complete help information.

See also: showHelp()

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

Checks whether the option was passed to the application. Returns true if the option was set, false otherwise.

This is the recommended way to check for options with no values.

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

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

Checks whether the option name was passed to the application.

Returns true if the option name was set, false otherwise.

The name provided can be any long or short name of any option that was added with addOption(). All the options names are treated as being equivalent. If the name is not recognized or that option was not present, false is returned.

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

QStringList QCommandLineParser::optionNames ( ) const

Returns a list of option names that were found.

This returns a list of all the recognized option names found by the parser, in the order in which they were found. For any long options that were in the form {–option=value}, the value part will have been dropped.

The names in this list do not include the preceding dash characters. Names may appear more than once in this list if they were encountered more than once by the parser.

Any entry in the list can be used with value() or with values() to get any relevant option values.

bool QCommandLineParser::parse ( const QStringList & arguments )

Parses the command line arguments. The first element must be the name of the executable. Returns false in case of a parse error (unknown option or missing value), returns true otherwise.

Most programs do not need to call this method since a simple call to process() is enough. The application will have to take care of the error handling, using errorText() if parse() returns false. This can be useful for instance to show a graphical error message in graphical programs.

Calling parse() instead of process() can also be useful in order to ignore unknown options temporarily, because more option definitions will be provided later on (depending on one of the arguments), before calling process().

See also: process()

QStringList QCommandLineParser::positionalArguments ( ) const

Returns a list of positional arguments.

These are all of the arguments that were not recognized as part of an option.

void QCommandLineParser::process ( const QCoreApplication & app )

The command line is obtained from the QCoreApplication instance app.

void QCommandLineParser::process ( const QStringList & arguments )

Processes the command line arguments. In addition to parsing the options (like parse()), this function also handles the builtin options and handles errors. The builtin options are –version if addVersionOption was called and –help if addHelpOption was called.

When invoking one of these options, or when an error happens (for instance an unknown option was passed), the current process will then stop, using the exit() function.

See also: QCoreApplication::arguments(), parse()

void QCommandLineParser::setApplicationDescription ( const QString & description )

Sets the application description shown by helpText().

See also: applicationDescription()

void QCommandLineParser::setSingleDashWordOptionMode ( SingleDashWordOptionMode parsingMode )

Sets the parsing mode to parsingMode. This must be called before process() or parse().

void QCommandLineParser::showHelp ( int exitCode = 0 )

Displays the help information, and exits the application. This is automatically triggered by the –help option, but can also be used to display the help when the user is not invoking the application correctly. The exit code is set to exitCode. It should be set to 0 if the user requested to see the help, and to any other value in case of an error.

See also: helpText()

QStringList QCommandLineParser::unknownOptionNames ( ) const

Returns a list of unknown option names.

This list will include both long an short name options that were not recognized. For any long options that were in the form {–option=value}, the value part will have been dropped and only the long name is added.

The names in this list do not include the preceding dash characters. Names may appear more than once in this list if they were encountered more than once by the parser.

See also: optionNames()

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

Returns the option value found for the given option, or an empty string if not found.

For options found by the parser, the last value found for that option is returned. If the option was not specified on the command line, the default value is returned.

An empty string is returned if the option does not take a value.

See also: values(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()

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

Returns the option value found for the given option name optionName, or an empty string if not found.

The name provided can be any long or short name of any option that was added with addOption(). All the option names are treated as being equivalent. If the name is not recognized or that option was not present, an empty string is returned.

For options found by the parser, the last value found for that option is returned. If the option was not specified on the command line, the default value is returned.

An empty string is returned if the option does not take a value.

See also: values(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()

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

Returns a list of option values found for the given option, or an empty list if not found.

For options found by the parser, the list will contain an entry for each time the option was encountered by the parser. If the option was not specified on the command line, the default values are returned.

An empty list is returned if the option does not take a value.

See also: value(), QCommandLineOption::setDefaultValue(), QCommandLineOption::setDefaultValues()

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

Returns a list of option values found for the given option name optionName, or an empty list if not found.

The name provided can be any long or short name of any option that was added with addOption(). All the options names are treated as being equivalent. If the name is not recognized or that option was not present, an empty list is returned.