set of possibilities</a>
<li><a href="#namedalternatives">Named alternatives</a>
<li><a href="#list">Parsing a list of options</a>
+ <li><a href="#description">Adding freeform text to help output</a>
</ol>
<li><a href="#referenceguide">Reference Guide</a>
<ol>
specified</a>
<li><a href="#formatting">Controlling other formatting options</a>
</ul>
- <li><a href="#optionclasses">Option Classes</a>
+ <li><a href="#toplevel">Top-Level Classes and Functions</a>
<ul>
+ <li><a href="#cl::ParseCommandLineOptions">The
+ <tt>cl::ParseCommandLineOptions</tt> function</a>
<li><a href="#cl::opt">The <tt>cl::opt</tt> class</a>
<li><a href="#cl::list">The <tt>cl::list</tt> class</a>
<li><a href="#cl::alias">The <tt>cl::alias</tt> class</a>
<!-- *********************************************************************** -->
-</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
+<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
<a name="introduction">Introduction
</b></font></td></tr></table><ul>
the parser. This also makes supporting <a href="#dynamicopts">dynamically
loaded options</a> trivial.<p>
-<li>More Clean: CommandLine supports enum and other types directly, meaning that
+<li>Cleaner: CommandLine supports enum and other types directly, meaning that
there is less error and more security built into the library. You don't have to
worry about whether your integral command line argument accidentally got
assigned a value that is not valid for your enum type.<p>
<pre>
int main(int argc, char **argv) {
- cl::ParseCommandLineOptions(argc, argv);
+ <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv);
...
}
</pre><p>
OPTIONS:
-help - display available options (--help-hidden for more)
- -o <filename> - Specify output filename
+ <b>-o <filename> - Specify output filename</b>
</pre>
Because we specified that the command line option should parse using the
option handling library, but the above example shows the general interface to
these options. The options can be specified in any order, and are specified
with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so
-there are no positional dependencies to have to remember. The available options
-
are discussed in detail in the <a href="#referenceguide">Reference Guide</a>.<p>
+there are no positional dependencies to remember. The available options are
+discussed in detail in the <a href="#referenceguide">Reference Guide</a>.<p>
Continuing the example, we would like to have our compiler take an input
extended to:<p>
<pre>
-USAGE: compiler [options] <input file>
+USAGE: compiler [options] <b><input file></b>
OPTIONS:
-help - display available options (--help-hidden for more)
... indicating that an input filename is expected.<p>
+
<!-- ======================================================================= -->
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
<a name="bool">Boolean Arguments
from being shown by the standard "<tt>--help</tt>" output (note that it is still
shown in the "<tt>--help-hidden</tt>" output).<p>
-The CommandLine library uses a different parser for different data types. For
-example, in the string case, the argument passed to the option is copied
-literally into the content of the string variable... we obviously cannot do that
-in the boolean case, however, so we must use a smarter parser. In the case of
-the boolean parser, it allows no options (in which case it assigns the value of
-true to the variable), or it allows the values "<tt>true</tt>" or
-"<tt>false</tt>" to be specified, allowing any of the following inputs:<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
+to the option is copied literally into the content of the string variable... we
+obviously cannot do that in the boolean case, however, so we must use a smarter
+parser. In the case of the boolean parser, it allows no options (in which case
+it assigns the value of true to the variable), or it allows the values
+"<tt>true</tt>" or "<tt>false</tt>" to be specified, allowing any of the
+following inputs:<p>
<pre>
compiler -f # No value, 'Force' == true
compiler -f=FALSE # Value specified, 'Force' == false
</pre>
-... you get the idea. The bool parser just turns the string values into boolean
-values, and rejects things like '<tt>compiler -f=foo</tt>'. Similarly, the
-float, double, and int parsers work 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>
+... 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
+-f=foo</tt>'. Similarly, the <a href="#doubleparser">float</a>, <a
+href="#doubleparser">double</a>, and <a href="#intparser">int</a> parsers work
+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>
With the declarations above, "<tt>compiler --help</tt>" emits this:<p>
USAGE: compiler [options] <input file>
OPTIONS:
- -f - Overwrite output files
+ <b>-f - Overwrite output files</b>
-o - Override output filename
- -quiet - Don't print informational messages
+ <b>-quiet - Don't print informational messages</b>
-help - display available options (--help-hidden for more)
</pre><p>
and "<tt>opt --help-hidden</tt>" prints this:<p>
<pre>
-USAGE: opt [options] <input file>
+USAGE: compiler [options] <input file>
OPTIONS:
-f - Overwrite output files
-o - Override output filename
- -q - Don't print informational messages
+ <b>-q - Don't print informational messages</b>
-quiet - Don't print informational messages
-help - display available options (--help-hidden for more)
</pre><p>
USAGE: compiler [options] <input file>
OPTIONS:
- Choose optimization level:
+ <b>Choose optimization level:
-g - No optimizations, enable debugging
-O1 - Enable trivial optimizations
-O2 - Enable default optimizations
- -O3 - Enable expensive optimizations
+ -O3 - Enable expensive optimizations</b>
-f - Overwrite output files
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
-O1 - Enable trivial optimizations
-O2 - Enable default optimizations
-O3 - Enable expensive optimizations
- -debug_level - Set the debugging level:
+ <b>-debug_level - Set the debugging level:
=none - disable debug information
=quick - enable quick debug information
- =detailed - enable detailed debug information
+ =detailed - enable detailed debug information</b>
-f - Overwrite output files
-help - display available options (--help-hidden for more)
-o <filename> - Specify output filename
+<!-- ======================================================================= -->
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
+<a name="description">Adding freeform text to help output
+</b></font></td></tr></table><ul>
+
+As our program grows and becomes more mature, we may decide to put summary
+information about what it does into the help output. The help output is styled
+to look similar to a Unix <tt>man</tt> page, providing concise information about
+a program. Unix <tt>man</tt> pages, however often have a description about what
+the program does. To add this to your CommandLine program, simply pass a third
+argument to the <a
+href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
+call in main. This additional argument is then printed as the overview
+information for your program, allowing you to include any additional information
+that you want. For example:<p>
+
+<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><p>
+
+Would yield the help output:
+
+<pre>
+<b>OVERVIEW: CommandLine compiler example
+
+ This program blah blah blah...</b>
+
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ ...
+ -help - display available options (--help-hidden for more)
+ -o <filename> - Specify output filename
+</pre><p>
+
+
+
+
<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0><tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
<a name="referenceguide">Reference Guide
replacement would look like this:<p>
<pre>
-USAGE: spiffygrep [options] <regular expression> <input file>
+USAGE: spiffygrep [options] <b><regular expression> <input file></b>
OPTIONS:
-help - display available options (--help-hidden for more)
which automatically provides the help output:<p>
<pre>
-USAGE: spiffysh [options] <input script> <program arguments>...
+USAGE: spiffysh [options] <b><input script> <program arguments>...</b>
OPTIONS:
-help - display available options (--help-hidden for more)
- -x - Enable trace output
+ <b>-x - Enable trace output</b>
</pre><p>
At runtime, if we run our new shell replacement as '<tt>spiffysh -x test.sh -a
href="#positional">positional options</a>) specifies what the option name is.
This option is specified in simple double quotes:<p>
-<a href="#cl::opt">cl::opt</a><bool> Quiet("<i>quiet</i>");<p>
+<pre>
+<a href="#cl::opt">cl::opt</a><<b>bool</b>> Quiet("<i>quiet</i>");
+</pre><p>
<li><a name="cl::desc">The <b><tt>cl::desc</tt></b> attribute specifies a
description for the option to be shown in the <tt>--help</tt> output for the
<!-- ======================================================================= -->
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
-<a name="optionclasses">Option Classes
+<a name="toplevel">Top-Level Classes and Functions
</b></font></td></tr></table><ul>
Despite all of the builtin flexibility, the CommandLine option library really
-only consists of three main classes: <a href="#cl::opt">cl::opt</a>, <a
-href="#cl::list">cl::list</a>, and <a href="#cl::alias">cl::alias</a>. This
-section describes these three classes in detail.<p>
+only consists of one function (<a
+href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>)
+and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a
+href="#cl::list"><tt>cl::list</tt></a>, and <a
+href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three
+classes in detail.<p>
+
+<!-- _______________________________________________________________________ -->
+</ul><a name="cl::ParseCommandLineOptions"><h4><hr size=0>The
+<tt>cl::ParseCommandLineOptions</tt> function</h4><ul>
+
+The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
+directly from <tt>main</tt>, and is used to fill in the values of all of the
+command line option variables once <tt>argc</tt> and <tt>argv</tt> are
+available.<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>
+
<!-- _______________________________________________________________________ -->
</ul><a name="cl::opt"><h4><hr size=0>The <tt>cl::opt</tt> class</h4><ul>
though):<p>
<pre>
-namespace cl {
- template <class DataType, bool ExternalStorage = false,
- class ParserClass = parser<DataType> >
- class opt;
+<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><p>
arguments:<p>
<pre>
-namespace cl {
- template <class DataType, class Storage = bool,
- class ParserClass = parser<DataType> >
- class list;
+<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><p>
aliases for other arguments.<p>
<pre>
-namespace cl {
- class alias;
+<b>namespace</b> cl {
+ <b>class</b> alias;
}
</pre></p>
</b></font></td></tr></table><ul>
<!-- *********************************************************************** -->
-TODO
+Although the CommandLine library has a lot of functionality built into it
+already (as discussed previously), one of its true strengths lie in its
+extensibility. This section discusses how the CommandLine library works under
+the covers and illustrates how to do some simple, common, extensions.<p>
+
<!-- ======================================================================= -->
-</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
-<a name="customparser">Writing a custom parser
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
+<tr><td> </td><td width="100%"> <font color="#EEEEFF"
+face="Georgia,Palatino"><b> <a name="customparser">Writing a custom parser
</b></font></td></tr></table><ul>
+One of the simplest and most common extensions is the use of a custom parser.
+As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
+of the CommandLine library that turns string input from the user into a
+particular parsed data type, validating the input in the process.<p>
+
+There are two ways to use a new parser:<p>
+
+<ol>
+<li>Specialize the <a href="#genericparser"><tt>cl::parser</tt></a> template for
+ your custom data type.<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>
+
+<li>Write an independant class, using it explicitly from options that need
+ it.<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>
+
+</ol><p>
+
+To guide the discussion, we will discuss a custom parser that accepts file
+sizes, specified with an optional unit after the numeric size. For example, we
+would like to parse "102kb", "41M", "1G" into the appropriate integer value. In
+this case, the underlying data type we want to parse into is
+'<tt>unsigned</tt>'. We choose approach #2 above because we don't want to make
+this the default for all <tt>unsigned</tt> options.<p>
+
+To start out, we declare our new <tt>FileSizeParser</tt> class:<p>
+
+<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><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>
+
+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. 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>
+<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);
+
+ <b>while</b> (1) {
+ <b>switch</b> (*End++) {
+ <b>case</b> 0: <b>return</b> false; <i>// No error</i>
+ <b>case</b> 'i': <i>// Ignore the 'i' in KiB if people use that</i>
+ <b>case</b> 'b': <b>case</b> 'B': <i>// Ignore B suffix</i>
+ <b>break</b>;
+
+ <b>case</b> 'g': <b>case</b> 'G': Val *= 1024*1024*1024; <b>break</b>;
+ <b>case</b> 'm': <b>case</b> 'M': Val *= 1024*1024; <b>break</b>;
+ <b>case</b> 'k': <b>case</b> 'K': Val *= 1024; <b>break</b>;
+
+ default:
+ <i>// Print an error message if unrecognized character!</i>
+ <b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
+ }
+ }
+}
+</pre><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
+example), it is good enough for this example. Note that we use the option
+itself to print out the error message (the <tt>error</tt> method always returns
+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>
+<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><p>
+
+Which adds this to the output of our program:<p>
+
+<pre>
+OPTIONS:
+ -help - display available options (--help-hidden for more)
+ ...
+ <b>-max-file-size=<size> - Maximum file size to accept</b>
+</pre><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>
+$ ./test
+MFS: 0
+$ ./test -max-file-size=123MB
+MFS: 128974848
+$ ./test -max-file-size=3G
+MFS: 3221225472
+$ ./test -max-file-size=dog
+-max-file-size option: 'dog' value invalid for file size argument!
+</pre><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"
+tutorial.<p>
<!-- ======================================================================= -->
-</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
-<a name="explotingexternal">Exploiting external storage
-</b></font></td></tr></table><ul>
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
+<tr><td> </td><td width="100%"> <font color="#EEEEFF"
+face="Georgia,Palatino"><b> <a name="explotingexternal">Exploiting external
+storage </b></font></td></tr></table><ul>
<!-- ======================================================================= -->
-</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0><tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
-<a name="dynamicopts">Dynamically adding command line options
-</b></font></td></tr></table><ul>
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
+<tr><td> </td><td width="100%"> <font color="#EEEEFF"
+face="Georgia,Palatino"><b> <a name="dynamicopts">Dynamically adding command
+line options </b></font></td></tr></table><ul>
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
<!-- hhmts start -->
-Last modified: Tue Aug 6 14:34:47 CDT 2002
+Last modified: Wed Aug 7 13:22:40 CDT 2002
<!-- hhmts end -->
</font>
</body></html>
projects / oota-llvm.git / commitdiff