Command line parsing

Once a module is registered, it can then be invoked by its name. A module usually accepts flags or inputs as parameters to the module. The SUIF system includes a command-line-option package to help with this tedious task of parsing the input parameters. The module's initialization routine should store the definition of its parameter profile in the _command_line field. The _command_line is an OptionList, which is a subclass of Option. It defines the options to be parsed, the locations where the input values should be saved, and some ``help'' information to be displayed when the user fails to supply the expected inputs.

As an example, consider writing a pass that that writes the SUIF representation to a given file. The pass therefore requires a filename as an argument. This is how the command line options are specified:

        #include <suifkernel/command_line_parsing.h>
        String _file_name; 

        _command_line->set_description("Write SUIF out to a given file.");

        OptionString *_file_name_argument = new OptionString("Filename", &_file_name);
        _file_name_argument->set_description("Input file name");
        _command_line->add(_file_name_argument);

        // the input file name can be accessed as _file_name.c_str();

The code above simply adds to the _command_line the requirement to accept a string as an argument. The argument is given the mnemonic name of ``Filename'', and the user supplied string is expected to be stored in the _file_name String. The actual C string can be retrieved from the String data structure as _file_name.c_str(). It is also possible to retrieve the file name with the method invocation         _file_name_argument->get_string()->get_string()
The code also gives a short description of the pass as well as the argument. The description will be printed out if the user invokes the pass incorrectly. The following will be printed for the example above if parsing fails:

        Description:
        save_file
        Write SUIF out to a given file

        <Filename>
        Input file name
        ERROR IN
        FILE: module.cpp   LINE: 42 MODULE: suifkernel
        Parsing of command line has failed.

The system provides the support for many common command line options, such as a collection of optional or repeated flags, which may be followed by a parameter. This is implemented with a class hierarchy; deriving from the Option base class are different subclasses to represent different expected inputs. For example, the OptionString class accepts an input string. All options have similar interfaces. The first argument of an option's constructor is its mnemonic name as a string. The second argument is optional, and it corresponds to the address to which the input is to be saved if parsing succeeds. Some options accept additional parameters to change its default behavior. It is also possible to retrieve the inputs using methods supplied by the option class. Table 2 shows all the Option subclasses.

Table 2: Parameter Profile Classes

Option	The base class from which all options are derived. All Options have a set_description method which allows the user to supply a short explanation of the option.
OptionLiteral	Matches a given literal in the input. The is_set method specifies whether there is a match. The result is also stored in the bool to the constructor.
OptionString	Accepts a string token in the command line. The get_string()->get_string() method returns the input String. Alternatively, the address of a String can be passed to the constructor as a second parameter and this string will receive the value.
OptionInt	Accepts an integer from the command line. Similarly to OptionString, a second parameter can be given to the constructor giving a pointer to an integer where the accepted value is to be stored. The result can also be retrieved with get_int()->get_int().
OptionList	Accepts a sequence of options. Options are added to the OptionList with the add method. Note that these added options are not alternatives but rather required parameters.
OptionSelection	Contains a list of optional parameters. Choices are specified by using the add method. The default is that it has to match exactly one of the options. By passing true to the constructor, it can match zero or one option.
OptionLoop	A kleene star option. The constructor takes a pointer to the Option, and matches the given option zero or more times. By passing false to the constructor, the option has to be matched at least once. There is no way to tell how many times the option matched.
OptionStream	Matches part of a command line enclosed in braces ( { and } ). No parsing is done inside the braces.

The command_line_parsing.h includes additional functions to support two common option styles. The first is the build_prefixed_string function which creates an Option tree that matches a literal followed by a string (e.g. -I /usr/include). The second is the build_multi_string function that creates an option that matches a set of strings.