.. _dune_instance_from_id:

dune_instance_from_id
=====================

.. cmake_function:: dune_instance_from_id

   .. cmake_brief::

      Determine a template file name and an instance file name from a file
      specification and a unique id.

   .. cmake_param:: file_spec
      :positional:
      :single:
      :required:

      The file specification.

   .. cmake_param:: id
      :positional:
      :single:
      :required:

      The id specification.  This should uniquely identify an instance.

   .. cmake_param:: template_var
      :positional:
      :single:

      Name of the variable to store the template file name in.  Can be empty
      to discard the template file name.

   .. cmake_param:: instance_var
      :positional:
      :single:

      Name of the variable to store the instance file name in.  Can be empty
      to discard the instance file name.

   The file specification is handed to :ref:`dune_instance_parse_file_spec()
   <dune_instance_parse_file_spec>` to determine a template file name and a
   *base* instance file name.

   The ID is mangled by replacing any runs of non-alphanumeric characters
   with an underscore ``_``, and stripping any resulting underscore from the
   beginning and the end.  The result is inserted before any extension into
   the base instance file name to form the instance file name.

   .. note::

      This is the function use to parse the file specifications given in
      :ref:`dune_instance_add(FILES ...) <dune_instance_add>`.


