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:
@@ -254,8 +257,8 @@ example:... - ofstream Output(OutputFilename.c_str()); - if (Out.good()) ... + std::ofstream Output(OutputFilename.c_str()); + if (Output.good()) ... ...
and "opt --help-hidden" prints this:
+and "compiler --help-hidden" prints this:
USAGE: compiler [options] <input file> @@ -430,7 +433,7 @@ 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 @@ -460,24 +463,24 @@ uses.
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:
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 @@ -632,7 +635,7 @@ that you can choose the form most appropriate for your application.
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 @@ -748,7 +751,7 @@ the first are discarded.
Finally, if external storage is used, then the location specified must be of type unsigned. In all other ways a cl::bits option is morally equivalent to a cl::bits option is equivalent to a cl::list option.
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 @@ -911,10 +914,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) {
// ...
@@ -946,7 +949,7 @@ 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.
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:
@@ -1127,7 +1127,7 @@ an alias for.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.So far, these are the only two miscellaneous option modifiers.
+So far, these are the only three miscellaneous option modifiers.
+ +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. +
+ +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.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 reponse files +should be read.cl::ParseEnvironmentOptions will break the environment variable's value up into words and then process them using @@ -1516,7 +1550,7 @@ input.
The cl::SetVersionPrinter function is designed to be called -directly from main, and before +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 @@ -1654,7 +1688,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 @@ -1702,6 +1736,12 @@ is used to convert boolean strings to a boolean value. Currently accepted strings are "true", "TRUE", "True", "1", "false", "FALSE", "False", and "0".
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.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:
@@ -1817,7 +1857,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);