.. # split from OESystemFunctions.rst:1972

.. include:: ../substitutions

.. oe:namespace:: OESystem

.. meta::
   :keywords: OEParseCommandLine

.. oe:function:: OEParseCommandLine

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

      .. oe:api::

         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)

   .. oe:language:: python

      .. oe:api:: python

         OEParseCommandLine(itf: OEInterface, argc: int, argv: str,
                            requirements: str = None, error_level: int,
                            checkhelp: bool = True) -> bool
         OEParseCommandLine(itf: OEInterface, version: str, argc: int,
                            argv: str, requirements: str = None,
                            error_level: int, checkhelp: bool = True) -> bool


   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
   :oe:constns:`OESystem::OEThrow`.

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

   By default, ``checkhelp`` is true, forcing
   :oe:func:`OESystem::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.

   .. code-block:: bash

      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.

   .. code-block:: bash

      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

      .. code-block:: bash

         program -b true -x 5

      and

      .. code-block:: bash

         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 :ref:`OEInterface <OESystem_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 :oe:meth:`OESystem::OEParameter::GetKeyless`
      method) can be entered at the end of the command line as a
      value without a key. The format is as follows

      .. code-block:: bash

         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.

      .. code-block:: bash

         program -b true keylessvalue

   If '-b' is a boolean parameter true could either be the setting of
   '-b' or the first keyless parameter. :oe:func:`OESystem::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 :oe:func:`OESystem::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 :ref:`OEParameter <OESystem_OEParameter>` class (or the ``!REQUIRED`` field on
   :oe:func:`OESystem::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.

   .. code-block:: bash

      !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 :oe:meth:`OESystem::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
      :oe:meth:`OESystem::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 :oe:constns:`OESystem::OEThrow` and the
   function returns false.

   The following is an example parameter record:

   .. code-block:: bash

      !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 :oe:constns:`OESystem::OEThrow` and the function returns ``false``.

