X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCommandLine.html;h=47ab2cc074dda4aa8ab4be56e522a014a9e71460;hb=a75ce9f5d2236d93c117e861e60e6f3f748c9555;hp=67177bfa6feda47f711acfb1713ce300129744c4;hpb=8b44b9064427821ba2784ff3617d7cc5460df5de;p=oota-llvm.git diff --git a/docs/CommandLine.html b/docs/CommandLine.html index 67177bfa6fe..47ab2cc074d 100644 --- a/docs/CommandLine.html +++ b/docs/CommandLine.html @@ -44,7 +44,7 @@
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
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 +372,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 '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:
@@ -513,7 +514,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 @@ -529,8 +530,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
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 +614,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
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 @@ -793,7 +794,7 @@ 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
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 @@ -871,7 +872,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 @@ -902,10 +903,10 @@ can use it like this: 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 @@ -913,7 +914,7 @@ 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:
- +@@ -985,7 +986,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 outputstatic cl::list<std::string> Files(cl::Positional, cl::OneOrMore); static cl::list<std::string> Libraries("l", cl::ZeroOrMore); @@ -948,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.
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:
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.
@@ -1189,14 +1200,14 @@ usually shouldn't have to worry about these.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:
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: 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 @@ -1645,7 +1689,7 @@ 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 { @@ -1653,7 +1697,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 @@ -1822,7 +1866,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); @@ -1839,7 +1883,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!"); } } } @@ -1862,7 +1906,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