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:
@@ -383,7 +383,7 @@ OPTIONS: -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> @@ -432,7 +432,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 @@ -462,24 +462,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:
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 @@ -750,7 +750,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.
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) {
// ...
@@ -969,7 +969,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:
@@ -1042,10 +1042,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:
-//
-// DOUT << "Bitset contains: " << Bitset << "\n";
-//
+// executed. Otherwise it will not be.
#ifdef NDEBUG
#define DEBUG(X)
#else
@@ -1057,7 +1054,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:
@@ -1206,15 +1203,15 @@ 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
+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.
@@ -1255,7 +1252,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.
@@ -1328,7 +1325,7 @@ 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
-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.
@@ -1337,7 +1334,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.
@@ -1358,7 +1355,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
@@ -1426,7 +1423,7 @@ 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.
@@ -1487,14 +1484,14 @@ 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 three 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
additional extra text to emit when the
--help option is invoked.
@@ -1518,7 +1515,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
@@ -1783,7 +1780,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.
@@ -1807,16 +1804,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: