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