.. _dune_instance_parse_file_spec:

dune_instance_parse_file_spec
=============================

.. cmake_function:: dune_instance_parse_file_spec

   .. cmake_brief::

      Parse a file specification into a template file name and an instance
      file name.

   .. cmake_param:: spec
      :positional:
      :single:
      :required:

      The file specification.

   .. 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 then instance file name.

   The file specification can be the name of a template file if it has
   ``.in`` at the end, or the name of an instance file if it doesn't.  The
   name of the other file is obtained by appending or removing ``.in``, as
   applicable.  Both file names can also be given explicitly in the form
   ``template_file_name:instance_file_name``.

   .. note::

      This is the function use to parse the file specifications in
      :ref:`dune_instance_begin() <dune_instance_begin>`.  It is also used
      as a helper in :ref:`dune_instance_from_id() <dune_instance_from_id>`
      to determine template file name and base instance file name.


