###########################
Paths and variables in Yaml
###########################

.. role:: bash(code)
   :language: bash

Environment variables
=====================

When setting up pyCIF, please prefer absolute paths as much as possible.
However, for conveniency, the YAML parser in pyCIF has been designed to understand environment variables, as well as the tilde expansion.

Below is a simple example of how it works:

.. code-block:: yaml

    myrefdir: ~/somedir/somesubdir

    myrelativedirfromenvvariable: ${ENV_VARIABLE}/somesubdir

Please note that environment variables must be necessary between :bash:`{}`.

As a reminder, the following command should be used in bash to define an environment variable:

.. code-block:: bash

    export ENV_VARIABLE="/some_path_to_whatever"

Anchors in Yaml
===============

It is possible to define shortcuts to variables defined in your Yaml and use them elsewhere.
However, concatenation does not work straight away in basic Yaml.
A functionality was used in pyCIF following examples on `StackOverflow <https://stackoverflow.com/a/23212501>`__.

The anchors are defined with the character :bash:`&`, and called with :bash:`*` and concatenation is allowed with the custom constructor :bash:`!join`:

.. code-block:: yaml

    ref_dir : &ref_dir /some/reference/dir/
    secondary_dir : &second_dir /some/other/dir/
    reference_ID: &ref_id some_ref

    myrelativedir: !join [ *ref_dir, input/ ]
    mycomplexname: !join [ *secondary_dir, *reference_ID, /complementary_name.txt ]

In the example, after initialization of the yaml, the configuration file is equivalent to:

.. code-block:: yaml

    myrelativedir: /some/reference/dir/input/
    mycomplexname: /some/other/dir/some_ref/complementary_name.txt

File name formats and dates
===========================

.. role:: bash(code)
   :language: bash


Various types of files are necessary to run pyCIF. pyCIF accepts generic
formats when file names are dependent on, e.g., the date of the
simulation. In this case, the generic date-dependent file name should be
given as a string compatible with the Python datetime function,
:bash:`strptime` as detailed
`here <https://docs.python.org/2/library/datetime.html#strftime-and-strptime-behavior>`__.

For instance, if your meteo file names are function of the current date,
the following syntax will be required in the Yaml file:

.. code-block:: yaml

    mymeteo: /mymeteo_folder/mymeteo_%Y%m%d_%H%M.nc

pyCIF will automatically recognize a date format as YYYYMMDD_HHMM, i.e.
20140327_1212 corresponds to March 27 :sup:`th`, 2014
at 12:12.