rougail/doc/dev/README.md

La bibliothèque Rougail

Rougail est une bibliothèque qui permet de charger simplement des dictionnaires et de générer des templates.

Dans les exemples suivant, nous utiliserons une configuration particulière de Rougail. Vous retrouverez toutes les options pour personnaliser les répertoires utilisés.

Le script contiendra donc les éléments de configuration suivant :

from rougail import RougailConfig

RougailConfig['dictionaries_dir'] = ['dict']
RougailConfig['templates_dir'] = ['tmpl']
RougailConfig['tmp_dir'] = 'tmp'
RougailConfig['destinations_dir'] = 'dest'
RougailConfig['functions_file'] = 'funcs/functions.py'

Penser a créer les répertoires :

$ mkdir dest dict tmp tmpl extras

Convertisons un dictionnaire

Un dictionnaire est un ensemble d'instruction qui vont permettre de créer des variables.

Commençons par créer un dictionnaire simple.

Voici un premier dictionnaire dict/00-base.yml :

version: '0.10'
variables:
- variable:
  - name: my_variable
    value:
    - text: my_value

Puis, créons les objets Tiramisu :

from rougail import Rougail, RougailConfig
from asyncio import run

async def main():
    RougailConfig['dictionaries_dir'] = ['dict']
    rougail = Rougail()
    config = await rougail.get_config()
    print(await config.value.dict())

run(main())

Exécution le script :

$ python3 script.py
{'rougail.my_variable': 'my_value'}

Convertisons un dictionnaire extra

L'espace de nommage par défaut des variables et familles est "rougail". Il est possible de définir d'autres espaces de nom. Ces espaces de nom additionnels s'appelle des "extras".

Les espaces de nom additionnels se définissent lors de la configuration.

Par exemple, voici comment ajouter une espace de nom "example" :

RougailConfig['extra_dictionaries']['example'] = ['extras/']

Ensuite créons un dictionnaire extra extras/00-base.yml :

version: '0.10'
variables:
- variable:
  - name: my_variable_extra
    value:
    - text: my_value_extra

Construisons les objets Tiramisu :

from rougail import Rougail, RougailConfig
from asyncio import run

async def main():
    RougailConfig['dictionaries_dir'] = ['dict']
    RougailConfig['extra_dictionaries']['example'] = ['extras/']
    rougail = Rougail()
    config = await rougail.get_config()
    print(await config.value.dict())

run(main())

Exécution le script :

$ python3 script.py
{'rougail.my_variable': 'my_value', 'example.my_variable_extra': 'my_value_extra'}

Templatisons un fichier

Un template est un fichier dans laquelle on va remplacer les valeurs attendus par le nom des variables.

Premièrement déclarons dans un dictionnaire complémentaire notre template dict/00-template.yml :

version: '0.10'
services:
- service:
  - name: test
    file:
    - text: /etc/example.conf

Et un template tmpl/example.conf (par défaut il est généré via une configuration particulière de Cheetah :

The value: %%my_variable

The extra value: %%example.my_variable_extra

Générons le template :

from rougail import Rougail, RougailConfig
from asyncio import run

async def main():
    RougailConfig['dictionaries_dir'] = ['dict']
    RougailConfig['templates_dir'] = ['tmpl']
    RougailConfig['tmp_dir'] = 'tmp'
    RougailConfig['destinations_dir'] = 'dest'
    RougailConfig['extra_dictionaries']['example'] = ['extras/']
    RougailConfig['functions_file'] = 'funcs/functions.py'
    rougail = Rougail()
    config = await rougail.get_config()
    await rougail.template()

run(main())

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

The value: my_value

The extra value: my_value_extra

Créons une fonction personnalisé

Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variable "my_variable" dans dict/00-fill.yml :

version: '0.10'
constraints:
- fill:
  - name: return_no
    target:
    - text: my_variable

Puis créons la fonction "return_no" dans 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 dest/etc/example.conf :

The value: no

The extra value: my_value_extra

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

#FIXME systemd