rougail/docs/gettingstarted.rst

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 <dictionaries>`.

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/commit/v1.1_001/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: An empty rougail dictionnary file. It's a YAML format.
   :name: RougailDictionaryEmptyFile

:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml>`

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 <dictionary>` example with a variable into it:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/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

:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml>`

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_004/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description.
   :name: RougailDictionaryFirstVariableDescription

The same with a default value:


.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
   :name: RougailDictionaryFirstVariableDefault

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, <name> " 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'}