Sprinkle code examples and command-line interaction examples with some style
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@20557 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/CommandLine.html b/docs/CommandLine.html
index da28beb..b708d9a 100644
--- a/docs/CommandLine.html
+++ b/docs/CommandLine.html
@@ -192,19 +192,19 @@
<p>To start out, you need to include the CommandLine header file into your
program:</p>
-<pre>
+<div class="doc_code"><pre>
#include "Support/CommandLine.h"
-</pre>
+</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>
@@ -220,9 +220,9 @@
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
@@ -235,25 +235,25 @@
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()) ...
...
-</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
@@ -270,9 +270,9 @@
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
@@ -285,16 +285,16 @@
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
@@ -304,13 +304,13 @@
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>
@@ -329,11 +329,11 @@
compatibility with some of our users. We can support these by declaring options
of boolean type like this:</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::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
@@ -351,12 +351,12 @@
"<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
@@ -367,7 +367,7 @@
<p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
-<pre>
+<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
@@ -375,11 +375,11 @@
-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>
-<pre>
+<div class="doc_code"><pre>
USAGE: compiler [options] <input file>
OPTIONS:
@@ -388,7 +388,7 @@
<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
@@ -408,22 +408,22 @@
<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
@@ -436,11 +436,11 @@
<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
@@ -486,7 +486,7 @@
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
};
@@ -502,7 +502,7 @@
...
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
@@ -514,7 +514,7 @@
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:
@@ -527,14 +527,14 @@
-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
};
@@ -550,7 +550,7 @@
...
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
@@ -575,7 +575,7 @@
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
};
@@ -587,14 +587,14 @@
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:
@@ -611,7 +611,7 @@
-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 optimization level declaration is that the debug level declaration includes
@@ -637,16 +637,16 @@
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>"),
@@ -654,17 +654,17 @@
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>
@@ -676,11 +676,11 @@
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
@@ -709,17 +709,17 @@
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>
@@ -730,7 +730,7 @@
...
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
-</pre>
+</pre></div>
</div>
@@ -764,20 +764,20 @@
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>
@@ -804,7 +804,7 @@
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'
@@ -813,7 +813,7 @@
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
@@ -821,10 +821,10 @@
'<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>
@@ -847,7 +847,9 @@
<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);
@@ -877,8 +879,8 @@
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
@@ -906,23 +908,23 @@
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
@@ -1308,7 +1310,7 @@
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>
@@ -1324,10 +1326,10 @@
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>
@@ -1452,13 +1454,13 @@
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
@@ -1486,13 +1488,13 @@
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
@@ -1512,11 +1514,11 @@
<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
@@ -1535,22 +1537,22 @@
<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>
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>
<!-- ======================================================================= -->
@@ -1677,13 +1679,13 @@
<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
@@ -1699,7 +1701,7 @@
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();
@@ -1725,7 +1727,7 @@
}
}
}
-</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
@@ -1734,25 +1736,25 @@
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
@@ -1761,7 +1763,7 @@
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"