10.25 OEParseCommandLine

bool OEParseCommandLine(OEInterface& itf,
                        int argc,
                        char** argv,
                        const unsigned char* requirements = NULL,
                        unsigned int error_level = OEErrorLevel::Error);

The overall purpose of this function is to set parameters in the itf object by parsing the command line, argc and argv. This function returns true if it was successful and false otherwise. Errors are reported at error_level to OEThrow.

Parameters are entered in key-value pairs after the executable name on the command line. The key is the parameters name appendend with its instance (typically instance is just an empty string, so key is just the parameter name).

E.g.

program <parameter1 key> <parameter1 value> <parameter2 key> <parameter2 value>

The order in which the parameter key-value pairs appear on the command line is unimportant, except when the same key is specified twice in which case the second value specified is used.

E.g.

program <parameter2 key> <parameter2 value> <parameter1 key> <parameter1 value>

is the same as the preceding example.

The following special case rules also apply when parsing the command line.

Boolean parameter keys can optionally not be followed by a boolean value in which case the boolean parameter is set to true. E.g.,
```
program -b true -x 5
```
and
```
program -b -x 5
```
are equivilant, provided that -b is a boolean parameter.
Parameters of type "param_file" will be assumed to be text files containing key-value parameter pairs for the OEInterface object, itf. These files will be parsed and the parameters set accordingly. The format of these files should be one key-value pair per line. Blank lines and lines begining with # will be ignored. If a parameter is set both in a parameter file and on the command line, the command line setting will be used.
Parameters with non-zero keyless values (see GetKeyless() method of OEParameter) can be entered at the end of the command line as a value without a key. The format is as follows
```
program [<key> <value>]... <keyless1 value> [<keyless2 value>]...
```
Any number of key-value pairs can be entered on the command line before the keyless values. Parsing from left to right the first argument on the command line not recognized as a key-value pair is assigned to the parameter with the keyless value 1. Additional arguments beyond the first are assigned to the parameter with keyless value 2, 3, 4 and so on. If the itf object does not have a parameter with the appropriate keyless value or has more than one parameter with the appropriate keyless value an error will be reported and the function will return false.
Note: There is a potential ambiguity in the command line when the last key-value pair specified before the first keyless parameter is a boolean, as in the following example.
```
program -b true keylessvalue
```
If -b is a boolean parameter true could either be the setting of -b or the first keyless parameter. OEParseCommandLine resolves this by always assuming that true, or any valid boolean setting (i.e., true/yes/on/t/y or false/no/off/f/n), is a setting for the boolean parameter -b and NOT the first keyless value.

After OEParseCommandLine parses the command line it then check that all required parameter have been set. If all required parameters have not been set and error is issued and the function returns false.

There are two types of requirements

single parameter requirements

This type of requirement forces that a particular parameter must be specified on the command line in a parameter file or by a default value. This requirment is turned on using the SetRequired method of the OEParameter class (or !REQUIRED field on OEConfigure).

multi-parameter requirements

This type of requirement can include inter-dependent settings of parameters. These requirements are specified by passing requirements to this function, which is a specially formatted text file that has been converted into a null terminated character array. The format is a series of one or more requirement records of the following format.

!REQUIREMENT
  !OPTION [[!]key [value] [[!]key [value]...
  !OPTION [[!]key [value] [[!]key [value]...
  .
  .
  .
  !ERROR_MSG
    <error message line 1>
    <error message line 2>
    .
    .
    .
!END

One or more !OPTION fields may appear in a requirement record. Each !OPTION field is a list of keys, optionally with values, to require. The rules for the format of the !OPTION line are as follows.

If a key appears on the !OPTION line, but is not followed by a parameter value, then that parameter must have a valid setting (e.g., the parameter method IsSet must return true).
If a key appears on the !OPTION line followed by a value, then that parameter must be set to the specified value.
If a key appears on the !OPTION line preceeded by a !, but is not followed by a parameter value, then that parameter must not have a valid setting (e.g., the parameter method IsSet must return false).

If any !OPTION field of a requirement record is satisfied, the entire requirement is satisfied. No !OPTION in the requirement record is satisfied, the error message is sent to OEThrow and the function returns false.

The following is an example parameter record

!REQUIREMENT
  !OPTION -a 5
  !OPTION !-b
  !OPTION -a -b !-c 1
  !ERROR_MSG
    The command line must satisfy one of the following criteion
    1) -a is set to 5
    2) -b is not set
    3) -a and -b are set and -c is not set to 1
!END

This requirement record requires that the settings in itf follow the rules listed between !ERROR_MSG and !END. If it does not those lines are sent to OEThrow and the function returns false.

				OEChem - API Manual Version 1.3.1

				OEChem - API Manual Version 1.3.1