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](config.md).

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

```python
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 :

```bash
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](../dictionary/rougail.md) simple.

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

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

Puis, créons les objets [Tiramisu](https://framagit.org/tiramisu/tiramisu) :

```python
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 :

```python
$ 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](../dictionary/extra.md)".

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

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

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

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

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

Construisons les objets Tiramisu :

```python
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 :

```python
$ 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 :

```xml
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](https://cheetahtemplate.org/) :

```
The value: %%my_variable

The extra value: %%example.my_variable_extra
```

Générons le template :

```python
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 :

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

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

```python
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".