rougail/docs/structured_data/path.rst

.. index:: path, variable's relative path, variable's full path

.. _variablepath:

Full or relative path
=====================

To access a variable, it is necessary to know which family or subfamily it belongs to.

Let's create some variables to illustrate this point.

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1

    my_family:  # A family

      my_sub_family:  # A family inside an other family

        my_first_variable:  # My first variable

        my_second_variable:  # My second variable

      my_third_variable:  # My third variable

    my_fourth_variable:  # My forth variable
    ...

So we have three variables.

Here the full paths are:

- `my_family.my_sub_family.my_first_variable`
- `my_family.my_sub_family.my_second_variable`
- `my_family.my_third_variable`
- `my_fourth_variable`

But in calculation it's often better to use :term:`relative path`.

.. glossary::

   relative path

        In a calculation definition, a relative path defines the location of a variable relative to the family of the variable where the parameter is calculated.
        Instead of starting from the root, it uses references like `_. (current family)`, `__. (parent family)`, `___. (sub parent family)` and so on.

        Relative paths are shorter and portable across custom type.

Now we can define the :term:`relative path` from the `my_first_variable` variable:

- `_.my_second_variable`
- `__.my_third_variable`
- `___.my_fourth_variable`

From the `my_third_variable`:

- `_.my_sub_family.my_first_variable`
- `_.my_sub_family.my_second_variable`
- `__.my_fourth_variable`

Finally from the `my_fourth_variable`:

- `_.my_family.my_sub_family.my_first_variable`
- `_.my_family.my_sub_family.my_second_variable`
- `_.my_family.my_third_variable`