187 lines
6.4 KiB
ReStructuredText
187 lines
6.4 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.
|
|
|
|
File naming convention
|
|
--------------------------
|
|
|
|
.. _filenamingconvention:
|
|
|
|
The structure files in a given folder
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
For the sake of clarity, we put the structured data in separate files.
|
|
It's a good way to organize your rougail structures this way,
|
|
in the real world we need separate files for different topics.
|
|
|
|
For example some files like this:
|
|
|
|
A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml`
|
|
|
|
::
|
|
|
|
.
|
|
└── firefox
|
|
├── 00-proxy.yml
|
|
└── 10-manual.yml
|
|
|
|
.. note:: We of course could have put everything in one file.
|
|
Again, it is better to separate the structures in different files
|
|
for reasons of ordering and clarity.
|
|
|
|
Ordering your structure files
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The order in which files are loaded is important in Rougail.
|
|
In a given folder, files are loaded in alphabetical order.
|
|
|
|
Furthermore, for better readability of the order in which files are
|
|
loaded into a folder, we have adopted a convention.
|
|
To facilitate classification, we have defined a standard notation for structure file names:
|
|
|
|
::
|
|
|
|
XX-<name>.yml
|
|
|
|
Where `XX` is a two digits integer followed by an hyphen, and `<name>` is a name that describes
|
|
the structure that is in this file. We advise you to adopt this convention as well.
|
|
|
|
File naming convention
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The is no restriction to the `<name>` name part of file name. But it is preferable to only use
|
|
lowercase ASCII letters, numbers and the `"_"` (undescore) character.
|
|
|
|
.. _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.
|
|
|
|
Versioned
|
|
---------
|
|
|
|
The format can evolve. This means that parameters can be added, removed, or modified.
|
|
When writing structured data, you must always specify the format version.
|
|
You must also ensure that your Rougail version is compatible with your format version.
|