<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qcommandlineparser.cpp -->
<title>QCommandLineParser Class | Qt Core 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtcore-index.html">Qt Core</a></td><td ><a href="qtcore-module.html">C++ Classes</a></td><td >QCommandLineParser</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#public-types">Public Types</a></li>
<li class="level1"><a href="#public-functions">Public Functions</a></li>
<li class="level1"><a href="#details">Detailed Description</a></li>
<li class="level2"><a href="#how-to-use-qcommandlineparser-in-complex-applications">How to Use QCommandLineParser in Complex Applications</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">QCommandLineParser Class</h1>
<!-- $$$QCommandLineParser-brief -->
<p>The <a href="qcommandlineparser.html">QCommandLineParser</a> class provides a means for handling the command line options. <a href="#details">More...</a></p>
<!-- @@@QCommandLineParser -->
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> Header:</td><td class="memItemRight bottomAlign"> <span class="preprocessor">#include <QCommandLineParser></span>
</td></tr><tr><td class="memItemLeft rightAlign topAlign"> qmake:</td><td class="memItemRight bottomAlign"> QT += core</td></tr><tr><td class="memItemLeft rightAlign topAlign"> Since:</td><td class="memItemRight bottomAlign"> Qt 5.2</td></tr></table></div><ul>
<li><a href="qcommandlineparser-members.html">List of all members, including inherited members</a></li>
</ul>
<a name="public-types"></a>
<h2 id="public-types">Public Types</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#OptionsAfterPositionalArgumentsMode-enum">OptionsAfterPositionalArgumentsMode</a></b> { ParseAsOptions, ParseAsPositionalArguments }</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> enum </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#SingleDashWordOptionMode-enum">SingleDashWordOptionMode</a></b> { ParseAsCompactedShortOptions, ParseAsLongOptions }</td></tr>
</table></div>
<a name="public-functions"></a>
<h2 id="public-functions">Public Functions</h2>
<div class="table"><table class="alignedsummary">
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#dtor.QCommandLineParser">~QCommandLineParser</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QCommandLineOption </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#addHelpOption">addHelpOption</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#addOption">addOption</a></b>(const QCommandLineOption &<i>option</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#addOptions">addOptions</a></b>(const QList<QCommandLineOption> &<i>options</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#addPositionalArgument">addPositionalArgument</a></b>(const QString &<i>name</i>, const QString &<i>description</i>, const QString &<i>syntax</i> = QString())</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QCommandLineOption </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#addVersionOption">addVersionOption</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#applicationDescription">applicationDescription</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#clearPositionalArguments">clearPositionalArguments</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#errorText">errorText</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#helpText">helpText</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#isSet">isSet</a></b>(const QString &<i>name</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#isSet-1">isSet</a></b>(const QCommandLineOption &<i>option</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#optionNames">optionNames</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> bool </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#parse">parse</a></b>(const QStringList &<i>arguments</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#positionalArguments">positionalArguments</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#process">process</a></b>(const QStringList &<i>arguments</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#process-1">process</a></b>(const QCoreApplication &<i>app</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#setApplicationDescription">setApplicationDescription</a></b>(const QString &<i>description</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#setOptionsAfterPositionalArgumentsMode">setOptionsAfterPositionalArgumentsMode</a></b>(OptionsAfterPositionalArgumentsMode <i>parsingMode</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#setSingleDashWordOptionMode">setSingleDashWordOptionMode</a></b>(SingleDashWordOptionMode <i>singleDashWordOptionMode</i>)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#showHelp">showHelp</a></b>(int <i>exitCode</i> = 0)</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> void </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#showVersion">showVersion</a></b>()</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#unknownOptionNames">unknownOptionNames</a></b>() const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#value">value</a></b>(const QString &<i>optionName</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QString </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#value-1">value</a></b>(const QCommandLineOption &<i>option</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#values">values</a></b>(const QString &<i>optionName</i>) const</td></tr>
<tr><td class="memItemLeft rightAlign topAlign"> QStringList </td><td class="memItemRight bottomAlign"><b><a href="qcommandlineparser.html#values-1">values</a></b>(const QCommandLineOption &<i>option</i>) const</td></tr>
</table></div>
<a name="details"></a>
<!-- $$$QCommandLineParser-description -->
<div class="descr">
<h2 id="details">Detailed Description</h2>
<p>The <a href="qcommandlineparser.html">QCommandLineParser</a> class provides a means for handling the command line options.</p>
<p><a href="qcoreapplication.html">QCoreApplication</a> provides the command-line arguments as a simple list of strings. <a href="qcommandlineparser.html">QCommandLineParser</a> 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.</p>
<p>Any argument that isn't an option (i.e. doesn't start with a <code>-</code>) is stored as a "positional argument".</p>
<p>The parser handles short names, long names, more than one name for the same option, and option values.</p>
<p>Options on the command line are recognized as starting with a single or double <code>-</code> character(s). The option <code>-</code> (single dash alone) is a special case, often meaning standard input, and not treated as an option. The parser will treat everything after the option <code>--</code> (double dash) as positional arguments.</p>
<p>Short options are single letters. The option <code>v</code> would be specified by passing <code>-v</code> on the command line. In the default parsing mode, short options can be written in a compact form, for instance <code>-abc</code> is equivalent to <code>-a -b -c</code>. The parsing mode for can be set to <a href="qcommandlineparser.html#SingleDashWordOptionMode-enum">ParseAsLongOptions</a>, in which case <code>-abc</code> will be parsed as the long option <code>abc</code>.</p>
<p>Long options are more than one letter long and cannot be compacted together. The long option <code>verbose</code> would be passed as <code>--verbose</code> or <code>-verbose</code>.</p>
<p>Passing values to options can be done using the assignment operator: <code>-v=value</code> <code>--verbose=value</code>, or a space: <code>-v value</code> <code>--verbose value</code>, i.e. the next argument is used as value (even if it starts with a <code>-</code>).</p>
<p>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.</p>
<p>The parser does not automatically support negating or disabling long options by using the format <code>--disable-option</code> or <code>--no-option</code>. However, it is possible to handle this case explicitly by making an option with <code>no-option</code> as one of its names, and handling the option explicitly.</p>
<p>Example:</p>
<pre class="cpp">
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>)
{
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>setApplicationName(<span class="string">"my-copy-program"</span>);
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>setApplicationVersion(<span class="string">"1.0"</span>);
<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span> parser;
parser<span class="operator">.</span>setApplicationDescription(<span class="string">"Test helper"</span>);
parser<span class="operator">.</span>addHelpOption();
parser<span class="operator">.</span>addVersionOption();
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"source"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Source file to copy."</span>));
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"destination"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Destination directory."</span>));
<span class="comment">// A boolean option with a single name (-p)</span>
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> showProgressOption(<span class="string">"p"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Show progress during copy"</span>));
parser<span class="operator">.</span>addOption(showProgressOption);
<span class="comment">// A boolean option with multiple names (-f, --force)</span>
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> forceOption(<span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"f"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"force"</span><span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Overwrite existing files."</span>));
parser<span class="operator">.</span>addOption(forceOption);
<span class="comment">// An option with a value</span>
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> targetDirectoryOption(<span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"t"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"target-directory"</span><span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Copy all source files into <directory>."</span>)<span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"directory"</span>));
parser<span class="operator">.</span>addOption(targetDirectoryOption);
<span class="comment">// Process the actual command line arguments given by the user</span>
parser<span class="operator">.</span>process(app);
<span class="keyword">const</span> <span class="type"><a href="qstringlist.html">QStringList</a></span> args <span class="operator">=</span> parser<span class="operator">.</span>positionalArguments();
<span class="comment">// source is args.at(0), destination is args.at(1)</span>
bool showProgress <span class="operator">=</span> parser<span class="operator">.</span>isSet(showProgressOption);
bool force <span class="operator">=</span> parser<span class="operator">.</span>isSet(forceOption);
<span class="type"><a href="qstring.html">QString</a></span> targetDir <span class="operator">=</span> parser<span class="operator">.</span>value(targetDirectoryOption);
<span class="comment">// ...</span>
}
</pre>
<p>If your compiler supports the C++11 standard, the three <a href="qcommandlineparser.html#addOption">addOption</a>() calls in the above example can be simplified:</p>
<pre class="cpp">
parser<span class="operator">.</span>addOptions({
<span class="comment">// A boolean option with a single name (-p)</span>
{<span class="string">"p"</span><span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Show progress during copy"</span>)}<span class="operator">,</span>
<span class="comment">// A boolean option with multiple names (-f, --force)</span>
{{<span class="string">"f"</span><span class="operator">,</span> <span class="string">"force"</span>}<span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Overwrite existing files."</span>)}<span class="operator">,</span>
<span class="comment">// An option with a value</span>
{{<span class="string">"t"</span><span class="operator">,</span> <span class="string">"target-directory"</span>}<span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Copy all source files into <directory>."</span>)<span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"directory"</span>)}<span class="operator">,</span>
});
</pre>
<p>Known limitation: the parsing of Qt options inside <a href="qcoreapplication.html">QCoreApplication</a> and subclasses happens before <a href="qcommandlineparser.html">QCommandLineParser</a> exists, so it can't take it into account. This means any option value that looks like a builtin Qt option, will be treated by <a href="qcoreapplication.html">QCoreApplication</a> as a builtin Qt option. Example: <code>--profile -reverse</code> will lead to <a href="../qtgui/qguiapplication.html">QGuiApplication</a> seeing the -reverse option set, and removing it from <a href="qcoreapplication.html#arguments">QCoreApplication::arguments</a>() before <a href="qcommandlineparser.html">QCommandLineParser</a> defines the <code>profile</code> option and parses the command line.</p>
<a name="how-to-use-qcommandlineparser-in-complex-applications"></a>
<h4 >How to Use QCommandLineParser in Complex Applications</h4>
<p>In practice, additional error checking needs to be performed on the positional arguments and option values. For example, ranges of numbers should be checked.</p>
<p>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 <a href="../qtnetwork/qtnetwork-module.html">QtNetwork</a> module illustrates this:</p>
<pre class="cpp">
<span class="keyword">struct</span> DnsQuery
{
DnsQuery() : type(<span class="type"><a href="../qtnetwork/qdnslookup.html">QDnsLookup</a></span><span class="operator">::</span>A) {}
<span class="type"><a href="../qtnetwork/qdnslookup.html">QDnsLookup</a></span><span class="operator">::</span>Type type;
<span class="type"><a href="../qtnetwork/qhostaddress.html">QHostAddress</a></span> nameServer;
<span class="type"><a href="qstring.html">QString</a></span> name;
};
<span class="keyword">enum</span> CommandLineParseResult
{
CommandLineOk<span class="operator">,</span>
CommandLineError<span class="operator">,</span>
CommandLineVersionRequested<span class="operator">,</span>
CommandLineHelpRequested
};
CommandLineParseResult parseCommandLine(<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span> <span class="operator">&</span>parser<span class="operator">,</span> DnsQuery <span class="operator">*</span>query<span class="operator">,</span> <span class="type"><a href="qstring.html">QString</a></span> <span class="operator">*</span>errorMessage)
{
parser<span class="operator">.</span>setSingleDashWordOptionMode(<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span><span class="operator">::</span>ParseAsLongOptions);
<span class="keyword">const</span> <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> nameServerOption(<span class="string">"n"</span><span class="operator">,</span> <span class="string">"The name server to use."</span><span class="operator">,</span> <span class="string">"nameserver"</span>);
parser<span class="operator">.</span>addOption(nameServerOption);
<span class="keyword">const</span> <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> typeOption(<span class="string">"t"</span><span class="operator">,</span> <span class="string">"The lookup type."</span><span class="operator">,</span> <span class="string">"type"</span>);
parser<span class="operator">.</span>addOption(typeOption);
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"name"</span><span class="operator">,</span> <span class="string">"The name to look up."</span>);
<span class="keyword">const</span> <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> helpOption <span class="operator">=</span> parser<span class="operator">.</span>addHelpOption();
<span class="keyword">const</span> <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> versionOption <span class="operator">=</span> parser<span class="operator">.</span>addVersionOption();
<span class="keyword">if</span> (<span class="operator">!</span>parser<span class="operator">.</span>parse(<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>arguments())) {
<span class="operator">*</span>errorMessage <span class="operator">=</span> parser<span class="operator">.</span>errorText();
<span class="keyword">return</span> CommandLineError;
}
<span class="keyword">if</span> (parser<span class="operator">.</span>isSet(versionOption))
<span class="keyword">return</span> CommandLineVersionRequested;
<span class="keyword">if</span> (parser<span class="operator">.</span>isSet(helpOption))
<span class="keyword">return</span> CommandLineHelpRequested;
<span class="keyword">if</span> (parser<span class="operator">.</span>isSet(nameServerOption)) {
<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> nameserver <span class="operator">=</span> parser<span class="operator">.</span>value(nameServerOption);
query<span class="operator">-</span><span class="operator">></span>nameServer <span class="operator">=</span> <span class="type"><a href="../qtnetwork/qhostaddress.html">QHostAddress</a></span>(nameserver);
<span class="keyword">if</span> (query<span class="operator">-</span><span class="operator">></span>nameServer<span class="operator">.</span>isNull() <span class="operator">|</span><span class="operator">|</span> query<span class="operator">-</span><span class="operator">></span>nameServer<span class="operator">.</span>protocol() <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="../qtnetwork/qabstractsocket.html">QAbstractSocket</a></span><span class="operator">::</span>UnknownNetworkLayerProtocol) {
<span class="operator">*</span>errorMessage <span class="operator">=</span> <span class="string">"Bad nameserver address: "</span> <span class="operator">+</span> nameserver;
<span class="keyword">return</span> CommandLineError;
}
}
<span class="keyword">if</span> (parser<span class="operator">.</span>isSet(typeOption)) {
<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> typeParameter <span class="operator">=</span> parser<span class="operator">.</span>value(typeOption);
<span class="keyword">const</span> <span class="type">int</span> type <span class="operator">=</span> typeFromParameter(typeParameter<span class="operator">.</span>toLower());
<span class="keyword">if</span> (type <span class="operator"><</span> <span class="number">0</span>) {
<span class="operator">*</span>errorMessage <span class="operator">=</span> <span class="string">"Bad record type: "</span> <span class="operator">+</span> typeParameter;
<span class="keyword">return</span> CommandLineError;
}
query<span class="operator">-</span><span class="operator">></span>type <span class="operator">=</span> <span class="keyword">static_cast</span><span class="operator"><</span><span class="type"><a href="../qtnetwork/qdnslookup.html">QDnsLookup</a></span><span class="operator">::</span>Type<span class="operator">></span>(type);
}
<span class="keyword">const</span> <span class="type"><a href="qstringlist.html">QStringList</a></span> positionalArguments <span class="operator">=</span> parser<span class="operator">.</span>positionalArguments();
<span class="keyword">if</span> (positionalArguments<span class="operator">.</span>isEmpty()) {
<span class="operator">*</span>errorMessage <span class="operator">=</span> <span class="string">"Argument 'name' missing."</span>;
<span class="keyword">return</span> CommandLineError;
}
<span class="keyword">if</span> (positionalArguments<span class="operator">.</span>size() <span class="operator">></span> <span class="number">1</span>) {
<span class="operator">*</span>errorMessage <span class="operator">=</span> <span class="string">"Several 'name' arguments specified."</span>;
<span class="keyword">return</span> CommandLineError;
}
query<span class="operator">-</span><span class="operator">></span>name <span class="operator">=</span> positionalArguments<span class="operator">.</span>first();
<span class="keyword">return</span> CommandLineOk;
}
</pre>
<p>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.</p>
<p>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.</p>
<pre class="cpp">
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>setApplicationVersion(QT_VERSION_STR);
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>setApplicationName(<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"QDnsLookupExample"</span><span class="operator">,</span> <span class="string">"DNS Lookup Example"</span>));
<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span> parser;
parser<span class="operator">.</span>setApplicationDescription(<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"QDnsLookupExample"</span><span class="operator">,</span> <span class="string">"An example demonstrating the class QDnsLookup."</span>));
DnsQuery query;
<span class="type"><a href="qstring.html">QString</a></span> errorMessage;
<span class="keyword">switch</span> (parseCommandLine(parser<span class="operator">,</span> <span class="operator">&</span>query<span class="operator">,</span> <span class="operator">&</span>errorMessage)) {
<span class="keyword">case</span> CommandLineOk:
<span class="keyword">break</span>;
<span class="keyword">case</span> CommandLineError:
fputs(<a href="qtglobal.html#qPrintable">qPrintable</a>(errorMessage)<span class="operator">,</span> stderr);
fputs(<span class="string">"\n\n"</span><span class="operator">,</span> stderr);
fputs(<a href="qtglobal.html#qPrintable">qPrintable</a>(parser<span class="operator">.</span>helpText())<span class="operator">,</span> stderr);
<span class="keyword">return</span> <span class="number">1</span>;
<span class="keyword">case</span> CommandLineVersionRequested:
printf(<span class="string">"%s %s\n"</span><span class="operator">,</span> <a href="qtglobal.html#qPrintable">qPrintable</a>(<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>applicationName())<span class="operator">,</span>
<a href="qtglobal.html#qPrintable">qPrintable</a>(<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>applicationVersion()));
<span class="keyword">return</span> <span class="number">0</span>;
<span class="keyword">case</span> CommandLineHelpRequested:
parser<span class="operator">.</span>showHelp();
Q_UNREACHABLE();
}
</pre>
<p>A special case to consider here are GUI applications on Windows and mobile platforms. These applications may not use the standard output or error channels since the output is either discarded or not accessible.</p>
<p>On Windows, <a href="qcommandlineparser.html">QCommandLineParser</a> uses message boxes to display usage information and errors if no console window can be obtained.</p>
<p>For other platforms, it is recommended to display help texts and error messages using a <a href="../qtwidgets/qmessagebox.html">QMessageBox</a>. To preserve the formatting of the help text, rich text with <code><pre></code> elements should be used:</p>
<pre class="cpp">
<span class="keyword">switch</span> (parseCommandLine(parser<span class="operator">,</span> <span class="operator">&</span>query<span class="operator">,</span> <span class="operator">&</span>errorMessage)) {
<span class="keyword">case</span> CommandLineOk:
<span class="keyword">break</span>;
<span class="keyword">case</span> CommandLineError:
<span class="type"><a href="../qtwidgets/qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>warning(<span class="number">0</span><span class="operator">,</span> <span class="type"><a href="../qtgui/qguiapplication.html">QGuiApplication</a></span><span class="operator">::</span>applicationDisplayName()<span class="operator">,</span>
<span class="string">"<html><head/><body><h2>"</span> <span class="operator">+</span> errorMessage <span class="operator">+</span> <span class="string">"</h2><pre>"</span>
<span class="operator">+</span> parser<span class="operator">.</span>helpText() <span class="operator">+</span> <span class="string">"</pre></body></html>"</span>);
<span class="keyword">return</span> <span class="number">1</span>;
<span class="keyword">case</span> CommandLineVersionRequested:
<span class="type"><a href="../qtwidgets/qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>information(<span class="number">0</span><span class="operator">,</span> <span class="type"><a href="../qtgui/qguiapplication.html">QGuiApplication</a></span><span class="operator">::</span>applicationDisplayName()<span class="operator">,</span>
<span class="type"><a href="../qtgui/qguiapplication.html">QGuiApplication</a></span><span class="operator">::</span>applicationDisplayName() <span class="operator">+</span> <span class="char">' '</span>
<span class="operator">+</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>applicationVersion());
<span class="keyword">return</span> <span class="number">0</span>;
<span class="keyword">case</span> CommandLineHelpRequested:
<span class="type"><a href="../qtwidgets/qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>warning(<span class="number">0</span><span class="operator">,</span> <span class="type"><a href="../qtgui/qguiapplication.html">QGuiApplication</a></span><span class="operator">::</span>applicationDisplayName()<span class="operator">,</span>
<span class="string">"<html><head/><body><pre>"</span>
<span class="operator">+</span> parser<span class="operator">.</span>helpText() <span class="operator">+</span> <span class="string">"</pre></body></html>"</span>);
<span class="keyword">return</span> <span class="number">0</span>;
}
</pre>
<p>However, this does not apply to the dnslookup example, because it is a console application.</p>
</div>
<p><b>See also </b><a href="qcommandlineoption.html">QCommandLineOption</a> and <a href="qcoreapplication.html">QCoreApplication</a>.</p>
<!-- @@@QCommandLineParser -->
<div class="types">
<h2>Member Type Documentation</h2>
<!-- $$$OptionsAfterPositionalArgumentsMode$$$ParseAsOptions$$$ParseAsPositionalArguments -->
<h3 class="fn" id="OptionsAfterPositionalArgumentsMode-enum"><a name="OptionsAfterPositionalArgumentsMode-enum"></a>enum QCommandLineParser::<span class="name">OptionsAfterPositionalArgumentsMode</span></h3>
<p>This enum describes the way the parser interprets options that occur after positional arguments.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QCommandLineParser::ParseAsOptions</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign"><code>application argument --opt -t</code> is interpreted as setting the options <code>opt</code> and <code>t</code>, just like <code>application --opt -t argument</code> would do. This is the default parsing mode. In order to specify that <code>--opt</code> and <code>-t</code> are positional arguments instead, the user can use <code>--</code>, as in <code>application argument -- --opt -t</code>.</td></tr>
<tr><td class="topAlign"><code>QCommandLineParser::ParseAsPositionalArguments</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign"><code>application argument --opt</code> is interpreted as having two positional arguments, <code>argument</code> and <code>--opt</code>. This mode is useful for executables that aim to launch other executables (e.g. wrappers, debugging tools, etc.) or that support internal commands followed by options for the command. <code>argument</code> is the name of the command, and all options occurring after it can be collected and parsed by another command line parser, possibly in another executable.</td></tr>
</table></div>
<p>This enum was introduced or modified in Qt 5.6.</p>
<p><b>See also </b><a href="qcommandlineparser.html#setOptionsAfterPositionalArgumentsMode">setOptionsAfterPositionalArgumentsMode</a>().</p>
<!-- @@@OptionsAfterPositionalArgumentsMode -->
<!-- $$$SingleDashWordOptionMode$$$ParseAsCompactedShortOptions$$$ParseAsLongOptions -->
<h3 class="fn" id="SingleDashWordOptionMode-enum"><a name="SingleDashWordOptionMode-enum"></a>enum QCommandLineParser::<span class="name">SingleDashWordOptionMode</span></h3>
<p>This enum describes the way the parser interprets command-line options that use a single dash followed by multiple letters, as as <code>-abc</code>.</p>
<div class="table"><table class="valuelist"><tr valign="top" class="odd"><th class="tblConst">Constant</th><th class="tblval">Value</th><th class="tbldscr">Description</th></tr>
<tr><td class="topAlign"><code>QCommandLineParser::ParseAsCompactedShortOptions</code></td><td class="topAlign tblval"><code>0</code></td><td class="topAlign"><code>-abc</code> is interpreted as <code>-a -b -c</code>, i.e. as three short options that have been compacted on the command-line, if none of the options take a value. If <code>a</code> takes a value, then it is interpreted as <code>-a bc</code>, i.e. the short option <code>a</code> followed by the value <code>bc</code>. This is typically used in tools that behave like compilers, in order to handle options such as <code>-DDEFINE=VALUE</code> or <code>-I/include/path</code>. This is the default parsing mode. New applications are recommended to use this mode.</td></tr>
<tr><td class="topAlign"><code>QCommandLineParser::ParseAsLongOptions</code></td><td class="topAlign tblval"><code>1</code></td><td class="topAlign"><code>-abc</code> is interpreted as <code>--abc</code>, i.e. as the long option named <code>abc</code>. This is how Qt's own 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. There is an exception if the <code>a</code> option has the <a href="qcommandlineoption.html#Flag-enum">QCommandLineOption::ShortOptionStyle</a> flag set, in which case it is still interpreted as <code>-a bc</code>.</td></tr>
</table></div>
<p><b>See also </b><a href="qcommandlineparser.html#setSingleDashWordOptionMode">setSingleDashWordOptionMode</a>().</p>
<!-- @@@SingleDashWordOptionMode -->
</div>
<div class="func">
<h2>Member Function Documentation</h2>
<!-- $$$QCommandLineParser[overload1]$$$QCommandLineParser -->
<h3 class="fn" id="QCommandLineParser"><a name="QCommandLineParser"></a>QCommandLineParser::<span class="name">QCommandLineParser</span>()</h3>
<p>Constructs a command line parser object.</p>
<!-- @@@QCommandLineParser -->
<!-- $$$~QCommandLineParser[overload1]$$$~QCommandLineParser -->
<h3 class="fn" id="dtor.QCommandLineParser"><a name="dtor.QCommandLineParser"></a>QCommandLineParser::<span class="name">~QCommandLineParser</span>()</h3>
<p>Destroys the command line parser object.</p>
<!-- @@@~QCommandLineParser -->
<!-- $$$addHelpOption[overload1]$$$addHelpOption -->
<h3 class="fn" id="addHelpOption"><a name="addHelpOption"></a><span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> QCommandLineParser::<span class="name">addHelpOption</span>()</h3>
<p>Adds the help option (<code>-h</code>, <code>--help</code> and <code>-?</code> on Windows) This option is handled automatically by <a href="qcommandlineparser.html">QCommandLineParser</a>.</p>
<p>Remember to use <a href="qcommandlineparser.html#setApplicationDescription">setApplicationDescription</a> to set the application description, which will be displayed when this option is used.</p>
<p>Example:</p>
<pre class="cpp">
<span class="type">int</span> main(<span class="type">int</span> argc<span class="operator">,</span> <span class="type">char</span> <span class="operator">*</span>argv<span class="operator">[</span><span class="operator">]</span>)
{
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>setApplicationName(<span class="string">"my-copy-program"</span>);
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>setApplicationVersion(<span class="string">"1.0"</span>);
<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span> parser;
parser<span class="operator">.</span>setApplicationDescription(<span class="string">"Test helper"</span>);
parser<span class="operator">.</span>addHelpOption();
parser<span class="operator">.</span>addVersionOption();
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"source"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Source file to copy."</span>));
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"destination"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Destination directory."</span>));
<span class="comment">// A boolean option with a single name (-p)</span>
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> showProgressOption(<span class="string">"p"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Show progress during copy"</span>));
parser<span class="operator">.</span>addOption(showProgressOption);
<span class="comment">// A boolean option with multiple names (-f, --force)</span>
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> forceOption(<span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"f"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"force"</span><span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Overwrite existing files."</span>));
parser<span class="operator">.</span>addOption(forceOption);
<span class="comment">// An option with a value</span>
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> targetDirectoryOption(<span class="type"><a href="qstringlist.html">QStringList</a></span>() <span class="operator"><</span><span class="operator"><</span> <span class="string">"t"</span> <span class="operator"><</span><span class="operator"><</span> <span class="string">"target-directory"</span><span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Copy all source files into <directory>."</span>)<span class="operator">,</span>
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"directory"</span>));
parser<span class="operator">.</span>addOption(targetDirectoryOption);
<span class="comment">// Process the actual command line arguments given by the user</span>
parser<span class="operator">.</span>process(app);
<span class="keyword">const</span> <span class="type"><a href="qstringlist.html">QStringList</a></span> args <span class="operator">=</span> parser<span class="operator">.</span>positionalArguments();
<span class="comment">// source is args.at(0), destination is args.at(1)</span>
bool showProgress <span class="operator">=</span> parser<span class="operator">.</span>isSet(showProgressOption);
bool force <span class="operator">=</span> parser<span class="operator">.</span>isSet(forceOption);
<span class="type"><a href="qstring.html">QString</a></span> targetDir <span class="operator">=</span> parser<span class="operator">.</span>value(targetDirectoryOption);
<span class="comment">// ...</span>
}
</pre>
<p>Returns the option instance, which can be used to call <a href="qcommandlineparser.html#isSet">isSet</a>().</p>
<!-- @@@addHelpOption -->
<!-- $$$addOption[overload1]$$$addOptionconstQCommandLineOption& -->
<h3 class="fn" id="addOption"><a name="addOption"></a><span class="type">bool</span> QCommandLineParser::<span class="name">addOption</span>(const <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> &<i>option</i>)</h3>
<p>Adds the option <i>option</i> to look for while parsing.</p>
<p>Returns <code>true</code> if adding the option was successful; otherwise returns <code>false</code>.</p>
<p>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.</p>
<!-- @@@addOption -->
<!-- $$$addOptions[overload1]$$$addOptionsconstQList<QCommandLineOption>& -->
<h3 class="fn" id="addOptions"><a name="addOptions"></a><span class="type">bool</span> QCommandLineParser::<span class="name">addOptions</span>(const <span class="type"><a href="qlist.html">QList</a></span><<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span>> &<i>options</i>)</h3>
<p>Adds the options to look for while parsing. The options are specified by the parameter <i>options</i>.</p>
<p>Returns <code>true</code> if adding all of the options was successful; otherwise returns <code>false</code>.</p>
<p>See the documentation for <a href="qcommandlineparser.html#addOption">addOption</a>() for when this function may fail.</p>
<p>This function was introduced in Qt 5.4.</p>
<!-- @@@addOptions -->
<!-- $$$addPositionalArgument[overload1]$$$addPositionalArgumentconstQString&constQString&constQString& -->
<h3 class="fn" id="addPositionalArgument"><a name="addPositionalArgument"></a><span class="type">void</span> QCommandLineParser::<span class="name">addPositionalArgument</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>name</i>, const <span class="type"><a href="qstring.html">QString</a></span> &<i>description</i>, const <span class="type"><a href="qstring.html">QString</a></span> &<i>syntax</i> = QString())</h3>
<p>Defines an additional argument to the application, for the benefit of the help text.</p>
<p>The argument <i>name</i> and <i>description</i> will appear under the <code>Arguments:</code> section of the help. If <i>syntax</i> is specified, it will be appended to the Usage line, otherwise the <i>name</i> will be appended.</p>
<p>Example:</p>
<pre class="cpp">
<span class="comment">// Usage: image-editor file</span>
<span class="comment">//</span>
<span class="comment">// Arguments:</span>
<span class="comment">// file The file to open.</span>
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"file"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"The file to open."</span>));
<span class="comment">// Usage: web-browser [urls...]</span>
<span class="comment">//</span>
<span class="comment">// Arguments:</span>
<span class="comment">// urls URLs to open, optionally.</span>
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"urls"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"URLs to open, optionally."</span>)<span class="operator">,</span> <span class="string">"[urls...]"</span>);
<span class="comment">// Usage: cp source destination</span>
<span class="comment">//</span>
<span class="comment">// Arguments:</span>
<span class="comment">// source Source file to copy.</span>
<span class="comment">// destination Destination directory.</span>
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"source"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Source file to copy."</span>));
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"destination"</span><span class="operator">,</span> <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>translate(<span class="string">"main"</span><span class="operator">,</span> <span class="string">"Destination directory."</span>));
</pre>
<p><b>See also </b><a href="qcommandlineparser.html#addHelpOption">addHelpOption</a>() and <a href="qcommandlineparser.html#helpText">helpText</a>().</p>
<!-- @@@addPositionalArgument -->
<!-- $$$addVersionOption[overload1]$$$addVersionOption -->
<h3 class="fn" id="addVersionOption"><a name="addVersionOption"></a><span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> QCommandLineParser::<span class="name">addVersionOption</span>()</h3>
<p>Adds the <code>-v</code> / <code>--version</code> option, which displays the version string of the application.</p>
<p>This option is handled automatically by <a href="qcommandlineparser.html">QCommandLineParser</a>.</p>
<p>You can set the actual version string by using <a href="qcoreapplication.html#applicationVersion-prop">QCoreApplication::setApplicationVersion</a>().</p>
<p>Returns the option instance, which can be used to call <a href="qcommandlineparser.html#isSet">isSet</a>().</p>
<!-- @@@addVersionOption -->
<!-- $$$applicationDescription[overload1]$$$applicationDescription -->
<h3 class="fn" id="applicationDescription"><a name="applicationDescription"></a><span class="type"><a href="qstring.html">QString</a></span> QCommandLineParser::<span class="name">applicationDescription</span>() const</h3>
<p>Returns the application description set in <a href="qcommandlineparser.html#setApplicationDescription">setApplicationDescription</a>().</p>
<p><b>See also </b><a href="qcommandlineparser.html#setApplicationDescription">setApplicationDescription</a>().</p>
<!-- @@@applicationDescription -->
<!-- $$$clearPositionalArguments[overload1]$$$clearPositionalArguments -->
<h3 class="fn" id="clearPositionalArguments"><a name="clearPositionalArguments"></a><span class="type">void</span> QCommandLineParser::<span class="name">clearPositionalArguments</span>()</h3>
<p>Clears the definitions of additional arguments from the help text.</p>
<p>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.</p>
<p>Example:</p>
<pre class="cpp">
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span> parser;
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"command"</span><span class="operator">,</span> <span class="string">"The command to execute."</span>);
<span class="comment">// Call parse() to find out the positional arguments.</span>
parser<span class="operator">.</span>parse(<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span><span class="operator">::</span>arguments());
<span class="keyword">const</span> <span class="type"><a href="qstringlist.html">QStringList</a></span> args <span class="operator">=</span> parser<span class="operator">.</span>positionalArguments();
<span class="keyword">const</span> <span class="type"><a href="qstring.html">QString</a></span> command <span class="operator">=</span> args<span class="operator">.</span>isEmpty() <span class="operator">?</span> <span class="type"><a href="qstring.html">QString</a></span>() : args<span class="operator">.</span>first();
<span class="keyword">if</span> (command <span class="operator">=</span><span class="operator">=</span> <span class="string">"resize"</span>) {
parser<span class="operator">.</span>clearPositionalArguments();
parser<span class="operator">.</span>addPositionalArgument(<span class="string">"resize"</span><span class="operator">,</span> <span class="string">"Resize the object to a new size."</span><span class="operator">,</span> <span class="string">"resize [resize_options]"</span>);
parser<span class="operator">.</span>addOption(<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span>(<span class="string">"size"</span><span class="operator">,</span> <span class="string">"New size."</span><span class="operator">,</span> <span class="string">"new_size"</span>));
parser<span class="operator">.</span>process(app);
<span class="comment">// ...</span>
}
<span class="comment">/*
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.
*/</span>
</pre>
<!-- @@@clearPositionalArguments -->
<!-- $$$errorText[overload1]$$$errorText -->
<h3 class="fn" id="errorText"><a name="errorText"></a><span class="type"><a href="qstring.html">QString</a></span> QCommandLineParser::<span class="name">errorText</span>() const</h3>
<p>Returns a translated error text for the user. This should only be called when <a href="qcommandlineparser.html#parse">parse</a>() returns <code>false</code>.</p>
<!-- @@@errorText -->
<!-- $$$helpText[overload1]$$$helpText -->
<h3 class="fn" id="helpText"><a name="helpText"></a><span class="type"><a href="qstring.html">QString</a></span> QCommandLineParser::<span class="name">helpText</span>() const</h3>
<p>Returns a string containing the complete help information.</p>
<p><b>See also </b><a href="qcommandlineparser.html#showHelp">showHelp</a>().</p>
<!-- @@@helpText -->
<!-- $$$isSet[overload1]$$$isSetconstQString& -->
<h3 class="fn" id="isSet"><a name="isSet"></a><span class="type">bool</span> QCommandLineParser::<span class="name">isSet</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>name</i>) const</h3>
<p>Checks whether the option <i>name</i> was passed to the application.</p>
<p>Returns <code>true</code> if the option <i>name</i> was set, false otherwise.</p>
<p>The name provided can be any long or short name of any option that was added with <code>addOption()</code>. All the options names are treated as being equivalent. If the name is not recognized or that option was not present, false is returned.</p>
<p>Example:</p>
<pre class="cpp">
bool verbose <span class="operator">=</span> parser<span class="operator">.</span>isSet(<span class="string">"verbose"</span>);
</pre>
<!-- @@@isSet -->
<!-- $$$isSet$$$isSetconstQCommandLineOption& -->
<h3 class="fn" id="isSet-1"><a name="isSet-1"></a><span class="type">bool</span> QCommandLineParser::<span class="name">isSet</span>(const <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> &<i>option</i>) const</h3>
<p>This is an overloaded function.</p>
<p>Checks whether the <i>option</i> was passed to the application.</p>
<p>Returns <code>true</code> if the <i>option</i> was set, false otherwise.</p>
<p>This is the recommended way to check for options with no values.</p>
<p>Example:</p>
<pre class="cpp">
<span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="type"><a href="qcommandlineparser.html#QCommandLineParser">QCommandLineParser</a></span> parser;
<span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> verboseOption(<span class="string">"verbose"</span>);
parser<span class="operator">.</span>addOption(verboseOption);
parser<span class="operator">.</span>process(app);
bool verbose <span class="operator">=</span> parser<span class="operator">.</span>isSet(verboseOption);
</pre>
<!-- @@@isSet -->
<!-- $$$optionNames[overload1]$$$optionNames -->
<h3 class="fn" id="optionNames"><a name="optionNames"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QCommandLineParser::<span class="name">optionNames</span>() const</h3>
<p>Returns a list of option names that were found.</p>
<p>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.</p>
<p>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.</p>
<p>Any entry in the list can be used with <code>value()</code> or with <code>values()</code> to get any relevant option values.</p>
<!-- @@@optionNames -->
<!-- $$$parse[overload1]$$$parseconstQStringList& -->
<h3 class="fn" id="parse"><a name="parse"></a><span class="type">bool</span> QCommandLineParser::<span class="name">parse</span>(const <span class="type"><a href="qstringlist.html">QStringList</a></span> &<i>arguments</i>)</h3>
<p>Parses the command line <i>arguments</i>.</p>
<p>Most programs don't need to call this, a simple call to <a href="qcommandlineparser.html#process">process</a>() is enough.</p>
<p>parse() is more low-level, and only does the parsing. The application will have to take care of the error handling, using <a href="qcommandlineparser.html#errorText">errorText</a>() if parse() returns <code>false</code>. This can be useful for instance to show a graphical error message in graphical programs.</p>
<p>Calling parse() instead of <a href="qcommandlineparser.html#process">process</a>() 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 <a href="qcommandlineparser.html#process">process</a>().</p>
<p>Don't forget that <i>arguments</i> must start with the name of the executable (ignored, though).</p>
<p>Returns <code>false</code> in case of a parse error (unknown option or missing value); returns <code>true</code> otherwise.</p>
<p><b>See also </b><a href="qcommandlineparser.html#process">process</a>().</p>
<!-- @@@parse -->
<!-- $$$positionalArguments[overload1]$$$positionalArguments -->
<h3 class="fn" id="positionalArguments"><a name="positionalArguments"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QCommandLineParser::<span class="name">positionalArguments</span>() const</h3>
<p>Returns a list of positional arguments.</p>
<p>These are all of the arguments that were not recognized as part of an option.</p>
<!-- @@@positionalArguments -->
<!-- $$$process[overload1]$$$processconstQStringList& -->
<h3 class="fn" id="process"><a name="process"></a><span class="type">void</span> QCommandLineParser::<span class="name">process</span>(const <span class="type"><a href="qstringlist.html">QStringList</a></span> &<i>arguments</i>)</h3>
<p>Processes the command line <i>arguments</i>.</p>
<p>In addition to parsing the options (like <a href="qcommandlineparser.html#parse">parse</a>()), this function also handles the builtin options and handles errors.</p>
<p>The builtin options are <code>--version</code> if <a href="qcommandlineparser.html#addVersionOption">addVersionOption</a> was called and <code>--help</code> if <a href="qcommandlineparser.html#addHelpOption">addHelpOption</a> was called.</p>
<p>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.</p>
<p><b>See also </b><a href="qcoreapplication.html#arguments">QCoreApplication::arguments</a>() and <a href="qcommandlineparser.html#parse">parse</a>().</p>
<!-- @@@process -->
<!-- $$$process$$$processconstQCoreApplication& -->
<h3 class="fn" id="process-1"><a name="process-1"></a><span class="type">void</span> QCommandLineParser::<span class="name">process</span>(const <span class="type"><a href="qcoreapplication.html">QCoreApplication</a></span> &<i>app</i>)</h3>
<p>This is an overloaded function.</p>
<p>The command line is obtained from the <a href="qcoreapplication.html">QCoreApplication</a> instance <i>app</i>.</p>
<!-- @@@process -->
<!-- $$$setApplicationDescription[overload1]$$$setApplicationDescriptionconstQString& -->
<h3 class="fn" id="setApplicationDescription"><a name="setApplicationDescription"></a><span class="type">void</span> QCommandLineParser::<span class="name">setApplicationDescription</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>description</i>)</h3>
<p>Sets the application <i>description</i> shown by <a href="qcommandlineparser.html#helpText">helpText</a>().</p>
<p><b>See also </b><a href="qcommandlineparser.html#applicationDescription">applicationDescription</a>().</p>
<!-- @@@setApplicationDescription -->
<!-- $$$setOptionsAfterPositionalArgumentsMode[overload1]$$$setOptionsAfterPositionalArgumentsModeOptionsAfterPositionalArgumentsMode -->
<h3 class="fn" id="setOptionsAfterPositionalArgumentsMode"><a name="setOptionsAfterPositionalArgumentsMode"></a><span class="type">void</span> QCommandLineParser::<span class="name">setOptionsAfterPositionalArgumentsMode</span>(<span class="type"><a href="qcommandlineparser.html#OptionsAfterPositionalArgumentsMode-enum">OptionsAfterPositionalArgumentsMode</a></span> <i>parsingMode</i>)</h3>
<p>Sets the parsing mode to <i>parsingMode</i>. This must be called before <a href="qcommandlineparser.html#process">process</a>() or <a href="qcommandlineparser.html#parse">parse</a>().</p>
<p>This function was introduced in Qt 5.6.</p>
<!-- @@@setOptionsAfterPositionalArgumentsMode -->
<!-- $$$setSingleDashWordOptionMode[overload1]$$$setSingleDashWordOptionModeSingleDashWordOptionMode -->
<h3 class="fn" id="setSingleDashWordOptionMode"><a name="setSingleDashWordOptionMode"></a><span class="type">void</span> QCommandLineParser::<span class="name">setSingleDashWordOptionMode</span>(<span class="type"><a href="qcommandlineparser.html#SingleDashWordOptionMode-enum">SingleDashWordOptionMode</a></span> <i>singleDashWordOptionMode</i>)</h3>
<p>Sets the parsing mode to <i>singleDashWordOptionMode</i>. This must be called before <a href="qcommandlineparser.html#process">process</a>() or <a href="qcommandlineparser.html#parse">parse</a>().</p>
<!-- @@@setSingleDashWordOptionMode -->
<!-- $$$showHelp[overload1]$$$showHelpint -->
<h3 class="fn" id="showHelp"><a name="showHelp"></a><span class="type">void</span> QCommandLineParser::<span class="name">showHelp</span>(<span class="type">int</span> <i>exitCode</i> = 0)</h3>
<p>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 <i>exitCode</i>. It should be set to 0 if the user requested to see the help, and to any other value in case of an error.</p>
<p><b>See also </b><a href="qcommandlineparser.html#helpText">helpText</a>().</p>
<!-- @@@showHelp -->
<!-- $$$showVersion[overload1]$$$showVersion -->
<h3 class="fn" id="showVersion"><a name="showVersion"></a><span class="type">void</span> QCommandLineParser::<span class="name">showVersion</span>()</h3>
<p>Displays the version information from <a href="qcoreapplication.html#applicationVersion-prop">QCoreApplication::applicationVersion</a>(), and exits the application. This is automatically triggered by the --version option, but can also be used to display the version when not using <a href="qcommandlineparser.html#process">process</a>(). The exit code is set to EXIT_SUCCESS (0).</p>
<p>This function was introduced in Qt 5.4.</p>
<p><b>See also </b><a href="qcommandlineparser.html#addVersionOption">addVersionOption</a>().</p>
<!-- @@@showVersion -->
<!-- $$$unknownOptionNames[overload1]$$$unknownOptionNames -->
<h3 class="fn" id="unknownOptionNames"><a name="unknownOptionNames"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QCommandLineParser::<span class="name">unknownOptionNames</span>() const</h3>
<p>Returns a list of unknown option names.</p>
<p>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.</p>
<p>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.</p>
<p><b>See also </b><a href="qcommandlineparser.html#optionNames">optionNames</a>().</p>
<!-- @@@unknownOptionNames -->
<!-- $$$value[overload1]$$$valueconstQString& -->
<h3 class="fn" id="value"><a name="value"></a><span class="type"><a href="qstring.html">QString</a></span> QCommandLineParser::<span class="name">value</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>optionName</i>) const</h3>
<p>Returns the option value found for the given option name <i>optionName</i>, or an empty string if not found.</p>
<p>The name provided can be any long or short name of any option that was added with <code>addOption()</code>. 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.</p>
<p>For options found by the parser, the last value found for that option is returned. If the option wasn't specified on the command line, the default value is returned.</p>
<p>An empty string is returned if the option does not take a value.</p>
<p><b>See also </b><a href="qcommandlineparser.html#values">values</a>(), <a href="qcommandlineoption.html#setDefaultValue">QCommandLineOption::setDefaultValue</a>(), and <a href="qcommandlineoption.html#setDefaultValues">QCommandLineOption::setDefaultValues</a>().</p>
<!-- @@@value -->
<!-- $$$value$$$valueconstQCommandLineOption& -->
<h3 class="fn" id="value-1"><a name="value-1"></a><span class="type"><a href="qstring.html">QString</a></span> QCommandLineParser::<span class="name">value</span>(const <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> &<i>option</i>) const</h3>
<p>This is an overloaded function.</p>
<p>Returns the option value found for the given <i>option</i>, or an empty string if not found.</p>
<p>For options found by the parser, the last value found for that option is returned. If the option wasn't specified on the command line, the default value is returned.</p>
<p>An empty string is returned if the option does not take a value.</p>
<p><b>See also </b><a href="qcommandlineparser.html#values">values</a>(), <a href="qcommandlineoption.html#setDefaultValue">QCommandLineOption::setDefaultValue</a>(), and <a href="qcommandlineoption.html#setDefaultValues">QCommandLineOption::setDefaultValues</a>().</p>
<!-- @@@value -->
<!-- $$$values[overload1]$$$valuesconstQString& -->
<h3 class="fn" id="values"><a name="values"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QCommandLineParser::<span class="name">values</span>(const <span class="type"><a href="qstring.html">QString</a></span> &<i>optionName</i>) const</h3>
<p>Returns a list of option values found for the given option name <i>optionName</i>, or an empty list if not found.</p>
<p>The name provided can be any long or short name of any option that was added with <code>addOption()</code>. 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.</p>
<p>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 wasn't specified on the command line, the default values are returned.</p>
<p>An empty list is returned if the option does not take a value.</p>
<p><b>See also </b><a href="qcommandlineparser.html#value">value</a>(), <a href="qcommandlineoption.html#setDefaultValue">QCommandLineOption::setDefaultValue</a>(), and <a href="qcommandlineoption.html#setDefaultValues">QCommandLineOption::setDefaultValues</a>().</p>
<!-- @@@values -->
<!-- $$$values$$$valuesconstQCommandLineOption& -->
<h3 class="fn" id="values-1"><a name="values-1"></a><span class="type"><a href="qstringlist.html">QStringList</a></span> QCommandLineParser::<span class="name">values</span>(const <span class="type"><a href="qcommandlineoption.html">QCommandLineOption</a></span> &<i>option</i>) const</h3>
<p>This is an overloaded function.</p>
<p>Returns a list of option values found for the given <i>option</i>, or an empty list if not found.</p>
<p>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 wasn't specified on the command line, the default values are returned.</p>
<p>An empty list is returned if the option does not take a value.</p>
<p><b>See also </b><a href="qcommandlineparser.html#value">value</a>(), <a href="qcommandlineoption.html#setDefaultValue">QCommandLineOption::setDefaultValue</a>(), and <a href="qcommandlineoption.html#setDefaultValues">QCommandLineOption::setDefaultValues</a>().</p>
<!-- @@@values -->
</div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
323
