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>
<p>To start out, you need to include the CommandLine header file into your
program:</p>
-<pre>
- #include "Support/CommandLine.h"
-</pre>
+<div class="doc_code"><pre>
+ #include "llvm/Support/CommandLine.h"
+</pre></div>
<p>Additionally, you need to add this as the first line of your main
program:</p>
-<pre>
+<div class="doc_code"><pre>
int main(int argc, char **argv) {
<a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv);
...
}
-</pre>
+</pre></div>
<p>... which actually parses the arguments and fills in the variable
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>
<a name="value_desc_example"></a>
-<pre>
+<div class="doc_code"><pre>
<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>
+</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
to output for the "<tt>--help</tt>" option. In this case, we get a line that
looks like this:</p>
-<pre>
+<div class="doc_code"><pre>
USAGE: compiler [options]
OPTIONS:
-help - display available options (--help-hidden for more)
<b>-o <filename> - Specify output filename</b>
-</pre>
+</pre></div>
<p>Because we specified that the command line option should parse using the
<tt>string</tt> data type, the variable declared is automatically usable as a
real string in all contexts that a normal C++ string object may be used. For
example:</p>
-<pre>
+<div class="doc_code"><pre>
...
- ofstream Output(OutputFilename.c_str());
- if (Out.good()) ...
+ std::ofstream Output(OutputFilename.c_str());
+ if (Output.good()) ...
...
-</pre>
+</pre></div>
<p>There are many different options that you can use to customize the command
line option handling library, but the above example shows the general interface
These positional arguments are filled with command line parameters that are not
in option form. We use this feature like this:</p>
-<pre>
+<div class="doc_code"><pre>
<a href="#cl::opt">cl::opt</a><string> InputFilename(<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>
+</pre></div>
<p>This declaration indicates that the first positional argument should be
treated as the input filename. Here we use the <tt><a
href="#cl::Required">cl::Required</a></tt> flag, and we could eliminate the
<tt><a href="#cl::init">cl::init</a></tt> modifier, like this:</p>
-<pre>
+<div class="doc_code"><pre>
<a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <b><a href="#cl::Required">cl::Required</a></b>);
-</pre>
+</pre></div>
<p>Again, the CommandLine library does not require the options to be specified
in any particular order, so the above declaration is equivalent to:</p>
-<pre>
+<div class="doc_code"><pre>
<a href="#cl::opt">cl::opt</a><string> InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::Required">cl::Required</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"));
-</pre>
+</pre></div>
<p>By simply adding the <tt><a href="#cl::Required">cl::Required</a></tt> flag,
the CommandLine library will automatically issue an error if the argument is not
adding one of the declarations above, the <tt>--help</tt> option synopsis is now
extended to:</p>
-<pre>
+<div class="doc_code"><pre>
USAGE: compiler [options] <b><input file></b>
OPTIONS:
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
-</pre>
+</pre></div>
<p>... indicating that an input filename is expected.</p>
<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>
-<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>"));
+<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>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>
+</pre></div>
<p>This does what you would expect: it declares three boolean variables
("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
"<tt>true</tt>" or "<tt>false</tt>" to be specified, allowing any of the
following inputs:</p>
-<pre>
+<div class="doc_code"><pre>
compiler -f # No value, 'Force' == true
compiler -f=true # Value specified, 'Force' == true
compiler -f=TRUE # Value specified, 'Force' == true
compiler -f=FALSE # Value specified, 'Force' == false
-</pre>
+</pre></div>
<p>... you get the idea. The <a href="#boolparser">bool parser</a> just turns
the string values into boolean values, and rejects things like '<tt>compiler
<p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
-<pre>
+<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)
-</pre>
+</pre></div>
-<p>and "<tt>opt --help-hidden</tt>" prints this:</p>
+<p>and "<tt>compiler --help-hidden</tt>" prints this:</p>
-<pre>
+<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)
-</pre>
+</pre></div>
<p>This brief example has shown you how to use the '<tt><a
href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line
<p>So far, the example works well, except for the fact that we need to check the
quiet condition like this now:</p>
-<pre>
+<div class="doc_code"><pre>
...
if (!Quiet && !Quiet2) printInformationalMessage(...);
...
-</pre>
+</pre></div>
<p>... which is a real pain! Instead of defining two values for the same
condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
a value itself:</p>
-<pre>
+<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> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
<a href="#cl::alias">cl::alias</a> QuietA("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Alias for -quiet</i>"), <a href="#cl::aliasopt">cl::aliasopt</a>(Quiet));
-</pre>
+</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
<p>Now the application code can simply use:</p>
-<pre>
+<div class="doc_code"><pre>
...
if (!Quiet) printInformationalMessage(...);
...
-</pre>
+</pre></div>
<p>... which is much nicer! The "<tt><a href="#cl::alias">cl::alias</a></tt>"
can be used to specify an alternative name for any variable type, and has many
<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>
CommandLine library fill it in with the appropriate level directly, which is
used like this:</p>
-<pre>
+<div class="doc_code"><pre>
enum OptLevel {
g, O1, O2, O3
};
...
if (OptimizationLevel >= O2) doPartialRedundancyElimination(...);
...
-</pre>
+</pre></div>
<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
command line arguments matched the enum values. With this option added, our
help output now is:</p>
-<pre>
+<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
-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
-</pre>
+</pre></div>
<p>In this case, it is sort of awkward that flag names correspond directly to
enum names, because we probably don't want a enum definition named "<tt>g</tt>"
in our program. Because of this, we can alternatively write this example like
this:</p>
-<pre>
+<div class="doc_code"><pre>
enum OptLevel {
Debug, O1, O2, O3
};
...
if (OptimizationLevel == Debug) outputDebugInfo(...);
...
-</pre>
+</pre></div>
<p>By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we
can directly specify the name that the flag should get. In general a direct
our optimization level flags, but we also specify an option name. For this
case, the code looks like this:</p>
-<pre>
+<div class="doc_code"><pre>
enum DebugLev {
nodebuginfo, quick, detailed
};
clEnumVal(quick, "<i>enable quick debug information</i>"),
clEnumVal(detailed, "<i>enable detailed debug information</i>"),
clEnumValEnd));
-</pre>
+</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>
-<pre>
+<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
=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
-</pre>
+</pre></div>
<p>Again, the only structural difference between the debug level declaration and
-the optimiation level declaration is that the debug level declaration includes
+the optimization level declaration is that the debug level declaration includes
an option name (<tt>"debug_level"</tt>), which automatically changes how the
library processes the argument. The CommandLine library supports both forms so
that you can choose the form most appropriate for your application.</p>
<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
template is for. First, start by defining an enum of the optimizations that you
would like to perform:</p>
-<pre>
+<div class="doc_code"><pre>
enum Opts {
// 'inline' is a C++ keyword, so name it 'inlining'
dce, constprop, inlining, strip
};
-</pre>
+</pre></div>
<p>Then define your "<tt><a href="#cl::list">cl::list</a></tt>" variable:</p>
-<pre>
+<div class="doc_code"><pre>
<a href="#cl::list">cl::list</a><Opts> OptimizationList(<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>"),
clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
clEnumVal(strip , "<i>Strip Symbols</i>"),
clEnumValEnd));
-</pre>
+</pre></div>
<p>This defines a variable that is conceptually of the type
"<tt>std::vector<enum Opts></tt>". Thus, you can access it with standard
vector methods:</p>
-<pre>
+<div class="doc_code"><pre>
for (unsigned i = 0; i != OptimizationList.size(); ++i)
switch (OptimizationList[i])
...
-</pre>
+</pre></div>
<p>... to iterate through the list of options specified.</p>
linker, for example, the linker takes several '<tt>.o</tt>' files, and needs to
capture them into a list. This is naturally specified as:</p>
-<pre>
+<div class="doc_code"><pre>
...
<a href="#cl::list">cl::list</a><std::string> InputFilenames(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<Input files>"), <a href="#cl::OneOrMore">cl::OneOrMore</a>);
...
-</pre>
+</pre></div>
<p>This variable works just like a "<tt>vector<string></tt>" object. As
such, accessing the list is simple, just like above. In this example, we used
</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>
information for your program, allowing you to include any additional information
that you want. For example:</p>
-<pre>
+<div class="doc_code"><pre>
int main(int argc, char **argv) {
<a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv, " CommandLine compiler example\n\n"
" This program blah blah blah...\n");
...
}
-</pre>
+</pre></div>
-<p>Would yield the help output:</p>
+<p>would yield the help output:</p>
-<pre>
+<div class="doc_code"><pre>
<b>OVERVIEW: CommandLine compiler example
This program blah blah blah...</b>
...
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
-</pre>
+</pre></div>
</div>
through (which defaults to standard input if a filename is not specified).
Using the CommandLine library, this would be specified as:</p>
-<pre>
+<div class="doc_code"><pre>
<a href="#cl::opt">cl::opt</a><string> Regex (<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><regular expression></i>"), <a href="#cl::Required">cl::Required</a>);
<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>
+</pre></div>
<p>Given these two option declarations, the <tt>--help</tt> output for our grep
replacement would look like this:</p>
-<pre>
+<div class="doc_code"><pre>
USAGE: spiffygrep [options] <b><regular expression> <input file></b>
OPTIONS:
-help - display available options (--help-hidden for more)
-</pre>
+</pre></div>
<p>... and the resultant program could be used just like the standard
<tt>grep</tt> tool.</p>
named '<tt>-foo</tt>', and will fail (and single quotes will not save you).
Note that the system <tt>grep</tt> has the same problem:</p>
-<pre>
+<div class="doc_code"><pre>
$ spiffygrep '-foo' test.txt
Unknown command line argument '-foo'. Try: spiffygrep --help'
grep: illegal option -- o
grep: illegal option -- o
Usage: grep -hblcnsviw pattern file . . .
-</pre>
+</pre></div>
<p>The solution for this problem is the same for both your tool and the system
version: use the '<tt>--</tt>' marker. When the user specifies '<tt>--</tt>' on
'<tt>--</tt>' should be treated as positional arguments, not options. Thus, we
can use it like this:</p>
-<pre>
+<div class="doc_code"><pre>
$ spiffygrep -- -foo test.txt
...output...
-</pre>
+</pre></div>
</div>
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
<tt>cl::list::getPosition(optnum)</tt> method. This method returns 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:<pre><tt>
+ <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) {
// ...
else
break; // we're done with the list
}
- }
- </tt></pre></p>
+ }</pre></div>
+
<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>
-<pre>
+<div class="doc_code"><pre>
<a href="#cl::opt">cl::opt</a><string> Script(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input script></i>"), <a href="#cl::init">cl::init</a>("-"));
<a href="#cl::list">cl::list</a><string> Argv(<a href="#cl::ConsumeAfter">cl::ConsumeAfter</a>, <a href="#cl::desc">cl::desc</a>("<i><program arguments>...</i>"));
<a href="#cl::opt">cl::opt</a><bool> Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
-</pre>
+</pre></div>
<p>which automatically provides the help output:</p>
-<pre>
+<div class="doc_code"><pre>
USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
OPTIONS:
-help - display available options (--help-hidden for more)
<b>-x - Enable trace output</b>
-</pre>
+</pre></div>
-<p>At runtime, if we run our new shell replacement as '<tt>spiffysh -x test.sh
+<p>At runtime, if we run our new shell replacement as `<tt>spiffysh -x test.sh
-a -x -y bar</tt>', the <tt>Trace</tt> variable will be set to true, the
<tt>Script</tt> variable will be set to "<tt>test.sh</tt>", and the
<tt>Argv</tt> list will contain <tt>["-a", "-x", "-y", "bar"]</tt>, because they
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>
<p>To do this, set up your .h file with your option, like this for example:</p>
+<div class="doc_code">
<pre>
<i>// DebugFlag.h - Get access to the '-debug' command line option
//
<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(cerr << "Bitset contains: " << Bitset << "\n");
-//</i>
-<span class="doc_red">#ifdef NDEBUG
+// executed. Otherwise it will not be.</i>
+<span class="doc_hilite">#ifdef NDEBUG
#define DEBUG(X)
#else
-#define DEBUG(X)</span> \
- do { if (DebugFlag) { X; } } while (0)
-<span class="doc_red">#endif</span>
+#define DEBUG(X)</span> do { if (DebugFlag) { X; } } while (0)
+<span class="doc_hilite">#endif</span>
</pre>
+</div>
<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>
+<div class="doc_code">
<pre>
-bool DebugFlag; <i>// the actual value</i>
+bool DebugFlag; <i>// the actual value</i>
static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i>
-Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>"), <a href="#cl::Hidden">cl::Hidden</a>,
- <a href="#cl::location">cl::location</a>(DebugFlag));
+Debug("<i>debug</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable debug output</i>"), <a href="#cl::Hidden">cl::Hidden</a>, <a href="#cl::location">cl::location</a>(DebugFlag));
</pre>
+</div>
<p>In the above example, we specify "<tt>true</tt>" as the second argument to
-the <a href="#cl::opt">cl::opt</a> template, indicating that the template should
-not maintain a copy of the value itself. In addition to this, we specify the <a
-href="#cl::location">cl::location</a> attribute, so that <tt>DebugFlag</tt> is
-automatically set.</p>
+the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the
+template should not maintain a copy of the value itself. In addition to this,
+we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so
+that <tt>DebugFlag</tt> is automatically set.</p>
</div>
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
-specifies which option a <a href="#cl::alias">cl::alias</a> option is an alias
-for.</li>
+specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is
+an alias for.</li>
<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>
specifies that this option is used to capture "interpreter style" arguments. See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
<li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
-that this option prefixes its value. With 'Prefix' options, there is no equal
-sign that separates the value from the option name specified. This is useful
-for processing odd arguments like '<tt>-lmalloc -L/usr/lib'</tt> in a linker
-tool. Here, the '<tt>l</tt>' and '<tt>L</tt>' options are normal string (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>
+that this option prefixes its value. With 'Prefix' options, the equal sign does
+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
+'<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
+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
strategy basically looks like this:</p>
-<p><tt>parse(string OrigInput) {</tt>
+<div class="doc_code"><tt>parse(string OrigInput) {</tt>
<ol>
<li><tt>string input = OrigInput;</tt>
while (!isOption(input) && !input.empty()) input.pop_back();<br>
}</tt>
<li><tt>if (!OrigInput.empty()) error();</tt></li>
-
</ol>
<p><tt>}</tt></p>
+</div>
</div>
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>
can take up to three arguments (all except for the first have default values
though):</p>
-<pre>
+<div class="doc_code"><pre>
<b>namespace</b> cl {
<b>template</b> <<b>class</b> DataType, <b>bool</b> ExternalStorage = <b>false</b>,
<b>class</b> ParserClass = parser<DataType> >
<b>class</b> opt;
}
-</pre>
+</pre></div>
<p>The first template argument specifies what underlying data type the command
line argument is, and is used to select a default parser implementation. The
line options. It too is a templated class which can take up to three
arguments:</p>
-<pre>
+<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> list;
}
-</pre>
+</pre></div>
<p>This class works the exact same as the <a
href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is
</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>
<p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
aliases for other arguments.</p>
-<pre>
+<div class="doc_code"><pre>
<b>namespace</b> cl {
<b>class</b> alias;
}
-</pre>
+</pre></div>
<p>The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be
used to specify which option this is an alias for. Alias arguments default to
<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>
-<pre>
+<div class="doc_code"><pre>
<b>namespace</b> cl {
<b>struct</b> extrahelp;
}
-</pre>
+</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
+<tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
your tool needs to print additional help information, put all that help into a
single <tt>cl::extrahelp</tt> instance.</p>
<p>For example:</p>
-<pre>
+<div class="doc_code"><pre>
cl::extrahelp("\nADDITIONAL HELP:\n\n This is the extra help\n");
-</pre>
+</pre></div>
</div>
<!-- ======================================================================= -->
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>
<p>To start out, we declare our new <tt>FileSizeParser</tt> class:</p>
-<pre>
+<div class="doc_code"><pre>
<b>struct</b> FileSizeParser : <b>public</b> cl::basic_parser<<b>unsigned</b>> {
<i>// parse - Return true on error.</i>
<b>bool</b> parse(cl::Option &O, <b>const char</b> *ArgName, <b>const</b> std::string &ArgValue,
<b>unsigned</b> &Val);
};
-</pre>
+</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>
-<pre>
+<div class="doc_code"><pre>
<b>bool</b> FileSizeParser::parse(cl::Option &O, <b>const char</b> *ArgName,
<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!");
}
}
}
-</pre>
+</pre></div>
<p>This function implements a very simple parser for the kinds of strings we are
interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for
true) in order to get a nice error message (shown below). Now that we have our
parser class, we can use it like this:</p>
-<pre>
+<div class="doc_code"><pre>
<b>static</b> <a href="#cl::opt">cl::opt</a><<b>unsigned</b>, <b>false</b>, FileSizeParser>
MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
<a href="#cl::value_desc">cl::value_desc</a>("<i>size</i>"));
-</pre>
+</pre></div>
<p>Which adds this to the output of our program:</p>
-<pre>
+<div class="doc_code"><pre>
OPTIONS:
-help - display available options (--help-hidden for more)
...
<b>-max-file-size=<size> - Maximum file size to accept</b>
-</pre>
+</pre></div>
<p>And we can test that our parse works correctly now (the test program just
prints out the max-file-size argument value):</p>
-<pre>
+<div class="doc_code"><pre>
$ ./test
MFS: 0
$ ./test -max-file-size=123MB
MFS: 3221225472
$ ./test -max-file-size=dog
-max-file-size option: 'dog' value invalid for file size argument!
-</pre>
+</pre></div>
<p>It looks like it works. The error message that we get is nice and helpful,
and we seem to accept reasonable file sizes. This wraps up the "custom parser"
<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