</head>
<body>
-<div class="doc_title">
+<h1>
CommandLine 2.0 Library Manual
-</div>
+</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<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>
specified</a></li>
<li><a href="#formatting">Controlling other formatting options</a></li>
<li><a href="#misc">Miscellaneous option modifiers</a></li>
+ <li><a href="#response">Response files</a></li>
</ul></li>
<li><a href="#toplevel">Top-Level Classes and Functions</a>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="introduction">Introduction</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This document describes the CommandLine argument processing library. It will
show you how to use it, and what it can do. The CommandLine library uses a
<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>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="quickstart">Quick Start Guide</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This section of the manual runs through a simple CommandLine'ification of a
basic compiler tool. This is intended to show you how to jump into using the
<a href="#cl::opt">cl::opt</a><string> OutputFilename("<i>o</i>", <a href="#cl::desc">cl::desc</a>("<i>Specify output filename</i>"), <a href="#cl::value_desc">cl::value_desc</a>("<i>filename</i>"));
</pre></div>
-<p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
-capture the result of the "<tt>o</tt>" argument (first parameter). We specify
-that this is a simple scalar option by using the
"<tt><a
-href="#cl::opt">cl::opt</a></tt>
" template (as opposed to the <a
-href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
+<p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
+capture the result of the "<tt>o</tt>" argument (first parameter). We specify
+that this is a simple scalar option by using the
"<tt><a
+href="#cl::opt">cl::opt</a></tt>
" template (as opposed to the <a
+href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
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>
<div class="doc_code"><pre>
...
- ofstream Output(OutputFilename.c_str());
- if (Out.good()) ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
...
</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>
<p>... indicating that an input filename is expected.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="bool">Boolean Arguments</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="alias">Argument Aliases</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>So far, the example works well, except for the fact that we need to check the
quiet condition like this now:</p>
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>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="onealternative">Selecting an alternative from a set of
possibilities</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>So far we have seen how the CommandLine library handles builtin types like
<tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
-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>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="namedalternatives">Named Alternatives</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Another useful argument form is a named alternative style. We shall use this
style in our compiler to specify different debug levels that can be used.
<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>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="list">Parsing a list of options</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Now that we have the standard run-of-the-mill argument types out of the way,
lets get a little wild and crazy. Lets say that we want our optimizer to accept
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="bits">Collecting options as a set of flags</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<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
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="description">Adding freeform text to help output</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>As our program grows and becomes more mature, we may decide to put summary
information about what it does into the help output. The help output is styled
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>
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="referenceguide">Reference Guide</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Now that you know the basics of how to use the CommandLine library, this
section will give you the detailed information you need to tune how command line
options work, as well as information on more "advanced" command line option
processing capabilities.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="positional">Positional Arguments</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Positional arguments are those arguments that are not named, and are not
specified with a hyphen. Positional arguments should be used when an option is
<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
are defined in multiple .cpp files. The fix for this problem is simply to
define all of your positional arguments in one .cpp file.</p>
-</div>
-
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="--">Specifying positional options with hyphens</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>Sometimes you may want to specify a value to your positional argument that
starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At
<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
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="getPosition">Determining absolute position with getPosition()</a>
-</div>
-<div class="doc_text">
+</h4>
+<div>
<p>Sometimes an option can affect or modify the meaning of another option. For
example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
<tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
the file to be interpreted as if it contained source code in language
- <tt>LANG</tt>. In order to handle this properly , you need to know the
+ <tt>LANG</tt>. In order to handle this properly, you need to know the
absolute position of each argument, especially those in lists, so their
interaction(s) can be applied correctly. This is also useful for options like
<tt>-llibname</tt> which is actually a positional argument that starts with
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
used to construct programs that use "interpreter style" option processing. With
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>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="storage">Internal vs External Storage</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>By default, all command line options automatically hold the value that they
parse from the command line. This is very convenient in the common case,
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>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="attributes">Option Attributes</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>This section describes the basic attributes that you can specify on
options.</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>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="modifiers">Option Modifiers</a>
-</div>
+</h3>
-<div class="doc_text">
+<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>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
- <a name="hiding">Hiding an option from <tt>--help</tt> output</a>
-</div>
+<h4>
+ <a name="hiding">Hiding an option from <tt>-help</tt> output</a>
+</h4>
-<div class="doc_text">
+<div>
<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>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="numoccurrences">Controlling the number of occurrences required and
allowed</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>This group of options is used to control how many time an option is allowed
(or required) to be specified on the command line of your program. Specifying a
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="valrequired">Controlling whether or not a value must be specified</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>This group of options is used to control whether or not the option allows a
value to be present. In the case of the CommandLine library, a value is either
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="formatting">Controlling other formatting options</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The formatting option group is used to specify that the command line option
has special abilities and is otherwise different from other command line
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="misc">Miscellaneous option modifiers</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The miscellaneous option modifiers are the only flags where you can specify
more than one flag from the set: they are not mutually exclusive. These flags
<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>
</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="response">Response files</a>
+</h4>
+
+<div>
+
+<p>Some systems, such as certain variants of Microsoft Windows and
+some older Unices have a relatively low limit on command-line
+length. It is therefore customary to use the so-called 'response
+files' to circumvent this restriction. These files are mentioned on
+the command-line (using the "@file") syntax. The program reads these
+files and inserts the contents into argv, thereby working around the
+command-line length limits. Response files are enabled by an optional
+fourth argument to
+<a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a>
+and
+<a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
+</p>
+
+</div>
+
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="toplevel">Top-Level Classes and Functions</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Despite all of the built-in flexibility, the CommandLine option library
really only consists of one function (<a
href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
classes in detail.</p>
-</div>
-
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
function</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
directly from <tt>main</tt>, and is used to fill in the values of all of the
<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.</p>
+<tt>-help</tt> option is invoked, and a fourth boolean parameter that enables
+<a href="#response">response files</a>.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
function</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
as <a
href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
does.</p>
-<p>It takes three parameters: the name of the program (since <tt>argv</tt> may
+<p>It takes four parameters: the name of the program (since <tt>argv</tt> may
not be available, it can't just look in <tt>argv[0]</tt>), the name of the
-environment variable to examine, and the optional
+environment variable to examine, the optional
<a href="#description">additional extra text</a> to emit when the
-<tt>--help</tt> option is invoked.</p>
+<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
variable's value up into words and then process them using
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
function</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
directly from <tt>main</tt> and <i>before</i>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::opt">The <tt>cl::opt</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
options, and is the one used most of the time. It is a templated class which
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::list">The <tt>cl::list</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::list</tt> class is the class used to represent a list of command
line options. It too is a templated class which can take up to three
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::bits">The <tt>cl::bits</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::bits</tt> class is the class used to represent a list of command
line options in the form of a bit vector. It is also a templated class which
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::alias">The <tt>cl::alias</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
aliases for other arguments.</p>
</div>
<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
+<h4>
<a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
-</div>
+</h4>
-<div class="doc_text">
+<div>
<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 {
</pre></div>
</div>
+</div>
+
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="builtinparsers">Builtin parsers</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Parsers control how the string value taken from the command line is
translated into a typed value, suitable for use in a C++ program. By default,
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="extensionguide">Extension Guide</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Although the CommandLine library has a lot of functionality built into it
already (as discussed previously), one of its true strengths lie in its
extensibility. This section discusses how the CommandLine library works under
the covers and illustrates how to do some simple, common, extensions.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="customparser">Writing a custom parser</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>One of the simplest and most common extensions is the use of a custom parser.
As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
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>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="explotingexternal">Exploiting external storage</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
will automatically be included in any program that links with that library.
This is a feature. However, sometimes it is necessary to know the value of the
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="dynamicopts">Dynamically adding command line options</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>TODO: fill in this section</p>
</div>
+</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>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff