diff --git a/README.md b/README.md
index c5d2c0a46..b810dd48b 100644
--- a/README.md
+++ b/README.md
@@ -32,23 +32,23 @@ version: '0.10'
# describe a first service with a single file
services:
- service:
- - name: my_service
- file:
- - engine: jinja2
- text: /etc/filename
+ - name: my_service
+ file:
+ - engine: jinja
+ text: /etc/filename
# describe a variable my_first_variable
# and a family with a variable my_second_variable
variables:
- variable:
- name: my_first_variable
+ - name: my_first_variable
value:
- text: my_value
- family:
- name: my_family
+ - name: my_family
variables:
- variable:
- name: my_second_variable
+ - name: my_second_variable
type: number
mandatory: true
value:
@@ -82,7 +82,6 @@ async def main():
rougail = Rougail()
await rougail.template()
-
run(main())
```
diff --git a/doc/README.md b/doc/README.md
index 1796b8000..5d9c36176 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -34,6 +34,5 @@ Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fi
## Les templates
- - Type creole
- - Type jinja2
-FIXME ^^
+ - [Les moteurs de templates](template/README.md)
+ - [Les patches](template/patch.md)
diff --git a/doc/dev/README.md b/doc/dev/README.md
index 184d6b5ea..50d130fe5 100644
--- a/doc/dev/README.md
+++ b/doc/dev/README.md
@@ -1,79 +1,130 @@
-# La bibliothèque rougail
+# La bibliothèque Rougail
-Rougail est une bibliothèque simple a utiliser.
+Rougail est une bibliothèque qui permet de charger simplement des dictionnaires et de générer des templates.
-Dans les exemples suivant, nous utilisons la configuration par défaut de Rougail. Vous pouvez [personnaliser les répertoires utilisés](config.md).
+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).
-## 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
-
-
-
-
- my_value
-
-
-
-```
-
-Construisons les objets tiramisu :
+Le script contiendra donc les éléments de configuration suivant :
```python
-from rougail import RougailConvert
+from rougail import RougailConfig
-rougail = RougailConvert()
-rougail.save('example.py')
+RougailConfig['dictionaries_dir'] = ['dict']
+RougailConfig['templates_dir'] = ['tmpl']
+RougailConfig['tmp_dir'] = 'tmp'
+RougailConfig['destinations_dir'] = 'dest'
+RougailConfig['functions_file'] = 'funcs/functions.py'
```
-Un nouveau fichier 'example.py' va être créé dans le répertoire local
+Penser a créer les répertoires :
-## Convertisons un dictionnaire extra en objet tiramisu
+```bash
+mkdir dest dict tmp tmpl extras
+```
-En plus du dictionnaire précédent, créons un dictionnaire extra /srv/rougail/extra_dictionaries/00-base.xml
+## 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
-
-
-
-
- my_value_extra
-
-
-
+version: '0.10'
+variables:
+- variable:
+ - name: my_variable
+ value:
+ - text: my_value
```
-Construisons les objets tiramisu :
+Puis, créons les objets [Tiramisu](https://framagit.org/tiramisu/tiramisu) :
```python
-from rougail import RougailConvert, RougailConfig
+from rougail import Rougail, RougailConfig
+from asyncio import run
-RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/']
+async def main():
+ RougailConfig['dictionaries_dir'] = ['dict']
+ rougail = Rougail()
+ config = await rougail.get_config()
+ print(await config.value.dict())
-rougail = RougailConvert()
-rougail.save('example.py')
+run(main())
```
-## Templatisons un template
+Exécution le script :
-Nous créons un dictionnaire complémentaire pour ajouter notre template /srv/rougail/dictionaries/00-template.xml :
+```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
```
-Et un template /srv/rougail/templates/example.conf :
+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 [CheetahTemplate](https://cheetahtemplate.org/) :
```
The value: %%my_variable
@@ -81,42 +132,27 @@ The value: %%my_variable
The extra value: %%example.my_variable_extra
```
-Générons le fichier tiramisu :
-
-```python
-from rougail import RougailConvert, RougailConfig
-
-RougailConfig['extra_dictionaries']['example'] = ['/srv/rougail/extra_dictionaries/']
-
-rougail = RougailConvert()
-rougail.save('example.py')
-```
-
-Créer les répertoires utils pour la templatisation :
-
-```bash
-mkdir /srv/rougail/destinations /srv/rougail/tmp
-```
-
Générons le template :
```python
-import asyncio
-from example import option_0
-from tiramisu import Config
-from rougail import RougailSystemdTemplate
+from rougail import Rougail, RougailConfig
+from asyncio import run
-async def template():
- config = await Config(option_0)
- engine = RougailSystemdTemplate(config)
- await engine.instance_files()
+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()
-loop = asyncio.get_event_loop()
-loop.run_until_complete(template())
-loop.close()
+run(main())
```
-Le fichier /srv/rougail/destinations/etc/example.conf est maintenant créé avec le contenu attendu suivant :
+Le fichier dest/etc/example.conf est maintenant créé avec le contenu attendu suivant :
```
The value: my_value
@@ -124,68 +160,32 @@ 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 :
-
-```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 doit 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" dans /srv/rougail/dictionaries/00-fill.xml :
+Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variable "my_variable" dans dict/00-fill.yml :
-```xml
-
-
-
-
- my_variable
-
-
-
+```yml
+version: '0.10'
+constraints:
+- fill:
+ - name: return_no
+ target:
+ - text: my_variable
```
-Puis créons la fonction "return_no" dans /srv/rougail/functions.py :
+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 /srv/rougail/destinations/etc/example.conf :
+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
-
-Add by a patch
```
La valeur de la variable "my_variable" est bien calculé à partir de la fonction "return_no".
diff --git a/doc/dev/config.md b/doc/dev/config.md
index 75426100f..7bde28492 100644
--- a/doc/dev/config.md
+++ b/doc/dev/config.md
@@ -111,7 +111,7 @@ Le répertoire où se trouve les fichiers tmpfile.d sont par défaut dans "/usr/
### Le moteur de templates par défaut
-Le moteur de template est géré dans la clef "default_files_engine" et a comme valeur par défaut : "creole". Les valeurs possible sont "none", "creole" ou "jinja2".
+Le moteur de template est géré dans la clef "default_files_engine" et a comme valeur par défaut : "cheetah". Les valeurs possible sont "none", "cheetah" ou "jinja".
### Les droits par défaut des fichiers
@@ -129,4 +129,4 @@ La méthode d'inclusion des fichiers générés est géré dans la clef "default
## La configuration du moteur de templates
-Le moteur de template est géré dans la clef "default_overrides_engine" et a comme valeur par défaut : "creole". Les valeurs possible sont "none", "creole" ou "jinja2".
+Le moteur de template est géré dans la clef "default_overrides_engine" et a comme valeur par défaut : "cheetah". Les valeurs possible sont "none", "cheetah" ou "jinja".
diff --git a/doc/dictionary/convention.md b/doc/dictionary/convention.md
index efeecd687..617b7bf3e 100644
--- a/doc/dictionary/convention.md
+++ b/doc/dictionary/convention.md
@@ -8,6 +8,14 @@ L'ordre des informations mise dans le dictionnaire est idéalement :
- variables
- constraintes
-## Le nom d'espace
+## Nom des fichiers de dictionnaire
-Le nom d'espace dans un dictionnaire est de deux espaces.
+L'ordre des dictionnaires est important pour l'ordre de création des variables et des familles.
+
+Les fichiers devront donc démarrés par deux numéros suivit d'un tiret.
+
+Par exemple : 00-base.xml
+
+## Le nombre d'espace XML
+
+Le nombre d'espace dans un dictionnaire au format XML est de deux espaces.
diff --git a/doc/service/README.md b/doc/service/README.md
index 02bab8fe6..cc219766d 100644
--- a/doc/service/README.md
+++ b/doc/service/README.md
@@ -70,11 +70,11 @@ Dans ce cas, il est possible de créé un template, dont le nom est obligatoirem
Deux types de template sont aujourd'hui disponible :
-- creole
-- jinja2
+- cheetah
+- jinja
```xml
-
+
```
En YAML :
@@ -83,7 +83,7 @@ En YAML :
- service:
- name: dev-disk-by\x2dpartlabel-swap
type: swap
- engine: creole
+ engine: cheetah
```
Dans ce cas, rougail utilisera le template "dev-disk-by\x2dpartlabel-swap.swap" pour générer le fichier systemd de gestion de ce service.
diff --git a/doc/service/file.md b/doc/service/file.md
index 927f0faea..02a99794c 100644
--- a/doc/service/file.md
+++ b/doc/service/file.md
@@ -275,7 +275,7 @@ file:
## Choix du moteur de templating
-Par défaut, le moteur de templating est le moteur de templating compatible avec "creole".
+Par défaut, le moteur de templating est le moteur de templating compatible avec "cheetah".
Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) :
@@ -291,17 +291,17 @@ file:
text: /etc/squid/squid.conf
```
-Ou d'utiliser le moteur "jinja2" :
+Ou d'utiliser le moteur "jinja" :
```xml
-/etc/squid/squid.conf
+/etc/squid/squid.conf
```
En YAML :
```yml
file:
-- engine: jinja2
+- engine: jinja
text: /etc/squid/squid.conf
```
diff --git a/doc/service/override.md b/doc/service/override.md
index 3a1486dd4..cfe11e2b5 100644
--- a/doc/service/override.md
+++ b/doc/service/override.md
@@ -44,7 +44,7 @@ Dans ce cas le fichier de destination aura le même nom.
## Choix du moteur de templating
-Par défaut, le moteur de templating est le moteur de templating compatible avec "creole".
+Par défaut, le moteur de templating est le moteur de templating compatible avec "cheetah".
Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) :
@@ -59,17 +59,17 @@ override:
- engine: 'none'
```
-Ou d'utiliser le moteur "jinja2" :
+Ou d'utiliser le moteur "jinja" :
```xml
-
+
```
En YAML :
```yml
override:
-- engine: 'jinja2'
+- engine: 'jinja'
```
Il est possible de personnaliser le moteur par défaut dans la [configuration de rougail](../dev/config.md)
diff --git a/doc/template/README.md b/doc/template/README.md
new file mode 100644
index 000000000..f7e2a99ce
--- /dev/null
+++ b/doc/template/README.md
@@ -0,0 +1,103 @@
+# Les templates
+
+## Le moteur "cheetah"
+
+Le moteur de templating par défaut est le moteur [CheetahTemplate](https://cheetahtemplate.org/).
+
+Par contre, la configuration par défaut de CheetahTemplate a été modifié.
+
+Dans un template de configuration, il est très fréquent que le caractère "#" est le caractère des commentaires.
+C'est pourquoi la configuration par défaut a été modifié.
+
+Les choix sont maintenant les suivants :
+
+- le caractère des directives : "%" ;
+- les variables : "%%" ;
+- le caractère des commentaires : "#".
+
+Voici quelques exemples d'utilisateurs de ce moteur :
+
+### utiliser une variable
+
+```
+%%variable_name
+```
+
+### condition
+
+```
+%if %%variable_name == 'oui'
+text
+%end if
+```
+
+### vérifier si une variable existe
+
+```
+%if %%varExists('variable_name')
+text
+%end if
+```
+
+### boucle
+
+```
+%for %%var in %%variable_name
+%%var
+%end for
+```
+
+### boucle avec variables meneuse et suiveuse
+
+```
+%for %%var in %%variable_leader
+%%var.variable_follower
+%end for
+```
+
+Pour plus d'informations, voir la documentation de CheetahTemplate.
+
+## Le moteur "jinja"
+
+Il est possible d'utiliser le moteur de templating [Jinja](https://jinja.palletsprojects.com/).
+
+Il n'y a pas d'adaptation particulière pour ce moteur.
+
+Voici quelques exemples d'utilisateurs de ce moteur :
+
+### utiliser une variable
+
+```
+{{ variable_name }}
+```
+
+### condition
+
+```
+{% if variable_name == 'oui' %}
+text
+{% endif -%}
+```
+
+### boucle
+
+```
+{% for var in variable_name %}
+{{ var }}
+{% endfor -%}
+```
+
+### boucle avec variables meneuse et suiveuse
+
+```
+{% for var in variable_leader %}
+{{ var.variable_follower }}
+{% endfor -%}
+```
+
+Pour plus d'informations, voir la documentation de Jinja.
+
+## Le moteur "none"
+
+Ce moteur permet de copie le fichier sans y apporter la moindre modification.
+C'est utile pour les templates ne contenant aucune variable ni condition.
diff --git a/doc/template/patch.md b/doc/template/patch.md
new file mode 100644
index 000000000..f14a323a0
--- /dev/null
+++ b/doc/template/patch.md
@@ -0,0 +1,39 @@
+# Patcher un 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.
+
+Par exemple le template :
+
+```
+The value: %%my_value
+
+The extra value: %%example.my_variable_extra
+```
+
+Peut être modifié via le patch :
+
+```patch
+--- tmpl/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 fichier généré ressemblera alors à cela :
+
+```
+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 doit toujours commencer par "+++ tmp/" (tmp étant le nom du répertoire mis dans la configuration) + le nom du template source
diff --git a/logo.png b/logo.png
index 412ce26fe..3c1833f05 100644
Binary files a/logo.png and b/logo.png differ
diff --git a/logo.svg b/logo.svg
index 14da07da2..04513d2cd 100644
--- a/logo.svg
+++ b/logo.svg
@@ -81,14 +81,14 @@
+ sodipodi:nodetypes="ccccc" />