rougail/docs/structured_data/path.rst

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 the 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_forth_variable:  # My forth variable
    ...

So we have three variables.

Here full path are:

- my_family.my_sub_family.my_first_variable
- my_family.my_sub_family.my_second_variable
- my_family.my_third_variable
- my_forth_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 define :term:`relative path` from the `my_first_variable` variable:

- _.my_second_variable
- __.my_third_variable
- ___.my_third_variable

From the `my_third_variable`:

- _.my_sub_family.my_first_variable
- _.my_sub_family.my_second_variable
- __.my_third_variable

Finally from `my_forth_variable`:

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