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