OEConfigure¶

bool OEConfigure(OEInterface &itf, OEPlatform::oeistream &istr)
bool OEConfigure(OEInterface &itf, const unsigned char *dataptr)

Provides a mechanism for adding parameters and child OEInterface’s to an OEInterface object, itf, by parsing a specifically formatted text file. The text file must be converted into a null terminated character array at compile time, and passed as the configdata to this function. The format of the config file is a series of parameter or category records.

When OEConfigure encounters a parameter record, it adds an OEParameter object to the OEInterface. A parameter record takes the following form.

!PARAMETER <name> [order priority]
  !TYPE <type>
  !ALIAS <alias>
  !BRIEF <brief description>
  !DEFAULT <default value>
  !REQUIRED <true or false>
  !VISIBILITY <visibility>
  !KEYLESS <keyless setting>
  !LEGAL_VALUE <value>
  !ILLEGAL_VALUE <value>
  !LEGAL_RANGE <hi value> <low value>
  !ILLEGAL_RANGE <hi_value> <low_value>
  !DETAIL
    <detailed description line 1>
    <detailed description line 2>
    <detailed description line 3>
    .
    .
    .
!END

The order of individual fields appear within the parameter record is unimportant. Each parameter record must begin with !PARAMETER and end with !END, and each record must have a !TYPE field. All other fields within the parameter record are optional. So the simplest possible parameter record is.

!PARAMETER <name> [order priority]
  !TYPE <type>
!END

When OEConfigure parses this record it does the equivalent of the following C++ code.

OEParameter* param = itf.AddParameter(<type>);
param->SetName(<name>);
param->SetOrderPriority([order priority]);

If [order priority] isn’t specified, zero is assumed.

Legitimate values of <type> are

string: Creates a std::string parameter
double: Creates a double parameter
float: Creates a float parameter
bool: Creates a bool parameter
int: Creates an int parameter
file: Creates a oeisstream parameter
param_file: Creates a oeisstream parameter that is recognized as a text file holding parameter settings, by OEParseCommandLine.

The remaining fields in a parameter record are optional and do the following:

!ALIAS

alias

param->AddAlias(alias);

This field can appear multiple times.

!BRIEF

brief description

param->SetBrief(brief description);

This field can only appear once.

!DEFAULT

default value

param->SetStringDefault(default value);

This field can only appear once.

!REQUIRED

true or false

param->SetRequired(true or false);

This field can only appear once.

!VISIBILITY

visibility

Visibility must be either simple, normal or hidden This causes either:

param->SetVisibility(OEParamVisibility::Simple);
param->SetVisibility(OEParamVisibility::Normal);
param->SetVisibility(OEParamVisibility::Hidden);

to be called respectively. This field can only appear once in a parameter record.

!KEYLESS

keyless setting

param->SetKeyless(keyless setting);

The keyless setting must be a non-negative integer. This field can only appear once in a parameter record.

!LEGAL_VALUE

value

param->AddLegalValue(value);

Parameters of type bool cannot have a !LEGAL_VALUE field. This field can appear multiple times in a parameter record.

!ILLEGAL_VALUE

value

param->AddIllegalValue(value);

Parameters of type bool cannot have an !ILLEGAL_VALUE field. This field can appear multiple times in a parameter record.

!LEGAL_RANGE

high value low value

param->AddLegalRange(hi value, low value);

Parameters of type bool, string, file and file_param cannot have a !LEGAL_RANGE field. This field can appear multiple times in a parameter record.

!ILLEGAL_RANGE

high value low value

param->AddIllegalRange(hi value, low value);

Parameters of type bool, string, file and file_param cannot have an !ILLEGAL_RANGE field. This field can appear multiple times in a parameter record.

!DETAIL

multi-line

All the lines following the !DETAIL keyword up until a line beginning with another parameter record keyword are added to the parameter.

This field can only appear once.

!CATEGORY

Category record format

When OEConfigure encounters a category record it adds a child OEInterface object to the current OEInterface. A category record takes the following form:
!CATEGORY <name> [order priority]
  !DETAIL
    <detailed description line 1>
    [detailed description line 2]
    [detailed description line 3]
    .
    .
    .
  !BRIEF <brief description>
  [Parameter Record]
  [Category Record]
!END
The order individual fields appear within the category record is unimportant. All fields within the category record are optional. So the following is the minimal category allowed:
!CATEGORY <name> [order priority]
!END
When parsed by OEConfigure is equivalent to:
OEInterface* child_itf = itf.AddInterface();
child_itf->SetName(<name>);
child_itf->SetOrderPriority([order priority]);
If [order priority] is not specified 0 is assumed.

Fields within the category record have the following meaning:
!DETAIL
multi-line

All the lines following the !DETAIL keyword up until a line beginning with another category record keyword are added to the parameter.

This field can appear once in a category record.

!BRIEF
brief description
param->SetBrief(brief description);
This field can only appear once.
parameter record
Parameter records can appear inside category records. Their format is the same as those outside the category record, however the parameter will be added to the child interface. A category record can hold any number of parameter records.

category record
Category records can be nested within category records, thus creating a child OEInterface of a child OEInterface. There is no limit to the depth of nesting, and any number of nested category records can appear within a category record.