rougail/doc/dev/README.md

La bibliothèque rougail

Rougail est une bibliothèque simple a utiliser.

Dans les exemples suivant, nous utilisons la configuration par défaut de Rougail. Vous pouvez personnaliser les répertoires utilisés.

Convertisons un dictionnaire en objet tiramisu

Commençons par créer un dictionnaire simple.

Voici un premier dictionnaire /srv/rougail/dictionaries/00-base.xml :

<?xml version='1.0' encoding='UTF-8'?>
<rougail>
    <variables>
        <variable name="my_variable">
            <value>my_value</value>
        </variable>
    </variables>
</rougail>

Construisons les objets tiramisu :

from rougail import RougailConvert

rougail = RougailConvert()
rougail.save('example1.py')

Un nouveau fichier 'example1.py' va être créé dans le répertoire local

Convertisons un dictionnaire et un dictionnaire extra en objet tiramisu

En plus du dictionnaire précédent, créons un dictionnaire extra /srv/rougail/extra_dictionaries/00-base.xml

<?xml version='1.0' encoding='UTF-8'?>
<rougail>
    <variables>
        <variable name="my_variable_extra">
            <value>my_value_extra</value>
        </variable>
    </variables>
</rougail>

Construisons les objets tiramisu :

from rougail import RougailConvert, RougailConfig

RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/']

rougail = RougailConvert()
rougail.save('example2.py')

Templatisons un template

Nous créons un dictionnaire complémentaire pour ajouter notre template /srv/rougail/dictionaries/00-template.xml :

<?xml version='1.0' encoding='UTF-8'?>
<rougail>
    <services>
        <service name="example">
            <file name="/etc/example.conf"/>
        </service>
    </services>
</rougail>

Et un template /srv/rougail/templates/example.conf :

The value: %%my_variable

The extra value: %%example.my_variable_extra

Générons le fichier tiramisu :

from rougail import RougailConvert, RougailConfig

RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/']

rougail = RougailConvert()
rougail.save('example3.py')

Créer les répertoires utils pour la templatisation : mkdir /srv/rougail/destinations /srv/rougail/tmp

Générons le template :

import asyncio
from tiramisu import Config
from rougail import RougailTemplate
from example3 import option_0

async def template():
    config = await Config(option_0)
    engine = RougailTemplate(config)
    await engine.instance_files()

loop = asyncio.get_event_loop()
loop.run_until_complete(template())
loop.close()

Le fichier /srv/rougail/destinations/etc/example.conf est maintenant créé avec le contenu attendu suivant :

The value: my_value

The extra value: my_value_extra

Appliquons un patch au template

Il peut être intéressant de réaliser un patch à un template pour corriger un problème spécifique à notre environnement, sans attendre que le mainteneur du template n'est fait la correction.

Testons en créant le patch /srv/rougail/patches/example.conf.patch :

--- /srv/rougail/templates/example.conf	2021-02-13 19:41:38.677491087 +0100
+++ tmp/example.conf	2021-02-13 20:12:55.525089820 +0100
@@ -1,3 +1,5 @@
 The value: %%my_variable
 
 The extra value: %%example.my_variable_extra
+
+Add by a patch

Le patch est bien appliquer sur notre fichier /srv/rougail/destinations/etc/example.conf :

The value: my_value

The extra value: my_value_extra

Add by a patch

Deux choses importantes à savoir sur les patchs :

• le nom du patch est obligatoire le nom du template source + ".patch"
• la deuxième ligne toujours commencer par "+++ tmp/" + le nom du template source

Créons une fonction personnalisé

Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variable my_variable_extra dans /srv/rougail/dictionaries/00-fill.xml :

<?xml version='1.0' encoding='UTF-8'?>
<rougail>
    <constraints>
        <fill name="return_no">
            <target>my_variable</target>
        </fill>
    </constraints>
</rougail>

Puis créons la fonction "return_no" dans /srv/rougail/functions.py :

def return_no():
    return 'no'

Après avoir reconverti les dictionnaires et regénérer le template nous avons donc le contenu du fichier /srv/rougail/destinations/etc/example.conf :

The value: no

The extra value: my_value_extra

Add by a patch

La valeur de la variable my_variable est bien calculé à partir de la fonction "return_no".