Introduction -
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 @@ -160,7 +161,7 @@ you declare it. Custom parsers are no problem.
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 @@ -230,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
... - ofstream Output(OutputFilename.c_str()); - if (Out.good()) ... + std::ofstream Output(OutputFilename.c_str()); + if (Output.good()) ... ...
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.
-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);
The CommandLine library uses a different parser for different data types. For example, in the string case, the argument passed @@ -371,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 "compiler --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:
@@ -437,7 +436,7 @@ 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:
@@ -455,12 +454,12 @@ uses.So far we have seen how the CommandLine library handles builtin types like std::string, bool and int, but how does it handle @@ -529,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
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. @@ -598,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>
@@ -613,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
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 @@ -698,14 +697,14 @@ checking we have to do.
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 +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 @@ -757,11 +756,11 @@ href="#list"> cl::list option.
- + -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 @@ -793,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 are those arguments that are not named, and are not specified with a hyphen. Positional arguments should be used when an option is @@ -834,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 @@ -853,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.
-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 @@ -871,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 @@ -894,15 +889,15 @@ can use it like this:
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 + 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 @@ -953,11 +948,11 @@ can use it like this:
The cl::ConsumeAfter formatting option is used to construct programs that use "interpreter style" option processing. With @@ -985,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 outputBy default, all command line options automatically hold the value that they parse from the command line. This is very convenient in the common case, @@ -1021,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). @@ -1075,11 +1072,11 @@ that DebugFlag is automatically set.This section describes the basic attributes that you can specify on options.
@@ -1097,16 +1094,16 @@ This option is specified in simple double quotes:-
@@ -1150,27 +1147,37 @@ and the second is the description.
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
@@ -1179,24 +1186,22 @@ 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 +
-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:
-
@@ -1208,8 +1213,8 @@ 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. +the option should not appear in the -help output, but should appear in +the -help-hidden output.
- The cl::ReallyHidden modifier indicates that the option should not appear in any help output. @@ -1219,12 +1224,12 @@ indicates that the option should not appear in any help output.
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 @@ -1268,11 +1273,11 @@ retained.
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 @@ -1317,11 +1322,11 @@ when extending the library.
The formatting option group is used to specify that the command line option has special abilities and is otherwise different from other command line @@ -1398,11 +1403,11 @@ strategy basically looks like this:
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
@@ -1430,24 +1435,47 @@ string "-pos1 -foo -bar baz -pos2 -bork" would cause the "-foo -bar
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. +
+ +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 is designed to be called directly from main, and is used to fill in the values of all of the @@ -1475,17 +1501,18 @@ 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 has mostly the same effects as cl::ParseCommandLineOptions does.
-It takes three parameters: the name of the program (since argv may +
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, and the optional +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 @@ -1515,12 +1544,12 @@ input.
The cl::SetVersionPrinter function is designed to be called directly from main and before @@ -1536,11 +1565,11 @@ called when the --version option is given by the user.
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 @@ -1571,11 +1600,11 @@ href="#customparser">custom parser.
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 @@ -1598,11 +1627,11 @@ be used.
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 @@ -1623,11 +1652,11 @@ must be of type unsigned if external storage is used.
The cl::alias class is a nontemplated class that is used to form aliases for other arguments.
@@ -1646,14 +1675,14 @@ the conversion from string to data.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 {
@@ -1673,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, @@ -1737,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.
-One of the simplest and most common extensions is the use of a custom parser. As discussed previously, parsers are the portion @@ -1847,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!"); } } } @@ -1870,7 +1901,7 @@ MFS("max-file-size", cl::desc("Maximum file siOPTIONS: - -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
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 @@ -1915,27 +1946,29 @@ tutorial.
TODO: fill in this section
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS">
- LLVM Compiler Infrastructure
+ LLVM Compiler Infrastructure
Last modified: $Date$