rougail/doc/dev/README.md

# La bibliothèque Rougail

Rougail est une bibliothèque de gestion de configuration qui permet de charger simplement des variables.

Dans les exemples suivants, nous utiliserons une configuration particulière de Rougail.
Vous retrouverez toutes les options pour [personnaliser les répertoires utilisés](config.md).

Pour charger la configuration il faut importer la variable RougailConfig et changer les valeurs :

```python
from rougail import RougailConfig

RougailConfig['dictionaries_dir'] = ['dict']
```

## Convertisons un dictionnaire

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

Commençons par créer un [dictionnaire](../dictionary/rougail.md) simple.

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

```yml
---
version: '1.0'
my_variable:
  default: my_value
```

Puis, créons les objets [Tiramisu](https://forge.cloud.silique.fr/gnunux/tiramisu) via la script script.py suivant :

```python
from rougail import Rougail, RougailConfig

RougailConfig['dictionaries_dir'] = ['dict']
rougail = Rougail()
config = rougail.get_config()
print(config.value.get())
```

Exécution le script :

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

```yml
---
version: '1.0'
my_variable_extra:
  default: my_value_extra
```

Puis, créons les objets [Tiramisu](https://forge.cloud.silique.fr/gnunux/tiramisu) via la script script.py suivant :

```python
from rougail import Rougail, RougailConfig

RougailConfig['dictionaries_dir'] = ['dict']
RougailConfig['extra_dictionaries']['example'] = ['extras/']
rougail = Rougail()
config = rougail.get_config()
print(config.value.dict())
```

Exécution le script :

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

## Créons une fonction personnalisé

Nous créons le dictionnaire complémentaire dict/01-function.yml pour que la variable "my_variable_jinja" soit [calculée](fill/README.md) :

```yml
---
version: '1.0'
my_variable_jinja:
  type: "string"
  default:    
    type: jinja
    jinja: "{{ return_no() }}"
```

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

```python
def return_no():
    return 'no'
```

Puis, créons les objets [Tiramisu](https://forge.cloud.silique.fr/gnunux/tiramisu) via la script script.py suivant :

```python
from rougail import Rougail, RougailConfig

RougailConfig['dictionaries_dir'] = ['dict']
RougailConfig['extra_dictionaries']['example'] = ['extras/']
RougailConfig['functions_file'] = 'functions.py'
rougail = Rougail()
config = rougail.get_config()
print(config.value.dict())
```

Exécution le script :

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

La valeur de la variable `my_variable_extra` est bien calculé à partir de la fonction `return_no`.