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 ` and :term:`variables ` 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-.yml Where `XX` is a two digits integer followed by an hyphen, and `` 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 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 ` parameter of the :doc:`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 `. 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.