130 lines
4.6 KiB
ReStructuredText
130 lines
4.6 KiB
ReStructuredText
The structure file and data
|
|
============================
|
|
|
|
What contains exactly a :term:`structure file`?
|
|
-------------------------------------------------
|
|
|
|
.. 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`.
|
|
|
|
A :term:`structure file` is a YAML file whose structure is described in this documentation page.
|
|
|
|
A structure file contains a set of variables, usable in your application, for example in a template
|
|
to generate configuration files.
|
|
|
|
:term:`Families <family>` and :term:`variables <variable>` can be defined in several structure files. These structure files are then aggregated.
|
|
|
|
.. _namespace:
|
|
|
|
Separation of structures into namespaces
|
|
----------------------------------------
|
|
|
|
.. glossary::
|
|
|
|
namespace
|
|
|
|
A namespace is a way to organize and group related variables under a unique name.
|
|
|
|
It enables us to:
|
|
|
|
- avoid naming conflicts
|
|
- permit logical grouping: related variables can be grouped together
|
|
- scope control: namespaces limit the visibility of variable to the namespace itself
|
|
|
|
By default there is no namespace.
|
|
|
|
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 (the default 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.
|
|
|
|
The header of a structure file
|
|
-----------------------------------
|
|
|
|
A basic structure file is composed of:
|
|
|
|
- a YAML 1.2 standard header
|
|
- a version attribute
|
|
|
|
.. code-block:: yaml
|
|
|
|
%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.
|
|
This is what we call :term:`structured data` writen in Rougail format.
|
|
|
|
.. figure:: images/schema.png
|
|
:alt: The Rougail process
|
|
:align: center
|
|
|
|
The Rougail process from structure files to Tiramisu valition handler object
|
|
|
|
A variable-first DSL
|
|
-----------------------
|
|
|
|
All of the declaring variables and writing consistency is as simple as writing YAML.
|
|
|
|
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.
|
|
|
|
.. glossary::
|
|
|
|
DSL
|
|
|
|
A DSL stands for **Domain-Specific Language**, it is a programming or markup language designed for a specific application domain.
|
|
Unlike general-purpose languages (like Python or Java), DSLs are optimized for a narrow set of problems, offering concise syntax and specialized features tailored to their domain.
|
|
|
|
Rougail format (or :term:`structured data`) is a DSL (Domain-Specific Language) designed for describing variables and consistency.
|
|
|
|
Declarative abstraction
|
|
-----------------------
|
|
|
|
The variables are described using a declarative model.
|
|
This means that the user simply defines the desired final state of the variable.
|
|
Tiramisu will then determine the actions necessary to reach that state.
|
|
|
|
In other words, the user defines the variable schema, which will then be applied deterministically.
|
|
|
|
The language is a mix of YAML 1.2 and Jinja Templating.
|
|
|
|
Each variables are declaring in a mapping object in YAML (the keys are variable properties).
|
|
|
|
There is an execption. That what we call the short-hand declaration.
|
|
|
|
.. glossary::
|
|
|
|
Short-hand notation
|
|
|
|
Shorthand notation allows you to condense as much information as possible when creating a variable.
|
|
Generally, the declaration is done on a single line (or at most, a very small number of lines).
|
|
|
|
Of course, it's not possible to fully customize the variable with this notation.
|
|
|
|
Use shorthand notation whenever possible. This makes the file easier to read.
|