################
Script templates
################

Autosubmit jobs require a ``FILE`` property that points to a
script template. Script templates can be written in Bash shell,
R, or Python. By default, the ``TYPE`` property of a job is set
to ``bash``. Template scripts can have any file extension,
the generated script will have it replaced by ``.cmd``.

.. code-block:: yaml
  :emphasize-lines: 3
  :caption: Job ``JOB_1`` with template script ``PRINT_EXPID.sh``

  JOBS:
    JOB_1:
      FILE: PRINT_EXPID.sh
      PLATFORM: LOCAL
      RUNNING: once
      TYPE: bash # default

The script template ``PRINT_EXPID.sh`` file must exist in the
Autosubmit Project. When you run ``autosubmit create`` or
``autosubmit refresh``, Autosubmit will copy the Project files,
including template scripts, to the experiment `proj` folder.
The template scripts are then preprocessed and the final script
is generated when an Autosubmit experiment is
:ref:`inspected <inspect_cmd>` or :doc:`created </userguide/run/index>`.

When Autosubmit preprocesses the template script, it will replace
*placeholders* by configuration values. A placeholder is any
configuration key wrapped by ``%%``. For example, ``%DEFAULT.EXPID%``,
as seen below, refers to the Autosubmit configuration value
found in the ``DEFAULT.EXPID`` YAML key.

Assuming that one of the Autosubmit experiment configuration files
contains the following:

.. code-block:: yaml
  :caption: Autosubmit configuration

  DEFAULT:
    EXPID: a000
    # ... other settings

And a template script used in that experiment contains the following
code:

.. code-block:: bash
  :caption: A template script

  #!/bin/bash

  echo "The experiment ID is %DEFAULT.EXPID%"

Then after the template script is preprocessed by Autosubmit, the
generated script will will be written in the experiment folders
with the extension ``.cmd`` and it will look like this:

.. code-block:: bash
  :caption: Generated script

  #!/bin/bash

  # Autosubmit Header
  # ...

  echo "The experiment ID is a000"

  # Autosubmit Tailer

Header and Tailer
=================

Autosubmit does not require users to modify the header and
tailer used. The header contains code to set the correct locale,
and create supporting files for Autosubmit (e.g. ``<EXPID>_TEST_STAT``),
to functions used internally by Autosubmit (e.g. for checkpointing).

While the tailer takes care to create other supporting files
(e.g. ``<EXPID>_TEST_COMPLETED`` and update ``<EXPID>_TEST_STAT``).

Although, if necessary, Autosubmit supports appending to the default
header and tailer an user-defined script. Using directives
``EXTENDED_HEADER_PATH`` and ``EXTENDED_TAILER_PATH``, users can
indicate the position, with respect to the project root folder, the
where is the script for Autosubmit to append.
