This document describes the CommandLine argument processing library. It will show you how to use it, and what it can do. The CommandLine library uses a @@ -134,7 +139,7 @@ code.

Globally accessible: Libraries can specify command line arguments that are automatically enabled in any tool that links to the library. This is possible -because the application doesn't have to keep a "list" of arguments to pass to +because the application doesn't have to keep a list of arguments to pass to the parser. This also makes supporting dynamically loaded options trivial.

@@ -156,7 +161,7 @@ you declare it. Custom parsers are no problem.

Labor Saving: The CommandLine library cuts down on the amount of grunt work that you, the user, have to do. For example, it automatically provides a ---help option that shows the available command line options for your +-help option that shows the available command line options for your tool. Additionally, it does most of the basic correctness checking for you.

@@ -179,12 +184,12 @@ href="mailto:sabre@nondot.org">Chris Lattner.

Quick Start Guide -

+ -

This section of the manual runs through a simple CommandLine'ification of a basic compiler tool. This is intended to show you how to jump into using the @@ -195,7 +200,7 @@ can do.

program:

-  #include "Support/CommandLine.h"
+  #include "llvm/Support/CommandLine.h"

Additionally, you need to add this as the first line of your main @@ -212,12 +217,12 @@ int main(int argc, char **argv) { declarations.

Now that you are ready to support command line arguments, we need to tell the -system which ones we want, and what type of argument they are. The CommandLine +system which ones we want, and what type of arguments they are. The CommandLine library uses a declarative syntax to model command line arguments with the global variable declarations that capture the parsed values. This means that for every command line option that you would like to support, there should be a global variable declaration to capture the result. For example, in a compiler, -we would like to support the unix standard '-o <filename>' option +we would like to support the Unix-standard '-o <filename>' option to specify where to put the output. With the CommandLine library, this is represented like this:

@@ -226,22 +231,22 @@ represented like this:

cl::opt<string> OutputFilename("o", cl::desc("Specify output filename"), cl::value_desc("filename"));

This declares a global variable "OutputFilename" that is used to -capture the result of the "o" argument (first parameter). We specify -that this is a simple scalar option by using the "cl::opt" template (as opposed to the "cl::list template), and tell the CommandLine library +

This declares a global variable "OutputFilename" that is used to +capture the result of the "o" argument (first parameter). We specify +that this is a simple scalar option by using the "cl::opt" template (as opposed to the "cl::list template), and tell the CommandLine library that the data type that we are parsing is a string.

The second and third parameters (which are optional) are used to specify what -to output for the "--help" option. In this case, we get a line that +to output for the "-help" option. In this case, we get a line that looks like this:

 USAGE: compiler [options]
 
 OPTIONS:
-  -help             - display available options (--help-hidden for more)
+  -help             - display available options (-help-hidden for more)
   -o <filename>     - Specify output filename

@@ -252,8 +257,8 @@ example:

   ...
-  ofstream Output(OutputFilename.c_str());
-  if (Out.good()) ...
+  std::ofstream Output(OutputFilename.c_str());
+  if (Output.good()) ...
   ...

@@ -303,36 +308,34 @@ the CommandLine library will automatically issue an error if the argument is not specified, which shifts all of the command line option verification code out of your application into the library. This is just one example of how using flags can alter the default behaviour of the library, on a per-option basis. By -adding one of the declarations above, the --help option synopsis is now +adding one of the declarations above, the -help option synopsis is now extended to:

 USAGE: compiler [options] <input file>
 
 OPTIONS:
-  -help             - display available options (--help-hidden for more)
+  -help             - display available options (-help-hidden for more)
   -o <filename>     - Specify output filename

... indicating that an input filename is expected.

- -

Boolean Arguments -

+ -

In addition to input and output filenames, we would like the compiler example -to support three boolean flags: "-f" to force overwriting of the output -file, "--quiet" to enable quiet mode, and "-q" for backwards -compatibility with some of our users. We can support these by declaring options -of boolean type like this:

+to support three boolean flags: "-f" to force writing binary output to +a terminal, "--quiet" to enable quiet mode, and "-q" for +backwards compatibility with some of our users. We can support these by +declaring options of boolean type like this:

-cl::opt<bool> Force ("f", cl::desc("Overwrite output files"));
+cl::opt<bool> Force ("f", cl::desc("Enable binary output on terminals"));
 cl::opt<bool> Quiet ("quiet", cl::desc("Don't print informational messages"));
 cl::opt<bool> Quiet2("q", cl::desc("Don't print informational messages"), cl::Hidden);

@@ -341,8 +344,8 @@ of boolean type like this:

("Force", "Quiet", and "Quiet2") to recognize these options. Note that the "-q" option is specified with the "cl::Hidden" flag. This modifier prevents it -from being shown by the standard "--help" output (note that it is still -shown in the "--help-hidden" output).

+from being shown by the standard "-help" output (note that it is still +shown in the "-help-hidden" output).

The CommandLine library uses a different parser for different data types. For example, in the string case, the argument passed @@ -367,29 +370,29 @@ href="#doubleparser">double, and int parsers work like you would expect, using the 'strtol' and 'strtod' C library calls to parse the string value into the specified data type.

With the declarations above, "compiler --help" emits this:

With the declarations above, "compiler -help" emits this:

 USAGE: compiler [options] <input file>
 
 OPTIONS:
-  -f     - Overwrite output files
+  -f     - Enable binary output on terminals
   -o     - Override output filename
   -quiet - Don't print informational messages
-  -help  - display available options (--help-hidden for more)
+  -help  - display available options (-help-hidden for more)

and "opt --help-hidden" prints this:

and "compiler -help-hidden" prints this:

 USAGE: compiler [options] <input file>
 
 OPTIONS:
-  -f     - Overwrite output files
+  -f     - Enable binary output on terminals
   -o     - Override output filename
   -q     - Don't print informational messages
   -quiet - Don't print informational messages
-  -help  - display available options (--help-hidden for more)
+  -help  - display available options (-help-hidden for more)

This brief example has shown you how to use the 'lists of options.

- + Argument Aliases - + - + So far, the example works well, except for the fact that we need to check the quiet condition like this now: @@ -428,12 +431,12 @@ a value itself: The third line (which is the only one we modified from above) defines a -"-q alias that updates the "Quiet" variable (as specified by +"-q" alias that updates the "Quiet" variable (as specified by the cl::aliasopt modifier) whenever it is specified. Because aliases do not hold state, the only thing the program has to query is the Quiet variable now. Another nice feature of aliases is that they automatically hide themselves from the -help output -(although, again, they are still visible in the --help-hidden +(although, again, they are still visible in the -help-hidden output). Now the application code can simply use: @@ -451,31 +454,31 @@ uses. - + Selecting an alternative from a set of possibilities - + - + -So far, we have seen how the CommandLine library handles builtin types like + So far we have seen how the CommandLine library handles builtin types like std::string, bool and int, but how does it handle things it doesn't know about, like enums or 'int*'s? -The answer is that it uses a table driven generic parser (unless you specify + The answer is that it uses a table-driven generic parser (unless you specify your own parser, as described in the Extension Guide). This parser maps literal strings to whatever type is required, and requires you to tell it what this mapping should be. -Lets say that we would like to add four optimization levels to our + Let's say that we would like to add four optimization levels to our optimizer, using the standard flags "-g", "-O0", "-O1", and "-O2". We could easily implement this with boolean options like above, but there are several problems with this strategy: A user could specify more than one of the options at a time, for example, -"opt -O3 -O2". The CommandLine library would not be able to catch this -erroneous input for us. +"compiler -O3 -O2". The CommandLine library would not be able to +catch this erroneous input for us. We would have to test 4 different variables to see which ones are set. @@ -509,7 +512,7 @@ enum OptLevel { This declaration defines a variable "OptimizationLevel" of the "OptLevel" enum type. This variable can be assigned any of the values that are listed in the declaration (Note that the declaration list must be -terminated with the "clEnumValEnd" argument!). The CommandLine +terminated with the "clEnumValEnd" argument!). The CommandLine library enforces that the user can only specify one of the options, and it ensure that only valid enum values can be specified. The "clEnumVal" macros ensure that the @@ -525,8 +528,8 @@ OPTIONS: -O1 - Enable trivial optimizations -O2 - Enable default optimizations -O3 - Enable expensive optimizations - -f - Overwrite output files - -help - display available options (--help-hidden for more) + -f - Enable binary output on terminals + -help - display available options (-help-hidden for more) -o <filename> - Specify output filename -quiet - Don't print informational messages @@ -562,11 +565,11 @@ which is when you would use it. - + Named Alternatives - + - + Another useful argument form is a named alternative style. We shall use this style in our compiler to specify different debug levels that can be used. @@ -594,7 +597,7 @@ enum DebugLev { This definition defines an enumerated command line variable of type "enum DebugLev", which works exactly the same way as before. The difference here is just the interface exposed to the user of your program and the help output by -the "--help" option: +the "-help" option: USAGE: compiler [options] <input file> @@ -609,8 +612,8 @@ OPTIONS: =none - disable debug information =quick - enable quick debug information =detailed - enable detailed debug information - -f - Overwrite output files - -help - display available options (--help-hidden for more) + -f - Enable binary output on terminals + -help - display available options (-help-hidden for more) -o <filename> - Specify output filename -quiet - Don't print informational messages @@ -624,13 +627,13 @@ that you can choose the form most appropriate for your application. - + Parsing a list of options - + - + -Now that we have the standard run of the mill argument types out of the way, + Now that we have the standard run-of-the-mill argument types out of the way, lets get a little wild and crazy. Lets say that we want our optimizer to accept a list of optimizations to perform, allowing duplicates. For example, we might want to run: "compiler -dce -constprop -inline -dce -strip". In @@ -694,15 +697,15 @@ checking we have to do. - + Collecting options as a set of flags - + - + Instead of collecting sets of options in a list, it is also possible to -gather information for enum values in a bit vector. The represention used by -the cl::bits class is an unsigned long +gather information for enum values in a bit vector. The representation used by +the cl::bits class is an unsigned integer. An enum value is represented by a 0/1 in the enum's ordinal value bit position. 1 indicating that the enum was specified, 0 otherwise. As each specified value is parsed, the resulting enum's bit is set in the option's bit @@ -712,8 +715,8 @@ vector: bits |= 1 << (unsigned)enum; -An option specified more than once is redundant as far as the result is -concerned. The argument position information is however updated. +Options that are specified multiple times are redundant. Any instances after +the first are discarded. Reworking the above list example, we could replace cl::list with cl::bits: @@ -741,23 +744,23 @@ concerned. The argument position information is however updated. cl::bits::getBits function: - unsigned long bits = OptimizationBits.getBits(); + unsigned bits = OptimizationBits.getBits(); Finally, if external storage is used, then the location specified must be of -type unsigned long. In all other ways a cl::bits option is morally equivalent to a cl::list option +type unsigned. In all other ways a cl::bits option is equivalent to a cl::list option. - + Adding freeform text to help output - + - + As our program grows and becomes more mature, we may decide to put summary information about what it does into the help output. The help output is styled @@ -789,34 +792,33 @@ USAGE: compiler [options] <input file> OPTIONS: ... - -help - display available options (--help-hidden for more) + -help - display available options (-help-hidden for more) -o <filename> - Specify output filename + - + Reference Guide - + - + Now that you know the basics of how to use the CommandLine library, this section will give you the detailed information you need to tune how command line options work, as well as information on more "advanced" command line option processing capabilities. - - - + Positional Arguments - + - + Positional arguments are those arguments that are not named, and are not specified with a hyphen. Positional arguments should be used when an option is @@ -830,14 +832,14 @@ Using the CommandLine library, this would be specified as: cl::opt<string> Filename(cl::Positional, cl::desc("<input file>"), cl::init("-")); -Given these two option declarations, the --help output for our grep + Given these two option declarations, the -help output for our grep replacement would look like this: USAGE: spiffygrep [options] <regular expression> <input file> OPTIONS: - -help - display available options (--help-hidden for more) + -help - display available options (-help-hidden for more) ... and the resultant program could be used just like the standard @@ -849,15 +851,12 @@ that command line options will be ordered according to how they are listed in a are defined in multiple .cpp files. The fix for this problem is simply to define all of your positional arguments in one .cpp file. - - - - + Specifying positional options with hyphens - + - + Sometimes you may want to specify a value to your positional argument that starts with a hyphen (for example, searching for '-foo' in a file). At @@ -867,7 +866,7 @@ Note that the system grep has the same problem: $ spiffygrep '-foo' test.txt - Unknown command line argument '-foo'. Try: spiffygrep --help' + Unknown command line argument '-foo'. Try: spiffygrep -help' $ grep '-foo' test.txt grep: illegal option -- f @@ -890,18 +889,18 @@ can use it like this: - + Determining absolute position with getPosition() - - + + Sometimes an option can affect or modify the meaning of another option. For example, consider gcc's -x LANG option. This tells gcc to ignore the suffix of subsequent positional arguments and force the file to be interpreted as if it contained source code in language - LANG. In order to handle this properly , you need to know the - absolute position of each argument, especially those in lists, so their - interaction(s) can be applied correctly. This is also useful for options like - -llibname which is actually a positional argument that starts with + LANG. In order to handle this properly, you need to know the + absolute position of each argument, especially those in lists, so their + interaction(s) can be applied correctly. This is also useful for options like + -llibname which is actually a positional argument that starts with a dash. So, generally, the problem is that you have two cl::list variables that interact in some way. To ensure the correct interaction, you can use the @@ -909,10 +908,10 @@ can use it like this: absolute position (as found on the command line) of the optnum item in the cl::list. The idiom for usage is like this: - + static cl::list<std::string> Files(cl::Positional, cl::OneOrMore); - static cl::listlt;std::string> Libraries("l", cl::ZeroOrMore); + static cl::list<std::string> Libraries("l", cl::ZeroOrMore); int main(int argc, char**argv) { // ... @@ -944,16 +943,16 @@ can use it like this: Note that, for compatibility reasons, the cl::opt also supports an unsigned getPosition() option that will provide the absolute position - of that option. You can apply the same approach as above with a + of that option. You can apply the same approach as above with a cl::opt and a cl::list option as you can with two lists. - + The cl::ConsumeAfter modifier - + - + The cl::ConsumeAfter formatting option is used to construct programs that use "interpreter style" option processing. With @@ -965,7 +964,7 @@ interpreted by the command line argument. standard Unix Bourne shell (/bin/sh). To run /bin/sh, first you specify options to the shell itself (like -x which turns on trace output), then you specify the name of the script to run, then you specify -arguments to the script. These arguments to the script are parsed by the bourne +arguments to the script. These arguments to the script are parsed by the Bourne shell command line option processor, but are not interpreted as options to the shell itself. Using the CommandLine library, we would specify this as: @@ -981,7 +980,7 @@ shell itself. Using the CommandLine library, we would specify this as: USAGE: spiffysh [options] <input script> <program arguments>... OPTIONS: - -help - display available options (--help-hidden for more) + -help - display available options (-help-hidden for more) -x - Enable trace output @@ -1001,12 +1000,14 @@ href="#cl::list">cl::list option. + + - + Internal vs External Storage - + - + By default, all command line options automatically hold the value that they parse from the command line. This is very convenient in the common case, @@ -1017,7 +1018,7 @@ files that use them. This is called the internal storage model. code from the storage of the value parsed. For example, lets say that we have a '-debug' option that we would like to use to enable debug information across the entire body of our program. In this case, the boolean value -controlling the debug code should be globally accessable (in a header file, for +controlling the debug code should be globally accessible (in a header file, for example) yet the command line option processing code should not be exposed to all of these clients (requiring lots of .cpp files to #include CommandLine.h). @@ -1038,10 +1039,7 @@ extern bool DebugFlag; // DEBUG macro - This macro should be used by code to emit debug information. // In the '-debug' option is specified on the command line, and if this is a // debug build, then the code specified as the option to the macro will be -// executed. Otherwise it will not be. Example: -// -// DEBUG(std::cerr << "Bitset contains: " << Bitset << "\n"); -// +// executed. Otherwise it will not be. #ifdef NDEBUG #define DEBUG(X) #else @@ -1053,7 +1051,7 @@ extern bool DebugFlag; This allows clients to blissfully use the DEBUG() macro, or the DebugFlag explicitly if they want to. Now we just need to be able to set the DebugFlag boolean when the option is set. To do this, we pass -an additial argument to our command line argument processor, and we specify +an additional argument to our command line argument processor, and we specify where to fill in with the cl::location attribute: @@ -1074,11 +1072,11 @@ that DebugFlag is automatically set. - + Option Attributes - + - + This section describes the basic attributes that you can specify on options. @@ -1096,16 +1094,16 @@ This option is specified in simple double quotes: The cl::desc attribute specifies a -description for the option to be shown in the --help output for the +description for the option to be shown in the -help output for the program. The cl::value_desc attribute -specifies a string that can be used to fine tune the --help output for +specifies a string that can be used to fine tune the -help output for a command line option. Look here for an example. The cl::init attribute specifies an -inital value for a scalar option. If this attribute is +initial value for a scalar option. If this attribute is not specified then the command line option value defaults to the value created by the default constructor for the type. Warning: If you specify both cl::init and cl::location for an option, @@ -1114,9 +1112,9 @@ command-line parser sees cl::init, it knows where to put the initial value. (You will get an error at runtime if you don't put them in the right order.) -The cl::location attribute where to -store the value for a parsed command line option if using external storage. See -the section on Internal vs External Storage for more + The cl::location attribute where +to store the value for a parsed command line option if using external storage. +See the section on Internal vs External Storage for more information. The cl::aliasopt attribute @@ -1125,10 +1123,10 @@ an alias for. The cl::values attribute specifies the string-to-value mapping to be used by the generic parser. It takes a -clEnumValEnd terminated list of (option, value, description) triplets +clEnumValEnd terminated list of (option, value, description) triplets that specify the option name, the value mapped to, and the description shown in the ---help for the tool. Because the generic parser is used most +-help for the tool. Because the generic parser is used most frequently with enum values, two macros are often useful: @@ -1149,27 +1147,37 @@ and the second is the description. You will get a compile time error if you try to use cl::values with a parser that does not support it. +The cl::multi_val +attribute specifies that this option takes has multiple values +(example: -sectalign segname sectname sectvalue). This +attribute takes one unsigned argument - the number of values for the +option. This attribute is valid only on cl::list options (and +will fail with compile error if you try to use it with other option +types). It is allowed to use all of the usual modifiers on +multi-valued options (besides cl::ValueDisallowed, +obviously). + - + Option Modifiers - + - + Option modifiers are the flags and expressions that you pass into the constructors for cl::opt and cl::list. These modifiers give you the ability to -tweak how options are parsed and how --help output is generated to fit +tweak how options are parsed and how -help output is generated to fit your application well. -These options fall into five main catagories: +These options fall into five main categories: -Hiding an option from --help output +Hiding an option from -help output Controlling the number of occurrences required and allowed Controlling whether or not a value must be @@ -1178,39 +1186,37 @@ your application well. Miscellaneous option modifiers -It is not possible to specify two options from the same catagory (you'll get + It is not possible to specify two options from the same category (you'll get a runtime error) to a single option, except for options in the miscellaneous -catagory. The CommandLine library specifies defaults for all of these settings +category. The CommandLine library specifies defaults for all of these settings that are the most useful in practice and the most common, which mean that you usually shouldn't have to worry about these. - - - - Hiding an option from --help output - + + Hiding an option from -help output + - + The cl::NotHidden, cl::Hidden, and cl::ReallyHidden modifiers are used to control whether or not an option -appears in the --help and --help-hidden output for the +appears in the -help and -help-hidden output for the compiled program: The cl::NotHidden modifier (which is the default for cl::opt and cl::list options), indicates the option is to appear +href="#cl::list">cl::list options) indicates the option is to appear in both help listings. The cl::Hidden modifier (which is the -default for cl::alias options), indicates that -the option should not appear in the --help output, but should appear in -the --help-hidden output. +default for cl::alias options) indicates that +the option should not appear in the -help output, but should appear in +the -help-hidden output. -The cl::ReallyHidden modifier, + The cl::ReallyHidden modifier indicates that the option should not appear in any help output. @@ -1218,12 +1224,12 @@ indicates that the option should not appear in any help output. - + Controlling the number of occurrences required and allowed - + - + This group of options is used to control how many time an option is allowed (or required) to be specified on the command line of your program. Specifying a @@ -1251,7 +1257,7 @@ indicates that the specified option must be specified exactly one time. indicates that the option must be specified at least one time. The cl::ConsumeAfter modifier is described in the Positional arguments section +href="#positional">Positional arguments section. @@ -1267,11 +1273,11 @@ retained. - + Controlling whether or not a value must be specified - + - + This group of options is used to control whether or not the option allows a value to be present. In the case of the CommandLine library, a value is either @@ -1316,15 +1322,15 @@ when extending the library. - + Controlling other formatting options - + - + The formatting option group is used to specify that the command line option has special abilities and is otherwise different from other command line -arguments. As usual, you can only specify at most one of these arguments. +arguments. As usual, you can only specify one of these arguments at most. @@ -1333,7 +1339,7 @@ modifier (which is the default all options) specifies that this option is "normal". The cl::Positional modifier -specifies that this is a positional argument, that does not have a command line +specifies that this is a positional argument that does not have a command line option associated with it. See the Positional Arguments section for more information. @@ -1354,7 +1360,7 @@ modifier added to allow the CommandLine library to recognize them. Note that specified. The cl::Grouping modifier is used -to implement unix style tools (like ls) that have lots of single letter +to implement Unix-style tools (like ls) that have lots of single letter arguments, but only require a single dash. For example, the 'ls -labF' command actually enables four different options, all of which are single letters. Note that cl::Grouping @@ -1397,11 +1403,11 @@ strategy basically looks like this: - + Miscellaneous option modifiers - + - + The miscellaneous option modifiers are the only flags where you can specify more than one flag from the set: they are not mutually exclusive. These flags @@ -1422,23 +1428,54 @@ more values (i.e. it is a cl::list option). positional arguments, and only makes sense for lists) indicates that positional argument should consume any strings after it (including strings that start with a "-") up until another recognized positional argument. For example, if you -have two "eating" positional arguments "pos1" and "pos2" the +have two "eating" positional arguments, "pos1" and "pos2", the string "-pos1 -foo -bar baz -pos2 -bork" would cause the "-foo -bar -baz" strings to be applied to the "-pos1" option and the "-bork" string to be applied to the "-pos2" option. + The cl::Sink modifier is +used to handle unknown options. If there is at least one option with +cl::Sink modifier specified, the parser passes +unrecognized option strings to it as values instead of signaling an +error. As with cl::CommaSeparated, this modifier +only makes sense with a cl::list option. + -So far, these are the only two miscellaneous option modifiers. +So far, these are the only three miscellaneous option modifiers. + + + + + + Response files + + + + +Some systems, such as certain variants of Microsoft Windows and +some older Unices have a relatively low limit on command-line +length. It is therefore customary to use the so-called 'response +files' to circumvent this restriction. These files are mentioned on +the command-line (using the "@file") syntax. The program reads these +files and inserts the contents into argv, thereby working around the +command-line length limits. Response files are enabled by an optional +fourth argument to +cl::ParseEnvironmentOptions +and +cl::ParseCommandLineOptions. + + + - + Top-Level Classes and Functions - + - + Despite all of the built-in flexibility, the CommandLine option library really only consists of one function (cl::list, and cl::alias. This section describes these three classes in detail. - - - + The cl::ParseCommandLineOptions function - + - + The cl::ParseCommandLineOptions function is designed to be called directly from main, and is used to fill in the values of all of the @@ -1466,33 +1501,36 @@ available. The cl::ParseCommandLineOptions function requires two parameters (argc and argv), but may also take an optional third parameter which holds additional extra text to emit when the ---help option is invoked. +-help option is invoked, and a fourth boolean parameter that enables +response files. - + The cl::ParseEnvironmentOptions function - + - + The cl::ParseEnvironmentOptions function has mostly the same effects as cl::ParseCommandLineOptions, except that it is designed to take values for options from an environment variable, for those cases in which reading the command line is not convenient or -not desired. It fills in the values of all the command line option variables -just like cl::ParseCommandLineOptions does. -It takes three parameters: first, the name of the program (since -argv may not be available, it can't just look in argv[0]), -second, the name of the environment variable to examine, and third, the optional + It takes four parameters: the name of the program (since argv may +not be available, it can't just look in argv[0]), the name of the +environment variable to examine, the optional additional extra text to emit when the ---help option is invoked. +-help option is invoked, and the boolean +switch that controls whether response files +should be read. cl::ParseEnvironmentOptions will break the environment variable's value up into words and then process them using @@ -1506,11 +1544,32 @@ input. - - The cl::opt class + + The cl::SetVersionPrinter + function + + + + +The cl::SetVersionPrinter function is designed to be called +directly from main and before +cl::ParseCommandLineOptions. Its use is optional. It simply arranges +for a function to be called in response to the --version option instead +of having the CommandLine library print out the usual version string +for LLVM. This is useful for programs that are not part of LLVM but wish to use +the CommandLine facilities. Such programs should just define a small +function that takes no arguments and returns void and that prints out +whatever version information is appropriate for the program. Pass the address +of that function to cl::SetVersionPrinter to arrange for it to be +called when the --version option is given by the user. + + + + The cl::opt class + - + The cl::opt class is the class used to represent scalar command line options, and is the one used most of the time. It is a templated class which @@ -1541,11 +1600,11 @@ href="#customparser">custom parser. - + The cl::list class - + - + The cl::list class is the class used to represent a list of command line options. It too is a templated class which can take up to three @@ -1568,11 +1627,11 @@ be used. - + The cl::bits class - + - + The cl::bits class is the class used to represent a list of command line options in the form of a bit vector. It is also a templated class which @@ -1588,16 +1647,16 @@ can take up to three arguments: This class works the exact same as the cl::lists class, except that the second argument -must be of type unsigned long if external storage is used. +must be of type unsigned if external storage is used. - + The cl::alias class - + - + The cl::alias class is a nontemplated class that is used to form aliases for other arguments. @@ -1616,14 +1675,14 @@ the conversion from string to data. - + The cl::extrahelp class - + - + The cl::extrahelp class is a nontemplated class that allows extra -help text to be printed out for the --help option. +help text to be printed out for the -help option. namespace cl { @@ -1631,7 +1690,7 @@ help text to be printed out for the --help option. } -To use the extrahelp, simply construct one with a const char* + To use the extrahelp, simply construct one with a const char* parameter to the constructor. The text passed to the constructor will be printed at the bottom of the help message, verbatim. Note that multiple cl::extrahelp can be used, but this practice is discouraged. If @@ -1643,12 +1702,14 @@ single cl::extrahelp instance. + + - + Builtin parsers - + - + Parsers control how the string value taken from the command line is translated into a typed value, suitable for use in a C++ program. By default, @@ -1679,6 +1740,12 @@ is used to convert boolean strings to a boolean value. Currently accepted strings are "true", "TRUE", "True", "1", "false", "FALSE", "False", and "0". + The parser<boolOrDefault> + specialization is used for cases where the value is boolean, +but we also need to know whether the option was specified at all. boolOrDefault +is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE. This parser accepts +the same strings as parser<bool>. + The parser<string> specialization simply stores the parsed string into the string value specified. No conversion or modification of the data is performed. @@ -1701,27 +1768,27 @@ exponential notation (ex: 1.7e15) and properly supports locales. + + - + Extension Guide - + - + Although the CommandLine library has a lot of functionality built into it already (as discussed previously), one of its true strengths lie in its extensibility. This section discusses how the CommandLine library works under the covers and illustrates how to do some simple, common, extensions. - - - + Writing a custom parser - + - + One of the simplest and most common extensions is the use of a custom parser. As discussed previously, parsers are the portion @@ -1740,7 +1807,7 @@ your custom data type. This approach has the advantage that users of your custom data type will automatically use your custom parser whenever they define an option with a value type of your data type. The disadvantage of this approach is that it doesn't -work if your fundemental data type is something that is already supported. +work if your fundamental data type is something that is already supported. @@ -1752,7 +1819,7 @@ it. This approach works well in situations where you would line to parse an option using special syntax for a not-very-special data-type. The drawback of this approach is that users of your parser have to be aware that they are using -your parser, instead of the builtin ones. +your parser instead of the builtin ones. @@ -1776,16 +1843,16 @@ this the default for all unsigned options. Our new class inherits from the cl::basic_parser template class to -fill in the default, boiler plate, code for us. We give it the data type that -we parse into (the last argument to the parse method so that clients of -our custom parser know what object type to pass in to the parse method (here we -declare that we parse into 'unsigned' variables. +fill in the default, boiler plate code for us. We give it the data type that +we parse into, the last argument to the parse method, so that clients of +our custom parser know what object type to pass in to the parse method. (Here we +declare that we parse into 'unsigned' variables.) For most purposes, the only method that must be implemented in a custom parser is the parse method. The parse method is called whenever the option is invoked, passing in the option itself, the option name, the string to parse, and a reference to a return value. If the string to parse -is not well formed, the parser should output an error message and return true. +is not well-formed, the parser should output an error message and return true. Otherwise it should return false and set 'Val' to the parsed value. In our example, we implement parse as: @@ -1794,7 +1861,7 @@ our example, we implement parse as: const std::string &Arg, unsigned &Val) { const char *ArgStart = Arg.c_str(); char *End; - + // Parse integer part, leaving 'End' pointing to the first non-integer char Val = (unsigned)strtol(ArgStart, &End, 0); @@ -1811,7 +1878,7 @@ our example, we implement parse as: default: // Print an error message if unrecognized character! - return O.error(": '" + Arg + "' value invalid for file size argument!"); + return O.error("'" + Arg + "' value invalid for file size argument!"); } } } @@ -1834,7 +1901,7 @@ MFS("max-file-size", cl::desc("Maximum file si OPTIONS: - -help - display available options (--help-hidden for more) + -help - display available options (-help-hidden for more) ... -max-file-size=<size> - Maximum file size to accept @@ -1860,11 +1927,11 @@ tutorial. - + Exploiting external storage - + - + Several of the LLVM libraries define static cl::opt instances that will automatically be included in any program that links with that library. This is a feature. However, sometimes it is necessary to know the value of the @@ -1879,27 +1946,29 @@ tutorial. - + Dynamically adding command line options - + - + TODO: fill in this section + + + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"> + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"> Chris Lattner - LLVM Compiler Infrastructure + LLVM Compiler Infrastructure Last modified: $Date$

Positional Arguments -

Specifying positional options with hyphens -

Determining absolute position with getPosition() -

The `cl::ConsumeAfter` modifier -

Internal vs External Storage -

Option Attributes -

Option Modifiers -

+ Hiding an option from `-help` output +

Controlling the number of occurrences required and allowed -

Controlling whether or not a value must be specified -

Controlling other formatting options -

Miscellaneous option modifiers -

+ Response files +

Top-Level Classes and Functions -

The `cl::ParseCommandLineOptions` function -

The `cl::ParseEnvironmentOptions` function -

+ The `cl::SetVersionPrinter` + function +

+ The `cl::opt` class +

The `cl::list` class -

The `cl::bits` class -

The `cl::alias` class -

The `cl::extrahelp` class -

Builtin parsers -

Extension Guide -

Writing a custom parser -

Exploiting external storage -

Dynamically adding command line options -

CommandLine 2.0 Library Manual -

Introduction -

Quick Start Guide -

Boolean Arguments -

Argument Aliases -

Selecting an alternative from a set of possibilities -

Named Alternatives -

Parsing a list of options -

Collecting options as a set of flags -

Adding freeform text to help output -

Reference Guide -