docs/CommandLine.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>CommandLine 2.0 Library Manual</title>
   7   <link rel="stylesheet" href="llvm.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <div class="doc_title">
  12   CommandLine 2.0 Library Manual
  13 </div>
  14
  15 <ol>
  16   <li><a href="#introduction">Introduction</a></li>
  17
  18   <li><a href="#quickstart">Quick Start Guide</a>
  19     <ol>
  20       <li><a href="#bool">Boolean Arguments</a></li>
  21       <li><a href="#alias">Argument Aliases</a></li>
  22       <li><a href="#onealternative">Selecting an alternative from a
  23                                     set of possibilities</a></li>
  24       <li><a href="#namedalternatives">Named alternatives</a></li>
  25       <li><a href="#list">Parsing a list of options</a></li>
  26       <li><a href="#bits">Collecting options as a set of flags</a></li>
  27       <li><a href="#description">Adding freeform text to help output</a></li>
  28     </ol></li>
  29
  30   <li><a href="#referenceguide">Reference Guide</a>
  31     <ol>
  32       <li><a href="#positional">Positional Arguments</a>
  33         <ul>
  34         <li><a href="#--">Specifying positional options with hyphens</a></li>
  35         <li><a href="#getPosition">Determining absolute position with
  36           getPosition</a></li>
  37         <li><a href="#cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt>
  38              modifier</a></li>
  39         </ul></li>
  40
  41       <li><a href="#storage">Internal vs External Storage</a></li>
  42
  43       <li><a href="#attributes">Option Attributes</a></li>
  44
  45       <li><a href="#modifiers">Option Modifiers</a>
  46         <ul>
  47         <li><a href="#hiding">Hiding an option from <tt>--help</tt>
  48             output</a></li>
  49         <li><a href="#numoccurrences">Controlling the number of occurrences
  50                                      required and allowed</a></li>
  51         <li><a href="#valrequired">Controlling whether or not a value must be
  52                                    specified</a></li>
  53         <li><a href="#formatting">Controlling other formatting options</a></li>
  54         <li><a href="#misc">Miscellaneous option modifiers</a></li>
  55         </ul></li>
  56
  57       <li><a href="#toplevel">Top-Level Classes and Functions</a>
  58         <ul>
  59         <li><a href="#cl::ParseCommandLineOptions">The
  60             <tt>cl::ParseCommandLineOptions</tt> function</a></li>
  61         <li><a href="#cl::ParseEnvironmentOptions">The
  62             <tt>cl::ParseEnvironmentOptions</tt> function</a></li>
  63         <li><a href="#cl::SetVersionPrinter">The cl::SetVersionPrinter
  64           function</a></li>
  65         <li><a href="#cl::opt">The <tt>cl::opt</tt> class</a></li>
  66         <li><a href="#cl::list">The <tt>cl::list</tt> class</a></li>
  67         <li><a href="#cl::bits">The <tt>cl::bits</tt> class</a></li>
  68         <li><a href="#cl::alias">The <tt>cl::alias</tt> class</a></li>
  69         <li><a href="#cl::extrahelp">The <tt>cl::extrahelp</tt> class</a></li>
  70         </ul></li>
  71
  72       <li><a href="#builtinparsers">Builtin parsers</a>
  73         <ul>
  74         <li><a href="#genericparser">The Generic <tt>parser&lt;t&gt;</tt>
  75             parser</a></li>
  76         <li><a href="#boolparser">The <tt>parser&lt;bool&gt;</tt>
  77             specialization</a></li>
  78         <li><a href="#stringparser">The <tt>parser&lt;string&gt;</tt>
  79             specialization</a></li>
  80         <li><a href="#intparser">The <tt>parser&lt;int&gt;</tt>
  81             specialization</a></li>
  82         <li><a href="#doubleparser">The <tt>parser&lt;double&gt;</tt> and
  83             <tt>parser&lt;float&gt;</tt> specializations</a></li>
  84         </ul></li>
  85     </ol></li>
  86   <li><a href="#extensionguide">Extension Guide</a>
  87     <ol>
  88       <li><a href="#customparser">Writing a custom parser</a></li>
  89       <li><a href="#explotingexternal">Exploiting external storage</a></li>
  90       <li><a href="#dynamicopts">Dynamically adding command line
  91           options</a></li>
  92     </ol></li>
  93 </ol>
  94
  95 <div class="doc_author">
  96   <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
  97 </div>
  98
  99 <!-- *********************************************************************** -->
 100 <div class="doc_section">
 101   <a name="introduction">Introduction</a>
 102 </div>
 103 <!-- *********************************************************************** -->
 104
 105 <div class="doc_text">
 106
 107 <p>This document describes the CommandLine argument processing library.  It will
 108 show you how to use it, and what it can do.  The CommandLine library uses a
 109 declarative approach to specifying the command line options that your program
 110 takes.  By default, these options declarations implicitly hold the value parsed
 111 for the option declared (of course this <a href="#storage">can be
 112 changed</a>).</p>
 113
 114 <p>Although there are a <b>lot</b> of command line argument parsing libraries
 115 out there in many different languages, none of them fit well with what I needed.
 116 By looking at the features and problems of other libraries, I designed the
 117 CommandLine library to have the following features:</p>
 118
 119 <ol>
 120 <li>Speed: The CommandLine library is very quick and uses little resources.  The
 121 parsing time of the library is directly proportional to the number of arguments
 122 parsed, not the the number of options recognized.  Additionally, command line
 123 argument values are captured transparently into user defined global variables,
 124 which can be accessed like any other variable (and with the same
 125 performance).</li>
 126
 127 <li>Type Safe: As a user of CommandLine, you don't have to worry about
 128 remembering the type of arguments that you want (is it an int?  a string? a
 129 bool? an enum?) and keep casting it around.  Not only does this help prevent
 130 error prone constructs, it also leads to dramatically cleaner source code.</li>
 131
 132 <li>No subclasses required: To use CommandLine, you instantiate variables that
 133 correspond to the arguments that you would like to capture, you don't subclass a
 134 parser.  This means that you don't have to write <b>any</b> boilerplate
 135 code.</li>
 136
 137 <li>Globally accessible: Libraries can specify command line arguments that are
 138 automatically enabled in any tool that links to the library.  This is possible
 139 because the application doesn't have to keep a "list" of arguments to pass to
 140 the parser.  This also makes supporting <a href="#dynamicopts">dynamically
 141 loaded options</a> trivial.</li>
 142
 143 <li>Cleaner: CommandLine supports enum and other types directly, meaning that
 144 there is less error and more security built into the library.  You don't have to
 145 worry about whether your integral command line argument accidentally got
 146 assigned a value that is not valid for your enum type.</li>
 147
 148 <li>Powerful: The CommandLine library supports many different types of
 149 arguments, from simple <a href="#boolparser">boolean flags</a> to <a
 150 href="#cl::opt">scalars arguments</a> (<a href="#stringparser">strings</a>, <a
 151 href="#intparser">integers</a>, <a href="#genericparser">enums</a>, <a
 152 href="#doubleparser">doubles</a>), to <a href="#cl::list">lists of
 153 arguments</a>.  This is possible because CommandLine is...</li>
 154
 155 <li>Extensible: It is very simple to add a new argument type to CommandLine.
 156 Simply specify the parser that you want to use with the command line option when
 157 you declare it.  <a href="#customparser">Custom parsers</a> are no problem.</li>
 158
 159 <li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
 160 that you, the user, have to do.  For example, it automatically provides a
 161 <tt>--help</tt> option that shows the available command line options for your
 162 tool.  Additionally, it does most of the basic correctness checking for
 163 you.</li>
 164
 165 <li>Capable: The CommandLine library can handle lots of different forms of
 166 options often found in real programs.  For example, <a
 167 href="#positional">positional</a> arguments, <tt>ls</tt> style <a
 168 href="#cl::Grouping">grouping</a> options (to allow processing '<tt>ls
 169 -lad</tt>' naturally), <tt>ld</tt> style <a href="#cl::Prefix">prefix</a>
 170 options (to parse '<tt>-lmalloc -L/usr/lib</tt>'), and <a
 171 href="#cl::ConsumeAfter">interpreter style options</a>.</li>
 172
 173 </ol>
 174
 175 <p>This document will hopefully let you jump in and start using CommandLine in
 176 your utility quickly and painlessly.  Additionally it should be a simple
 177 reference manual to figure out how stuff works.  If it is failing in some area
 178 (or you want an extension to the library), nag the author, <a
 179 href="mailto:sabre@nondot.org">Chris Lattner</a>.</p>
 180
 181 </div>
 182
 183 <!-- *********************************************************************** -->
 184 <div class="doc_section">
 185   <a name="quickstart">Quick Start Guide</a>
 186 </div>
 187 <!-- *********************************************************************** -->
 188
 189 <div class="doc_text">
 190
 191 <p>This section of the manual runs through a simple CommandLine'ification of a
 192 basic compiler tool.  This is intended to show you how to jump into using the
 193 CommandLine library in your own program, and show you some of the cool things it
 194 can do.</p>
 195
 196 <p>To start out, you need to include the CommandLine header file into your
 197 program:</p>
 198
 199 <div class="doc_code"><pre>
 200   #include "llvm/Support/CommandLine.h"
 201 </pre></div>
 202
 203 <p>Additionally, you need to add this as the first line of your main
 204 program:</p>
 205
 206 <div class="doc_code"><pre>
 207 int main(int argc, char **argv) {
 208   <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv);
 209   ...
 210 }
 211 </pre></div>
 212
 213 <p>... which actually parses the arguments and fills in the variable
 214 declarations.</p>
 215
 216 <p>Now that you are ready to support command line arguments, we need to tell the
 217 system which ones we want, and what type of argument they are.  The CommandLine
 218 library uses a declarative syntax to model command line arguments with the
 219 global variable declarations that capture the parsed values.  This means that
 220 for every command line option that you would like to support, there should be a
 221 global variable declaration to capture the result.  For example, in a compiler,
 222 we would like to support the unix standard '<tt>-o &lt;filename&gt;</tt>' option
 223 to specify where to put the output.  With the CommandLine library, this is
 224 represented like this:</p>
 225
 226 <a name="value_desc_example"></a>
 227 <div class="doc_code"><pre>
 228 <a href="#cl::opt">cl::opt</a>&lt;string&gt; 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>"));
 229 </pre></div>
 230
 231 <p>This declares a global variable "<tt>OutputFilename</tt>" that is used to
 232 capture the result of the "<tt>o</tt>" argument (first parameter).  We specify
 233 that this is a simple scalar option by using the "<tt><a
 234 href="#cl::opt">cl::opt</a></tt>" template (as opposed to the <a
 235 href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library
 236 that the data type that we are parsing is a string.</p>
 237
 238 <p>The second and third parameters (which are optional) are used to specify what
 239 to output for the "<tt>--help</tt>" option.  In this case, we get a line that
 240 looks like this:</p>
 241
 242 <div class="doc_code"><pre>
 243 USAGE: compiler [options]
 244
 245 OPTIONS:
 246   -help             - display available options (--help-hidden for more)
 247   <b>-o &lt;filename&gt;     - Specify output filename</b>
 248 </pre></div>
 249
 250 <p>Because we specified that the command line option should parse using the
 251 <tt>string</tt> data type, the variable declared is automatically usable as a
 252 real string in all contexts that a normal C++ string object may be used.  For
 253 example:</p>
 254
 255 <div class="doc_code"><pre>
 256   ...
 257   ofstream Output(OutputFilename.c_str());
 258   if (Out.good()) ...
 259   ...
 260 </pre></div>
 261
 262 <p>There are many different options that you can use to customize the command
 263 line option handling library, but the above example shows the general interface
 264 to these options.  The options can be specified in any order, and are specified
 265 with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so
 266 there are no positional dependencies to remember.  The available options are
 267 discussed in detail in the <a href="#referenceguide">Reference Guide</a>.</p>
 268
 269 <p>Continuing the example, we would like to have our compiler take an input
 270 filename as well as an output filename, but we do not want the input filename to
 271 be specified with a hyphen (ie, not <tt>-filename.c</tt>).  To support this
 272 style of argument, the CommandLine library allows for <a
 273 href="#positional">positional</a> arguments to be specified for the program.
 274 These positional arguments are filled with command line parameters that are not
 275 in option form.  We use this feature like this:</p>
 276
 277 <div class="doc_code"><pre>
 278 <a href="#cl::opt">cl::opt</a>&lt;string&gt; InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;input file&gt;</i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
 279 </pre></div>
 280
 281 <p>This declaration indicates that the first positional argument should be
 282 treated as the input filename.  Here we use the <tt><a
 283 href="#cl::init">cl::init</a></tt> option to specify an initial value for the
 284 command line option, which is used if the option is not specified (if you do not
 285 specify a <tt><a href="#cl::init">cl::init</a></tt> modifier for an option, then
 286 the default constructor for the data type is used to initialize the value).
 287 Command line options default to being optional, so if we would like to require
 288 that the user always specify an input filename, we would add the <tt><a
 289 href="#cl::Required">cl::Required</a></tt> flag, and we could eliminate the
 290 <tt><a href="#cl::init">cl::init</a></tt> modifier, like this:</p>
 291
 292 <div class="doc_code"><pre>
 293 <a href="#cl::opt">cl::opt</a>&lt;string&gt; InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;input file&gt;</i>"), <b><a href="#cl::Required">cl::Required</a></b>);
 294 </pre></div>
 295
 296 <p>Again, the CommandLine library does not require the options to be specified
 297 in any particular order, so the above declaration is equivalent to:</p>
 298
 299 <div class="doc_code"><pre>
 300 <a href="#cl::opt">cl::opt</a>&lt;string&gt; InputFilename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::Required">cl::Required</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;input file&gt;</i>"));
 301 </pre></div>
 302
 303 <p>By simply adding the <tt><a href="#cl::Required">cl::Required</a></tt> flag,
 304 the CommandLine library will automatically issue an error if the argument is not
 305 specified, which shifts all of the command line option verification code out of
 306 your application into the library.  This is just one example of how using flags
 307 can alter the default behaviour of the library, on a per-option basis.  By
 308 adding one of the declarations above, the <tt>--help</tt> option synopsis is now
 309 extended to:</p>
 310
 311 <div class="doc_code"><pre>
 312 USAGE: compiler [options] <b>&lt;input file&gt;</b>
 313
 314 OPTIONS:
 315   -help             - display available options (--help-hidden for more)
 316   -o &lt;filename&gt;     - Specify output filename
 317 </pre></div>
 318
 319 <p>... indicating that an input filename is expected.</p>
 320
 321 </div>
 322
 323 <!-- ======================================================================= -->
 324 <div class="doc_subsection">
 325   <a name="bool">Boolean Arguments</a>
 326 </div>
 327
 328 <div class="doc_text">
 329
 330 <p>In addition to input and output filenames, we would like the compiler example
 331 to support three boolean flags: "<tt>-f</tt>" to force overwriting of the output
 332 file, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for backwards
 333 compatibility with some of our users.  We can support these by declaring options
 334 of boolean type like this:</p>
 335
 336 <div class="doc_code"><pre>
 337 <a href="#cl::opt">cl::opt</a>&lt;bool&gt; Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
 338 <a href="#cl::opt">cl::opt</a>&lt;bool&gt; Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
 339 <a href="#cl::opt">cl::opt</a>&lt;bool&gt; 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>);
 340 </pre></div>
 341
 342 <p>This does what you would expect: it declares three boolean variables
 343 ("<tt>Force</tt>", "<tt>Quiet</tt>", and "<tt>Quiet2</tt>") to recognize these
 344 options.  Note that the "<tt>-q</tt>" option is specified with the "<a
 345 href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag.  This modifier prevents it
 346 from being shown by the standard "<tt>--help</tt>" output (note that it is still
 347 shown in the "<tt>--help-hidden</tt>" output).</p>
 348
 349 <p>The CommandLine library uses a <a href="#builtinparsers">different parser</a>
 350 for different data types.  For example, in the string case, the argument passed
 351 to the option is copied literally into the content of the string variable... we
 352 obviously cannot do that in the boolean case, however, so we must use a smarter
 353 parser.  In the case of the boolean parser, it allows no options (in which case
 354 it assigns the value of true to the variable), or it allows the values
 355 "<tt>true</tt>" or "<tt>false</tt>" to be specified, allowing any of the
 356 following inputs:</p>
 357
 358 <div class="doc_code"><pre>
 359  compiler -f          # No value, 'Force' == true
 360  compiler -f=true     # Value specified, 'Force' == true
 361  compiler -f=TRUE     # Value specified, 'Force' == true
 362  compiler -f=FALSE    # Value specified, 'Force' == false
 363 </pre></div>
 364
 365 <p>... you get the idea.  The <a href="#boolparser">bool parser</a> just turns
 366 the string values into boolean values, and rejects things like '<tt>compiler
 367 -f=foo</tt>'.  Similarly, the <a href="#doubleparser">float</a>, <a
 368 href="#doubleparser">double</a>, and <a href="#intparser">int</a> parsers work
 369 like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C
 370 library calls to parse the string value into the specified data type.</p>
 371
 372 <p>With the declarations above, "<tt>compiler --help</tt>" emits this:</p>
 373
 374 <div class="doc_code"><pre>
 375 USAGE: compiler [options] &lt;input file&gt;
 376
 377 OPTIONS:
 378   <b>-f     - Overwrite output files</b>
 379   -o     - Override output filename
 380   <b>-quiet - Don't print informational messages</b>
 381   -help  - display available options (--help-hidden for more)
 382 </pre></div>
 383
 384 <p>and "<tt>opt --help-hidden</tt>" prints this:</p>
 385
 386 <div class="doc_code"><pre>
 387 USAGE: compiler [options] &lt;input file&gt;
 388
 389 OPTIONS:
 390   -f     - Overwrite output files
 391   -o     - Override output filename
 392   <b>-q     - Don't print informational messages</b>
 393   -quiet - Don't print informational messages
 394   -help  - display available options (--help-hidden for more)
 395 </pre></div>
 396
 397 <p>This brief example has shown you how to use the '<tt><a
 398 href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line
 399 arguments.  In addition to simple scalar arguments, the CommandLine library also
 400 provides primitives to support CommandLine option <a href="#alias">aliases</a>,
 401 and <a href="#list">lists</a> of options.</p>
 402
 403 </div>
 404
 405 <!-- ======================================================================= -->
 406 <div class="doc_subsection">
 407   <a name="alias">Argument Aliases</a>
 408 </div>
 409
 410 <div class="doc_text">
 411
 412 <p>So far, the example works well, except for the fact that we need to check the
 413 quiet condition like this now:</p>
 414
 415 <div class="doc_code"><pre>
 416 ...
 417   if (!Quiet &amp;&amp; !Quiet2) printInformationalMessage(...);
 418 ...
 419 </pre></div>
 420
 421 <p>... which is a real pain!  Instead of defining two values for the same
 422 condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>"
 423 option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing
 424 a value itself:</p>
 425
 426 <div class="doc_code"><pre>
 427 <a href="#cl::opt">cl::opt</a>&lt;bool&gt; Force ("<i>f</i>", <a href="#cl::desc">cl::desc</a>("<i>Overwrite output files</i>"));
 428 <a href="#cl::opt">cl::opt</a>&lt;bool&gt; Quiet ("<i>quiet</i>", <a href="#cl::desc">cl::desc</a>("<i>Don't print informational messages</i>"));
 429 <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));
 430 </pre></div>
 431
 432 <p>The third line (which is the only one we modified from above) defines a
 433 "<tt>-q</tt> alias that updates the "<tt>Quiet</tt>" variable (as specified by
 434 the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is
 435 specified.  Because aliases do not hold state, the only thing the program has to
 436 query is the <tt>Quiet</tt> variable now.  Another nice feature of aliases is
 437 that they automatically hide themselves from the <tt>-help</tt> output
 438 (although, again, they are still visible in the <tt>--help-hidden
 439 output</tt>).</p>
 440
 441 <p>Now the application code can simply use:</p>
 442
 443 <div class="doc_code"><pre>
 444 ...
 445   if (!Quiet) printInformationalMessage(...);
 446 ...
 447 </pre></div>
 448
 449 <p>... which is much nicer!  The "<tt><a href="#cl::alias">cl::alias</a></tt>"
 450 can be used to specify an alternative name for any variable type, and has many
 451 uses.</p>
 452
 453 </div>
 454
 455 <!-- ======================================================================= -->
 456 <div class="doc_subsection">
 457   <a name="onealternative">Selecting an alternative from a set of
 458   possibilities</a>
 459 </div>
 460
 461 <div class="doc_text">
 462
 463 <p>So far, we have seen how the CommandLine library handles builtin types like
 464 <tt>std::string</tt>, <tt>bool</tt> and <tt>int</tt>, but how does it handle
 465 things it doesn't know about, like enums or '<tt>int*</tt>'s?</p>
 466
 467 <p>The answer is that it uses a table driven generic parser (unless you specify
 468 your own parser, as described in the <a href="#extensionguide">Extension
 469 Guide</a>).  This parser maps literal strings to whatever type is required, and
 470 requires you to tell it what this mapping should be.</p>
 471
 472 <p>Lets say that we would like to add four optimization levels to our
 473 optimizer, using the standard flags "<tt>-g</tt>", "<tt>-O0</tt>",
 474 "<tt>-O1</tt>", and "<tt>-O2</tt>".  We could easily implement this with boolean
 475 options like above, but there are several problems with this strategy:</p>
 476
 477 <ol>
 478 <li>A user could specify more than one of the options at a time, for example,
 479 "<tt>opt -O3 -O2</tt>".  The CommandLine library would not be able to catch this
 480 erroneous input for us.</li>
 481
 482 <li>We would have to test 4 different variables to see which ones are set.</li>
 483
 484 <li>This doesn't map to the numeric levels that we want... so we cannot easily
 485 see if some level &gt;= "<tt>-O1</tt>" is enabled.</li>
 486
 487 </ol>
 488
 489 <p>To cope with these problems, we can use an enum value, and have the
 490 CommandLine library fill it in with the appropriate level directly, which is
 491 used like this:</p>
 492
 493 <div class="doc_code"><pre>
 494 enum OptLevel {
 495   g, O1, O2, O3
 496 };
 497
 498 <a href="#cl::opt">cl::opt</a>&lt;OptLevel&gt; OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
 499   <a href="#cl::values">cl::values</a>(
 500     clEnumVal(g , "<i>No optimizations, enable debugging</i>"),
 501     clEnumVal(O1, "<i>Enable trivial optimizations</i>"),
 502     clEnumVal(O2, "<i>Enable default optimizations</i>"),
 503     clEnumVal(O3, "<i>Enable expensive optimizations</i>"),
 504    clEnumValEnd));
 505
 506 ...
 507   if (OptimizationLevel &gt;= O2) doPartialRedundancyElimination(...);
 508 ...
 509 </pre></div>
 510
 511 <p>This declaration defines a variable "<tt>OptimizationLevel</tt>" of the
 512 "<tt>OptLevel</tt>" enum type.  This variable can be assigned any of the values
 513 that are listed in the declaration (Note that the declaration list must be
 514 terminated with the "<tt>clEnumValEnd</tt>" argument!).  The CommandLine
 515 library enforces
 516 that the user can only specify one of the options, and it ensure that only valid
 517 enum values can be specified.  The "<tt>clEnumVal</tt>" macros ensure that the
 518 command line arguments matched the enum values.  With this option added, our
 519 help output now is:</p>
 520
 521 <div class="doc_code"><pre>
 522 USAGE: compiler [options] &lt;input file&gt;
 523
 524 OPTIONS:
 525   <b>Choose optimization level:
 526     -g          - No optimizations, enable debugging
 527     -O1         - Enable trivial optimizations
 528     -O2         - Enable default optimizations
 529     -O3         - Enable expensive optimizations</b>
 530   -f            - Overwrite output files
 531   -help         - display available options (--help-hidden for more)
 532   -o &lt;filename&gt; - Specify output filename
 533   -quiet        - Don't print informational messages
 534 </pre></div>
 535
 536 <p>In this case, it is sort of awkward that flag names correspond directly to
 537 enum names, because we probably don't want a enum definition named "<tt>g</tt>"
 538 in our program.  Because of this, we can alternatively write this example like
 539 this:</p>
 540
 541 <div class="doc_code"><pre>
 542 enum OptLevel {
 543   Debug, O1, O2, O3
 544 };
 545
 546 <a href="#cl::opt">cl::opt</a>&lt;OptLevel&gt; OptimizationLevel(<a href="#cl::desc">cl::desc</a>("<i>Choose optimization level:</i>"),
 547   <a href="#cl::values">cl::values</a>(
 548    clEnumValN(Debug, "g", "<i>No optimizations, enable debugging</i>"),
 549     clEnumVal(O1        , "<i>Enable trivial optimizations</i>"),
 550     clEnumVal(O2        , "<i>Enable default optimizations</i>"),
 551     clEnumVal(O3        , "<i>Enable expensive optimizations</i>"),
 552    clEnumValEnd));
 553
 554 ...
 555   if (OptimizationLevel == Debug) outputDebugInfo(...);
 556 ...
 557 </pre></div>
 558
 559 <p>By using the "<tt>clEnumValN</tt>" macro instead of "<tt>clEnumVal</tt>", we
 560 can directly specify the name that the flag should get.  In general a direct
 561 mapping is nice, but sometimes you can't or don't want to preserve the mapping,
 562 which is when you would use it.</p>
 563
 564 </div>
 565
 566 <!-- ======================================================================= -->
 567 <div class="doc_subsection">
 568   <a name="namedalternatives">Named Alternatives</a>
 569 </div>
 570
 571 <div class="doc_text">
 572
 573 <p>Another useful argument form is a named alternative style.  We shall use this
 574 style in our compiler to specify different debug levels that can be used.
 575 Instead of each debug level being its own switch, we want to support the
 576 following options, of which only one can be specified at a time:
 577 "<tt>--debug-level=none</tt>", "<tt>--debug-level=quick</tt>",
 578 "<tt>--debug-level=detailed</tt>".  To do this, we use the exact same format as
 579 our optimization level flags, but we also specify an option name.  For this
 580 case, the code looks like this:</p>
 581
 582 <div class="doc_code"><pre>
 583 enum DebugLev {
 584   nodebuginfo, quick, detailed
 585 };
 586
 587 // Enable Debug Options to be specified on the command line
 588 <a href="#cl::opt">cl::opt</a>&lt;DebugLev&gt; DebugLevel("<i>debug_level</i>", <a href="#cl::desc">cl::desc</a>("<i>Set the debugging level:</i>"),
 589   <a href="#cl::values">cl::values</a>(
 590     clEnumValN(nodebuginfo, "none", "<i>disable debug information</i>"),
 591      clEnumVal(quick,               "<i>enable quick debug information</i>"),
 592      clEnumVal(detailed,            "<i>enable detailed debug information</i>"),
 593     clEnumValEnd));
 594 </pre></div>
 595
 596 <p>This definition defines an enumerated command line variable of type "<tt>enum
 597 DebugLev</tt>", which works exactly the same way as before.  The difference here
 598 is just the interface exposed to the user of your program and the help output by
 599 the "<tt>--help</tt>" option:</p>
 600
 601 <div class="doc_code"><pre>
 602 USAGE: compiler [options] &lt;input file&gt;
 603
 604 OPTIONS:
 605   Choose optimization level:
 606     -g          - No optimizations, enable debugging
 607     -O1         - Enable trivial optimizations
 608     -O2         - Enable default optimizations
 609     -O3         - Enable expensive optimizations
 610   <b>-debug_level  - Set the debugging level:
 611     =none       - disable debug information
 612     =quick      - enable quick debug information
 613     =detailed   - enable detailed debug information</b>
 614   -f            - Overwrite output files
 615   -help         - display available options (--help-hidden for more)
 616   -o &lt;filename&gt; - Specify output filename
 617   -quiet        - Don't print informational messages
 618 </pre></div>
 619
 620 <p>Again, the only structural difference between the debug level declaration and
 621 the optimization level declaration is that the debug level declaration includes
 622 an option name (<tt>"debug_level"</tt>), which automatically changes how the
 623 library processes the argument.  The CommandLine library supports both forms so
 624 that you can choose the form most appropriate for your application.</p>
 625
 626 </div>
 627
 628 <!-- ======================================================================= -->
 629 <div class="doc_subsection">
 630   <a name="list">Parsing a list of options</a>
 631 </div>
 632
 633 <div class="doc_text">
 634
 635 <p>Now that we have the standard run of the mill argument types out of the way,
 636 lets get a little wild and crazy.  Lets say that we want our optimizer to accept
 637 a <b>list</b> of optimizations to perform, allowing duplicates.  For example, we
 638 might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>".  In
 639 this case, the order of the arguments and the number of appearances is very
 640 important.  This is what the "<tt><a href="#cl::list">cl::list</a></tt>"
 641 template is for.  First, start by defining an enum of the optimizations that you
 642 would like to perform:</p>
 643
 644 <div class="doc_code"><pre>
 645 enum Opts {
 646   // 'inline' is a C++ keyword, so name it 'inlining'
 647   dce, constprop, inlining, strip
 648 };
 649 </pre></div>
 650
 651 <p>Then define your "<tt><a href="#cl::list">cl::list</a></tt>" variable:</p>
 652
 653 <div class="doc_code"><pre>
 654 <a href="#cl::list">cl::list</a>&lt;Opts&gt; OptimizationList(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
 655   <a href="#cl::values">cl::values</a>(
 656     clEnumVal(dce               , "<i>Dead Code Elimination</i>"),
 657     clEnumVal(constprop         , "<i>Constant Propagation</i>"),
 658    clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
 659     clEnumVal(strip             , "<i>Strip Symbols</i>"),
 660   clEnumValEnd));
 661 </pre></div>
 662
 663 <p>This defines a variable that is conceptually of the type
 664 "<tt>std::vector&lt;enum Opts&gt;</tt>".  Thus, you can access it with standard
 665 vector methods:</p>
 666
 667 <div class="doc_code"><pre>
 668   for (unsigned i = 0; i != OptimizationList.size(); ++i)
 669     switch (OptimizationList[i])
 670        ...
 671 </pre></div>
 672
 673 <p>... to iterate through the list of options specified.</p>
 674
 675 <p>Note that the "<tt><a href="#cl::list">cl::list</a></tt>" template is
 676 completely general and may be used with any data types or other arguments that
 677 you can use with the "<tt><a href="#cl::opt">cl::opt</a></tt>" template.  One
 678 especially useful way to use a list is to capture all of the positional
 679 arguments together if there may be more than one specified.  In the case of a
 680 linker, for example, the linker takes several '<tt>.o</tt>' files, and needs to
 681 capture them into a list.  This is naturally specified as:</p>
 682
 683 <div class="doc_code"><pre>
 684 ...
 685 <a href="#cl::list">cl::list</a>&lt;std::string&gt; InputFilenames(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("&lt;Input files&gt;"), <a href="#cl::OneOrMore">cl::OneOrMore</a>);
 686 ...
 687 </pre></div>
 688
 689 <p>This variable works just like a "<tt>vector&lt;string&gt;</tt>" object.  As
 690 such, accessing the list is simple, just like above.  In this example, we used
 691 the <tt><a href="#cl::OneOrMore">cl::OneOrMore</a></tt> modifier to inform the
 692 CommandLine library that it is an error if the user does not specify any
 693 <tt>.o</tt> files on our command line.  Again, this just reduces the amount of
 694 checking we have to do.</p>
 695
 696 </div>
 697
 698 <!-- ======================================================================= -->
 699 <div class="doc_subsection">
 700   <a name="bits">Collecting options as a set of flags</a>
 701 </div>
 702
 703 <div class="doc_text">
 704
 705 <p>Instead of collecting sets of options in a list, it is also possible to
 706 gather information for enum values in a <b>bit vector</b>.  The represention used by
 707 the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt>
 708 integer.  An enum value is represented by a 0/1 in the enum's ordinal value bit
 709 position. 1 indicating that the enum was specified, 0 otherwise.  As each
 710 specified value is parsed, the resulting enum's bit is set in the option's bit
 711 vector:</p>
 712
 713 <div class="doc_code"><pre>
 714   <i>bits</i> |= 1 << (unsigned)<i>enum</i>;
 715 </pre></div>
 716
 717 <p>Options that are specified multiple times are redundant.  Any instances after
 718 the first are discarded.</p>
 719
 720 <p>Reworking the above list example, we could replace <a href="#list">
 721 <tt>cl::list</tt></a> with <a href="#bits"><tt>cl::bits</tt></a>:</p>
 722
 723 <div class="doc_code"><pre>
 724 <a href="#cl::bits">cl::bits</a>&lt;Opts&gt; OptimizationBits(<a href="#cl::desc">cl::desc</a>("<i>Available Optimizations:</i>"),
 725   <a href="#cl::values">cl::values</a>(
 726     clEnumVal(dce               , "<i>Dead Code Elimination</i>"),
 727     clEnumVal(constprop         , "<i>Constant Propagation</i>"),
 728    clEnumValN(inlining, "<i>inline</i>", "<i>Procedure Integration</i>"),
 729     clEnumVal(strip             , "<i>Strip Symbols</i>"),
 730   clEnumValEnd));
 731 </pre></div>
 732
 733 <p>To test to see if <tt>constprop</tt> was specified, we can use the
 734 <tt>cl:bits::isSet</tt> function:</p>
 735
 736 <div class="doc_code"><pre>
 737   if (OptimizationBits.isSet(constprop)) {
 738     ...
 739   }
 740 </pre></div>
 741
 742 <p>It's also possible to get the raw bit vector using the
 743 <tt>cl::bits::getBits</tt> function:</p>
 744
 745 <div class="doc_code"><pre>
 746   unsigned bits = OptimizationBits.getBits();
 747 </pre></div>
 748
 749 <p>Finally, if external storage is used, then the location specified must be of
 750 <b>type</b> <tt>unsigned</tt>. In all other ways a <a
 751 href="#bits"><tt>cl::bits</tt></a> option is morally equivalent to a <a
 752 href="#list"> <tt>cl::list</tt></a> option.</p>
 753
 754 </div>
 755
 756
 757 <!-- ======================================================================= -->
 758 <div class="doc_subsection">
 759   <a name="description">Adding freeform text to help output</a>
 760 </div>
 761
 762 <div class="doc_text">
 763
 764 <p>As our program grows and becomes more mature, we may decide to put summary
 765 information about what it does into the help output.  The help output is styled
 766 to look similar to a Unix <tt>man</tt> page, providing concise information about
 767 a program.  Unix <tt>man</tt> pages, however often have a description about what
 768 the program does.  To add this to your CommandLine program, simply pass a third
 769 argument to the <a
 770 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
 771 call in main.  This additional argument is then printed as the overview
 772 information for your program, allowing you to include any additional information
 773 that you want.  For example:</p>
 774
 775 <div class="doc_code"><pre>
 776 int main(int argc, char **argv) {
 777   <a href="#cl::ParseCommandLineOptions">cl::ParseCommandLineOptions</a>(argc, argv, " CommandLine compiler example\n\n"
 778                               "  This program blah blah blah...\n");
 779   ...
 780 }
 781 </pre></div>
 782
 783 <p>would yield the help output:</p>
 784
 785 <div class="doc_code"><pre>
 786 <b>OVERVIEW: CommandLine compiler example
 787
 788   This program blah blah blah...</b>
 789
 790 USAGE: compiler [options] &lt;input file&gt;
 791
 792 OPTIONS:
 793   ...
 794   -help             - display available options (--help-hidden for more)
 795   -o &lt;filename&gt;     - Specify output filename
 796 </pre></div>
 797
 798 </div>
 799
 800
 801 <!-- *********************************************************************** -->
 802 <div class="doc_section">
 803   <a name="referenceguide">Reference Guide</a>
 804 </div>
 805 <!-- *********************************************************************** -->
 806
 807 <div class="doc_text">
 808
 809 <p>Now that you know the basics of how to use the CommandLine library, this
 810 section will give you the detailed information you need to tune how command line
 811 options work, as well as information on more "advanced" command line option
 812 processing capabilities.</p>
 813
 814 </div>
 815
 816 <!-- ======================================================================= -->
 817 <div class="doc_subsection">
 818   <a name="positional">Positional Arguments</a>
 819 </div>
 820
 821 <div class="doc_text">
 822
 823 <p>Positional arguments are those arguments that are not named, and are not
 824 specified with a hyphen.  Positional arguments should be used when an option is
 825 specified by its position alone.  For example, the standard Unix <tt>grep</tt>
 826 tool takes a regular expression argument, and an optional filename to search
 827 through (which defaults to standard input if a filename is not specified).
 828 Using the CommandLine library, this would be specified as:</p>
 829
 830 <div class="doc_code"><pre>
 831 <a href="#cl::opt">cl::opt</a>&lt;string&gt; Regex   (<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;regular expression&gt;</i>"), <a href="#cl::Required">cl::Required</a>);
 832 <a href="#cl::opt">cl::opt</a>&lt;string&gt; Filename(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;input file&gt;</i>"), <a href="#cl::init">cl::init</a>("<i>-</i>"));
 833 </pre></div>
 834
 835 <p>Given these two option declarations, the <tt>--help</tt> output for our grep
 836 replacement would look like this:</p>
 837
 838 <div class="doc_code"><pre>
 839 USAGE: spiffygrep [options] <b>&lt;regular expression&gt; &lt;input file&gt;</b>
 840
 841 OPTIONS:
 842   -help - display available options (--help-hidden for more)
 843 </pre></div>
 844
 845 <p>... and the resultant program could be used just like the standard
 846 <tt>grep</tt> tool.</p>
 847
 848 <p>Positional arguments are sorted by their order of construction.  This means
 849 that command line options will be ordered according to how they are listed in a
 850 .cpp file, but will not have an ordering defined if the positional arguments
 851 are defined in multiple .cpp files.  The fix for this problem is simply to
 852 define all of your positional arguments in one .cpp file.</p>
 853
 854 </div>
 855
 856
 857 <!-- _______________________________________________________________________ -->
 858 <div class="doc_subsubsection">
 859   <a name="--">Specifying positional options with hyphens</a>
 860 </div>
 861
 862 <div class="doc_text">
 863
 864 <p>Sometimes you may want to specify a value to your positional argument that
 865 starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file).  At
 866 first, you will have trouble doing this, because it will try to find an argument
 867 named '<tt>-foo</tt>', and will fail (and single quotes will not save you).
 868 Note that the system <tt>grep</tt> has the same problem:</p>
 869
 870 <div class="doc_code"><pre>
 871   $ spiffygrep '-foo' test.txt
 872   Unknown command line argument '-foo'.  Try: spiffygrep --help'
 873
 874   $ grep '-foo' test.txt
 875   grep: illegal option -- f
 876   grep: illegal option -- o
 877   grep: illegal option -- o
 878   Usage: grep -hblcnsviw pattern file . . .
 879 </pre></div>
 880
 881 <p>The solution for this problem is the same for both your tool and the system
 882 version: use the '<tt>--</tt>' marker.  When the user specifies '<tt>--</tt>' on
 883 the command line, it is telling the program that all options after the
 884 '<tt>--</tt>' should be treated as positional arguments, not options.  Thus, we
 885 can use it like this:</p>
 886
 887 <div class="doc_code"><pre>
 888   $ spiffygrep -- -foo test.txt
 889     ...output...
 890 </pre></div>
 891
 892 </div>
 893
 894 <!-- _______________________________________________________________________ -->
 895 <div class="doc_subsubsection">
 896   <a name="getPosition">Determining absolute position with getPosition()</a>
 897 </div>
 898 <div class="doc_text">
 899   <p>Sometimes an option can affect or modify the meaning of another option. For
 900   example, consider <tt>gcc</tt>'s <tt>-x LANG</tt> option. This tells
 901   <tt>gcc</tt> to ignore the suffix of subsequent positional arguments and force
 902   the file to be interpreted as if it contained source code in language
 903   <tt>LANG</tt>. In order to handle this properly , you need to know the
 904   absolute position of each argument, especially those in lists, so their
 905   interaction(s) can be applied correctly. This is also useful for options like
 906   <tt>-llibname</tt> which is actually a positional argument that starts with
 907   a dash.</p>
 908   <p>So, generally, the problem is that you have two <tt>cl::list</tt> variables
 909   that interact in some way. To ensure the correct interaction, you can use the
 910   <tt>cl::list::getPosition(optnum)</tt> method. This method returns the
 911   absolute position (as found on the command line) of the <tt>optnum</tt>
 912   item in the <tt>cl::list</tt>.</p>
 913   <p>The idiom for usage is like this:</p>
 914
 915   <div class="doc_code"><pre>
 916   static cl::list&lt;std::string&gt; Files(cl::Positional, cl::OneOrMore);
 917   static cl::listlt;std::string&gt; Libraries("l", cl::ZeroOrMore);
 918
 919   int main(int argc, char**argv) {
 920     // ...
 921     std::vector&lt;std::string&gt;::iterator fileIt = Files.begin();
 922     std::vector&lt;std::string&gt;::iterator libIt  = Libraries.begin();
 923     unsigned libPos = 0, filePos = 0;
 924     while ( 1 ) {
 925       if ( libIt != Libraries.end() )
 926         libPos = Libraries.getPosition( libIt - Libraries.begin() );
 927       else
 928         libPos = 0;
 929       if ( fileIt != Files.end() )
 930         filePos = Files.getPosition( fileIt - Files.begin() );
 931       else
 932         filePos = 0;
 933
 934       if ( filePos != 0 &amp;&amp; (libPos == 0 || filePos &lt; libPos) ) {
 935         // Source File Is next
 936         ++fileIt;
 937       }
 938       else if ( libPos != 0 &amp;&amp; (filePos == 0 || libPos &lt; filePos) ) {
 939         // Library is next
 940         ++libIt;
 941       }
 942       else
 943         break; // we're done with the list
 944     }
 945   }</pre></div>
 946
 947   <p>Note that, for compatibility reasons, the <tt>cl::opt</tt> also supports an
 948   <tt>unsigned getPosition()</tt> option that will provide the absolute position
 949   of that option. You can apply the same approach as above with a
 950   <tt>cl::opt</tt> and a <tt>cl::list</tt> option as you can with two lists.</p>
 951 </div>
 952
 953 <!-- _______________________________________________________________________ -->
 954 <div class="doc_subsubsection">
 955   <a name="cl::ConsumeAfter">The <tt>cl::ConsumeAfter</tt> modifier</a>
 956 </div>
 957
 958 <div class="doc_text">
 959
 960 <p>The <tt>cl::ConsumeAfter</tt> <a href="#formatting">formatting option</a> is
 961 used to construct programs that use "interpreter style" option processing.  With
 962 this style of option processing, all arguments specified after the last
 963 positional argument are treated as special interpreter arguments that are not
 964 interpreted by the command line argument.</p>
 965
 966 <p>As a concrete example, lets say we are developing a replacement for the
 967 standard Unix Bourne shell (<tt>/bin/sh</tt>).  To run <tt>/bin/sh</tt>, first
 968 you specify options to the shell itself (like <tt>-x</tt> which turns on trace
 969 output), then you specify the name of the script to run, then you specify
 970 arguments to the script.  These arguments to the script are parsed by the bourne
 971 shell command line option processor, but are not interpreted as options to the
 972 shell itself.  Using the CommandLine library, we would specify this as:</p>
 973
 974 <div class="doc_code"><pre>
 975 <a href="#cl::opt">cl::opt</a>&lt;string&gt; Script(<a href="#cl::Positional">cl::Positional</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;input script&gt;</i>"), <a href="#cl::init">cl::init</a>("-"));
 976 <a href="#cl::list">cl::list</a>&lt;string&gt;  Argv(<a href="#cl::ConsumeAfter">cl::ConsumeAfter</a>, <a href="#cl::desc">cl::desc</a>("<i>&lt;program arguments&gt;...</i>"));
 977 <a href="#cl::opt">cl::opt</a>&lt;bool&gt;    Trace("<i>x</i>", <a href="#cl::desc">cl::desc</a>("<i>Enable trace output</i>"));
 978 </pre></div>
 979
 980 <p>which automatically provides the help output:</p>
 981
 982 <div class="doc_code"><pre>
 983 USAGE: spiffysh [options] <b>&lt;input script&gt; &lt;program arguments&gt;...</b>
 984
 985 OPTIONS:
 986   -help - display available options (--help-hidden for more)
 987   <b>-x    - Enable trace output</b>
 988 </pre></div>
 989
 990 <p>At runtime, if we run our new shell replacement as `<tt>spiffysh -x test.sh
 991 -a -x -y bar</tt>', the <tt>Trace</tt> variable will be set to true, the
 992 <tt>Script</tt> variable will be set to "<tt>test.sh</tt>", and the
 993 <tt>Argv</tt> list will contain <tt>["-a", "-x", "-y", "bar"]</tt>, because they
 994 were specified after the last positional argument (which is the script
 995 name).</p>
 996
 997 <p>There are several limitations to when <tt>cl::ConsumeAfter</tt> options can
 998 be specified.  For example, only one <tt>cl::ConsumeAfter</tt> can be specified
 999 per program, there must be at least one <a href="#positional">positional
1000 argument</a> specified, there must not be any <a href="#cl::list">cl::list</a>
1001 positional arguments, and the <tt>cl::ConsumeAfter</tt> option should be a <a
1002 href="#cl::list">cl::list</a> option.</p>
1003
1004 </div>
1005
1006 <!-- ======================================================================= -->
1007 <div class="doc_subsection">
1008   <a name="storage">Internal vs External Storage</a>
1009 </div>
1010
1011 <div class="doc_text">
1012
1013 <p>By default, all command line options automatically hold the value that they
1014 parse from the command line.  This is very convenient in the common case,
1015 especially when combined with the ability to define command line options in the
1016 files that use them.  This is called the internal storage model.</p>
1017
1018 <p>Sometimes, however, it is nice to separate the command line option processing
1019 code from the storage of the value parsed.  For example, lets say that we have a
1020 '<tt>-debug</tt>' option that we would like to use to enable debug information
1021 across the entire body of our program.  In this case, the boolean value
1022 controlling the debug code should be globally accessable (in a header file, for
1023 example) yet the command line option processing code should not be exposed to
1024 all of these clients (requiring lots of .cpp files to #include
1025 <tt>CommandLine.h</tt>).</p>
1026
1027 <p>To do this, set up your .h file with your option, like this for example:</p>
1028
1029 <div class="doc_code">
1030 <pre>
1031 <i>// DebugFlag.h - Get access to the '-debug' command line option
1032 //
1033
1034 // DebugFlag - This boolean is set to true if the '-debug' command line option
1035 // is specified.  This should probably not be referenced directly, instead, use
1036 // the DEBUG macro below.
1037 //</i>
1038 extern bool DebugFlag;
1039
1040 <i>// DEBUG macro - This macro should be used by code to emit debug information.
1041 // In the '-debug' option is specified on the command line, and if this is a
1042 // debug build, then the code specified as the option to the macro will be
1043 // executed.  Otherwise it will not be.  Example:
1044 //
1045 // DOUT &lt;&lt; "Bitset contains: " &lt;&lt; Bitset &lt;&lt; "\n";
1046 //</i>
1047 <span class="doc_hilite">#ifdef NDEBUG
1048 #define DEBUG(X)
1049 #else
1050 #define DEBUG(X)</span> do { if (DebugFlag) { X; } } while (0)
1051 <span class="doc_hilite">#endif</span>
1052 </pre>
1053 </div>
1054
1055 <p>This allows clients to blissfully use the <tt>DEBUG()</tt> macro, or the
1056 <tt>DebugFlag</tt> explicitly if they want to.  Now we just need to be able to
1057 set the <tt>DebugFlag</tt> boolean when the option is set.  To do this, we pass
1058 an additial argument to our command line argument processor, and we specify
1059 where to fill in with the <a href="#cl::location">cl::location</a>
1060 attribute:</p>
1061
1062 <div class="doc_code">
1063 <pre>
1064 bool DebugFlag;                  <i>// the actual value</i>
1065 static <a href="#cl::opt">cl::opt</a>&lt;bool, true&gt;       <i>// The parser</i>
1066 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));
1067 </pre>
1068 </div>
1069
1070 <p>In the above example, we specify "<tt>true</tt>" as the second argument to
1071 the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the
1072 template should not maintain a copy of the value itself.  In addition to this,
1073 we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so
1074 that <tt>DebugFlag</tt> is automatically set.</p>
1075
1076 </div>
1077
1078 <!-- ======================================================================= -->
1079 <div class="doc_subsection">
1080   <a name="attributes">Option Attributes</a>
1081 </div>
1082
1083 <div class="doc_text">
1084
1085 <p>This section describes the basic attributes that you can specify on
1086 options.</p>
1087
1088 <ul>
1089
1090 <li>The option name attribute (which is required for all options, except <a
1091 href="#positional">positional options</a>) specifies what the option name is.
1092 This option is specified in simple double quotes:
1093
1094 <pre>
1095 <a href="#cl::opt">cl::opt</a>&lt;<b>bool</b>&gt; Quiet("<i>quiet</i>");
1096 </pre>
1097
1098 </li>
1099
1100 <li><a name="cl::desc">The <b><tt>cl::desc</tt></b></a> attribute specifies a
1101 description for the option to be shown in the <tt>--help</tt> output for the
1102 program.</li>
1103
1104 <li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b></a> attribute
1105 specifies a string that can be used to fine tune the <tt>--help</tt> output for
1106 a command line option.  Look <a href="#value_desc_example">here</a> for an
1107 example.</li>
1108
1109 <li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an
1110 inital value for a <a href="#cl::opt">scalar</a> option.  If this attribute is
1111 not specified then the command line option value defaults to the value created
1112 by the default constructor for the type. <b>Warning</b>: If you specify both
1113 <b><tt>cl::init</tt></b> and <b><tt>cl::location</tt></b> for an option,
1114 you must specify <b><tt>cl::location</tt></b> first, so that when the
1115 command-line parser sees <b><tt>cl::init</tt></b>, it knows where to put the
1116 initial value. (You will get an error at runtime if you don't put them in
1117 the right order.)</li>
1118
1119 <li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where to
1120 store the value for a parsed command line option if using external storage.  See
1121 the section on <a href="#storage">Internal vs External Storage</a> for more
1122 information.</li>
1123
1124 <li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute
1125 specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is
1126 an alias for.</li>
1127
1128 <li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies
1129 the string-to-value mapping to be used by the generic parser.  It takes a
1130 <b>clEnumValEnd terminated</b> list of (option, value, description) triplets
1131 that
1132 specify the option name, the value mapped to, and the description shown in the
1133 <tt>--help</tt> for the tool.  Because the generic parser is used most
1134 frequently with enum values, two macros are often useful:
1135
1136 <ol>
1137
1138 <li><a name="clEnumVal">The <b><tt>clEnumVal</tt></b></a> macro is used as a
1139 nice simple way to specify a triplet for an enum.  This macro automatically
1140 makes the option name be the same as the enum name.  The first option to the
1141 macro is the enum, the second is the description for the command line
1142 option.</li>
1143
1144 <li><a name="clEnumValN">The <b><tt>clEnumValN</tt></b></a> macro is used to
1145 specify macro options where the option name doesn't equal the enum name.  For
1146 this macro, the first argument is the enum value, the second is the flag name,
1147 and the second is the description.</li>
1148
1149 </ol>
1150
1151 You will get a compile time error if you try to use cl::values with a parser
1152 that does not support it.</li>
1153
1154 </ul>
1155
1156 </div>
1157
1158 <!-- ======================================================================= -->
1159 <div class="doc_subsection">
1160   <a name="modifiers">Option Modifiers</a>
1161 </div>
1162
1163 <div class="doc_text">
1164
1165 <p>Option modifiers are the flags and expressions that you pass into the
1166 constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
1167 href="#cl::list">cl::list</a></tt>.  These modifiers give you the ability to
1168 tweak how options are parsed and how <tt>--help</tt> output is generated to fit
1169 your application well.</p>
1170
1171 <p>These options fall into five main catagories:</p>
1172
1173 <ol>
1174 <li><a href="#hiding">Hiding an option from <tt>--help</tt> output</a></li>
1175 <li><a href="#numoccurrences">Controlling the number of occurrences
1176                              required and allowed</a></li>
1177 <li><a href="#valrequired">Controlling whether or not a value must be
1178                            specified</a></li>
1179 <li><a href="#formatting">Controlling other formatting options</a></li>
1180 <li><a href="#misc">Miscellaneous option modifiers</a></li>
1181 </ol>
1182
1183 <p>It is not possible to specify two options from the same catagory (you'll get
1184 a runtime error) to a single option, except for options in the miscellaneous
1185 catagory.  The CommandLine library specifies defaults for all of these settings
1186 that are the most useful in practice and the most common, which mean that you
1187 usually shouldn't have to worry about these.</p>
1188
1189 </div>
1190
1191 <!-- _______________________________________________________________________ -->
1192 <div class="doc_subsubsection">
1193   <a name="hiding">Hiding an option from <tt>--help</tt> output</a>
1194 </div>
1195
1196 <div class="doc_text">
1197
1198 <p>The <tt>cl::NotHidden</tt>, <tt>cl::Hidden</tt>, and
1199 <tt>cl::ReallyHidden</tt> modifiers are used to control whether or not an option
1200 appears in the <tt>--help</tt> and <tt>--help-hidden</tt> output for the
1201 compiled program:</p>
1202
1203 <ul>
1204
1205 <li><a name="cl::NotHidden">The <b><tt>cl::NotHidden</tt></b></a> modifier
1206 (which is the default for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
1207 href="#cl::list">cl::list</a></tt> options), indicates the option is to appear
1208 in both help listings.</li>
1209
1210 <li><a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b></a> modifier (which is the
1211 default for <tt><a href="#cl::alias">cl::alias</a></tt> options), indicates that
1212 the option should not appear in the <tt>--help</tt> output, but should appear in
1213 the <tt>--help-hidden</tt> output.</li>
1214
1215 <li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier,
1216 indicates that the option should not appear in any help output.</li>
1217
1218 </ul>
1219
1220 </div>
1221
1222 <!-- _______________________________________________________________________ -->
1223 <div class="doc_subsubsection">
1224   <a name="numoccurrences">Controlling the number of occurrences required and
1225   allowed</a>
1226 </div>
1227
1228 <div class="doc_text">
1229
1230 <p>This group of options is used to control how many time an option is allowed
1231 (or required) to be specified on the command line of your program.  Specifying a
1232 value for this setting allows the CommandLine library to do error checking for
1233 you.</p>
1234
1235 <p>The allowed values for this option group are:</p>
1236
1237 <ul>
1238
1239 <li><a name="cl::Optional">The <b><tt>cl::Optional</tt></b></a> modifier (which
1240 is the default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a
1241 href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will
1242 allow either zero or one occurrence of the option to be specified.</li>
1243
1244 <li><a name="cl::ZeroOrMore">The <b><tt>cl::ZeroOrMore</tt></b></a> modifier
1245 (which is the default for the <tt><a href="#cl::list">cl::list</a></tt> class)
1246 indicates that your program will allow the option to be specified zero or more
1247 times.</li>
1248
1249 <li><a name="cl::Required">The <b><tt>cl::Required</tt></b></a> modifier
1250 indicates that the specified option must be specified exactly one time.</li>
1251
1252 <li><a name="cl::OneOrMore">The <b><tt>cl::OneOrMore</tt></b></a> modifier
1253 indicates that the option must be specified at least one time.</li>
1254
1255 <li>The <b><tt>cl::ConsumeAfter</tt></b> modifier is described in the <a
1256 href="#positional">Positional arguments section</a></li>
1257
1258 </ul>
1259
1260 <p>If an option is not specified, then the value of the option is equal to the
1261 value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute.  If
1262 the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the
1263 option value is initialized with the default constructor for the data type.</p>
1264
1265 <p>If an option is specified multiple times for an option of the <tt><a
1266 href="#cl::opt">cl::opt</a></tt> class, only the last value will be
1267 retained.</p>
1268
1269 </div>
1270
1271 <!-- _______________________________________________________________________ -->
1272 <div class="doc_subsubsection">
1273   <a name="valrequired">Controlling whether or not a value must be specified</a>
1274 </div>
1275
1276 <div class="doc_text">
1277
1278 <p>This group of options is used to control whether or not the option allows a
1279 value to be present.  In the case of the CommandLine library, a value is either
1280 specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing
1281 string (e.g. '<tt>-o a.out</tt>').</p>
1282
1283 <p>The allowed values for this option group are:</p>
1284
1285 <ul>
1286
1287 <li><a name="cl::ValueOptional">The <b><tt>cl::ValueOptional</tt></b></a> modifier
1288 (which is the default for <tt>bool</tt> typed options) specifies that it is
1289 acceptable to have a value, or not.  A boolean argument can be enabled just by
1290 appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'.
1291 If an option is specified with this mode, it is illegal for the value to be
1292 provided without the equal sign.  Therefore '<tt>-foo true</tt>' is illegal.  To
1293 get this behavior, you must use the <a
1294 href="#cl::ValueRequired">cl::ValueRequired</a> modifier.</li>
1295
1296 <li><a name="cl::ValueRequired">The <b><tt>cl::ValueRequired</tt></b></a> modifier
1297 (which is the default for all other types except for <a
1298 href="#onealternative">unnamed alternatives using the generic parser</a>)
1299 specifies that a value must be provided.  This mode informs the command line
1300 library that if an option is not provides with an equal sign, that the next
1301 argument provided must be the value.  This allows things like '<tt>-o
1302 a.out</tt>' to work.</li>
1303
1304 <li><a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b></a>
1305 modifier (which is the default for <a href="#onealternative">unnamed
1306 alternatives using the generic parser</a>) indicates that it is a runtime error
1307 for the user to specify a value.  This can be provided to disallow users from
1308 providing options to boolean options (like '<tt>-foo=true</tt>').</li>
1309
1310 </ul>
1311
1312 <p>In general, the default values for this option group work just like you would
1313 want them to.  As mentioned above, you can specify the <a
1314 href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean
1315 argument to restrict your command line parser.  These options are mostly useful
1316 when <a href="#extensionguide">extending the library</a>.</p>
1317
1318 </div>
1319
1320 <!-- _______________________________________________________________________ -->
1321 <div class="doc_subsubsection">
1322   <a name="formatting">Controlling other formatting options</a>
1323 </div>
1324
1325 <div class="doc_text">
1326
1327 <p>The formatting option group is used to specify that the command line option
1328 has special abilities and is otherwise different from other command line
1329 arguments.  As usual, you can only specify at most one of these arguments.</p>
1330
1331 <ul>
1332
1333 <li><a name="cl::NormalFormatting">The <b><tt>cl::NormalFormatting</tt></b></a>
1334 modifier (which is the default all options) specifies that this option is
1335 "normal".</li>
1336
1337 <li><a name="cl::Positional">The <b><tt>cl::Positional</tt></b></a> modifier
1338 specifies that this is a positional argument, that does not have a command line
1339 option associated with it.  See the <a href="#positional">Positional
1340 Arguments</a> section for more information.</li>
1341
1342 <li>The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier
1343 specifies that this option is used to capture "interpreter style" arguments.  See <a href="#cl::ConsumeAfter">this section for more information</a>.</li>
1344
1345 <li><a name="cl::Prefix">The <b><tt>cl::Prefix</tt></b></a> modifier specifies
1346 that this option prefixes its value.  With 'Prefix' options, the equal sign does
1347 not separate the value from the option name specified. Instead, the value is
1348 everything after the prefix, including any equal sign if present. This is useful
1349 for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a
1350 linker tool or <tt>-DNAME=value</tt> in a compiler tool.   Here, the
1351 '<tt>l</tt>', '<tt>D</tt>' and '<tt>L</tt>' options are normal string (or list)
1352 options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b>
1353 modifier added to allow the CommandLine library to recognize them.  Note that
1354 <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> options must not have the
1355 <b><tt><a href="#cl::ValueDisallowed">cl::ValueDisallowed</a></tt></b> modifier
1356 specified.</li>
1357
1358 <li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used
1359 to implement unix style tools (like <tt>ls</tt>) that have lots of single letter
1360 arguments, but only require a single dash.  For example, the '<tt>ls -labF</tt>'
1361 command actually enables four different options, all of which are single
1362 letters.  Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b>
1363 options cannot have values.</li>
1364
1365 </ul>
1366
1367 <p>The CommandLine library does not restrict how you use the <b><tt><a
1368 href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a
1369 href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to
1370 specify ambiguous argument settings.  Thus, it is possible to have multiple
1371 letter options that are prefix or grouping options, and they will still work as
1372 designed.</p>
1373
1374 <p>To do this, the CommandLine library uses a greedy algorithm to parse the
1375 input option into (potentially multiple) prefix and grouping options.  The
1376 strategy basically looks like this:</p>
1377
1378 <div class="doc_code"><tt>parse(string OrigInput) {</tt>
1379
1380 <ol>
1381 <li><tt>string input = OrigInput;</tt>
1382 <li><tt>if (isOption(input)) return getOption(input).parse();</tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>// Normal option</i>
1383 <li><tt>while (!isOption(input) &amp;&amp; !input.empty()) input.pop_back();</tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>// Remove the last letter</i>
1384 <li><tt>if (input.empty()) return error();</tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>// No matching option</i>
1385 <li><tt>if (getOption(input).isPrefix())<br>
1386 &nbsp;&nbsp;return getOption(input).parse(input);</tt>
1387 <li><tt>while (!input.empty()) {&nbsp;&nbsp;&nbsp;&nbsp;<i>// Must be grouping options</i><br>
1388 &nbsp;&nbsp;getOption(input).parse();<br>
1389 &nbsp;&nbsp;OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());<br>
1390 &nbsp;&nbsp;input = OrigInput;<br>
1391 &nbsp;&nbsp;while (!isOption(input) &amp;&amp; !input.empty()) input.pop_back();<br>
1392 }</tt>
1393 <li><tt>if (!OrigInput.empty()) error();</tt></li>
1394 </ol>
1395
1396 <p><tt>}</tt></p>
1397 </div>
1398
1399 </div>
1400
1401 <!-- _______________________________________________________________________ -->
1402 <div class="doc_subsubsection">
1403   <a name="misc">Miscellaneous option modifiers</a>
1404 </div>
1405
1406 <div class="doc_text">
1407
1408 <p>The miscellaneous option modifiers are the only flags where you can specify
1409 more than one flag from the set: they are not mutually exclusive.  These flags
1410 specify boolean properties that modify the option.</p>
1411
1412 <ul>
1413
1414 <li><a name="cl::CommaSeparated">The <b><tt>cl::CommaSeparated</tt></b></a> modifier
1415 indicates that any commas specified for an option's value should be used to
1416 split the value up into multiple values for the option.  For example, these two
1417 options are equivalent when <tt>cl::CommaSeparated</tt> is specified:
1418 "<tt>-foo=a -foo=b -foo=c</tt>" and "<tt>-foo=a,b,c</tt>".  This option only
1419 makes sense to be used in a case where the option is allowed to accept one or
1420 more values (i.e. it is a <a href="#cl::list">cl::list</a> option).</li>
1421
1422 <li><a name="cl::PositionalEatsArgs">The
1423 <b><tt>cl::PositionalEatsArgs</tt></b></a> modifier (which only applies to
1424 positional arguments, and only makes sense for lists) indicates that positional
1425 argument should consume any strings after it (including strings that start with
1426 a "-") up until another recognized positional argument.  For example, if you
1427 have two "eating" positional arguments "<tt>pos1</tt>" and "<tt>pos2</tt>" the
1428 string "<tt>-pos1 -foo -bar baz -pos2 -bork</tt>" would cause the "<tt>-foo -bar
1429 -baz</tt>" strings to be applied to the "<tt>-pos1</tt>" option and the
1430 "<tt>-bork</tt>" string to be applied to the "<tt>-pos2</tt>" option.</li>
1431
1432 </ul>
1433
1434 <p>So far, these are the only two miscellaneous option modifiers.</p>
1435
1436 </div>
1437
1438 <!-- ======================================================================= -->
1439 <div class="doc_subsection">
1440   <a name="toplevel">Top-Level Classes and Functions</a>
1441 </div>
1442
1443 <div class="doc_text">
1444
1445 <p>Despite all of the built-in flexibility, the CommandLine option library
1446 really only consists of one function (<a
1447 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>)
1448 and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a
1449 href="#cl::list"><tt>cl::list</tt></a>, and <a
1450 href="#cl::alias"><tt>cl::alias</tt></a>.  This section describes these three
1451 classes in detail.</p>
1452
1453 </div>
1454
1455 <!-- _______________________________________________________________________ -->
1456 <div class="doc_subsubsection">
1457   <a name="cl::ParseCommandLineOptions">The <tt>cl::ParseCommandLineOptions</tt>
1458   function</a>
1459 </div>
1460
1461 <div class="doc_text">
1462
1463 <p>The <tt>cl::ParseCommandLineOptions</tt> function is designed to be called
1464 directly from <tt>main</tt>, and is used to fill in the values of all of the
1465 command line option variables once <tt>argc</tt> and <tt>argv</tt> are
1466 available.</p>
1467
1468 <p>The <tt>cl::ParseCommandLineOptions</tt> function requires two parameters
1469 (<tt>argc</tt> and <tt>argv</tt>), but may also take an optional third parameter
1470 which holds <a href="#description">additional extra text</a> to emit when the
1471 <tt>--help</tt> option is invoked.</p>
1472
1473 </div>
1474
1475 <!-- _______________________________________________________________________ -->
1476 <div class="doc_subsubsection">
1477   <a name="cl::ParseEnvironmentOptions">The <tt>cl::ParseEnvironmentOptions</tt>
1478   function</a>
1479 </div>
1480
1481 <div class="doc_text">
1482
1483 <p>The <tt>cl::ParseEnvironmentOptions</tt> function has mostly the same effects
1484 as <a
1485 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>,
1486 except that it is designed to take values for options from an environment
1487 variable, for those cases in which reading the command line is not convenient or
1488 not desired. It fills in the values of all the command line option variables
1489 just like <a
1490 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>
1491 does.</p>
1492
1493 <p>It takes three parameters: first, the name of the program (since
1494 <tt>argv</tt> may not be available, it can't just look in <tt>argv[0]</tt>),
1495 second, the name of the environment variable to examine, and third, the optional
1496 <a href="#description">additional extra text</a> to emit when the
1497 <tt>--help</tt> option is invoked.</p>
1498
1499 <p><tt>cl::ParseEnvironmentOptions</tt> will break the environment
1500 variable's value up into words and then process them using
1501 <a href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>.
1502 <b>Note:</b> Currently <tt>cl::ParseEnvironmentOptions</tt> does not support
1503 quoting, so an environment variable containing <tt>-option "foo bar"</tt> will
1504 be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>,
1505 which is different from what you would get from the shell with the same
1506 input.</p>
1507
1508 </div>
1509
1510 <!-- _______________________________________________________________________ -->
1511 <div class="doc_subsubsection">
1512   <a name="cl::SetVersionPrinter">The <tt>cl::SetVersionPrinter</tt>
1513   function</a>
1514 </div>
1515
1516 <div class="doc_text">
1517
1518 <p>The <tt>cl::SetVersionPrinter</tt> function is designed to be called
1519 directly from <tt>main</tt>, and <i>before</i>
1520 <tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges
1521 for a function to be called in response to the <tt>--version</tt> option instead
1522 of having the <tt>CommandLine</tt> library print out the usual version string
1523 for LLVM. This is useful for programs that are not part of LLVM but wish to use
1524 the <tt>CommandLine</tt> facilities. Such programs should just define a small
1525 function that takes no arguments and returns <tt>void</tt> and that prints out
1526 whatever version information is appropriate for the program. Pass the address
1527 of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be
1528 called when the <tt>--version</tt> option is given by the user.</p>
1529
1530 </div>
1531 <!-- _______________________________________________________________________ -->
1532 <div class="doc_subsubsection">
1533   <a name="cl::opt">The <tt>cl::opt</tt> class</a>
1534 </div>
1535
1536 <div class="doc_text">
1537
1538 <p>The <tt>cl::opt</tt> class is the class used to represent scalar command line
1539 options, and is the one used most of the time.  It is a templated class which
1540 can take up to three arguments (all except for the first have default values
1541 though):</p>
1542
1543 <div class="doc_code"><pre>
1544 <b>namespace</b> cl {
1545   <b>template</b> &lt;<b>class</b> DataType, <b>bool</b> ExternalStorage = <b>false</b>,
1546             <b>class</b> ParserClass = parser&lt;DataType&gt; &gt;
1547   <b>class</b> opt;
1548 }
1549 </pre></div>
1550
1551 <p>The first template argument specifies what underlying data type the command
1552 line argument is, and is used to select a default parser implementation.  The
1553 second template argument is used to specify whether the option should contain
1554 the storage for the option (the default) or whether external storage should be
1555 used to contain the value parsed for the option (see <a href="#storage">Internal
1556 vs External Storage</a> for more information).</p>
1557
1558 <p>The third template argument specifies which parser to use.  The default value
1559 selects an instantiation of the <tt>parser</tt> class based on the underlying
1560 data type of the option.  In general, this default works well for most
1561 applications, so this option is only used when using a <a
1562 href="#customparser">custom parser</a>.</p>
1563
1564 </div>
1565
1566 <!-- _______________________________________________________________________ -->
1567 <div class="doc_subsubsection">
1568   <a name="cl::list">The <tt>cl::list</tt> class</a>
1569 </div>
1570
1571 <div class="doc_text">
1572
1573 <p>The <tt>cl::list</tt> class is the class used to represent a list of command
1574 line options.  It too is a templated class which can take up to three
1575 arguments:</p>
1576
1577 <div class="doc_code"><pre>
1578 <b>namespace</b> cl {
1579   <b>template</b> &lt;<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
1580             <b>class</b> ParserClass = parser&lt;DataType&gt; &gt;
1581   <b>class</b> list;
1582 }
1583 </pre></div>
1584
1585 <p>This class works the exact same as the <a
1586 href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is
1587 the <b>type</b> of the external storage, not a boolean value.  For this class,
1588 the marker type '<tt>bool</tt>' is used to indicate that internal storage should
1589 be used.</p>
1590
1591 </div>
1592
1593 <!-- _______________________________________________________________________ -->
1594 <div class="doc_subsubsection">
1595   <a name="cl::bits">The <tt>cl::bits</tt> class</a>
1596 </div>
1597
1598 <div class="doc_text">
1599
1600 <p>The <tt>cl::bits</tt> class is the class used to represent a list of command
1601 line options in the form of a bit vector.  It is also a templated class which
1602 can take up to three arguments:</p>
1603
1604 <div class="doc_code"><pre>
1605 <b>namespace</b> cl {
1606   <b>template</b> &lt;<b>class</b> DataType, <b>class</b> Storage = <b>bool</b>,
1607             <b>class</b> ParserClass = parser&lt;DataType&gt; &gt;
1608   <b>class</b> bits;
1609 }
1610 </pre></div>
1611
1612 <p>This class works the exact same as the <a
1613 href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument
1614 must be of <b>type</b> <tt>unsigned</tt> if external storage is used.</p>
1615
1616 </div>
1617
1618 <!-- _______________________________________________________________________ -->
1619 <div class="doc_subsubsection">
1620   <a name="cl::alias">The <tt>cl::alias</tt> class</a>
1621 </div>
1622
1623 <div class="doc_text">
1624
1625 <p>The <tt>cl::alias</tt> class is a nontemplated class that is used to form
1626 aliases for other arguments.</p>
1627
1628 <div class="doc_code"><pre>
1629 <b>namespace</b> cl {
1630   <b>class</b> alias;
1631 }
1632 </pre></div>
1633
1634 <p>The <a href="#cl::aliasopt"><tt>cl::aliasopt</tt></a> attribute should be
1635 used to specify which option this is an alias for.  Alias arguments default to
1636 being <a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do
1637 the conversion from string to data.</p>
1638
1639 </div>
1640
1641 <!-- _______________________________________________________________________ -->
1642 <div class="doc_subsubsection">
1643   <a name="cl::extrahelp">The <tt>cl::extrahelp</tt> class</a>
1644 </div>
1645
1646 <div class="doc_text">
1647
1648 <p>The <tt>cl::extrahelp</tt> class is a nontemplated class that allows extra
1649 help text to be printed out for the <tt>--help</tt> option.</p>
1650
1651 <div class="doc_code"><pre>
1652 <b>namespace</b> cl {
1653   <b>struct</b> extrahelp;
1654 }
1655 </pre></div>
1656
1657 <p>To use the extrahelp, simply construct one with a <tt>const char*</tt>
1658 parameter to the constructor. The text passed to the constructor will be printed
1659 at the bottom of the help message, verbatim. Note that multiple
1660 <tt>cl::extrahelp</tt> <b>can</b> be used, but this practice is discouraged. If
1661 your tool needs to print additional help information, put all that help into a
1662 single <tt>cl::extrahelp</tt> instance.</p>
1663 <p>For example:</p>
1664 <div class="doc_code"><pre>
1665   cl::extrahelp("\nADDITIONAL HELP:\n\n  This is the extra help\n");
1666 </pre></div>
1667 </div>
1668
1669 <!-- ======================================================================= -->
1670 <div class="doc_subsection">
1671   <a name="builtinparsers">Builtin parsers</a>
1672 </div>
1673
1674 <div class="doc_text">
1675
1676 <p>Parsers control how the string value taken from the command line is
1677 translated into a typed value, suitable for use in a C++ program.  By default,
1678 the CommandLine library uses an instance of <tt>parser&lt;type&gt;</tt> if the
1679 command line option specifies that it uses values of type '<tt>type</tt>'.
1680 Because of this, custom option processing is specified with specializations of
1681 the '<tt>parser</tt>' class.</p>
1682
1683 <p>The CommandLine library provides the following builtin parser
1684 specializations, which are sufficient for most applications. It can, however,
1685 also be extended to work with new data types and new ways of interpreting the
1686 same data.  See the <a href="#customparser">Writing a Custom Parser</a> for more
1687 details on this type of library extension.</p>
1688
1689 <ul>
1690
1691 <li><a name="genericparser">The <b>generic <tt>parser&lt;t&gt;</tt> parser</b></a>
1692 can be used to map strings values to any data type, through the use of the <a
1693 href="#cl::values">cl::values</a> property, which specifies the mapping
1694 information.  The most common use of this parser is for parsing enum values,
1695 which allows you to use the CommandLine library for all of the error checking to
1696 make sure that only valid enum values are specified (as opposed to accepting
1697 arbitrary strings).  Despite this, however, the generic parser class can be used
1698 for any data type.</li>
1699
1700 <li><a name="boolparser">The <b><tt>parser&lt;bool&gt;</tt> specialization</b></a>
1701 is used to convert boolean strings to a boolean value.  Currently accepted
1702 strings are "<tt>true</tt>", "<tt>TRUE</tt>", "<tt>True</tt>", "<tt>1</tt>",
1703 "<tt>false</tt>", "<tt>FALSE</tt>", "<tt>False</tt>", and "<tt>0</tt>".</li>
1704
1705 <li><a name="stringparser">The <b><tt>parser&lt;string&gt;</tt>
1706 specialization</b></a> simply stores the parsed string into the string value
1707 specified.  No conversion or modification of the data is performed.</li>
1708
1709 <li><a name="intparser">The <b><tt>parser&lt;int&gt;</tt> specialization</b></a>
1710 uses the C <tt>strtol</tt> function to parse the string input.  As such, it will
1711 accept a decimal number (with an optional '+' or '-' prefix) which must start
1712 with a non-zero digit.  It accepts octal numbers, which are identified with a
1713 '<tt>0</tt>' prefix digit, and hexadecimal numbers with a prefix of
1714 '<tt>0x</tt>' or '<tt>0X</tt>'.</li>
1715
1716 <li><a name="doubleparser">The <b><tt>parser&lt;double&gt;</tt></b></a> and
1717 <b><tt>parser&lt;float&gt;</tt> specializations</b> use the standard C
1718 <tt>strtod</tt> function to convert floating point strings into floating point
1719 values.  As such, a broad range of string formats is supported, including
1720 exponential notation (ex: <tt>1.7e15</tt>) and properly supports locales.
1721 </li>
1722
1723 </ul>
1724
1725 </div>
1726
1727 <!-- *********************************************************************** -->
1728 <div class="doc_section">
1729   <a name="extensionguide">Extension Guide</a>
1730 </div>
1731 <!-- *********************************************************************** -->
1732
1733 <div class="doc_text">
1734
1735 <p>Although the CommandLine library has a lot of functionality built into it
1736 already (as discussed previously), one of its true strengths lie in its
1737 extensibility.  This section discusses how the CommandLine library works under
1738 the covers and illustrates how to do some simple, common, extensions.</p>
1739
1740 </div>
1741
1742 <!-- ======================================================================= -->
1743 <div class="doc_subsection">
1744   <a name="customparser">Writing a custom parser</a>
1745 </div>
1746
1747 <div class="doc_text">
1748
1749 <p>One of the simplest and most common extensions is the use of a custom parser.
1750 As <a href="#builtinparsers">discussed previously</a>, parsers are the portion
1751 of the CommandLine library that turns string input from the user into a
1752 particular parsed data type, validating the input in the process.</p>
1753
1754 <p>There are two ways to use a new parser:</p>
1755
1756 <ol>
1757
1758 <li>
1759
1760 <p>Specialize the <a href="#genericparser"><tt>cl::parser</tt></a> template for
1761 your custom data type.<p>
1762
1763 <p>This approach has the advantage that users of your custom data type will
1764 automatically use your custom parser whenever they define an option with a value
1765 type of your data type.  The disadvantage of this approach is that it doesn't
1766 work if your fundamental data type is something that is already supported.</p>
1767
1768 </li>
1769
1770 <li>
1771
1772 <p>Write an independent class, using it explicitly from options that need
1773 it.</p>
1774
1775 <p>This approach works well in situations where you would line to parse an
1776 option using special syntax for a not-very-special data-type.  The drawback of
1777 this approach is that users of your parser have to be aware that they are using
1778 your parser, instead of the builtin ones.</p>
1779
1780 </li>
1781
1782 </ol>
1783
1784 <p>To guide the discussion, we will discuss a custom parser that accepts file
1785 sizes, specified with an optional unit after the numeric size.  For example, we
1786 would like to parse "102kb", "41M", "1G" into the appropriate integer value.  In
1787 this case, the underlying data type we want to parse into is
1788 '<tt>unsigned</tt>'.  We choose approach #2 above because we don't want to make
1789 this the default for all <tt>unsigned</tt> options.</p>
1790
1791 <p>To start out, we declare our new <tt>FileSizeParser</tt> class:</p>
1792
1793 <div class="doc_code"><pre>
1794 <b>struct</b> FileSizeParser : <b>public</b> cl::basic_parser&lt;<b>unsigned</b>&gt; {
1795   <i>// parse - Return true on error.</i>
1796   <b>bool</b> parse(cl::Option &amp;O, <b>const char</b> *ArgName, <b>const</b> std::string &amp;ArgValue,
1797              <b>unsigned</b> &amp;Val);
1798 };
1799 </pre></div>
1800
1801 <p>Our new class inherits from the <tt>cl::basic_parser</tt> template class to
1802 fill in the default, boiler plate, code for us.  We give it the data type that
1803 we parse into (the last argument to the <tt>parse</tt> method so that clients of
1804 our custom parser know what object type to pass in to the parse method (here we
1805 declare that we parse into '<tt>unsigned</tt>' variables.</p>
1806
1807 <p>For most purposes, the only method that must be implemented in a custom
1808 parser is the <tt>parse</tt> method.  The <tt>parse</tt> method is called
1809 whenever the option is invoked, passing in the option itself, the option name,
1810 the string to parse, and a reference to a return value.  If the string to parse
1811 is not well formed, the parser should output an error message and return true.
1812 Otherwise it should return false and set '<tt>Val</tt>' to the parsed value.  In
1813 our example, we implement <tt>parse</tt> as:</p>
1814
1815 <div class="doc_code"><pre>
1816 <b>bool</b> FileSizeParser::parse(cl::Option &amp;O, <b>const char</b> *ArgName,
1817                            <b>const</b> std::string &amp;Arg, <b>unsigned</b> &amp;Val) {
1818   <b>const char</b> *ArgStart = Arg.c_str();
1819   <b>char</b> *End;
1820
1821   <i>// Parse integer part, leaving 'End' pointing to the first non-integer char</i>
1822   Val = (unsigned)strtol(ArgStart, &amp;End, 0);
1823
1824   <b>while</b> (1) {
1825     <b>switch</b> (*End++) {
1826     <b>case</b> 0: <b>return</b> false;   <i>// No error</i>
1827     <b>case</b> 'i':               <i>// Ignore the 'i' in KiB if people use that</i>
1828     <b>case</b> 'b': <b>case</b> 'B':     <i>// Ignore B suffix</i>
1829       <b>break</b>;
1830
1831     <b>case</b> 'g': <b>case</b> 'G': Val *= 1024*1024*1024; <b>break</b>;
1832     <b>case</b> 'm': <b>case</b> 'M': Val *= 1024*1024;      <b>break</b>;
1833     <b>case</b> 'k': <b>case</b> 'K': Val *= 1024;           <b>break</b>;
1834
1835     default:
1836       <i>// Print an error message if unrecognized character!</i>
1837       <b>return</b> O.error(": '" + Arg + "' value invalid for file size argument!");
1838     }
1839   }
1840 }
1841 </pre></div>
1842
1843 <p>This function implements a very simple parser for the kinds of strings we are
1844 interested in.  Although it has some holes (it allows "<tt>123KKK</tt>" for
1845 example), it is good enough for this example.  Note that we use the option
1846 itself to print out the error message (the <tt>error</tt> method always returns
1847 true) in order to get a nice error message (shown below).  Now that we have our
1848 parser class, we can use it like this:</p>
1849
1850 <div class="doc_code"><pre>
1851 <b>static</b> <a href="#cl::opt">cl::opt</a>&lt;<b>unsigned</b>, <b>false</b>, FileSizeParser&gt;
1852 MFS(<i>"max-file-size"</i>, <a href="#cl::desc">cl::desc</a>(<i>"Maximum file size to accept"</i>),
1853     <a href="#cl::value_desc">cl::value_desc</a>("<i>size</i>"));
1854 </pre></div>
1855
1856 <p>Which adds this to the output of our program:</p>
1857
1858 <div class="doc_code"><pre>
1859 OPTIONS:
1860   -help                 - display available options (--help-hidden for more)
1861   ...
1862   <b>-max-file-size=&lt;size&gt; - Maximum file size to accept</b>
1863 </pre></div>
1864
1865 <p>And we can test that our parse works correctly now (the test program just
1866 prints out the max-file-size argument value):</p>
1867
1868 <div class="doc_code"><pre>
1869 $ ./test
1870 MFS: 0
1871 $ ./test -max-file-size=123MB
1872 MFS: 128974848
1873 $ ./test -max-file-size=3G
1874 MFS: 3221225472
1875 $ ./test -max-file-size=dog
1876 -max-file-size option: 'dog' value invalid for file size argument!
1877 </pre></div>
1878
1879 <p>It looks like it works.  The error message that we get is nice and helpful,
1880 and we seem to accept reasonable file sizes.  This wraps up the "custom parser"
1881 tutorial.</p>
1882
1883 </div>
1884
1885 <!-- ======================================================================= -->
1886 <div class="doc_subsection">
1887   <a name="explotingexternal">Exploiting external storage</a>
1888 </div>
1889
1890 <div class="doc_text">
1891   <p>Several of the LLVM libraries define static <tt>cl::opt</tt> instances that
1892   will automatically be included in any program that links with that library.
1893   This is a feature. However, sometimes it is necessary to know the value of the
1894   command line option outside of the library. In these cases the library does or
1895   should provide an external storage location that is accessible to users of the
1896   library. Examples of this include the <tt>llvm::DebugFlag</tt> exported by the
1897   <tt>lib/Support/Debug.cpp</tt> file and the <tt>llvm::TimePassesIsEnabled</tt>
1898   flag exported by the <tt>lib/VMCore/Pass.cpp</tt> file.</p>
1899
1900 <p>TODO: complete this section</p>
1901
1902 </div>
1903
1904 <!-- ======================================================================= -->
1905 <div class="doc_subsection">
1906   <a name="dynamicopts">Dynamically adding command line options</a>
1907 </div>
1908
1909 <div class="doc_text">
1910
1911 <p>TODO: fill in this section</p>
1912
1913 </div>
1914
1915 <!-- *********************************************************************** -->
1916
1917 <hr>
1918 <address>
1919   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1920   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
1921   <a href="http://validator.w3.org/check/referer"><img
1922   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
1923
1924   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1925   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
1926   Last modified: $Date$
1927 </address>
1928
1929 </body>
1930 </html>