1754 lines · plain
1==============================2CommandLine 2.0 Library Manual3==============================4 5.. contents::6 :local:7 8Introduction9============10 11This document describes the CommandLine argument processing library. It will12show you how to use it, and what it can do. The CommandLine library uses a13declarative approach to specifying the command line options that your program14takes. By default, these options declarations implicitly hold the value parsed15for the option declared (of course this `can be changed`_).16 17Although there are a **lot** of command line argument parsing libraries out18there in many different languages, none of them fit well with what I needed. By19looking at the features and problems of other libraries, I designed the20CommandLine library to have the following features:21 22#. Speed: The CommandLine library is very quick and uses little resources. The23 parsing time of the library is directly proportional to the number of24 arguments parsed, not the number of options recognized. Additionally,25 command line argument values are captured transparently into user defined26 global variables, which can be accessed like any other variable (and with the27 same performance).28 29#. Type Safe: As a user of CommandLine, you don't have to worry about30 remembering the type of arguments that you want (is it an int? a string? a31 bool? an enum?) and keep casting it around. Not only does this help prevent32 error prone constructs, it also leads to dramatically cleaner source code.33 34#. No subclasses required: To use CommandLine, you instantiate variables that35 correspond to the arguments that you would like to capture, you don't36 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 are40 automatically enabled in any tool that links to the library. This is41 possible because the application doesn't have to keep a list of arguments to42 pass to the parser. This also makes supporting `dynamically loaded options`_43 trivial.44 45#. Cleaner: CommandLine supports enum and other types directly, meaning that46 there is less error and more security built into the library. You don't have47 to worry about whether your integral command line argument accidentally got48 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 is53 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 option57 when you declare it. `Custom parsers`_ are no problem.58 59#. Labor Saving: The CommandLine library cuts down on the amount of grunt work60 that you, the user, have to do. For example, it automatically provides a61 ``-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 of65 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 '``-lmalloc68 -L/usr/lib``'), and interpreter style options.69 70This document will hopefully let you jump in and start using CommandLine in your71utility quickly and painlessly. Additionally it should be a simple reference72manual to figure out how stuff works.73 74Quick Start Guide75=================76 77This section of the manual runs through a simple CommandLine'ification of a78basic compiler tool. This is intended to show you how to jump into using the79CommandLine library in your own program, and show you some of the cool things it80can 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 the100system which ones we want, and what type of arguments they are. The CommandLine101library uses a declarative syntax to model command line arguments with the102global variable declarations that capture the parsed values. This means that103for every command line option that you would like to support, there should be a104global variable declaration to capture the result. For example, in a compiler,105we would like to support the Unix-standard '``-o <filename>``' option to specify106where to put the output. With the CommandLine library, this is represented like107this: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 the117result of the "``o``" argument (first parameter). We specify that this is a118simple scalar option by using the "``cl::opt``" template (as opposed to the119"``cl::list``" template), and tell the CommandLine library that the data120type that we are parsing is a string.121 122The second and third parameters (which are optional) are used to specify what to123output for the "``-help``" option. In this case, we get a line that looks like124this:125 126::127 128 USAGE: compiler [options]129 130 OPTIONS:131 -h - Alias for -help132 -help - display available options (-help-hidden for more)133 -o <filename> - Specify output filename134 135Because we specified that the command line option should parse using the136``string`` data type, the variable declared is automatically usable as a real137string in all contexts that a normal C++ string object may be used. For138example: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 line148option handling library, but the above example shows the general interface to149these options. The options can be specified in any order, and are specified150with helper functions like `cl::desc(...)`_, so there are no positional151dependencies to remember. The available options are discussed in detail in the152`Reference Guide`_.153 154Continuing the example, we would like to have our compiler take an input155filename as well as an output filename, but we do not want the input filename to156be specified with a hyphen (ie, not ``-filename.c``). To support this style of157argument, the CommandLine library allows for `positional`_ arguments to be158specified for the program. These positional arguments are filled with command159line 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 treated167as the input filename. Here we use the `cl::init`_ option to specify an initial168value for the command line option, which is used if the option is not specified169(if you do not specify a `cl::init`_ modifier for an option, then the default170constructor for the data type is used to initialize the value). Command line171options default to being optional, so if we would like to require that the user172always specify an input filename, we would add the `cl::Required`_ flag, and we173could 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 in180any 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 will187automatically issue an error if the argument is not specified, which shifts all188of the command line option verification code out of your application into the189library. This is just one example of how using flags can alter the default190behaviour of the library, on a per-option basis. By adding one of the191declarations 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 -help199 -help - display available options (-help-hidden for more)200 -o <filename> - Specify output filename201 202... indicating that an input filename is expected.203 204Boolean Arguments205-----------------206 207In addition to input and output filenames, we would like the compiler example to208support three boolean flags: "``-f``" to force writing binary output to a209terminal, "``--quiet``" to enable quiet mode, and "``-q``" for backwards210compatibility with some of our users. We can support these by declaring options211of 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 variables220("``Force``", "``Quiet``", and "``Quiet2``") to recognize these options. Note221that the "``-q``" option is specified with the "`cl::Hidden`_" flag. This222modifier prevents it from being shown by the standard "``-help``" output (note223that 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 copied227literally into the content of the string variable... we obviously cannot do that228in the boolean case, however, so we must use a smarter parser. In the case of229the boolean parser, it allows no options (in which case it assigns the value of230true to the variable), or it allows the values "``true``" or "``false``" to be231specified, allowing any of the following inputs:232 233::234 235 compiler -f # No value, 'Force' == true236 compiler -f=true # Value specified, 'Force' == true237 compiler -f=TRUE # Value specified, 'Force' == true238 compiler -f=FALSE # Value specified, 'Force' == false239 240... you get the idea. The `bool parser`_ just turns the string values into241boolean values, and rejects things like '``compiler -f=foo``'. Similarly, the242`float`_, `double`_, and `int`_ parsers work like you would expect, using the243'``strtol``' and '``strtod``' C library calls to parse the string value into the244specified 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 terminals254 -o - Override output filename255 -quiet - Don't print informational messages256 -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 terminals266 -o - Override output filename267 -q - Don't print informational messages268 -quiet - Don't print informational messages269 -help - display available options (-help-hidden for more)270 271This brief example has shown you how to use the '`cl::opt`_' class to parse272simple scalar command line arguments. In addition to simple scalar arguments,273the CommandLine library also provides primitives to support CommandLine option274`aliases`_, and `lists`_ of options.275 276.. _aliases:277 278Argument Aliases279----------------280 281So far, the example works well, except for the fact that we need to check the282quiet 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 same291condition, we can use the "`cl::alias`_" class to make the "``-q``" option an292**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 only303thing the program has to query is the ``Quiet`` variable now. Another nice304feature 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 an316alternative 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 possibilities321----------------------------------------------------322 323So far we have seen how the CommandLine library handles builtin types like324``std::string``, ``bool`` and ``int``, but how does it handle things it doesn't325know about, like enums or '``int*``'s?326 327The answer is that it uses a table-driven generic parser (unless you specify328your own parser, as described in the `Extension Guide`_). This parser maps329literal strings to whatever type is required, and requires you to tell it what330this 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``". We334could easily implement this with boolean options like above, but there are335several 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 catch339 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 easily344 see if some level >= "``-O1``" is enabled.345 346To cope with these problems, we can use an enum value, and have the CommandLine347library 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, O3353 };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 the367"``OptLevel``" enum type. This variable can be assigned any of the values that368are listed in the declaration. The CommandLine library enforces that369the user can only specify one of the options, and it ensure that only valid enum370values can be specified. The "``clEnumVal``" macros ensure that the command371line arguments matched the enum values. With this option added, our help output372now is:373 374::375 376 USAGE: compiler [options] <input file>377 378 OPTIONS:379 Choose optimization level:380 -g - No optimizations, enable debugging381 -O1 - Enable trivial optimizations382 -O2 - Enable default optimizations383 -O3 - Enable expensive optimizations384 -f - Enable binary output on terminals385 -help - display available options (-help-hidden for more)386 -o <filename> - Specify output filename387 -quiet - Don't print informational messages388 389In this case, it is sort of awkward that flag names correspond directly to enum390names, because we probably don't want an enum definition named "``g``" in our391program. Because of this, we can alternatively write this example like this:392 393.. code-block:: c++394 395 enum OptLevel {396 Debug, O1, O2, O3397 };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 directly411specify 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 you413would use it.414 415Named Alternatives416------------------417 418Another useful argument form is a named alternative style. We shall use this419style 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 the421following 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 our424optimization 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, detailed431 };432 433 // Enable Debug Options to be specified on the command line434 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 "``enum441DebugLev``", which works exactly the same way as before. The difference here is442just the interface exposed to the user of your program and the help output by443the "``-help``" option:444 445::446 447 USAGE: compiler [options] <input file>448 449 OPTIONS:450 Choose optimization level:451 -g - No optimizations, enable debugging452 -O1 - Enable trivial optimizations453 -O2 - Enable default optimizations454 -O3 - Enable expensive optimizations455 -debug_level - Set the debugging level:456 =none - disable debug information457 =quick - enable quick debug information458 =detailed - enable detailed debug information459 -f - Enable binary output on terminals460 -help - display available options (-help-hidden for more)461 -o <filename> - Specify output filename462 -quiet - Don't print informational messages463 464Again, the only structural difference between the debug level declaration and465the optimization level declaration is that the debug level declaration includes466an option name (``"debug_level"``), which automatically changes how the library467processes the argument. The CommandLine library supports both forms so that you468can choose the form most appropriate for your application.469 470.. _lists:471 472Parsing a list of options473-------------------------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 accept477a **list** of optimizations to perform, allowing duplicates. For example, we478might want to run: "``compiler -dce -instsimplify -inline -dce -strip``". In this479case, the order of the arguments and the number of appearances is very480important. This is what the "``cl::list``" template is for. First, start by481defining 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, strip488 };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 type502"``std::vector<enum Opts>``". Thus, you can access it with standard vector503methods: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 with514any 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 the516positional arguments together if there may be more than one specified. In the517case of a linker, for example, the linker takes several '``.o``' files, and518needs 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, accessing527the list is simple, just like above. In this example, we used the528`cl::OneOrMore`_ modifier to inform the CommandLine library that it is an error529if the user does not specify any ``.o`` files on our command line. Again, this530just reduces the amount of checking we have to do.531 532Collecting options as a set of flags533------------------------------------534 535Instead of collecting sets of options in a list, it is also possible to gather536information for enum values in a **bit vector**. The representation used by the537`cl::bits`_ class is an ``unsigned`` integer. An enum value is represented by a5380/1 in the enum's ordinal value bit position. 1 indicating that the enum was539specified, 0 otherwise. As each specified value is parsed, the resulting enum's540bit 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 after547the 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 of577**type** ``unsigned``. In all other ways a `cl::bits`_ option is equivalent to a578`cl::list`_ option.579 580.. _additional extra text:581 582Adding freeform text to help output583-----------------------------------584 585As our program grows and becomes more mature, we may decide to put summary586information about what it does into the help output. The help output is styled587to look similar to a Unix ``man`` page, providing concise information about a588program. Unix ``man`` pages, however often have a description about what the589program does. To add this to your CommandLine program, simply pass a third590argument to the `cl::ParseCommandLineOptions`_ call in main. This additional591argument is then printed as the overview information for your program, allowing592you 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 example607 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 filename616 617.. _grouping options into categories:618 619Grouping options into categories620--------------------------------621 622If our program has a large number of options it may become difficult for users623of our tool to navigate the output of ``-help``. To alleviate this problem we624can put our options into categories. This can be done by declaring option625categories (`cl::OptionCategory`_ objects) and then placing our options into626these 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 is640declared. The output looks something like ::641 642 OVERVIEW: This is a small program to demo the LLVM CommandLine API643 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 is660declared, the command line option ``-help-list`` becomes visible which will661print the command line options as uncategorized list.662 663Note that Options that are not explicitly categorized will be placed in the664``cl::getGeneralCategory()`` category.665 666.. _Reference Guide:667 668Reference Guide669===============670 671Now that you know the basics of how to use the CommandLine library, this section672will give you the detailed information you need to tune how command line options673work, as well as information on more "advanced" command line option processing674capabilities.675 676.. _positional:677.. _positional argument:678.. _Positional Arguments:679.. _Positional arguments section:680.. _positional options:681 682Positional Arguments683--------------------684 685Positional arguments are those arguments that are not named, and are not686specified with a hyphen. Positional arguments should be used when an option is687specified by its position alone. For example, the standard Unix ``grep`` tool688takes a regular expression argument, and an optional filename to search through689(which defaults to standard input if a filename is not specified). Using the690CommandLine 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 grep698replacement 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 that711command line options will be ordered according to how they are listed in a .cpp712file, but will not have an ordering defined if the positional arguments are713defined in multiple .cpp files. The fix for this problem is simply to define714all of your positional arguments in one .cpp file.715 716Specifying positional options with hyphens717^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^718 719Sometimes you may want to specify a value to your positional argument that720starts with a hyphen (for example, searching for '``-foo``' in a file). At721first, you will have trouble doing this, because it will try to find an argument722named '``-foo``', and will fail (and single quotes will not save you). Note723that the system ``grep`` has the same problem:724 725::726 727 $ spiffygrep '-foo' test.txt728 Unknown command line argument '-foo'. Try: spiffygrep -help'729 730 $ grep '-foo' test.txt731 grep: illegal option -- f732 grep: illegal option -- o733 grep: illegal option -- o734 Usage: grep -hblcnsviw pattern file . . .735 736The solution for this problem is the same for both your tool and the system737version: use the '``--``' marker. When the user specifies '``--``' on the738command line, it is telling the program that all options after the '``--``'739should be treated as positional arguments, not options. Thus, we can use it740like this:741 742::743 744 $ spiffygrep -- -foo test.txt745 ...output...746 747Determining absolute position with getPosition()748^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^749 750Sometimes an option can affect or modify the meaning of another option. For751example, consider ``gcc``'s ``-x LANG`` option. This tells ``gcc`` to ignore the752suffix of subsequent positional arguments and force the file to be interpreted753as if it contained source code in language ``LANG``. In order to handle this754properly, you need to know the absolute position of each argument, especially755those in lists, so their interaction(s) can be applied correctly. This is also756useful for options like ``-llibname`` which is actually a positional argument757that starts with a dash.758 759So, generally, the problem is that you have two ``cl::list`` variables that760interact in some way. To ensure the correct interaction, you can use the761``cl::list::getPosition(optnum)`` method. This method returns the absolute762position (as found on the command line) of the ``optnum`` item in the763``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");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 else781 libPos = 0;782 if ( fileIt != Files.end() )783 filePos = Files.getPosition( fileIt - Files.begin() );784 else785 filePos = 0;786 787 if ( filePos != 0 && (libPos == 0 || filePos < libPos) ) {788 // Source File Is next789 ++fileIt;790 }791 else if ( libPos != 0 && (filePos == 0 || libPos < filePos) ) {792 // Library is next793 ++libIt;794 }795 else796 break; // we're done with the list797 }798 }799 800Note that, for compatibility reasons, the ``cl::opt`` also supports an801``unsigned getPosition()`` option that will provide the absolute position of802that option. You can apply the same approach as above with a ``cl::opt`` and a803``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`` modifier810^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^811 812The ``cl::ConsumeAfter`` `formatting option`_ is used to construct programs that813use "interpreter style" option processing. With this style of option814processing, all arguments specified after the last positional argument are815treated as special interpreter arguments that are not interpreted by the command816line argument.817 818As a concrete example, lets say we are developing a replacement for the standard819Unix Bourne shell (``/bin/sh``). To run ``/bin/sh``, first you specify options820to the shell itself (like ``-x`` which turns on trace output), then you specify821the name of the script to run, then you specify arguments to the script. These822arguments to the script are parsed by the Bourne shell command line option823processor, but are not interpreted as options to the shell itself. Using the824CommandLine 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 output841 842At runtime, if we run our new shell replacement as ```spiffysh -x test.sh -a -x843-y bar``', the ``Trace`` variable will be set to true, the ``Script`` variable844will be set to "``test.sh``", and the ``Argv`` list will contain ``["-a", "-x",845"-y", "bar"]``, because they were specified after the last positional argument846(which is the script name).847 848There are several limitations to when ``cl::ConsumeAfter`` options can be849specified. For example, only one ``cl::ConsumeAfter`` can be specified per850program, there must be at least one `positional argument`_ specified, there must851not be any `cl::list`_ positional arguments, and the ``cl::ConsumeAfter`` option852should be a `cl::list`_ option.853 854.. _can be changed:855.. _Internal vs External Storage:856 857Internal vs External Storage858----------------------------859 860By default, all command line options automatically hold the value that they861parse from the command line. This is very convenient in the common case,862especially when combined with the ability to define command line options in the863files that use them. This is called the internal storage model.864 865Sometimes, however, it is nice to separate the command line option processing866code from the storage of the value parsed. For example, lets say that we have a867'``-debug``' option that we would like to use to enable debug information across868the entire body of our program. In this case, the boolean value controlling the869debug code should be globally accessible (in a header file, for example) yet the870command line option processing code should not be exposed to all of these871clients (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 option878 //879 880 // DebugFlag - This boolean is set to true if the '-debug' command line option881 // is specified. This should probably not be referenced directly, instead, use882 // 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 a888 // debug build, then the code specified as the option to the macro will be889 // executed. Otherwise it will not be.890 #ifdef NDEBUG891 #define LLVM_DEBUG(X)892 #else893 #define LLVM_DEBUG(X) do { if (DebugFlag) { X; } } while (0)894 #endif895 896This allows clients to blissfully use the ``LLVM_DEBUG()`` macro, or the897``DebugFlag`` explicitly if they want to. Now we just need to be able to set898the ``DebugFlag`` boolean when the option is set. To do this, we pass an899additional argument to our command line argument processor, and we specify where900to fill in with the `cl::location`_ attribute:901 902.. code-block:: c++903 904 bool DebugFlag; // the actual value905 static cl::opt<bool, true> // The parser906 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 the909`cl::opt`_ template, indicating that the template should not maintain a copy of910the value itself. In addition to this, we specify the `cl::location`_911attribute, so that ``DebugFlag`` is automatically set.912 913Option Attributes914-----------------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, except919 `positional options`_) specifies what the option name is. This option is920 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 be929 shown in the ``-help`` output for the program. This attribute supports930 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 to935 fine tune the ``-help`` output for a command line option. Look `here`_ for an936 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 value942 defaults to the value created by the default constructor for the943 type.944 945 .. warning::946 947 If you specify both **cl::init** and **cl::location** for an option, you948 must specify **cl::location** first, so that when the command-line parser949 sees **cl::init**, it knows where to put the initial value. (You will get an950 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 command955 line option if using external storage. See the section on `Internal vs956 External Storage`_ for more information.957 958.. _cl::aliasopt:959 960* The **cl::aliasopt** attribute specifies which option a `cl::alias`_ option is961 an alias for.962 963.. _cl::values:964 965* The **cl::values** attribute specifies the string-to-value mapping to be used966 by the generic parser. It takes a list of (option, value, description)967 triplets that specify the option name, the value mapped to, and the968 description shown in the ``-help`` for the tool. Because the generic parser969 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 triplet972 for an enum. This macro automatically makes the option name be the same as973 the enum name. The first option to the macro is the enum, the second is974 the description for the command line option.975 976 #. The **clEnumValN** macro is used to specify macro options where the option977 name doesn't equal the enum name. For this macro, the first argument is978 the enum value, the second is the flag name, and the second is the979 description.980 981 You will get a compile time error if you try to use cl::values with a parser982 that does not support it.983 984.. _cl::multi_val:985 986* The **cl::multi_val** attribute specifies that this option takes has multiple987 values (example: ``-sectalign segname sectname sectvalue``). This attribute988 takes one unsigned argument - the number of values for the option. This989 attribute is valid only on ``cl::list`` options (and will fail with compile990 error if you try to use it with other option types). It is allowed to use all991 of the usual modifiers on multi-valued options (besides992 ``cl::ValueDisallowed``, obviously).993 994.. _cl::cat:995 996* The **cl::cat** attribute specifies the option category that the option997 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 is1002 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 fire1005 once for each value. This could be used to validate combinations or1006 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 Modifiers1025----------------1026 1027Option modifiers are the flags and expressions that you pass into the1028constructors for `cl::opt`_ and `cl::list`_. These modifiers give you the1029ability to tweak how options are parsed and how ``-help`` output is generated to1030fit your application well.1031 1032These options fall into five main categories:1033 1034#. Hiding an option from ``-help`` output1035 1036#. Controlling the number of occurrences required and allowed1037 1038#. Controlling whether or not a value must be specified1039 1040#. Controlling other formatting options1041 1042#. Miscellaneous option modifiers1043 1044It is not possible to specify two options from the same category (you'll get a1045runtime error) to a single option, except for options in the miscellaneous1046category. The CommandLine library specifies defaults for all of these settings1047that are the most useful in practice and the most common, which mean that you1048usually shouldn't have to worry about these.1049 1050Hiding an option from ``-help`` output1051^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1052 1053The ``cl::NotHidden``, ``cl::Hidden``, and ``cl::ReallyHidden`` modifiers are1054used to control whether or not an option appears in the ``-help`` and1055``-help-hidden`` output for the compiled program:1056 1057.. _cl::NotHidden:1058 1059* The **cl::NotHidden** modifier (which is the default for `cl::opt`_ and1060 `cl::list`_ options) indicates the option is to appear in both help1061 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, but1067 should appear in the ``-help-hidden`` output.1068 1069.. _cl::ReallyHidden:1070 1071* The **cl::ReallyHidden** modifier indicates that the option should not appear1072 in any help output.1073 1074Controlling the number of occurrences required and allowed1075^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1076 1077This group of options is used to control how many time an option is allowed (or1078required) to be specified on the command line of your program. Specifying a1079value for this setting allows the CommandLine library to do error checking for1080you.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`_ and1087 `cl::alias`_ classes) indicates that your program will allow either zero or1088 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 zero1094 or more times.1095 1096.. _cl::Required:1097 1098* The **cl::Required** modifier indicates that the specified option must be1099 specified exactly one time.1100 1101.. _cl::OneOrMore:1102 1103* The **cl::OneOrMore** modifier indicates that the option must be specified at1104 least one time.1105 1106* The **cl::ConsumeAfter** modifier is described in the `Positional arguments1107 section`_.1108 1109If an option is not specified, then the value of the option is equal to the1110value specified by the `cl::init`_ attribute. If the ``cl::init`` attribute is1111not specified, the option value is initialized with the default constructor for1112the 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 specified1118^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1119 1120This group of options is used to control whether or not the option allows a1121value to be present. In the case of the CommandLine library, a value is either1122specified with an equal sign (e.g. '``-index-depth=17``') or as a trailing1123string (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`` typed1130 options) specifies that it is acceptable to have a value, or not. A boolean1131 argument can be enabled just by appearing on the command line, or it can have1132 an explicit '``-foo=true``'. If an option is specified with this mode, it is1133 illegal for the value to be provided without the equal sign. Therefore1134 '``-foo true``' is illegal. To get this behavior, you must use1135 the `cl::ValueRequired`_ modifier.1136 1137.. _cl::ValueRequired:1138 1139* The **cl::ValueRequired** modifier (which is the default for all other types1140 except for `unnamed alternatives using the generic parser`_) specifies that a1141 value must be provided. This mode informs the command line library that if an1142 option is not provides with an equal sign, that the next argument provided1143 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 `unnamed1148 alternatives using the generic parser`_) indicates that it is a runtime error1149 for the user to specify a value. This can be provided to disallow users from1150 providing options to boolean options (like '``-foo=true``').1151 1152In general, the default values for this option group work just like you would1153want them to. As mentioned above, you can specify the `cl::ValueDisallowed`_1154modifier to a boolean argument to restrict your command line parser. These1155options are mostly useful when `extending the library`_.1156 1157.. _formatting option:1158 1159Controlling other formatting options1160^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1161 1162The formatting option group is used to specify that the command line option has1163special 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 argument1174 that does not have a command line option associated with it. See the1175 `Positional Arguments`_ section for more information.1176 1177* The **cl::ConsumeAfter** modifier specifies that this option is used to1178 capture "interpreter style" arguments. See `this section for more1179 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 the1186 option name specified. Instead, the value is everything after the prefix,1187 including any equal sign if present. This is useful for processing odd1188 arguments like ``-lmalloc`` and ``-L/usr/lib`` in a linker tool or1189 ``-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 that1192 **cl::Prefix** options must not have the **cl::ValueDisallowed** modifier1193 specified.1194 1195.. _grouping:1196.. _cl::Grouping:1197 1198Controlling options grouping1199^^^^^^^^^^^^^^^^^^^^^^^^^^^^1200 1201The **cl::Grouping** modifier can be combined with any formatting types except1202for `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 used1208separately or at the end of the groups. For `cl::ValueRequired`_, it is1209a 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** or1212**cl::Grouping** modifiers, but it is possible to specify ambiguous argument1213settings. Thus, it is possible to have multiple letter options that are prefix1214or grouping options, and they will still work as designed.1215 1216To do this, the CommandLine library uses a greedy algorithm to parse the input1217option into (potentially multiple) prefix and grouping options. The strategy1218basically 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 option1226 3. while (!Input.empty() && !isOption(Input)) Input.pop_back(); // Remove the last letter1227 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 = MaybeValue1237 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 modifiers1246^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1247 1248The miscellaneous option modifiers are the only flags where you can specify more1249than one flag from the set: they are not mutually exclusive. These flags1250specify boolean properties that modify the option.1251 1252.. _cl::CommaSeparated:1253 1254* The **cl::CommaSeparated** modifier indicates that any commas specified for an1255 option's value should be used to split the value up into multiple values for1256 the option. For example, these two options are equivalent when1257 ``cl::CommaSeparated`` is specified: "``-foo=a -foo=b -foo=c``" and1258 "``-foo=a,b,c``". This option only makes sense to be used in a case where the1259 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 a1265 default that can be overridden by application-specific parsers. For example,1266 the ``-help`` alias, ``-h``, is registered this way, so it can be overridden1267 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 positional1273 arguments, and only makes sense for lists) indicates that positional argument1274 should consume any strings after it (including strings that start with a "-")1275 up until another recognized positional argument. For example, if you have two1276 "eating" positional arguments, "``pos1``" and "``pos2``", the string "``-pos11277 -foo -bar baz -pos2 -bork``" would cause the "``-foo -bar -baz``" strings to1278 be applied to the "``-pos1``" option and the "``-bork``" string to be applied1279 to the "``-pos2``" option.1280 1281.. _cl::Sink:1282 1283* The **cl::Sink** modifier is used to handle unknown options. If there is at1284 least one option with ``cl::Sink`` modifier specified, the parser passes1285 unrecognized option strings to it as values instead of signaling an error. As1286 with ``cl::CommaSeparated``, this modifier only makes sense with a `cl::list`_1287 option.1288 1289.. _response files:1290 1291Response files1292^^^^^^^^^^^^^^1293 1294Some systems, such as certain variants of Microsoft Windows and some older1295Unices have a relatively low limit on command-line length. It is therefore1296customary to use the so-called 'response files' to circumvent this1297restriction. 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 Functions1302-------------------------------1303 1304Despite all of the built-in flexibility, the CommandLine option library really1305only consists of one function `cl::ParseCommandLineOptions`_ and three main1306classes: `cl::opt`_, `cl::list`_, and `cl::alias`_. This section describes1307these three classes in detail.1308 1309.. _cl::getRegisteredOptions:1310 1311The ``cl::getRegisteredOptions`` function1312^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1313 1314The ``cl::getRegisteredOptions`` function is designed to give a programmer1315access to declared non-positional command line options so that how they appear1316in ``-help`` can be modified prior to calling `cl::ParseCommandLineOptions`_.1317Note this method should not be called during any static initialisation because1318it cannot be guaranteed that all options will have been initialised. Hence it1319should be called from ``main``.1320 1321This function can be used to gain access to options declared in libraries that1322the tool writer may not have direct access to.1323 1324The function retrieves a :ref:`StringMap <dss_stringmap>` that maps the option1325string (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 category1338 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 see1343 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-version1347 assert(Map.count("version") > 0);1348 Map["version"]->setArgStr("show-version");1349 1350 //Change --help description1351 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`` function1362^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1363 1364The ``cl::ParseCommandLineOptions`` function is designed to be called directly1365from ``main``, and is used to fill in the values of all of the command line1366option 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 holds1370`additional extra text`_ to emit when the ``-help`` option is invoked.1371 1372The ``cl::SetVersionPrinter`` function1373^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1374 1375The ``cl::SetVersionPrinter`` function is designed to be called directly from1376``main`` and *before* ``cl::ParseCommandLineOptions``. Its use is optional. It1377simply arranges for a function to be called in response to the ``--version``1378option instead of having the ``CommandLine`` library print out the usual version1379string for LLVM. This is useful for programs that are not part of LLVM but wish1380to use the ``CommandLine`` facilities. Such programs should just define a small1381function that takes no arguments and returns ``void`` and that prints out1382whatever version information is appropriate for the program. Pass the address of1383that function to ``cl::SetVersionPrinter`` to arrange for it to be called when1384the ``--version`` option is given by the user.1385 1386.. _cl::opt:1387.. _scalar:1388 1389The ``cl::opt`` class1390^^^^^^^^^^^^^^^^^^^^^1391 1392The ``cl::opt`` class is the class used to represent scalar command line1393options, and is the one used most of the time. It is a templated class which1394can take up to three arguments (all except for the first have default values1395though):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 line1406argument is, and is used to select a default parser implementation. The second1407template argument is used to specify whether the option should contain the1408storage for the option (the default) or whether external storage should be used1409to 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 value1413selects an instantiation of the ``parser`` class based on the underlying data1414type 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`` class1421^^^^^^^^^^^^^^^^^^^^^^1422 1423The ``cl::list`` class is the class used to represent a list of command line1424options. 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 second1435argument is the **type** of the external storage, not a boolean value. For this1436class, the marker type '``bool``' is used to indicate that internal storage1437should be used.1438 1439.. _cl::bits:1440 1441The ``cl::bits`` class1442^^^^^^^^^^^^^^^^^^^^^^1443 1444The ``cl::bits`` class is the class used to represent a list of command line1445options in the form of a bit vector. It is also a templated class which can1446take 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 second1457argument must be of **type** ``unsigned`` if external storage is used.1458 1459.. _cl::alias:1460 1461The ``cl::alias`` class1462^^^^^^^^^^^^^^^^^^^^^^^1463 1464The ``cl::alias`` class is a nontemplated class that is used to form aliases for1465other 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 an1474alias for. Alias arguments default to being `cl::Hidden`_, and use the aliased1475options parser to do the conversion from string to data.1476 1477.. _cl::extrahelp:1478 1479The ``cl::extrahelp`` class1480^^^^^^^^^^^^^^^^^^^^^^^^^^^1481 1482The ``cl::extrahelp`` class is a nontemplated class that allows extra help text1483to 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 to1492the constructor. The text passed to the constructor will be printed at the1493bottom of the help message, verbatim. Note that multiple ``cl::extrahelp``1494**can** be used, but this practice is discouraged. If your tool needs to print1495additional 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`` class1507^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^1508 1509The ``cl::OptionCategory`` class is a simple class for declaring1510option 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 are1519passed to the constructor as ``const char*``.1520 1521Note that declaring an option category and associating it with an option before1522parsing options (e.g. statically) will change the output of ``-help`` from1523uncategorized to categorized. If an option category is declared but not1524associated with an option then it will be hidden from the output of ``-help``.1525 1526.. _different parser:1527.. _discussed previously:1528 1529Builtin parsers1530---------------1531 1532Parsers control how the string value taken from the command line is translated1533into a typed value, suitable for use in a C++ program. By default, the1534CommandLine library uses an instance of ``parser<type>`` if the command line1535option specifies that it uses values of type '``type``'. Because of this,1536custom option processing is specified with specializations of the '``parser``'1537class.1538 1539The CommandLine library provides the following builtin parser specializations,1540which are sufficient for most applications. It can, however, also be extended to1541work with new data types and new ways of interpreting the same data. See the1542`Writing a Custom Parser`_ for more details on this type of library extension.1543 1544.. _enums:1545.. _cl::parser:1546 1547* The generic ``parser<t>`` parser can be used to map strings values to any data1548 type, through the use of the `cl::values`_ property, which specifies the1549 mapping information. The most common use of this parser is for parsing enum1550 values, which allows you to use the CommandLine library for all of the error1551 checking to make sure that only valid enum values are specified (as opposed to1552 accepting arbitrary strings). Despite this, however, the generic parser class1553 can be used for any data type.1554 1555.. _boolean flags:1556.. _bool parser:1557 1558* The **parser<bool> specialization** is used to convert boolean strings to a1559 boolean value. Currently accepted strings are "``true``", "``TRUE``",1560 "``True``", "``1``", "``false``", "``FALSE``", "``False``", and "``0``".1561 1562* The **parser<boolOrDefault> specialization** is used for cases where the value1563 is boolean, but we also need to know whether the option was specified at all.1564 boolOrDefault is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE.1565 This parser accepts the same strings as **``parser<bool>``**.1566 1567.. _strings:1568 1569* The **parser<string> specialization** simply stores the parsed string into the1570 string value specified. No conversion or modification of the data is1571 performed.1572 1573.. _integers:1574.. _int:1575 1576* The **parser<int> specialization** uses the C ``strtol`` function to parse the1577 string input. As such, it will accept a decimal number (with an optional '+'1578 or '-' prefix) which must start with a non-zero digit. It accepts octal1579 numbers, which are identified with a '``0``' prefix digit, and hexadecimal1580 numbers with a prefix of '``0x``' or '``0X``'.1581 1582.. _doubles:1583.. _float:1584.. _double:1585 1586* The **parser<double>** and **parser<float> specializations** use the standard1587 C ``strtod`` function to convert floating point strings into floating point1588 values. As such, a broad range of string formats is supported, including1589 exponential notation (ex: ``1.7e15``) and properly supports locales.1590 1591.. _Extension Guide:1592.. _extending the library:1593 1594Extension Guide1595===============1596 1597Although the CommandLine library has a lot of functionality built into it1598already (as discussed previously), one of its true strengths lie in its1599extensibility. This section discusses how the CommandLine library works under1600the covers and illustrates how to do some simple, common, extensions.1601 1602.. _Custom parsers:1603.. _custom parser:1604.. _Writing a Custom Parser:1605 1606Writing a custom parser1607-----------------------1608 1609One of the simplest and most common extensions is the use of a custom parser.1610As `discussed previously`_, parsers are the portion of the CommandLine library1611that turns string input from the user into a particular parsed data type,1612validating the input in the process.1613 1614There are two ways to use a new parser:1615 1616#. Specialize the `cl::parser`_ template for your custom data type.1617 1618 This approach has the advantage that users of your custom data type will1619 automatically use your custom parser whenever they define an option with a1620 value type of your data type. The disadvantage of this approach is that it1621 doesn't work if your fundamental data type is something that is already1622 supported.1623 1624#. Write an independent class, using it explicitly from options that need it.1625 1626 This approach works well in situations where you would line to parse an1627 option using special syntax for a not-very-special data-type. The drawback1628 of this approach is that users of your parser have to be aware that they are1629 using your parser instead of the builtin ones.1630 1631To guide the discussion, we will discuss a custom parser that accepts file1632sizes, specified with an optional unit after the numeric size. For example, we1633would like to parse "102kb", "41M", "1G" into the appropriate integer value. In1634this case, the underlying data type we want to parse into is '``unsigned``'. We1635choose approach #2 above because we don't want to make this the default for all1636``unsigned`` options.1637 1638To start out, we declare our new ``FileSizeParser`` class:1639 1640.. code-block:: c++1641 1642 struct FileSizeParser : public cl::parser<unsigned> {1643 // parse - Return true on error.1644 bool parse(cl::Option &O, StringRef ArgName, const std::string &ArgValue,1645 unsigned &Val);1646 };1647 1648Our new class inherits from the ``cl::parser`` template class to fill in1649the default, boiler plate code for us. We give it the data type that we parse1650into, the last argument to the ``parse`` method, so that clients of our custom1651parser know what object type to pass in to the parse method. (Here we declare1652that we parse into '``unsigned``' variables.)1653 1654For most purposes, the only method that must be implemented in a custom parser1655is the ``parse`` method. The ``parse`` method is called whenever the option is1656invoked, passing in the option itself, the option name, the string to parse, and1657a reference to a return value. If the string to parse is not well-formed, the1658parser should output an error message and return true. Otherwise it should1659return false and set '``Val``' to the parsed value. In our example, we1660implement ``parse`` as:1661 1662.. code-block:: c++1663 1664 bool FileSizeParser::parse(cl::Option &O, StringRef ArgName,1665 const std::string &Arg, unsigned &Val) {1666 const char *ArgStart = Arg.c_str();1667 char *End;1668 1669 // Parse integer part, leaving 'End' pointing to the first non-integer char1670 Val = (unsigned)strtol(ArgStart, &End, 0);1671 1672 while (1) {1673 switch (*End++) {1674 case 0: return false; // No error1675 case 'i': // Ignore the 'i' in KiB if people use that1676 case 'b': case 'B': // Ignore B suffix1677 break;1678 1679 case 'g': case 'G': Val *= 1024*1024*1024; break;1680 case 'm': case 'M': Val *= 1024*1024; break;1681 case 'k': case 'K': Val *= 1024; break;1682 1683 default:1684 // Print an error message if unrecognized character!1685 return O.error("'" + Arg + "' value invalid for file size argument!");1686 }1687 }1688 }1689 1690This function implements a very simple parser for the kinds of strings we are1691interested in. Although it has some holes (it allows "``123KKK``" for example),1692it is good enough for this example. Note that we use the option itself to print1693out the error message (the ``error`` method always returns true) in order to get1694a nice error message (shown below). Now that we have our parser class, we can1695use it like this:1696 1697.. code-block:: c++1698 1699 static cl::opt<unsigned, false, FileSizeParser>1700 MFS("max-file-size", cl::desc("Maximum file size to accept"),1701 cl::value_desc("size"));1702 1703Which adds this to the output of our program:1704 1705::1706 1707 OPTIONS:1708 -help - display available options (-help-hidden for more)1709 ...1710 -max-file-size=<size> - Maximum file size to accept1711 1712And we can test that our parse works correctly now (the test program just prints1713out the max-file-size argument value):1714 1715::1716 1717 $ ./test1718 MFS: 01719 $ ./test -max-file-size=123MB1720 MFS: 1289748481721 $ ./test -max-file-size=3G1722 MFS: 32212254721723 $ ./test -max-file-size=dog1724 -max-file-size option: 'dog' value invalid for file size argument!1725 1726It looks like it works. The error message that we get is nice and helpful, and1727we seem to accept reasonable file sizes. This wraps up the "custom parser"1728tutorial.1729 1730Exploiting external storage1731---------------------------1732 1733Several of the LLVM libraries define static ``cl::opt`` instances that will1734automatically be included in any program that links with that library. This is1735a feature. However, sometimes it is necessary to know the value of the command1736line option outside of the library. In these cases the library does or should1737provide an external storage location that is accessible to users of the1738library. Examples of this include the ``llvm::DebugFlag`` exported by the1739``lib/Support/Debug.cpp`` file and the ``llvm::TimePassesIsEnabled`` flag1740exported by the ``lib/IR/PassManager.cpp`` file.1741 1742.. todo::1743 1744 TODO: complete this section1745 1746.. _dynamically loaded options:1747 1748Dynamically adding command line options1749---------------------------------------1750 1751.. todo::1752 1753 TODO: fill in this section1754