<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 cl::SetVersionPrinter
+ <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>
<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>
<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>
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>
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>
<div class="doc_text">
<p>In addition to input and output filenames, we would like the compiler example
-to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
-file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
-compatibility with some of our users. We can support these by declaring options
-of boolean type like this:</p>
+to support three boolean flags: "<tt>-f</tt>" to force writing binary output to
+a terminal, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for
+backwards compatibility with some of our users. We can support these by
+declaring options of boolean type like this:</p>
<div class="doc_code"><pre>
-<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
+<a href="#cl::opt">cl::opt</a><bool> Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable binary output on terminals</i>"));
<a href="#cl::opt">cl::opt</a><bool> Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
<a href="#cl::opt">cl::opt</a><bool> Quiet2("<i>q</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"), <a href="#cl::Hidden">cl::Hidden</a>);
</pre></div>
("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
options. Note that the "<tt>-q</tt>" option is specified with the "<a
href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it
-from being shown by the standard "<tt>--help</tt>" output (note that it is still
-shown in the "<tt>--help-hidden</tt>" output).</p>
+from being shown by the standard "<tt>-help</tt>" output (note that it is still
+shown in the "<tt>-help-hidden</tt>" output).</p>
<p>The CommandLine library uses a <a href="#builtinparsers">different parser</a>
for different data types. For example, in the string case, the argument passed
like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
library calls to parse the string value into the specified data type.</p>
-<p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
+<p>With the declarations above, "<tt>compiler -help</tt>" emits this:</p>
<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
- <b>-f - Overwrite output files</b>
+ <b>-f - Enable binary output on terminals</b>
-o - Override output filename
<b>-quiet - Don't print informational messages</b>
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
</pre></div>
-<p>and "<tt>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
- -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
</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
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 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
- -help - display available options (--help-hidden for more)
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
-quiet - Don't print informational messages
</pre></div>
<p>This definition defines an enumerated command line variable of type "<tt>enum
DebugLev</tt>", which works exactly the same way as before. The difference here
is just the interface exposed to the user of your program and the help output by
-the "<tt>--help</tt>" option:</p>
+the "<tt>-help</tt>" option:</p>
<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
=none - disable debug information
=quick - enable quick debug information
=detailed - enable detailed debug information</b>
- -f - Overwrite output files
- -help - display available options (--help-hidden for more)
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
-quiet - Don't print informational messages
</pre></div>
<div class="doc_text">
-<p>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 class="doc_text">
<p>Instead of collecting sets of options in a list, it is also possible to
-gather information for enum values in a <b>bit vector</b>. The represention used by
+gather information for enum values in a <b>bit vector</b>. The representation used by
the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
integer. An enum value is represented by a 0/1 in the enum's ordinal value bit
position. 1 indicating that the enum was specified, 0 otherwise. As each
<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
morally equivalent to 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>
OPTIONS:
...
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
-o <filename> - Specify output filename
</pre></div>
<a href="#cl::opt">cl::opt</a><string> Filename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i><input file></i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
</pre></div>
-<p>Given these two option declarations, the <tt>--help</tt> output for our grep
+<p>Given these two option declarations, the <tt>-help</tt> output for our grep
replacement would look like this:</p>
<div class="doc_code"><pre>
USAGE: spiffygrep [options] <b><regular expression> <input file></b>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
</pre></div>
<p>... and the resultant program could be used just like the standard
<div class="doc_code"><pre>
$ spiffygrep '-foo' test.txt
- Unknown command line argument '-foo'. Try: spiffygrep --help'
+ Unknown command line argument '-foo'. Try: spiffygrep -help'
$ grep '-foo' test.txt
grep: illegal option -- f
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>
USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
<b>-x - Enable trace output</b>
</pre></div>
code from the storage of the value parsed. For example, lets say that we have a
'<tt>-debug</tt>' option that we would like to use to enable debug information
across the entire body of our program. In this case, the boolean value
-controlling the debug code should be globally accessable (in a header file, for
+controlling the debug code should be globally accessible (in a header file, for
example) yet the command line option processing code should not be exposed to
all of these clients (requiring lots of .cpp files to #include
<tt>CommandLine.h</tt>).</p>
<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:
-//
-// DOUT << "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>
</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
<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
+<tt>-help</tt> for the tool. Because the generic parser is used most
frequently with enum values, two macros are often useful:
<ol>
You will get a compile time error if you try to use cl::values with a parser
that does not support it.</li>
+<li><a name="cl::multi_val">The <b><tt>cl::multi_val</tt></b></a>
+attribute specifies that this option takes has multiple values
+(example: <tt>-sectalign segname sectname sectvalue</tt>). This
+attribute takes one unsigned argument - the number of values for the
+option. This attribute is valid only on <tt>cl::list</tt> options (and
+will fail with compile error if you try to use it with other option
+types). It is allowed to use all of the usual modifiers on
+multi-valued options (besides <tt>cl::ValueDisallowed</tt>,
+obviously).</li>
+
</ul>
</div>
<p>Option modifiers are the flags and expressions that you pass into the
constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to
-tweak how options are parsed and how <tt>--help</tt> output is generated to fit
+tweak how options are parsed and how <tt>-help</tt> output is generated to fit
your application well.</p>
-<p>These options fall into five main catagories:</p>
+<p>These options fall into five main categories:</p>
<ol>
-<li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
+<li><a href="#hiding">Hiding an option from <tt>-help</tt> output</a></li>
<li><a href="#numoccurrences">Controlling the number of occurrences
required and allowed</a></li>
<li><a href="#valrequired">Controlling whether or not a value must be
<li><a href="#misc">Miscellaneous option modifiers</a></li>
</ol>
-<p>It is not possible to specify two options from the same catagory (you'll get
+<p>It is not possible to specify two options from the same category (you'll get
a runtime error) to a single option, except for options in the miscellaneous
-catagory. The CommandLine library specifies defaults for all of these settings
+category. The CommandLine library specifies defaults for all of these settings
that are the most useful in practice and the most common, which mean that you
usually shouldn't have to worry about these.</p>
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection">
- <a name="hiding">Hiding an option from <tt>--help</tt> output</a>
+ <a name="hiding">Hiding an option from <tt>-help</tt> output</a>
</div>
<div class="doc_text">
<p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
<tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
-appears in the <tt>--help</tt> and <tt>--help-hidden</tt> output for the
+appears in the <tt>-help</tt> and <tt>-help-hidden</tt> output for the
compiled program:</p>
<ul>
<li><a name="cl::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
-the option should not appear in the <tt>--help</tt> output, but should appear in
-the <tt>--help-hidden</tt> output.</li>
+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>
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 <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
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 class="doc_text">
<p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
-directly from <tt>main</tt>, and <i>before</i>
+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
<div class="doc_text">
<p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
-help text to be printed out for the <tt>--help</tt> option.</p>
+help text to be printed out for the <tt>-help</tt> option.</p>
<div class="doc_code"><pre>
<b>namespace</b> cl {
}
</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
<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!");
}
}
}
<div class="doc_code"><pre>
OPTIONS:
- -help - display available options (--help-hidden for more)
+ -help - display available options (-help-hidden for more)
...
<b>-max-file-size=<size> - Maximum file size to accept</b>
</pre></div>
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
- src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
<a href="http://validator.w3.org/check/referer"><img
- src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+ src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
projects / oota-llvm.git / blobdiff