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 (a] 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 111 show you how to use it, and what it can do. The CommandLine library uses a 112 declarative approach to specifying the command line options that your program 113 takes. By default, these options declarations implicitly hold the value parsed 114 for the option declared (of course this <a href="#storage">can be 115 changed</a>).</p> 116 117 <p>Although there are a <b>lot</b> of command line argument parsing libraries 118 out there in many different languages, none of them fit well with what I needed. 119 By looking at the features and problems of other libraries, I designed the 120 CommandLine library to have the following features:</p> 121 122 <ol> 123 <li>Speed: The CommandLine library is very quick and uses little resources. The 124 parsing time of the library is directly proportional to the number of arguments 125 parsed, not the the number of options recognized. Additionally, command line 126 argument values are captured transparently into user defined global variables, 127 which can be accessed like any other variable (and with the same 128 performance).</li> 129 130 <li>Type Safe: As a user of CommandLine, you don't have to worry about 131 remembering the type of arguments that you want (is it an int? a string? a 132 bool? an enum?) and keep casting it around. Not only does this help prevent 133 error prone constructs, it also leads to dramatically cleaner source code.</li> 134 135 <li>No subclasses required: To use CommandLine, you instantiate variables that 136 correspond to the arguments that you would like to capture, you don't subclass a 137 parser. This means that you don't have to write <b>any</b> boilerplate 138 code.</li> 139 140 <li>Globally accessible: Libraries can specify command line arguments that are 141 automatically enabled in any tool that links to the library. This is possible 142 because the application doesn't have to keep a list of arguments to pass to 143 the parser. This also makes supporting <a href="#dynamicopts">dynamically 144 loaded options</a> trivial.</li> 145 146 <li>Cleaner: CommandLine supports enum and other types directly, meaning that 147 there is less error and more security built into the library. You don't have to 148 worry about whether your integral command line argument accidentally got 149 assigned a value that is not valid for your enum type.</li> 150 151 <li>Powerful: The CommandLine library supports many different types of 152 arguments, from simple <a href="#boolparser">boolean flags</a> to <a 153 href="#cl::opt">scalars arguments</a> (<a href="#stringparser">strings</a>, <a 154 href="#intparser">integers</a>, <a href="#genericparser">enums</a>, <a 155 href="#doubleparser">doubles</a>), to <a href="#cl::list">lists of 156 arguments</a>. This is possible because CommandLine is...</li> 157 158 <li>Extensible: It is very simple to add a new argument type to CommandLine. 159 Simply specify the parser that you want to use with the command line option when 160 you 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 163 that 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 165 tool. Additionally, it does most of the basic correctness checking for 166 you.</li> 167 168 <li>Capable: The CommandLine library can handle lots of different forms of 169 options often found in real programs. For example, <a 170 href="#positional">positional</a> arguments, <tt>ls</tt> style <a 171 href="#cl::Grouping">grouping</a> options (to allow processing '<tt>ls 172 -lad</tt>' naturally), <tt>ld</tt> style <a href="#cl::Prefix">prefix</a> 173 options (to parse '<tt>-lmalloc -L/usr/lib</tt>'), and <a 174 href="#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 179 your utility quickly and painlessly. Additionally it should be a simple 180 reference 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 182 href="mailto:sabre (a] 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 195 basic compiler tool. This is intended to show you how to jump into using the 196 CommandLine library in your own program, and show you some of the cool things it 197 can do.</p> 198 199 <p>To start out, you need to include the CommandLine header file into your 200 program:</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 207 program:</p> 208 209 <div class="doc_code"><pre> 210 int 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 217 declarations.</p> 218 219 <p>Now that you are ready to support command line arguments, we need to tell the 220 system which ones we want, and what type of arguments they are. The CommandLine 221 library uses a declarative syntax to model command line arguments with the 222 global variable declarations that capture the parsed values. This means that 223 for every command line option that you would like to support, there should be a 224 global variable declaration to capture the result. For example, in a compiler, 225 we would like to support the Unix-standard '<tt>-o <filename></tt>' option 226 to specify where to put the output. With the CommandLine library, this is 227 represented 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 235 capture the result of the "<tt>o</tt>" argument (first parameter). We specify 236 that this is a simple scalar option by using the "<tt><a 237 href="#cl::opt">cl::opt</a></tt>" template (as opposed to the <a 238 href="#list">"<tt>cl::list</tt> template</a>), and tell the CommandLine library 239 that 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 242 to output for the "<tt>-help</tt>" option. In this case, we get a line that 243 looks like this:</p> 244 245 <div class="doc_code"><pre> 246 USAGE: compiler [options] 247 248 OPTIONS: 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 255 real string in all contexts that a normal C++ string object may be used. For 256 example:</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 266 line option handling library, but the above example shows the general interface 267 to these options. The options can be specified in any order, and are specified 268 with helper functions like <a href="#cl::desc"><tt>cl::desc(...)</tt></a>, so 269 there are no positional dependencies to remember. The available options are 270 discussed 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 273 filename as well as an output filename, but we do not want the input filename to 274 be specified with a hyphen (ie, not <tt>-filename.c</tt>). To support this 275 style of argument, the CommandLine library allows for <a 276 href="#positional">positional</a> arguments to be specified for the program. 277 These positional arguments are filled with command line parameters that are not 278 in 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 285 treated as the input filename. Here we use the <tt><a 286 href="#cl::init">cl::init</a></tt> option to specify an initial value for the 287 command line option, which is used if the option is not specified (if you do not 288 specify a <tt><a href="#cl::init">cl::init</a></tt> modifier for an option, then 289 the default constructor for the data type is used to initialize the value). 290 Command line options default to being optional, so if we would like to require 291 that the user always specify an input filename, we would add the <tt><a 292 href="#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 300 in 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, 307 the CommandLine library will automatically issue an error if the argument is not 308 specified, which shifts all of the command line option verification code out of 309 your application into the library. This is just one example of how using flags 310 can alter the default behaviour of the library, on a per-option basis. By 311 adding one of the declarations above, the <tt>-help</tt> option synopsis is now 312 extended to:</p> 313 314 <div class="doc_code"><pre> 315 USAGE: compiler [options] <b><input file></b> 316 317 OPTIONS: 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 332 to support three boolean flags: "<tt>-f</tt>" to force writing binary output to 333 a terminal, "<tt>--quiet</tt>" to enable quiet mode, and "<tt>-q</tt>" for 334 backwards compatibility with some of our users. We can support these by 335 declaring 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 345 options. Note that the "<tt>-q</tt>" option is specified with the "<a 346 href="#cl::Hidden"><tt>cl::Hidden</tt></a>" flag. This modifier prevents it 347 from being shown by the standard "<tt>-help</tt>" output (note that it is still 348 shown in the "<tt>-help-hidden</tt>" output).</p> 349 350 <p>The CommandLine library uses a <a href="#builtinparsers">different parser</a> 351 for different data types. For example, in the string case, the argument passed 352 to the option is copied literally into the content of the string variable... we 353 obviously cannot do that in the boolean case, however, so we must use a smarter 354 parser. In the case of the boolean parser, it allows no options (in which case 355 it 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 357 following 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 367 the string values into boolean values, and rejects things like '<tt>compiler 368 -f=foo</tt>'. Similarly, the <a href="#doubleparser">float</a>, <a 369 href="#doubleparser">double</a>, and <a href="#intparser">int</a> parsers work 370 like you would expect, using the '<tt>strtol</tt>' and '<tt>strtod</tt>' C 371 library 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> 376 USAGE: compiler [options] <input file> 377 378 OPTIONS: 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> 388 USAGE: compiler [options] <input file> 389 390 OPTIONS: 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 399 href="#cl::opt">cl::opt</a></tt>' class to parse simple scalar command line 400 arguments. In addition to simple scalar arguments, the CommandLine library also 401 provides primitives to support CommandLine option <a href="#alias">aliases</a>, 402 and <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 414 quiet 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 423 condition, we can use the "<tt><a href="#cl::alias">cl::alias</a></tt>" class to make the "<tt>-q</tt>" 424 option an <b>alias</b> for the "<tt>-quiet</tt>" option, instead of providing 425 a 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 435 the <tt><a href="#cl::aliasopt">cl::aliasopt</a></tt> modifier) whenever it is 436 specified. Because aliases do not hold state, the only thing the program has to 437 query is the <tt>Quiet</tt> variable now. Another nice feature of aliases is 438 that they automatically hide themselves from the <tt>-help</tt> output 439 (although, again, they are still visible in the <tt>-help-hidden 440 output</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>" 451 can be used to specify an alternative name for any variable type, and has many 452 uses.</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 466 things 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 469 your own parser, as described in the <a href="#extensionguide">Extension 470 Guide</a>). This parser maps literal strings to whatever type is required, and 471 requires 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 474 optimizer, 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 476 options 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 481 catch 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 486 see 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 491 CommandLine library fill it in with the appropriate level directly, which is 492 used like this:</p> 493 494 <div class="doc_code"><pre> 495 enum 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 514 that are listed in the declaration (Note that the declaration list must be 515 terminated with the "<tt>clEnumValEnd</tt>" argument!). The CommandLine 516 library enforces 517 that the user can only specify one of the options, and it ensure that only valid 518 enum values can be specified. The "<tt>clEnumVal</tt>" macros ensure that the 519 command line arguments matched the enum values. With this option added, our 520 help output now is:</p> 521 522 <div class="doc_code"><pre> 523 USAGE: compiler [options] <input file> 524 525 OPTIONS: 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 538 enum names, because we probably don't want a enum definition named "<tt>g</tt>" 539 in our program. Because of this, we can alternatively write this example like 540 this:</p> 541 542 <div class="doc_code"><pre> 543 enum 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 561 can directly specify the name that the flag should get. In general a direct 562 mapping is nice, but sometimes you can't or don't want to preserve the mapping, 563 which 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 575 style in our compiler to specify different debug levels that can be used. 576 Instead of each debug level being its own switch, we want to support the 577 following 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 580 our optimization level flags, but we also specify an option name. For this 581 case, the code looks like this:</p> 582 583 <div class="doc_code"><pre> 584 enum 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 598 DebugLev</tt>", which works exactly the same way as before. The difference here 599 is just the interface exposed to the user of your program and the help output by 600 the "<tt>-help</tt>" option:</p> 601 602 <div class="doc_code"><pre> 603 USAGE: compiler [options] <input file> 604 605 OPTIONS: 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 622 the optimization level declaration is that the debug level declaration includes 623 an option name (<tt>"debug_level"</tt>), which automatically changes how the 624 library processes the argument. The CommandLine library supports both forms so 625 that 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, 637 lets get a little wild and crazy. Lets say that we want our optimizer to accept 638 a <b>list</b> of optimizations to perform, allowing duplicates. For example, we 639 might want to run: "<tt>compiler -dce -constprop -inline -dce -strip</tt>". In 640 this case, the order of the arguments and the number of appearances is very 641 important. This is what the "<tt><a href="#cl::list">cl::list</a></tt>" 642 template is for. First, start by defining an enum of the optimizations that you 643 would like to perform:</p> 644 645 <div class="doc_code"><pre> 646 enum 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 666 vector 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 677 completely general and may be used with any data types or other arguments that 678 you can use with the "<tt><a href="#cl::opt">cl::opt</a></tt>" template. One 679 especially useful way to use a list is to capture all of the positional 680 arguments together if there may be more than one specified. In the case of a 681 linker, for example, the linker takes several '<tt>.o</tt>' files, and needs to 682 capture 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 691 such, accessing the list is simple, just like above. In this example, we used 692 the <tt><a href="#cl::OneOrMore">cl::OneOrMore</a></tt> modifier to inform the 693 CommandLine 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 695 checking 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 707 gather information for enum values in a <b>bit vector</b>. The representation used by 708 the <a href="#bits"><tt>cl::bits</tt></a> class is an <tt>unsigned</tt> 709 integer. An enum value is represented by a 0/1 in the enum's ordinal value bit 710 position. 1 indicating that the enum was specified, 0 otherwise. As each 711 specified value is parsed, the resulting enum's bit is set in the option's bit 712 vector:</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 719 the 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 752 href="#bits"><tt>cl::bits</tt></a> option is equivalent to a <a 753 href="#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 766 information about what it does into the help output. The help output is styled 767 to look similar to a Unix <tt>man</tt> page, providing concise information about 768 a program. Unix <tt>man</tt> pages, however often have a description about what 769 the program does. To add this to your CommandLine program, simply pass a third 770 argument to the <a 771 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a> 772 call in main. This additional argument is then printed as the overview 773 information for your program, allowing you to include any additional information 774 that you want. For example:</p> 775 776 <div class="doc_code"><pre> 777 int 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 791 USAGE: compiler [options] <input file> 792 793 OPTIONS: 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 812 section will give you the detailed information you need to tune how command line 813 options work, as well as information on more "advanced" command line option 814 processing 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 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><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 836 replacement would look like this:</p> 837 838 <div class="doc_code"><pre> 839 USAGE: spiffygrep [options] <b><regular expression> <input file></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 <!-- _______________________________________________________________________ --> 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 862 starts with a hyphen (for example, searching for '<tt>-foo</tt>' in a file). At 863 first, you will have trouble doing this, because it will try to find an argument 864 named '<tt>-foo</tt>', and will fail (and single quotes will not save you). 865 Note 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 879 version: use the '<tt>--</tt>' marker. When the user specifies '<tt>--</tt>' on 880 the 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 882 can 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 958 used to construct programs that use "interpreter style" option processing. With 959 this style of option processing, all arguments specified after the last 960 positional argument are treated as special interpreter arguments that are not 961 interpreted by the command line argument.</p> 962 963 <p>As a concrete example, lets say we are developing a replacement for the 964 standard Unix Bourne shell (<tt>/bin/sh</tt>). To run <tt>/bin/sh</tt>, first 965 you specify options to the shell itself (like <tt>-x</tt> which turns on trace 966 output), then you specify the name of the script to run, then you specify 967 arguments to the script. These arguments to the script are parsed by the Bourne 968 shell command line option processor, but are not interpreted as options to the 969 shell 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> 980 USAGE: spiffysh [options] <b><input script> <program arguments>...</b> 981 982 OPTIONS: 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 991 were specified after the last positional argument (which is the script 992 name).</p> 993 994 <p>There are several limitations to when <tt>cl::ConsumeAfter</tt> options can 995 be specified. For example, only one <tt>cl::ConsumeAfter</tt> can be specified 996 per program, there must be at least one <a href="#positional">positional 997 argument</a> specified, there must not be any <a href="#cl::list">cl::list</a> 998 positional arguments, and the <tt>cl::ConsumeAfter</tt> option should be a <a 999 href="#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 1013 parse from the command line. This is very convenient in the common case, 1014 especially when combined with the ability to define command line options in the 1015 files 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 1018 code 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 1020 across the entire body of our program. In this case, the boolean value 1021 controlling the debug code should be globally accessible (in a header file, for 1022 example) yet the command line option processing code should not be exposed to 1023 all 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> 1037 extern 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 1053 set the <tt>DebugFlag</tt> boolean when the option is set. To do this, we pass 1054 an additional argument to our command line argument processor, and we specify 1055 where to fill in with the <a href="#cl::location">cl::location</a> 1056 attribute:</p> 1057 1058 <div class="doc_code"> 1059 <pre> 1060 bool DebugFlag; <i>// the actual value</i> 1061 static <a href="#cl::opt">cl::opt</a><bool, true> <i>// The parser</i> 1062 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)); 1063 </pre> 1064 </div> 1065 1066 <p>In the above example, we specify "<tt>true</tt>" as the second argument to 1067 the <tt><a href="#cl::opt">cl::opt</a></tt> template, indicating that the 1068 template should not maintain a copy of the value itself. In addition to this, 1069 we specify the <tt><a href="#cl::location">cl::location</a></tt> attribute, so 1070 that <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 1082 options.</p> 1083 1084 <ul> 1085 1086 <li>The option name attribute (which is required for all options, except <a 1087 href="#positional">positional options</a>) specifies what the option name is. 1088 This 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 1097 description for the option to be shown in the <tt>-help</tt> output for the 1098 program.</li> 1099 1100 <li><a name="cl::value_desc">The <b><tt>cl::value_desc</tt></b></a> attribute 1101 specifies a string that can be used to fine tune the <tt>-help</tt> output for 1102 a command line option. Look <a href="#value_desc_example">here</a> for an 1103 example.</li> 1104 1105 <li><a name="cl::init">The <b><tt>cl::init</tt></b></a> attribute specifies an 1106 initial value for a <a href="#cl::opt">scalar</a> option. If this attribute is 1107 not specified then the command line option value defaults to the value created 1108 by 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, 1110 you must specify <b><tt>cl::location</tt></b> first, so that when the 1111 command-line parser sees <b><tt>cl::init</tt></b>, it knows where to put the 1112 initial value. (You will get an error at runtime if you don't put them in 1113 the right order.)</li> 1114 1115 <li><a name="cl::location">The <b><tt>cl::location</tt></b></a> attribute where 1116 to store the value for a parsed command line option if using external storage. 1117 See the section on <a href="#storage">Internal vs External Storage</a> for more 1118 information.</li> 1119 1120 <li><a name="cl::aliasopt">The <b><tt>cl::aliasopt</tt></b></a> attribute 1121 specifies which option a <tt><a href="#cl::alias">cl::alias</a></tt> option is 1122 an alias for.</li> 1123 1124 <li><a name="cl::values">The <b><tt>cl::values</tt></b></a> attribute specifies 1125 the 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 1127 that 1128 specify 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 1130 frequently 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 1135 nice simple way to specify a triplet for an enum. This macro automatically 1136 makes the option name be the same as the enum name. The first option to the 1137 macro is the enum, the second is the description for the command line 1138 option.</li> 1139 1140 <li><a name="clEnumValN">The <b><tt>clEnumValN</tt></b></a> macro is used to 1141 specify macro options where the option name doesn't equal the enum name. For 1142 this macro, the first argument is the enum value, the second is the flag name, 1143 and the second is the description.</li> 1144 1145 </ol> 1146 1147 You will get a compile time error if you try to use cl::values with a parser 1148 that does not support it.</li> 1149 1150 <li><a name="cl::multi_val">The <b><tt>cl::multi_val</tt></b></a> 1151 attribute specifies that this option takes has multiple values 1152 (example: <tt>-sectalign segname sectname sectvalue</tt>). This 1153 attribute takes one unsigned argument - the number of values for the 1154 option. This attribute is valid only on <tt>cl::list</tt> options (and 1155 will fail with compile error if you try to use it with other option 1156 types). It is allowed to use all of the usual modifiers on 1157 multi-valued options (besides <tt>cl::ValueDisallowed</tt>, 1158 obviously).</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 1172 constructors for <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a 1173 href="#cl::list">cl::list</a></tt>. These modifiers give you the ability to 1174 tweak how options are parsed and how <tt>-help</tt> output is generated to fit 1175 your 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 1190 a runtime error) to a single option, except for options in the miscellaneous 1191 category. The CommandLine library specifies defaults for all of these settings 1192 that are the most useful in practice and the most common, which mean that you 1193 usually 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 1204 appears in the <tt>-help</tt> and <tt>-help-hidden</tt> output for the 1205 compiled 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 1211 href="#cl::list">cl::list</a></tt> options) indicates the option is to appear 1212 in both help listings.</li> 1213 1214 <li><a name="cl::Hidden">The <b><tt>cl::Hidden</tt></b></a> modifier (which is the 1215 default for <tt><a href="#cl::alias">cl::alias</a></tt> options) indicates that 1216 the option should not appear in the <tt>-help</tt> output, but should appear in 1217 the <tt>-help-hidden</tt> output.</li> 1218 1219 <li><a name="cl::ReallyHidden">The <b><tt>cl::ReallyHidden</tt></b></a> modifier 1220 indicates 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 1236 value for this setting allows the CommandLine library to do error checking for 1237 you.</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 1244 is the default for the <tt><a href="#cl::opt">cl::opt</a></tt> and <tt><a 1245 href="#cl::alias">cl::alias</a></tt> classes) indicates that your program will 1246 allow 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) 1250 indicates that your program will allow the option to be specified zero or more 1251 times.</li> 1252 1253 <li><a name="cl::Required">The <b><tt>cl::Required</tt></b></a> modifier 1254 indicates 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 1257 indicates 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 1260 href="#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 1265 value specified by the <tt><a href="#cl::init">cl::init</a></tt> attribute. If 1266 the <tt><a href="#cl::init">cl::init</a></tt> attribute is not specified, the 1267 option 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 1270 href="#cl::opt">cl::opt</a></tt> class, only the last value will be 1271 retained.</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 1283 value to be present. In the case of the CommandLine library, a value is either 1284 specified with an equal sign (e.g. '<tt>-index-depth=17</tt>') or as a trailing 1285 string (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 1293 acceptable to have a value, or not. A boolean argument can be enabled just by 1294 appearing on the command line, or it can have an explicit '<tt>-foo=true</tt>'. 1295 If an option is specified with this mode, it is illegal for the value to be 1296 provided without the equal sign. Therefore '<tt>-foo true</tt>' is illegal. To 1297 get this behavior, you must use the <a 1298 href="#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 1302 href="#onealternative">unnamed alternatives using the generic parser</a>) 1303 specifies that a value must be provided. This mode informs the command line 1304 library that if an option is not provides with an equal sign, that the next 1305 argument provided must be the value. This allows things like '<tt>-o 1306 a.out</tt>' to work.</li> 1307 1308 <li><a name="cl::ValueDisallowed">The <b><tt>cl::ValueDisallowed</tt></b></a> 1309 modifier (which is the default for <a href="#onealternative">unnamed 1310 alternatives using the generic parser</a>) indicates that it is a runtime error 1311 for the user to specify a value. This can be provided to disallow users from 1312 providing 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 1317 want them to. As mentioned above, you can specify the <a 1318 href="#cl::ValueDisallowed">cl::ValueDisallowed</a> modifier to a boolean 1319 argument to restrict your command line parser. These options are mostly useful 1320 when <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 1332 has special abilities and is otherwise different from other command line 1333 arguments. 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> 1338 modifier (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 1342 specifies that this is a positional argument that does not have a command line 1343 option associated with it. See the <a href="#positional">Positional 1344 Arguments</a> section for more information.</li> 1345 1346 <li>The <b><a href="#cl::ConsumeAfter"><tt>cl::ConsumeAfter</tt></a></b> modifier 1347 specifies 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 1350 that this option prefixes its value. With 'Prefix' options, the equal sign does 1351 not separate the value from the option name specified. Instead, the value is 1352 everything after the prefix, including any equal sign if present. This is useful 1353 for processing odd arguments like <tt>-lmalloc</tt> and <tt>-L/usr/lib</tt> in a 1354 linker 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) 1356 options, that have the <b><tt><a href="#cl::Prefix">cl::Prefix</a></tt></b> 1357 modifier 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 1360 specified.</li> 1361 1362 <li><a name="cl::Grouping">The <b><tt>cl::Grouping</tt></b></a> modifier is used 1363 to implement Unix-style tools (like <tt>ls</tt>) that have lots of single letter 1364 arguments, but only require a single dash. For example, the '<tt>ls -labF</tt>' 1365 command actually enables four different options, all of which are single 1366 letters. Note that <b><tt><a href="#cl::Grouping">cl::Grouping</a></tt></b> 1367 options cannot have values.</li> 1368 1369 </ul> 1370 1371 <p>The CommandLine library does not restrict how you use the <b><tt><a 1372 href="#cl::Prefix">cl::Prefix</a></tt></b> or <b><tt><a 1373 href="#cl::Grouping">cl::Grouping</a></tt></b> modifiers, but it is possible to 1374 specify ambiguous argument settings. Thus, it is possible to have multiple 1375 letter options that are prefix or grouping options, and they will still work as 1376 designed.</p> 1377 1378 <p>To do this, the CommandLine library uses a greedy algorithm to parse the 1379 input option into (potentially multiple) prefix and grouping options. The 1380 strategy 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 1413 more than one flag from the set: they are not mutually exclusive. These flags 1414 specify 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 1419 indicates that any commas specified for an option's value should be used to 1420 split the value up into multiple values for the option. For example, these two 1421 options 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 1423 makes sense to be used in a case where the option is allowed to accept one or 1424 more 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 1428 positional arguments, and only makes sense for lists) indicates that positional 1429 argument should consume any strings after it (including strings that start with 1430 a "-") up until another recognized positional argument. For example, if you 1431 have two "eating" positional arguments, "<tt>pos1</tt>" and "<tt>pos2</tt>", the 1432 string "<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 1437 used to handle unknown options. If there is at least one option with 1438 <tt>cl::Sink</tt> modifier specified, the parser passes 1439 unrecognized option strings to it as values instead of signaling an 1440 error. As with <tt>cl::CommaSeparated</tt>, this modifier 1441 only 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 1457 some older Unices have a relatively low limit on command-line 1458 length. It is therefore customary to use the so-called 'response 1459 files' to circumvent this restriction. These files are mentioned on 1460 the command-line (using the "@file") syntax. The program reads these 1461 files and inserts the contents into argv, thereby working around the 1462 command-line length limits. Response files are enabled by an optional 1463 fourth argument to 1464 <a href="#cl::ParseEnvironmentOptions"><tt>cl::ParseEnvironmentOptions</tt></a> 1465 and 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 1481 really only consists of one function (<a 1482 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>) 1483 and three main classes: <a href="#cl::opt"><tt>cl::opt</tt></a>, <a 1484 href="#cl::list"><tt>cl::list</tt></a>, and <a 1485 href="#cl::alias"><tt>cl::alias</tt></a>. This section describes these three 1486 classes 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 1497 directly from <tt>main</tt>, and is used to fill in the values of all of the 1498 command line option variables once <tt>argc</tt> and <tt>argv</tt> are 1499 available.</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 1503 which 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 1518 as <a 1519 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a>, 1520 except that it is designed to take values for options from an environment 1521 variable, for those cases in which reading the command line is not convenient or 1522 desired. It fills in the values of all the command line option variables just 1523 like <a 1524 href="#cl::ParseCommandLineOptions"><tt>cl::ParseCommandLineOptions</tt></a> 1525 does.</p> 1526 1527 <p>It takes four parameters: the name of the program (since <tt>argv</tt> may 1528 not be available, it can't just look in <tt>argv[0]</tt>), the name of the 1529 environment 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 1532 switch that controls whether <a href="#response">response files</a> 1533 should be read.</p> 1534 1535 <p><tt>cl::ParseEnvironmentOptions</tt> will break the environment 1536 variable'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 1539 quoting, so an environment variable containing <tt>-option "foo bar"</tt> will 1540 be parsed as three words, <tt>-option</tt>, <tt>"foo</tt>, and <tt>bar"</tt>, 1541 which is different from what you would get from the shell with the same 1542 input.</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 1555 directly from <tt>main</tt> and <i>before</i> 1556 <tt>cl::ParseCommandLineOptions</tt>. Its use is optional. It simply arranges 1557 for a function to be called in response to the <tt>--version</tt> option instead 1558 of having the <tt>CommandLine</tt> library print out the usual version string 1559 for LLVM. This is useful for programs that are not part of LLVM but wish to use 1560 the <tt>CommandLine</tt> facilities. Such programs should just define a small 1561 function that takes no arguments and returns <tt>void</tt> and that prints out 1562 whatever version information is appropriate for the program. Pass the address 1563 of that function to <tt>cl::SetVersionPrinter</tt> to arrange for it to be 1564 called 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 1575 options, and is the one used most of the time. It is a templated class which 1576 can take up to three arguments (all except for the first have default values 1577 though):</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 1588 line argument is, and is used to select a default parser implementation. The 1589 second template argument is used to specify whether the option should contain 1590 the storage for the option (the default) or whether external storage should be 1591 used to contain the value parsed for the option (see <a href="#storage">Internal 1592 vs External Storage</a> for more information).</p> 1593 1594 <p>The third template argument specifies which parser to use. The default value 1595 selects an instantiation of the <tt>parser</tt> class based on the underlying 1596 data type of the option. In general, this default works well for most 1597 applications, so this option is only used when using a <a 1598 href="#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 1610 line options. It too is a templated class which can take up to three 1611 arguments:</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 1622 href="#cl::opt"><tt>cl::opt</tt></a> class, except that the second argument is 1623 the <b>type</b> of the external storage, not a boolean value. For this class, 1624 the marker type '<tt>bool</tt>' is used to indicate that internal storage should 1625 be 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 1637 line options in the form of a bit vector. It is also a templated class which 1638 can 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 1649 href="#cl::opt"><tt>cl::lists</tt></a> class, except that the second argument 1650 must 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 1662 aliases 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 1671 used to specify which option this is an alias for. Alias arguments default to 1672 being <a href="#cl::Hidden">Hidden</a>, and use the aliased options parser to do 1673 the 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 1685 help 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> 1694 parameter to the constructor. The text passed to the constructor will be printed 1695 at 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 1697 your tool needs to print additional help information, put all that help into a 1698 single <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 1715 translated into a typed value, suitable for use in a C++ program. By default, 1716 the CommandLine library uses an instance of <tt>parser<type></tt> if the 1717 command line option specifies that it uses values of type '<tt>type</tt>'. 1718 Because of this, custom option processing is specified with specializations of 1719 the '<tt>parser</tt>' class.</p> 1720 1721 <p>The CommandLine library provides the following builtin parser 1722 specializations, which are sufficient for most applications. It can, however, 1723 also be extended to work with new data types and new ways of interpreting the 1724 same data. See the <a href="#customparser">Writing a Custom Parser</a> for more 1725 details 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> 1730 can be used to map strings values to any data type, through the use of the <a 1731 href="#cl::values">cl::values</a> property, which specifies the mapping 1732 information. The most common use of this parser is for parsing enum values, 1733 which allows you to use the CommandLine library for all of the error checking to 1734 make sure that only valid enum values are specified (as opposed to accepting 1735 arbitrary strings). Despite this, however, the generic parser class can be used 1736 for any data type.</li> 1737 1738 <li><a name="boolparser">The <b><tt>parser<bool></tt> specialization</b></a> 1739 is used to convert boolean strings to a boolean value. Currently accepted 1740 strings 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, 1745 but we also need to know whether the option was specified at all. boolOrDefault 1746 is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts 1747 the same strings as <b><tt>parser<bool></tt></b>.</li> 1748 1749 <li><a name="stringparser">The <b><tt>parser<string></tt> 1750 specialization</b></a> simply stores the parsed string into the string value 1751 specified. 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> 1754 uses the C <tt>strtol</tt> function to parse the string input. As such, it will 1755 accept a decimal number (with an optional '+' or '-' prefix) which must start 1756 with 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 1763 values. As such, a broad range of string formats is supported, including 1764 exponential 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 1782 already (as discussed previously), one of its true strengths lie in its 1783 extensibility. This section discusses how the CommandLine library works under 1784 the 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. 1794 As <a href="#builtinparsers">discussed previously</a>, parsers are the portion 1795 of the CommandLine library that turns string input from the user into a 1796 particular 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 1805 your custom data type.<p> 1806 1807 <p>This approach has the advantage that users of your custom data type will 1808 automatically use your custom parser whenever they define an option with a value 1809 type of your data type. The disadvantage of this approach is that it doesn't 1810 work 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 1817 it.</p> 1818 1819 <p>This approach works well in situations where you would line to parse an 1820 option using special syntax for a not-very-special data-type. The drawback of 1821 this approach is that users of your parser have to be aware that they are using 1822 your 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 1829 sizes, specified with an optional unit after the numeric size. For example, we 1830 would like to parse "102kb", "41M", "1G" into the appropriate integer value. In 1831 this 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 1833 this 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 1846 fill in the default, boiler plate code for us. We give it the data type that 1847 we parse into, the last argument to the <tt>parse</tt> method, so that clients of 1848 our custom parser know what object type to pass in to the parse method. (Here we 1849 declare 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 1852 parser is the <tt>parse</tt> method. The <tt>parse</tt> method is called 1853 whenever the option is invoked, passing in the option itself, the option name, 1854 the string to parse, and a reference to a return value. If the string to parse 1855 is not well-formed, the parser should output an error message and return true. 1856 Otherwise it should return false and set '<tt>Val</tt>' to the parsed value. In 1857 our 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 1888 interested in. Although it has some holes (it allows "<tt>123KKK</tt>" for 1889 example), it is good enough for this example. Note that we use the option 1890 itself to print out the error message (the <tt>error</tt> method always returns 1891 true) in order to get a nice error message (shown below). Now that we have our 1892 parser 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> 1896 MFS(<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> 1903 OPTIONS: 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 1910 prints out the max-file-size argument value):</p> 1911 1912 <div class="doc_code"><pre> 1913 $ ./test 1914 MFS: 0 1915 $ ./test -max-file-size=123MB 1916 MFS: 128974848 1917 $ ./test -max-file-size=3G 1918 MFS: 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, 1924 and we seem to accept reasonable file sizes. This wraps up the "custom parser" 1925 tutorial.</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 (a] nondot.org">Chris Lattner</a><br> 1971 <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br> 1972 Last modified: $Date$ 1973 </address> 1974 1975 </body> 1976 </html> 1977
