Getting started ==================== What is a consistency handling system ? ------------------------------------------------ .. questions:: "OK, I have understood that the Rougail stuff enables me to take advantage of :xref:`tiramisu`. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`tiramisu` library used for?" *Answer*: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it. .. glossary:: Tiramisu :xref:`tiramisu` is a consistency handling system that has initially been designed in the configuration management scope. To put it more simply, this library is generally used to handle configuration options. It manages variables and group of variables. In the Tiramisu scope we call it *options* and *option descriptions*. Here is the :xref:`tiramisu library`. In the Rougail scope, we call it :term:`variable`\ s and :term:`families`. In Rougail, the families and variables are located in the :term:`structure files `. And this is what we are going to explain in this page. The structure files --------------------- .. glossary:: structure file dictionary dictionaries A dictionary in the Rougail meaning is a YAML file that describes variables and their dependencies / consistencies. There can be a lot of dictionary files located in many different folders. Rougail reads all the dictionaries and loads them into a single object that handles the variables consistency. A dictionary file is a structure file, we call a dictionary a structure file. .. image:: images/schema.png The main advantage is 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 mode (that is, in a YAML file). Once the structure files are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool. The YAML structure files format ------------------------------------ Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts). .. todo:: parler de jinja https://jinja.palletsprojects.com Here is an empty rougail dictionary YAML file .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :linenos: :language: yaml :caption: An empty rougail dictionnary file. It's a YAML format. :name: RougailDictionaryEmptyFile .. --- version: 1.1 :download:`source file ` You can see that there is just a `version` specification. .. glossary:: version The version is here a Rougail YAML dictionary version format. It is set in the beginning of a YAML dictionary, or globaly in the Rougail settings for example from the command line .. note:: You can set the format in the Rougail command line tool like this: .. code-block:: bash foo@bar:~$ rougail -v 1.1 The variables ----------------- Here is a :term:`structure file ` example with a variable into it: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format. :name: RougailDictionaryFirstVariable .. --- proxy_mode: :download:`source file ` Here we declare a **variable** named `proxy_mode` without a default value. A variable can be defined with no default value at all. Here is the same variable with a description label: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description. :name: RougailDictionaryFirstVariableDescription .. --- proxy_mode: description: Configure Proxy Access to the Internet The same with a default value: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml :linenos: :language: yaml :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value. :name: RougailDictionaryFirstVariableDefault .. --- proxy_mode: description: Configure Proxy Access to the Internet default: No proxy variable A variable is a declaration unit that represents a business domain metaphor, the most common example is that a variable that represents a configuration option in a application, but a variable represents something more that a configuration option. It provides a business domain specific representation unit. .. todo:: définir une variable avec une description, un type, l'inférence de type, les notations condensées, une family sans variable doit avoir un type: family, .. note:: Dictionaries can just define a list of variables, but we will see that we can specify a lot more. We can define variables **and** their relations, **and** the relations between them. In the next step, we will explain through a tutorial how to construct a list of variables. Families of variables -------------------------- .. glossary:: family families A family of variables is simply a collection of variables that refer to the same business model category. It's just a variables container. Think of it as a container as well as a namespace. A "hello world" with Rougail ------------------------------ We're gonna make the simplest possible example. .. prerequisites:: Prerequisites We assume that Rougail's library is installed on your computer (or in a virtual environment). .. exercise:: Hello world's workshop Here is the tree structure we want to have:: workplace ├── dict    │   ├── hello.yml    └── hello.py - Let's make a :file:`workplace` directory, with a :file:`dict` subfolder. - First, we need a :term:`dictionary`, so let's make the :file:`hello.yml` file which is located in the :file:`dict` subfolder, with the following content: .. code-block:: yaml :caption: The `hello.yaml` file --- version: '1.1' hello: default: world .. todo:: mettre un appel à la CLI pour lancer le truc We launch the script: .. code-block:: bash python hello.py And we obtain the following result: .. code-block:: python {'rougail.hello': 'world'} **Congratulations ! You have successfully completed your first Rougail script.** A "Hello, " sample with a family ------------------------------------------ Let's continuing on our "Hello world" theme and add a :term:`family` container. .. code-block:: yaml :caption: the :file:`hello.yml` file :linenos: --- version: '1.1' world: description: Hello world family container name: description: Somebody to say hello default: rougail Here, we have a family named `world`. This family contains a variable named `name` Again, let's validate this YAML file against Rougail's API: .. code-block:: bash python hello.py We then have the output: .. code-block:: python {'rougail.world.name': 'rougail'}