Command line options library

Collaboration diagram for Command line options library:

A library that makes it very easy to set the value of parameters within a program, using command line options. More...

Modules
	Options library internals
	Methods used internally by the Option library.
Classes
class	_optionbase
	Abstract base class from which all _option<T> objects inherit. More...
class	_option< T >
	A variable in your program, controlled by a command line option. More...
class	Options
	A list of command line options, with methods for parsing strings and streams to set the options. More...
class	OptionVar
	The OptionVar class is an obsolete predecessor of Options. More...

---

Detailed Description

A library that makes it very easy to set the value of parameters within a program, using command line options.

The Option library allows programmers to very easily write programs that can be controlled at run-time, by setting parameters on the command line. Any parameter that can be set on the command line can also be described in a file containing many such "batch options", and the file can be read in using a single command line option.

Each parameter that can be set from the command line corresponds to a single variable in your source code. You declare and use the variable exactly as you normally would, but between its declaration/initialization and its first use, you register it with the Option library. Once you've registered all the variables you want to be command-line-settable, you ask the Options library to parse the command line (and/or, if you wish, any other string or stream).

The Options library looks for strings of the form "<name>=<value>", and sets any parameter that it finds with name "<name>" to <value>. That's it -- the Option library automatically identifies all the parameters that the user wanted to set, and changes their value. Any parameters not specifically changed on the command line are left unchanged (so make sure they're all initialized correctly to default values!

The usage is simple, as the following example demonstrates.

     #include <options.h>

     int main( int argc, char** argv ) // argc and argv are the C interface to the command line
     {
               // *** Step 1: declare your parameters.
          int NumBoxes = 2;                            
          double Volume = 3.57;
               // (note) Options can handle std::vector<T>, but not other STL containers.
          std::vector<bool> PaintTheSides(6);          
          std::string Color( "Red" );
          
               // *** Step 2: declare an Options object.
          Options MyOptions;
               // (note) The name comes first, then the variable.
          MyOptions.Add( "NumBoxes", NumBoxes );
               // (note) The option name doesn't have to match the variable name!
          MyOptions.Add( "V", Volume );           
          MyOptions.Add( "PaintFlag", PaintTheSides );
          MyOptions.Add( "Color", Color );
          
               // *** Step 3: Parse the command line.
          Options.Parse( argv, argc );
          
          std::cout << "Here are the parameters we're going with:" << std::endl;

               // *** Optional Step 3b: Output the parameters to terminal or file
               // (note) This can be done at any time -- e.g. before parsing.
          Options.Print( std::cout );

               // *** Step 4: Run your code!  The parameters are set.                                         
          DoMyStuff( NumBoxes, Volume );               
          
               // *** Step 5: Don't worry about cleanup; Options will do it.
          return 0;
     }

The example illustrates a couple of features. The Options class can deal with std::string (putting quotes around the value on the command line is optional), but should not be used for C style strings because there is no easy way to know how big an array has been allocated (they are not memory safe). Several standard numeric types, as well as bool, are tested. Other built-in types (e.g., float) should probably work.

Option can handle std::vector<T> (if it can handle T!). If a parameter of std::vector<T> type is referred to on the command line, all default values in the vector are eliminated, and the vector will end up containing only what was specified on the command line. A std::vector<T> parameter can be treated exactly like a scalar type by the user -- i.e., with notation like "myprogram intvecparam=1" -- and the vector will end up containing just one element. However, a comma-delimited list can also be provided, optionally enclosed in quotes, as in "myprogram intvecparam=1,2,3".

---