.. # split from OESystemFunctions.rst:611

.. include:: ../substitutions

.. oe:namespace:: OESystem

.. meta::
   :keywords: OEConfigure

.. oe:function:: OEConfigure

   .. oe:language:: c++ java csharp

      .. oe:api::

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

   .. oe:language:: python

      .. oe:api:: python

         OEConfigure(itf: OEInterface, istr: oeistream) -> bool
         OEConfigure(itf: OEInterface, itfdata: str) -> bool

   Provides a mechanism for adding parameters and child
   :ref:`OEInterface <OESystem_OEInterface>`'s to an :ref:`OEInterface <OESystem_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 :oe:func:`OESystem::OEConfigure` encounters a parameter record, it adds an
   :ref:`OEParameter <OESystem_OEParameter>` object to the :ref:`OEInterface <OESystem_OEInterface>`.
   A parameter record takes the following form.

   .. code-block:: bash

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

   .. code-block:: bash

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

   When :oe:func:`OESystem::OEConfigure` parses this record it does the
   equivalent of the
   following C++ code.

   .. code-block:: c++

      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 :ref:`oeisstream <OEPlatform_oeisstream>` parameter
   *param_file*
       Creates a :ref:`oeisstream <OEPlatform_oeisstream>` parameter that is recognized as a
       text file holding parameter settings, by :oe:func:`OESystem::OEParseCommandLine`.

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


   **!ALIAS**
       *alias*

       .. code-block:: c++

          param->AddAlias(alias);

       This field can appear multiple times.

   **!BRIEF**
       *brief description*

       .. code-block:: c++

          param->SetBrief(brief description);

       This field can only appear once.

   **!DEFAULT**
       *default value*

       .. code-block:: c++

           param->SetStringDefault(default value);

       This field can only appear once.

   **!REQUIRED**
       *true* or *false*

       .. code-block:: c++

          param->SetRequired(true or false);

       This field can only appear once.

   **!VISIBILITY**
       *visibility*

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

       .. code-block:: c++

          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*

       .. code-block:: c++

          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*

       .. code-block:: c++

          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*

       .. code-block:: c++

          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*

       .. code-block:: c++

          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*

       .. code-block:: c++

          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 :oe:func:`OESystem::OEConfigure` encounters a category record it adds a child
      :ref:`OEInterface <OESystem_OEInterface>` object to the current :ref:`OEInterface <OESystem_OEInterface>`.
      A category record
      takes the following form:

      .. code-block:: bash

         !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:

      .. code-block:: bash

         !CATEGORY <name> [order priority]
         !END

      When parsed by :oe:func:`OESystem::OEConfigure` is equivalent to:

      .. code-block:: c++

         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*

       .. code-block:: c++

          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 :ref:`OEInterface <OESystem_OEInterface>` of a child :ref:`OEInterface <OESystem_OEInterface>`.
         There is no
         limit to the depth of nesting, and any number of nested category
         records can appear within a category record.



