cmake_parse_arguments
---------------------

``cmake_parse_arguments`` is intended to be used in macros or functions for
parsing the arguments given to that macro or function.  It processes the
arguments and defines a set of variables which hold the values of the
respective options.

::

  cmake_parse_arguments(<prefix> <options> <one_value_keywords>
                        <multi_value_keywords> args...)

  cmake_parse_arguments(PARSE_ARGV N <prefix> <options> <one_value_keywords>
                        <multi_value_keywords>)

The first signature reads processes arguments passed in the ``args...``.
This may be used in either a :command:`macro` or a :command:`function`.

The ``PARSE_ARGV`` signature is only for use in a :command:`function`
body.  In this case the arguments that are parsed come from the
``ARGV#`` variables of the calling function.  The parsing starts with
the Nth argument, where ``N`` is an unsigned integer.  This allows for
the values to have special characters like ``;`` in them.

The ``<options>`` argument contains all options for the respective macro,
i.e.  keywords which can be used when calling the macro without any value
following, like e.g.  the ``OPTIONAL`` keyword of the :command:`install`
command.

The ``<one_value_keywords>`` argument contains all keywords for this macro
which are followed by one value, like e.g. ``DESTINATION`` keyword of the
:command:`install` command.

The ``<multi_value_keywords>`` argument contains all keywords for this
macro which can be followed by more than one value, like e.g. the
``TARGETS`` or ``FILES`` keywords of the :command:`install` command.

.. note::

   All keywords shall be unique. I.e. every keyword shall only be specified
   once in either ``<options>``, ``<one_value_keywords>`` or
   ``<multi_value_keywords>``. A warning will be emitted if uniqueness is
   violated.

When done, ``cmake_parse_arguments`` will have defined for each of the
keywords listed in ``<options>``, ``<one_value_keywords>`` and
``<multi_value_keywords>`` a variable composed of the given ``<prefix>``
followed by ``"_"`` and the name of the respective keyword.  These
variables will then hold the respective value from the argument list.
For the ``<options>`` keywords this will be ``TRUE`` or ``FALSE``.

All remaining arguments are collected in a variable
``<prefix>_UNPARSED_ARGUMENTS``, this can be checked afterwards to see
whether your macro was called with unrecognized parameters.

As an example here a ``my_install()`` macro, which takes similar arguments
as the real :command:`install` command:

.. code-block:: cmake

   function(MY_INSTALL)
       set(options OPTIONAL FAST)
       set(oneValueArgs DESTINATION RENAME)
       set(multiValueArgs TARGETS CONFIGURATIONS)
       cmake_parse_arguments(MY_INSTALL "${options}" "${oneValueArgs}"
                             "${multiValueArgs}" ${ARGN} )

       # ...

Assume ``my_install()`` has been called like this:

.. code-block:: cmake

   my_install(TARGETS foo bar DESTINATION bin OPTIONAL blub)

After the ``cmake_parse_arguments`` call the macro will have set the
following variables::

   MY_INSTALL_OPTIONAL = TRUE
   MY_INSTALL_FAST = FALSE (was not used in call to my_install)
   MY_INSTALL_DESTINATION = "bin"
   MY_INSTALL_RENAME = "" (was not used)
   MY_INSTALL_TARGETS = "foo;bar"
   MY_INSTALL_CONFIGURATIONS = "" (was not used)
   MY_INSTALL_UNPARSED_ARGUMENTS = "blub" (nothing expected after "OPTIONAL")

You can then continue and process these variables.

Keywords terminate lists of values, e.g.  if directly after a
one_value_keyword another recognized keyword follows, this is
interpreted as the beginning of the new option.  E.g.
``my_install(TARGETS foo DESTINATION OPTIONAL)`` would result in
``MY_INSTALL_DESTINATION`` set to ``"OPTIONAL"``, but as ``OPTIONAL``
is a keyword itself ``MY_INSTALL_DESTINATION`` will be empty and
``MY_INSTALL_OPTIONAL`` will therefore be set to ``TRUE``.