OEParseCommandLine¶

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

Sets 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.

The version argument specifies what should be printed whenever the --version is found in argv.

By default, checkhelp is true, forcing OECheckHelp to be called at the very beginning of this function. If checkhelp is true and the --help parameter is found, the exit system call is called to exit the process with a 0 exit code.

Parameters are entered in key-value pairs after the executable name on the command line.

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.

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
```
program -b true -x 5
```
and
```
program -b -x 5
```
are equivalent, 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 beginning 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 OEParameter.GetKeyless method) 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 checks that all required parameters have been set. If all required parameters have not been set an error is issued and the function returns false.

The following are the 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 requirement is turned on using the SetRequired method of the OEParameter class (or the !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 OEParameter.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 preceded by a !, but is not followed by a parameter value, then that parameter must not have a valid setting (e.g., the parameter method OEParameter.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 criterion
      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.