set of possibilities</a></li>
<li><a href="#namedalternatives">Named alternatives</a></li>
<li><a href="#list">Parsing a list of options</a></li>
+ <li><a href="#bits">Collecting options as a set of flags</a></li>
<li><a href="#description">Adding freeform text to help output</a></li>
</ol></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>
<ul>
- <li><a href="#cl::ParseCommandLineOptions">The
+ <li><a href="#cl::ParseCommandLineOptions">The
<tt>cl::ParseCommandLineOptions</tt> function</a></li>
- <li><a href="#cl::ParseEnvironmentOptions">The
+ <li><a href="#cl::ParseEnvironmentOptions">The
<tt>cl::ParseEnvironmentOptions</tt> function</a></li>
+ <li><a href="#cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a></li>
<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
<li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
+ <li><a href="#cl::bits">The <tt>cl::bits</tt> class</a></li>
<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
<li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
</ul></li>
parser</a></li>
<li><a href="#boolparser">The <tt>parser<bool></tt>
specialization</a></li>
+ <li><a href="#boolOrDefaultparser">The <tt>parser<boolOrDefault></tt>
+ specialization</a></li>
<li><a href="#stringparser">The <tt>parser<string></tt>
specialization</a></li>
<li><a href="#intparser">The <tt>parser<int></tt>
<ol>
<li><a href="#customparser">Writing a custom parser</a></li>
<li><a href="#explotingexternal">Exploiting external storage</a></li>
- <li><a href="#dynamicopts">Dynamically adding command line
+ <li><a href="#dynamicopts">Dynamically adding command line
options</a></li>
</ol></li>
</ol>
<li>Globally accessible: Libraries can specify command line arguments that are
automatically enabled in any tool that links to the library. This is possible
-because the application doesn't have to keep a "list" of arguments to pass to
+because the application doesn't have to keep a list of arguments to pass to
the parser. This also makes supporting <a href="#dynamicopts">dynamically
loaded options</a> trivial.</li>
program:</p>
<div class="doc_code"><pre>
- #include "Support/CommandLine.h"
+ #include "llvm/Support/CommandLine.h"
</pre></div>
<p>Additionally, you need to add this as the first line of your main
declarations.</p>
<p>Now that you are ready to support command line arguments, we need to tell the
-system which ones we want, and what type of argument they are. The CommandLine
+system which ones we want, and what type of arguments they are. The CommandLine
library uses a declarative syntax to model command line arguments with the
global variable declarations that capture the parsed values. This means that
for every command line option that you would like to support, there should be a
global variable declaration to capture the result. For example, in a compiler,
-we would like to support the unix standard '<tt>-o <filename></tt>' option
+we would like to support the Unix-standard '<tt>-o <filename></tt>' option
to specify where to put the output. With the CommandLine library, this is
represented like this:</p>
<div class="doc_code"><pre>
...
- ofstream Output(OutputFilename.c_str());
- if (Out.good()) ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
...
</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>
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)
</pre></div>
-<p>and "<tt>opt --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
</pre></div>
<p>The third line (which is the only one we modified from above) defines a
-"<tt>-q</tt> alias that updates the "<tt>Quiet</tt>" variable (as specified by
+"<tt>-q</tt>" alias that updates the "<tt>Quiet</tt>" variable (as specified by
the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is
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
<div class="doc_text">
-<p>So far, we have seen how the CommandLine library handles builtin types like
+<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
things it doesn't know about, like enums or '<tt>int*</tt>'s?</p>
-<p>The answer is that it uses a table driven generic parser (unless you specify
+<p>The answer is that it uses a table-driven generic parser (unless you specify
your own parser, as described in the <a href="#extensionguide">Extension
Guide</a>). This parser maps literal strings to whatever type is required, and
requires you to tell it what this mapping should be.</p>
-<p>Lets say that we would like to add four optimization levels to our
+<p>Let's say that we would like to add four optimization levels to our
optimizer, using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>",
"<tt>-O1</tt>", and "<tt>-O2</tt>". We could easily implement this with boolean
options like above, but there are several problems with this strategy:</p>
<ol>
<li>A user could specify more than one of the options at a time, for example,
-"<tt>opt -O3 -O2</tt>". The CommandLine library would not be able to catch this
-erroneous input for us.</li>
+"<tt>compiler -O3 -O2</tt>". The CommandLine library would not be able to
+catch this erroneous input for us.</li>
<li>We would have to test 4 different variables to see which ones are set.</li>
<p>This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
"<tt>OptLevel</tt>" enum type. This variable can be assigned any of the values
that are listed in the declaration (Note that the declaration list must be
-terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
+terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine
library enforces
that the user can only specify one of the options, and it ensure that only valid
enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the
-O1 - Enable trivial optimizations
-O2 - Enable default optimizations
-O3 - Enable expensive optimizations</b>
- -f - Overwrite output files
+ -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
=none - disable debug information
=quick - enable quick debug information
=detailed - enable detailed debug information</b>
- -f - Overwrite output files
+ -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
<div class="doc_text">
-<p>Now that we have the standard run of the mill argument types out of the way,
+<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
a <b>list</b> of optimizations to perform, allowing duplicates. For example, we
might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="bits">Collecting options as a set of flags</a>
+</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
+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
+specified value is parsed, the resulting enum's bit is set in the option's bit
+vector:</p>
+
+<div class="doc_code"><pre>
+ <i>bits</i> |= 1 << (unsigned)<i>enum</i>;
+</pre></div>
+
+<p>Options that are specified multiple times are redundant. Any instances after
+the first are discarded.</p>
+
+<p>Reworking the above list example, we could replace <a href="#list">
+<tt>cl::list</tt></a> with <a href="#bits"><tt>cl::bits</tt></a>:</p>
+
+<div class="doc_code"><pre>
+<a href="#cl::bits">cl::bits</a><Opts> OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
+ <a href="#cl::values">cl::values</a>(
+ clEnumVal(dce , "<i>Dead Code Elimination</i>"),
+ clEnumVal(constprop , "<i>Constant Propagation</i>"),
+ clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
+ clEnumVal(strip , "<i>Strip Symbols</i>"),
+ clEnumValEnd));
+</pre></div>
+
+<p>To test to see if <tt>constprop</tt> was specified, we can use the
+<tt>cl:bits::isSet</tt> function:</p>
+
+<div class="doc_code"><pre>
+ if (OptimizationBits.isSet(constprop)) {
+ ...
+ }
+</pre></div>
+
+<p>It's also possible to get the raw bit vector using the
+<tt>cl::bits::getBits</tt> function:</p>
+
+<div class="doc_code"><pre>
+ unsigned bits = OptimizationBits.getBits();
+</pre></div>
+
+<p>Finally, if external storage is used, then the location specified must be of
+<b>type</b> <tt>unsigned</tt>. In all other ways a <a
+href="#bits"><tt>cl::bits</tt></a> option is equivalent to a <a
+href="#list"> <tt>cl::list</tt></a> option.</p>
+
+</div>
+
+
<!-- ======================================================================= -->
<div class="doc_subsection">
<a name="description">Adding freeform text to help output</a>
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
- 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
+ <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
a dash.</p>
<p>So, generally, the problem is that you have two <tt>cl::list</tt> variables
that interact in some way. To ensure the correct interaction, you can use the
absolute position (as found on the command line) of the <tt>optnum</tt>
item in the <tt>cl::list</tt>.</p>
<p>The idiom for usage is like this:</p>
-
+
<div class="doc_code"><pre>
static cl::list<std::string> Files(cl::Positional, cl::OneOrMore);
- static cl::listlt;std::string> Libraries("l", cl::ZeroOrMore);
+ static cl::list<std::string> Libraries("l", cl::ZeroOrMore);
int main(int argc, char**argv) {
// ...
<p>Note that, for compatibility reasons, the <tt>cl::opt</tt> also supports an
<tt>unsigned getPosition()</tt> option that will provide the absolute position
- of that option. You can apply the same approach as above with a
+ of that option. You can apply the same approach as above with a
<tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
</div>
standard Unix Bourne shell (<tt>/bin/sh</tt>). To run <tt>/bin/sh</tt>, first
you specify options to the shell itself (like <tt>-x</tt> which turns on trace
output), then you specify the name of the script to run, then you specify
-arguments to the script. These arguments to the script are parsed by the bourne
+arguments to the script. These arguments to the script are parsed by the Bourne
shell command line option processor, but are not interpreted as options to the
shell itself. Using the CommandLine library, we would specify this as:</p>
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>
<i>// DEBUG macro - This macro should be used by code to emit debug information.
// In the '-debug' option is specified on the command line, and if this is a
// debug build, then the code specified as the option to the macro will be
-// executed. Otherwise it will not be. Example:
-//
-// DEBUG(std::cerr << "Bitset contains: " << Bitset << "\n");
-//</i>
+// executed. Otherwise it will not be.</i>
<span class="doc_hilite">#ifdef NDEBUG
#define DEBUG(X)
#else
<p>This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
<tt>DebugFlag</tt> explicitly if they want to. Now we just need to be able to
set the <tt>DebugFlag</tt> boolean when the option is set. To do this, we pass
-an additial argument to our command line argument processor, and we specify
+an additional argument to our command line argument processor, and we specify
where to fill in with the <a href="#cl::location">cl::location</a>
attribute:</p>
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
<li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies
the string-to-value mapping to be used by the generic parser. It takes a
-<b>clEnumValEnd terminated</b> list of (option, value, description) triplets
+<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
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>
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="#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>
<li><a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b></a> modifier
(which is the default for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
-href="#cl::list">cl::list</a></tt> options), indicates the option is to appear
+href="#cl::list">cl::list</a></tt> options) indicates the option is to appear
in both help listings.</li>
<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
+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>
-<li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier,
+<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>
</ul>
indicates that the option must be specified at least one time.</li>
<li>The <b><tt>cl::ConsumeAfter</tt></b> modifier is described in the <a
-href="#positional">Positional arguments section</a></li>
+href="#positional">Positional arguments section</a>.</li>
</ul>
<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
-arguments. As usual, you can only specify at most one of these arguments.</p>
+arguments. As usual, you can only specify one of these arguments at most.</p>
<ul>
"normal".</li>
<li><a name="cl::Positional">The <b><tt>cl::Positional</tt></b></a> modifier
-specifies that this is a positional argument, that does not have a command line
+specifies that this is a positional argument that does not have a command line
option associated with it. See the <a href="#positional">Positional
Arguments</a> section for more information.</li>
not separate the value from the option name specified. Instead, the value is
everything after the prefix, including any equal sign if present. This is useful
for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
-linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
+linker tool or <tt>-DNAME=value</tt> in a compiler tool. Here, the
'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
-options, that have the <a href="#cl::Prefix">cl::Prefix</a> modifier added to
-allow the CommandLine library to recognize them. Note that
-<a href="#cl::Prefix">cl::Prefix</a> options must not have the <a
-href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier specified.</li>
+options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
+modifier added to allow the CommandLine library to recognize them. Note that
+<b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
+<b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
+specified.</li>
<li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
-to implement unix style tools (like <tt>ls</tt>) that have lots of single letter
+to implement Unix-style tools (like <tt>ls</tt>) that have lots of single letter
arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>'
command actually enables four different options, all of which are single
-letters. Note that <a href="#cl::Grouping">cl::Grouping</a> options cannot have
-values.</li>
+letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
+options cannot have values.</li>
</ul>
-<p>The CommandLine library does not restrict how you use the <a
-href="#cl::Prefix">cl::Prefix</a> or <a href="#cl::Grouping">cl::Grouping</a>
-modifiers, but it is possible to specify ambiguous argument settings. Thus, it
-is possible to have multiple letter options that are prefix or grouping options,
-and they will still work as designed.</p>
+<p>The CommandLine library does not restrict how you use the <b><tt><a
+href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
+href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
+specify ambiguous argument settings. Thus, it is possible to have multiple
+letter options that are prefix or grouping options, and they will still work as
+designed.</p>
<p>To do this, the CommandLine library uses a greedy algorithm to parse the
input option into (potentially multiple) prefix and grouping options. The
positional arguments, and only makes sense for lists) indicates that positional
argument should consume any strings after it (including strings that start with
a "-") up until another recognized positional argument. For example, if you
-have two "eating" positional arguments "<tt>pos1</tt>" and "<tt>pos2</tt>" the
+have two "eating" positional arguments, "<tt>pos1</tt>" and "<tt>pos2</tt>", the
string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
-baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
"<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</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
+<tt>cl::Sink</tt> modifier specified, the parser passes
+unrecognized option strings to it as values instead of signaling an
+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 two miscellaneous option modifiers.</p>
+<p>So far, these are the only three miscellaneous option modifiers.</p>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="response">Response files</a>
+</div>
+
+<div class="doc_text">
+
+<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 class="doc_subsection">
<a name="toplevel">Top-Level Classes and Functions</a>
<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>
href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
except that it is designed to take values for options from an environment
variable, for those cases in which reading the command line is not convenient or
-not desired. It fills in the values of all the command line option variables
+desired. It fills in the values of all the command line option variables just
+like <a
href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
does.</p>
-<p>It takes three parameters: first, the name of the program (since
-<tt>argv</tt> may not be available, it can't just look in <tt>argv[0]</tt>),
-second, the name of the environment variable to examine, and third, the optional
+<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, 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">
+ <a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
+ function</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
+directly from <tt>main</tt> and <i>before</i>
+<tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
+for a function to be called in response to the <tt>--version</tt> option instead
+of having the <tt>CommandLine</tt> library print out the usual version string
+for LLVM. This is useful for programs that are not part of LLVM but wish to use
+the <tt>CommandLine</tt> facilities. Such programs should just define a small
+function that takes no arguments and returns <tt>void</tt> and that prints out
+whatever version information is appropriate for the program. Pass the address
+of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
+called when the <tt>--version</tt> option is given by the user.</p>
+
+</div>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="cl::opt">The <tt>cl::opt</tt> class</a>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+ <a name="cl::bits">The <tt>cl::bits</tt> class</a>
+</div>
+
+<div class="doc_text">
+
+<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
+can take up to three arguments:</p>
+
+<div class="doc_code"><pre>
+<b>namespace</b> cl {
+ <b>template</b> <<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
+ <b>class</b> ParserClass = parser<DataType> >
+ <b>class</b> bits;
+}
+</pre></div>
+
+<p>This class works the exact same as the <a
+href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
+must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
+
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
<a name="cl::alias">The <tt>cl::alias</tt> class</a>
}
</pre></div>
-<p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
+<p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
parameter to the constructor. The text passed to the constructor will be printed
at the bottom of the help message, verbatim. Note that multiple
<tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
"<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".</li>
+<li><a name="boolOrDefaultparser">The <b><tt>parser<boolOrDefault></tt>
+ specialization</b></a> is used for cases where the value is boolean,
+but we also need to know whether the option was specified at all. boolOrDefault
+is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts
+the same strings as <b><tt>parser<bool></tt></b>.</li>
+
<li><a name="stringparser">The <b><tt>parser<string></tt>
specialization</b></a> simply stores the parsed string into the string value
specified. No conversion or modification of the data is performed.</li>
<p>This approach has the advantage that users of your custom data type will
automatically use your custom parser whenever they define an option with a value
type of your data type. The disadvantage of this approach is that it doesn't
-work if your fundemental data type is something that is already supported.</p>
+work if your fundamental data type is something that is already supported.</p>
</li>
<p>This approach works well in situations where you would line to parse an
option using special syntax for a not-very-special data-type. The drawback of
this approach is that users of your parser have to be aware that they are using
-your parser, instead of the builtin ones.</p>
+your parser instead of the builtin ones.</p>
</li>
</pre></div>
<p>Our new class inherits from the <tt>cl::basic_parser</tt> template class to
-fill in the default, boiler plate, code for us. We give it the data type that
-we parse into (the last argument to the <tt>parse</tt> method so that clients of
-our custom parser know what object type to pass in to the parse method (here we
-declare that we parse into '<tt>unsigned</tt>' variables.</p>
+fill in the default, boiler plate code for us. We give it the data type that
+we parse into, the last argument to the <tt>parse</tt> method, so that clients of
+our custom parser know what object type to pass in to the parse method. (Here we
+declare that we parse into '<tt>unsigned</tt>' variables.)</p>
<p>For most purposes, the only method that must be implemented in a custom
parser is the <tt>parse</tt> method. The <tt>parse</tt> method is called
whenever the option is invoked, passing in the option itself, the option name,
the string to parse, and a reference to a return value. If the string to parse
-is not well formed, the parser should output an error message and return true.
+is not well-formed, the parser should output an error message and return true.
Otherwise it should return false and set '<tt>Val</tt>' to the parsed value. In
our example, we implement <tt>parse</tt> as:</p>
<b>const</b> std::string &Arg, <b>unsigned</b> &Val) {
<b>const char</b> *ArgStart = Arg.c_str();
<b>char</b> *End;
-
+
<i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
Val = (unsigned)strtol(ArgStart, &End, 0);
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!");
}
}
}
<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.cs.uiuc.edu">LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff