<li><a href="#modifiers">Option Modifiers</a>
<ul>
- <li><a href="#hiding">Hiding an option from <tt>--help</tt>
+ <li><a href="#hiding">Hiding an option from <tt>-help</tt>
output</a></li>
<li><a href="#numoccurrences">Controlling the number of occurrences
required and allowed</a></li>
<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
that you, the user, have to do. For example, it automatically provides a
-<tt>--help</tt> option that shows the available command line options for your
+<tt>-help</tt> option that shows the available command line options for your
tool. Additionally, it does most of the basic correctness checking for
you.</li>
that the data type that we are parsing is a string.</p>
<p>The second and third parameters (which are optional) are used to specify what
-to output for the "<tt>--help</tt>" option. In this case, we get a line that
+to output for the "<tt>-help</tt>" option. In this case, we get a line that
looks like this:</p>
<div class="doc_code"><pre>
USAGE: compiler [options]
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
<b>-o <filename> - Specify output filename</b>
</pre></div>
specified, which shifts all of the command line option verification code out of
your application into the library. This is just one example of how using flags
can alter the default behaviour of the library, on a per-option basis. By
-adding one of the declarations above, the <tt>--help</tt> option synopsis is now
+adding one of the declarations above, the <tt>-help</tt> option synopsis is now
extended to:</p>
<div class="doc_code"><pre>
USAGE: compiler [options] <b><input file></b>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
</pre></div>
<div class="doc_text">
<p>In addition to input and output filenames, we would like the compiler example
-to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
-file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
-compatibility with some of our users. We can support these by declaring options
-of boolean type like this:</p>
+to support three boolean flags: "<tt>-f</tt>" to force writing binary output to
+a terminal, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for
+backwards compatibility with some of our users. We can support these by
+declaring options of boolean type like this:</p>
<div class="doc_code"><pre>
-<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable binary output on terminals</i>"));
<a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
<a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>);
</pre></div>
("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
options. Note that the "<tt>-q</tt>" option is specified with the "<a
href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it
-from being shown by the standard "<tt>--help</tt>" output (note that it is still
-shown in the "<tt>--help-hidden</tt>" output).</p>
+from being shown by the standard "<tt>-help</tt>" output (note that it is still
+shown in the "<tt>-help-hidden</tt>" output).</p>
<p>The CommandLine library uses a <a href="#builtinparsers">different parser</a>
for different data types. For example, in the string case, the argument passed
like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
library calls to parse the string value into the specified data type.</p>
-<p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
+<p>With the declarations above, "<tt>compiler -help</tt>" emits this:</p>
<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
- <b>-f - Overwrite output files</b>
+ <b>-f - Enable binary output on terminals</b>
-o - Override output filename
<b>-quiet - Don't print informational messages</b>
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
</pre></div>
-<p>and "<tt>compiler --help-hidden</tt>" prints this:</p>
+<p>and "<tt>compiler -help-hidden</tt>" prints this:</p>
<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
- -f - Overwrite output files
+ -f - Enable binary output on terminals
-o - Override output filename
<b>-q - Don't print informational messages</b>
-quiet - Don't print informational messages
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
</pre></div>
<p>This brief example has shown you how to use the '<tt><a
specified. Because aliases do not hold state, the only thing the program has to
query is the <tt>Quiet</tt> variable now. Another nice feature of aliases is
that they automatically hide themselves from the <tt>-help</tt> output
-(although, again, they are still visible in the <tt>--help-hidden
+(although, again, they are still visible in the <tt>-help-hidden
output</tt>).</p>
<p>Now the application code can simply use:</p>
-O1 - Enable trivial optimizations
-O2 - Enable default optimizations
-O3 - Enable expensive optimizations</b>
- -f - Overwrite output files
- -help - display available options (--help-hidden for more)
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
-quiet - Don't print informational messages
</pre></div>
<p>This definition defines an enumerated command line variable of type "<tt>enum
DebugLev</tt>", which works exactly the same way as before. The difference here
is just the interface exposed to the user of your program and the help output by
-the "<tt>--help</tt>" option:</p>
+the "<tt>-help</tt>" option:</p>
<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
=none - disable debug information
=quick - enable quick debug information
=detailed - enable detailed debug information</b>
- -f - Overwrite output files
- -help - display available options (--help-hidden for more)
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
-quiet - Don't print informational messages
</pre></div>
<div class="doc_text">
<p>Instead of collecting sets of options in a list, it is also possible to
-gather information for enum values in a <b>bit vector</b>. The represention used by
+gather information for enum values in a <b>bit vector</b>. The representation used by
the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
integer. An enum value is represented by a 0/1 in the enum's ordinal value bit
position. 1 indicating that the enum was specified, 0 otherwise. As each
OPTIONS:
...
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
</pre></div>
<a href="#cl::opt">cl::opt</a><string> Filename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
</pre></div>
-<p>Given these two option declarations, the <tt>--help</tt> output for our grep
+<p>Given these two option declarations, the <tt>-help</tt> output for our grep
replacement would look like this:</p>
<div class="doc_code"><pre>
USAGE: spiffygrep [options] <b><regular expression> <input file></b>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
</pre></div>
<p>... and the resultant program could be used just like the standard
<div class="doc_code"><pre>
$ spiffygrep '-foo' test.txt
- Unknown command line argument '-foo'. Try: spiffygrep --help'
+ Unknown command line argument '-foo'. Try: spiffygrep -help'
$ grep '-foo' test.txt
grep: illegal option -- f
USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
<b>-x - Enable trace output</b>
</pre></div>
code from the storage of the value parsed. For example, lets say that we have a
'<tt>-debug</tt>' option that we would like to use to enable debug information
across the entire body of our program. In this case, the boolean value
-controlling the debug code should be globally accessable (in a header file, for
+controlling the debug code should be globally accessible (in a header file, for
example) yet the command line option processing code should not be exposed to
all of these clients (requiring lots of .cpp files to #include
<tt>CommandLine.h</tt>).</p>
</li>
<li><a name="cl::desc">The <b><tt>cl::desc</tt></b></a> attribute specifies a
-description for the option to be shown in the <tt>--help</tt> output for the
+description for the option to be shown in the <tt>-help</tt> output for the
program.</li>
<li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b></a> attribute
-specifies a string that can be used to fine tune the <tt>--help</tt> output for
+specifies a string that can be used to fine tune the <tt>-help</tt> output for
a command line option. Look <a href="#value_desc_example">here</a> for an
example.</li>
<li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an
-inital value for a <a href="#cl::opt">scalar</a> option. If this attribute is
+init
ial value for a <a href="#cl::opt">scalar</a> option. If this attribute is
not specified then the command line option value defaults to the value created
by the default constructor for the type. <b>Warning</b>: If you specify both
<b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
initial value. (You will get an error at runtime if you don't put them in
the right order.)</li>
-<li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where to
-store the value for a parsed command line option if using external storage. See
-the section on <a href="#storage">Internal vs External Storage</a> for more
+<li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where
+to store the value for a parsed command line option if using external storage.
+
See the section on <a href="#storage">Internal vs External Storage</a> for more
information.</li>
<li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
<b>clEnumValEnd terminated</b> list of (option, value, description) triplets
that
specify the option name, the value mapped to, and the description shown in the
-<tt>--help</tt> for the tool. Because the generic parser is used most
+<tt>-help</tt> for the tool. Because the generic parser is used most
frequently with enum values, two macros are often useful:
<ol>
You will get a compile time error if you try to use cl::values with a parser
that does not support it.</li>
+<li><a name="cl::multi_val">The <b><tt>cl::multi_val</tt></b></a>
+attribute specifies that this option takes has multiple values
+(example: <tt>-sectalign segname sectname sectvalue</tt>). This
+attribute takes one unsigned argument - the number of values for the
+option. This attribute is valid only on <tt>cl::list</tt> options (and
+will fail with compile error if you try to use it with other option
+types). It is allowed to use all of the usual modifiers on
+multi-valued options (besides <tt>cl::ValueDisallowed</tt>,
+obviously).</li>
+
</ul>
</div>
<p>Option modifiers are the flags and expressions that you pass into the
constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
-tweak how options are parsed and how <tt>--help</tt> output is generated to fit
+tweak how options are parsed and how <tt>-help</tt> output is generated to fit
your application well.</p>
-<p>These options fall into five main catagories:</p>
+<p>These options fall into five main categories:</p>
<ol>
-<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
+<li><a href="#hiding">Hiding an option from <tt>-help</tt> output</a></li>
<li><a href="#numoccurrences">Controlling the number of occurrences
required and allowed</a></li>
<li><a href="#valrequired">Controlling whether or not a value must be
<li><a href="#misc">Miscellaneous option modifiers</a></li>
</ol>
-<p>It is not possible to specify two options from the same catagory (you'll get
+<p>It is not possible to specify two options from the same category (you'll get
a runtime error) to a single option, except for options in the miscellaneous
-catagory. The CommandLine library specifies defaults for all of these settings
+category. The CommandLine library specifies defaults for all of these settings
that are the most useful in practice and the most common, which mean that you
usually shouldn't have to worry about these.</p>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="hiding">Hiding an option from <tt>--help</tt> output</a>
+ <a name="hiding">Hiding an option from <tt>-help</tt> output</a>
</div>
<div class="doc_text">
<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
-appears in the <tt>--help</tt> and <tt>--help-hidden</tt> output for the
+appears in the <tt>-help</tt> and <tt>-help-hidden</tt> output for the
compiled program:</p>
<ul>
<li><a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b></a> modifier (which is the
default for <tt><a href="#cl::alias">cl::alias</a></tt> options) indicates that
-the option should not appear in the <tt>--help</tt> output, but should appear in
-the <tt>--help-hidden</tt> output.</li>
+the option should not appear in the <tt>-help</tt> output, but should appear in
+the <tt>-help-hidden</tt> output.</li>
<li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier
indicates that the option should not appear in any help output.</li>
<li><a name="cl::Sink">The <b><tt>cl::Sink</tt></b></a> modifier is
used to handle unknown options. If there is at least one option with
-<b><tt>cl::Sink</tt></b></a> modifier specified, the parser passes
+<tt>cl::Sink</tt> modifier specified, the parser passes
unrecognized option strings to it as values instead of signaling an
-error. As with <b><tt>cl::CommaSeparated</tt></b></a>, this modifier
+error. As with <tt>cl::CommaSeparated</tt>, this modifier
only makes sense with a <a href="#cl::list">cl::list</a> option.</li>
-
</ul>
<p>So far, these are the only three miscellaneous option modifiers.</p>
<p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
(<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
which holds <a href="#description">additional extra text</a> to emit when the
-<tt>--help</tt> option is invoked, and a fourth boolean parameter that enables
+<tt>-help</tt> option is invoked, and a fourth boolean parameter that enables
<a href="#response">response files</a>.</p>
</div>
not be available, it can't just look in <tt>argv[0]</tt>), the name of the
environment variable to examine, the optional
<a href="#description">additional extra text</a> to emit when the
-<tt>--help</tt> option is invoked, and the boolean
-switch that controls whether <a href="#response">reponse files</a>
+<tt>-help</tt> option is invoked, and the boolean
+switch that controls whether <a href="#response">response files</a>
should be read.</p>
<p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
<div class="doc_text">
<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
-help text to be printed out for the <tt>--help</tt> option.</p>
+help text to be printed out for the <tt>-help</tt> option.</p>
<div class="doc_code"><pre>
<b>namespace</b> cl {
default:
<i>// Print an error message if unrecognized character!</i>
- <b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
+ <b>return</b> O.error("'" + Arg + "' value invalid for file size argument!");
}
}
}
<div class="doc_code"><pre>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
...
<b>-max-file-size=<size> - Maximum file size to accept</b>
</pre></div>
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
projects / oota-llvm.git / blobdiff