The structure files
=====================

Definition
------------

.. glossary::

   structure file

       A structure file in the Rougail meaning is a YAML file that describes variables
       and their dependencies.
       There can be a lot of structure files located in many different folders.

       Rougail reads all the structure files and loads them into a single object
       that represents the whole :term:`context`.


The header of a structure file
-----------------------------------

A basic structure file is composed of:

- a YAML 1.2 standard header
- a version attribute

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
   :language: yaml
   :caption: An empty Rougail structure file.
   :name: RougailStructureFirstVariableDescription

..
    %YAML 1.2
    ---
    version: 1.1
    ...

The structure file processing
----------------------------------

The structured files contain information that will be used by the consistency 
handling system for structure validation. 

.. figure:: images/schema.png
   :alt: The Rougail process
   :align: center

   The Rougail process from structure files to Tiramisu valition handler object

The structured data
---------------------

.. glossary:: 

   structured data
   
       We sometimes call "structured datas" the datas that are defined in the structure files,
       as opposed to :term:`user datas <user datas>`\ .
       For example when a value of a variable is defined in the structured datas, that is
       in a structured file, the assigned value's status is that the variable's value is a default value. 
       If the assigned value of the variable is defined in a user data file, 
       it is an user assigned value.

We'll see later on some examples of default values and user assigned values.

The main advantage of all of this that declaring variables and writing consistency is as simple
as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more.
It simplifies a lot of things.

And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative style (that is, in a YAML file).

Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them.

What contains exactly a :term:`structure file`?
-------------------------------------------------

A :term:`structure file` is a YAML file whose structure is described in this documentation page.

A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a :term:`template` 
to generate configuration files.

:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated.

If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. <tutorial>`

The default namespace
-------------------------

The families and variables contained in these structure files are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace <variable_namespace>` parameter of the :doc:`configuration <configuration>`.

This namespace is a bit special, it can access variables in another namespace.

The extra structure files
---------------------------

An extra is a different namespace. The idea is to be able to classify the variables by theme.

Extra namespaces must be declared :doc:`when configuring Rougail <configuration>`.

In this namespace we cannot access variables from another `extra` namespace. 
On the other hand, it is possible to access the variable of the default namespace.