diff --git a/doc/README.md b/doc/README.md index 0e8c5a8ce..a6495126f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -2,7 +2,7 @@ # Rougail -Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fichiers au format XML ou YAML), de charger les variables dans Tiramisu et de générer des templates Cheetah ou Jinja. +Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fichiers au format YAML), de charger les variables dans Tiramisu. ![Schéma](schema.png "Schéma") @@ -19,23 +19,11 @@ Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fi ### Les variables - - [Les familles](family/README.md) - [Les variables](variable/README.md) - -### Les services - - - [La gestion d'un fichier](service/file.md) - - [La gestion d'un certificat](service/certificate.md) - - [La gestion d'un fichier de service systemd](service/override.md) - - [La gestion d'une ip](service/ip.md) + - [Les familles](family/README.md) ### Les contraintes - [Les calculs automatiques](fill/README.md) - [Les vérifications des valeurs](check/README.md) - [Les conditions](condition/README.md) - -## Les templates - - - [Les moteurs de templates](template/README.md) - - [Les patches](template/patch.md) diff --git a/doc/check/function.md b/doc/check/function.md index 2966de16b..487afd46d 100644 --- a/doc/check/function.md +++ b/doc/check/function.md @@ -6,49 +6,22 @@ Une fonction de vérification est une fonction complémentaire au type qui perme Voici un exemple simple de validation des valeurs : -```xml - - - - - - my_variable - - -``` - -En YAML : - ```yml -variables: -- variable: - name: my_variable -constraints: -- check: - - name: islower - target: - - text: my_variable -``` - - -La [cible (de type variable)](../target/variable.md) de la fonction de vérification est ici "my_variable". - -Dans cette exemple, la valeur de la variable "my_variable" va être validé par la fonction islower. - -Voici le contenu de la fonction : - -```python -def islower(value): - if value is None: - return - if not value.islower(): - raise ValueError(f'"{value}" is not lowercase string') +--- +version: '1.0' +my_variable: + validators: + - type: jinja + jinja: |+ + {% if rougail.my_variable and not rougail.my_variable.islower() %} + {{ rougail.my_variable }} is not lowercase string + {% endif %} ``` Une fonction de vérification doit prendre en compte 2 aspects important : - la valeur peut ne pas être renseigné (même si la variable est obligatoire), la valeur None doit être prise en compte -- si la valeur est invalide, il faut faire un raise de type ValueError avec, si possible, un message explicite. +- si la valeur est invalide, il faut renvoyer une phrase avec un message explicite. À partir de maintenant seule None et des valeurs en minuscule seront autorisés. @@ -58,20 +31,18 @@ Il est possible de définir des [paramètres](../param/README.md) à cette fonct Dans la contrainte, il est possible de spécifier le niveau d'erreur et le mettre en avertissement : -```xml - - my_variable - -``` - -En YAML : - ```yml -- check: - - name: islower - level: warning - target: - - text: my_variable +--- +version: '1.0' +my_variable: + validators: + - type: jinja + jinja: |+ + {% if rougail.my_variable and not rougail.my_variable.islower() %} + {{ rougail.my_variable }} is not lowercase string + {% endif %} + params: + warning: true ``` Dans ce cas une valeur avec une majuscule sera accepté, mais un message d'avertissement apparaitra. diff --git a/doc/check/redefine.md b/doc/check/redefine.md index 414ee9208..4bf6a2d60 100644 --- a/doc/check/redefine.md +++ b/doc/check/redefine.md @@ -4,55 +4,31 @@ Dans un premier dictionnaire déclarons notre variable et sa fonction de vérification : -```xml - - - - - - my_variable - - -``` - -En YAML : - ```yml -variables: -- variable: - name: my_variable -constraints: -- check: - - name: islower - target: - - text: my_variable +--- +version: '1.0' +my_variable: + validators: + - type: jinja + jinja: |+ + {% if rougail.my_variable and not rougail.my_variable.islower() %} + {{ rougail.my_variable }} is not lowercase string + {% endif %} ``` Dans un second dictionnaire il est possible de redéfinir le calcul : -```xml - - - - - - my_variable - - -``` - -En YAML : - ```yml -variables: -- variable: - name: my_variable - redefine: true -constraints: -- check: - - name: isspace - target: - - text: my_variable +--- +version: '1.0' +my_variable: + redefine: true + validators: + - type: jinja + jinja: |+ + {% if rougail.my_variable and ' ' in rougail.my_variable %} + {{ rougail.my_variable }} has a space + {% endif %} ``` Dans ce cas, la fonction "islower" exécuté. Si cette fonction ne retourne pas d'erreur, la seconde fonction "isspace" sera exécuté. @@ -65,44 +41,24 @@ Dans un second dictionnaire il est possible de supprimer cette vérification. Dans un premier dictionnaire déclarons notre variable et notre fonction de vérification : -```xml - - - - - - my_variable - - -``` - -En YAML : - ```yml -variables: -- variable: - name: my_variable -constraints: -- check: - - name: islower - target: - - text: my_variable +--- +version: '1.0' +my_variable: + validators: + - type: jinja + jinja: |+ + {% if rougail.my_variable and not rougail.my_variable.islower() %} + {{ rougail.my_variable }} is not lowercase string + {% endif %} ``` Dans un second dictionnaire supprimer cette vérification : -```xml - - - -``` - -En YAML : - ```yml -variables: -- variable: - name: my_variable - redefine: true - remove_check: true +--- +version: '1.0' +my_variable: + redefine: true + validators: ``` diff --git a/doc/condition/condition.md b/doc/condition/condition.md index 1bfdcfe4e..336cdb5ca 100644 --- a/doc/condition/condition.md +++ b/doc/condition/condition.md @@ -1,47 +1,53 @@ -# Les conditions +# Les propriétés calculées -## Un condition +Les propriétés calculées permettent d'ajouter ou de supprimer des propriétés à une [variable](../variable/README.md) ou une [famille](../family/README.md) suivant le contexte. -Les conditions permettent d'ajouter ou de supprimer des propriétés à une [variable](../variable/README.md), une [famille](../family/README.md), un [service](../service/README.md), un [fichier](../service/file.md) ou une [ip](../service/ip.md) suivant le contexte. +Nous allons nous concentrer ici sur la proprété `hidden`, mais ce qui est dit est vrai pour toutes les propriétés. -Nous allons nous concentrer ici sur la condition hidden_if_in, mais [il existe d'autre conditions](conditions.md). +## Une propriété calculée de type variable -La condition hidden_if_in permet de cacher une variable où une famille à l'utilisateur, mais cette variable est toujours accessible dans un calcul, un vérification ou dans un template. +Une variable peut donc être calculé via la résultat d'une autre variable. +Attention, cette autre variable doit obligatoirement être de type `boolean` : -```xml - - - - - - - - True - my_variable - - -``` - -En YAML : ```yml -variables: -- variable: - name: condition - type: boolean -- variable: - name: my_variable -constraints: -- condition: - - name: hidden_if_in - source: condition - param: - - text: true - target: - - text: my_variable +--- +version: '1.0' +condition: + type: boolean +my_variable: + hidden: + type: variable + variable: rougail.condition ``` -Le [paramètres](../param/README.md) de la condition permet de définir les valeurs que doit avoir la source pour appliquer l'action. +Si la valeur de la variable "rougail.condition" est `True` alors la variable "rougail.my_variable" est cachée. + +## Une propriété calculée de type jinja + +Il est possible d'écrire la condition en Jinja : + +```yml +--- +version: '1.0' +condition: + default: 'do not hide!' +my_variable: + hidden: + type: jinja + jinja: | + {% if rougail.condition and rougail.condition == "hide!" %} + true + {% else %} + false + {% endif %} +``` + +Dans ce cas la variable est cachée si la valeur de la variable "rougail.condition" est `hide!` et elle n'a pas caché pour tout autre valeur. +Attention toujours prendre en considération que "rougail.condition" peut être égale à `None`. + +Il est possible d'ajouter des [paramètres](../param/README.md) à la condition de type `jinja`. +Il est possible d'ajouter des paramètres à la fonction La [cible](../target/README.md) de la condition est ici "my_variable". diff --git a/doc/dev/README.md b/doc/dev/README.md index 53d3bbea2..a3abacace 100644 --- a/doc/dev/README.md +++ b/doc/dev/README.md @@ -1,58 +1,42 @@ # La bibliothèque Rougail -Rougail est une bibliothèque qui permet de charger simplement des dictionnaires et de générer des templates. +Rougail est une bibliothèque de gestion de configuration qui permet de charger simplement des variables. 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 : +Pour changer la configuration il faut importer la variable RougailConfig et changer les valeurs : ```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. +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: '0.10' -variables: -- variable: - - name: my_variable - value: - - text: my_value +--- +version: '1.0' +my_variable: + default: my_value ``` -Puis, créons les objets [Tiramisu](https://framagit.org/tiramisu/tiramisu) : +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 -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()) +RougailConfig['dictionaries_dir'] = ['dict'] +rougail = Rougail() +config = rougail.get_config() +print(config.value.dict()) ``` Exécution le script : @@ -78,28 +62,22 @@ RougailConfig['extra_dictionaries']['example'] = ['extras/'] Ensuite créons un dictionnaire extra extras/00-base.yml : ```yml -version: '0.10' -variables: -- variable: - - name: my_variable_extra - value: - - text: my_value_extra +--- +version: '1.0' +my_variable_extra: + default: my_value_extra ``` -Construisons les objets Tiramisu : +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 -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()) +RougailConfig['dictionaries_dir'] = ['dict'] +RougailConfig['extra_dictionaries']['example'] = ['extras/'] +rougail = Rougail() +config = rougail.get_config() +print(config.value.dict()) ``` Exécution le script : @@ -109,67 +87,18 @@ $ python3 script.py {'rougail.my_variable': 'my_value', 'example.my_variable_extra': 'my_value_extra'} ``` -## Templatisons un fichier - -Un [template](../template/README.md) est un fichier dans lequel on va remplacer les valeurs attendues par le nom des variables. - -Premièrement déclarons dans un dictionnaire complémentaire notre template dict/00-template.yml : - -```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](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() - 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 le dictionnaire complémentaire dict/00-fill.yml pour que la variable "my_variable" soit [calculée](fill/README.md) : +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: '0.10' -constraints: -- fill: - - name: return_no - target: - - text: my_variable +--- +version: '1.0' +my_variable_jinja: + type: "string" + default: + type: jinja + jinja: "{{ return_no() }}" ``` Puis créons la fonction "return_no" dans functions.py : @@ -179,41 +108,24 @@ 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". - -## Template et systemd - -Rougail peut également généré automatiquement le fichier [tmpfiles.d](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html) pour installer automatiquement les fichiers de configuration au démarrage de la machine. - -Pour générer le fichier tmpfiles.d, ajouter l'argument "systemd" à la methode "template" : +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 -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() - await rougail.template('systemd') - -run(main()) +RougailConfig['dictionaries_dir'] = ['dict'] +RougailConfig['extra_dictionaries']['example'] = ['extras/'] +RougailConfig['functions_file'] = 'functions.py' +rougail = Rougail() +config = rougail.get_config() +print(config.value.dict()) ``` -Ainsi le fichier supplémentaire "dest/tmpfiles.d/0rougail.conf" sera créé avec le contenu : +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'} ``` -C /etc/example.conf 0644 root root - /usr/local/lib/etc/example.conf -``` + +La valeur de la variable `my_variable_extra` est bien calculé à partir de la fonction `return_no`. diff --git a/doc/dev/config.md b/doc/dev/config.md index bda0d2a8f..006abb637 100644 --- a/doc/dev/config.md +++ b/doc/dev/config.md @@ -14,29 +14,17 @@ Pour modifier il suffit de faire : RougailConfig[key] = value ``` -## Ajout d'une fonction de conversion - -Les fonctions de conversion fait parti du moteur de rougail. Il converti les informations des dictionnaires pour créer des variables Tiramisu. - -La clef "extra_annotators" permet d'ajouter des fonctions complémentaires. - ## Configuration de chargement des dictionnaires ### Les répertoires des dictionnaires Il existe deux types de répertoires de dictionnaires : -- les dictionnaires principaux avec la clef "dictionaries_dir". La valeur par défaut est ['/srv/rougail/dictionaries']. Cette variable doit contenir la liste des répertoires contenants des dictionnaires. +- les dictionnaires principaux avec la clef `dictionaries_dir`. La valeur par défaut est `['/srv/rougail/dictionaries']`. Cette variable doit contenir la liste des répertoires contenants des dictionnaires. -Les dictionnaires sont chargés dans l'ordre des répertoires. Chaque répertoire est chargé les uns après les autres. A l'intérieur de ces répertoires les fichiers XML ou YAML seront classés par ordre alphabétique. +- les dictionnaires extra avec la clef `extra_dictionaries`. La valeur est un dictionnaire avec l'ensemble des espaces de nom. La clef étant l'espace de nom et la valeur étant une liste de répertoire. -Il n'y a pas de classement par ordre alphabétique de l'ensemble des fichiers XML ou YAML de tous les répertoires. - -Les familles et variables de ces dictionnaires sont classés, par défaut, dans l'espace de nom "rougail". Il est possible de changer le nom de cet espace de nom avec la clef "variable_namespace". - -- les dictionnaires extra avec la clef "extra_dictionaries". La valeur est un dictionnaire avec l'ensemble des espaces de nom. La clef étant l'espace de nom et la valeur étant une liste de répertoire. - -Par exemple pour ajouter l'extra "example" il faut faire : +Par exemple pour ajouter l'extra `example` il faut faire : ```python RougailConfig['extra_dictionaries']['example'] = ['/dir1', '/dir2'] @@ -44,14 +32,6 @@ RougailConfig['extra_dictionaries']['example'] = ['/dir1', '/dir2'] Les dictionnaires sont chargés dans le même ordre que les dictionnaires principaux. -### La DTD et le schema YAML - -Rougail a besoin du fichier de la DTD pour lire les fichiers dictionnaire de type XML et du schema YAML pour les fichiers dictionnaire de type YAML. - -Par défaut le fichier de la DTD et le schema YAML sont dans le sous répertoire "data" du répertoire de code. Le nom du fichier est rougail.dtd et rougail.yml. - -Pour pouvez changer le nom du fichier DTD avec la clef "dtdfilename" et le nom du schema YAML avec la clef "yamlschema_filename". - ### Le fichier de fonction Le fichier qui contient les fonctions personnalisés est géré dans la clef "functions_file" et a comme valeur par défaut "/srv/rougail/functions.py". Cette clef peut contenir une liste s'il y a plusieurs fichiers. @@ -147,3 +127,10 @@ 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 : "cheetah". Les valeurs possible sont "none", "cheetah" ou "jinja". + +## Ajout d'une fonction de conversion + +Les fonctions de conversion fait parti du moteur de rougail. Il converti les informations des dictionnaires pour créer des variables Tiramisu. + +La clef "extra_annotators" permet d'ajouter des fonctions complémentaires. + diff --git a/doc/dictionary/convention.md b/doc/dictionary/convention.md index 617b7bf3e..c87cff1b3 100644 --- a/doc/dictionary/convention.md +++ b/doc/dictionary/convention.md @@ -1,21 +1,20 @@ -# Convention de rédaction d'un dictionnaire +--- +gitea: none +include_toc: true +--- -## Ordonnancement du dictionnaire +# Conventions -L'ordre des informations mise dans le dictionnaire est idéalement : - -- services -- variables -- constraintes - -## Nom des fichiers de dictionnaire +## Convention de nom d'un fichier de dictionnaire 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 +Par exemple : `00-base.xml` -## Le nombre d'espace XML +## Convention du nom des familles et variables -Le nombre d'espace dans un dictionnaire au format XML est de deux espaces. +La seule restriction sur le nom des familles et variables est que le nom ne doit pas commencer par le caractèr "\_". +Néanmoins il est préférable de n'utiliser que des lettres minuscule ASCII, des chiffres et le caractère "\_". +C'est la convention typographique snake case qui est donc utilisée. diff --git a/doc/dictionary/extra.md b/doc/dictionary/extra.md index 4fea90c97..2a584bc87 100644 --- a/doc/dictionary/extra.md +++ b/doc/dictionary/extra.md @@ -4,9 +4,4 @@ Un extra est un espace de nom différent. L'idée et de pouvoir classer les vari Les espaces de nom extra doivent être déclaré au moment [de la configuration de Rougail](../dev/config.md). -Dans cet espace de nom : - -- des variables et des familles peuvent avoir le même nom dans différentes familles -- la valeur d'un cible, source, leader ou follower des contraintes doivent être avec un chemin complet -- on ne peut pas déclarer des services dans cet espace de nom -- dans un template il faut utiliser des chemins complet (%%my_extra.my_family.my_variable ou %%my_extra.my_family.leader.follower pour une variable suiveuse) +Dans cet espace de nom on ne peut pas accéder a des variables d'un autre espace de nom `extra`. Par contre il est possible d'accéder au variable de l'espace de nom par défaut. diff --git a/doc/dictionary/rougail.md b/doc/dictionary/rougail.md index ef26e903f..2a2b79c05 100644 --- a/doc/dictionary/rougail.md +++ b/doc/dictionary/rougail.md @@ -2,21 +2,20 @@ ## Un dictionnaire ? -Un dictionnaire est un fichier XML ou YAML donc la structure est décrite dans cette documentation. +Un dictionnaire est un fichier YAML dont la structure est décrite dans cette documentation. -Un dictionnaire contient en ensemble de variable chargé dans Tiramisu, utilisable à tout moment, notamment dans des templates. +Un dictionnaire contient en ensemble de variable chargé dans [Tiramisu](https://forge.cloud.silique.fr/gnunux/tiramisu), utilisable à tout moment, notamment dans des templates. -Les familles, les variables et les contraintes peuvent être défini dans plusieurs dictionnaires. Ces dictionnaires s'aggrège alors. +Les familles et les variables peuvent être défini dans plusieurs dictionnaires. Ces dictionnaires s'aggrègent alors. -Il est également possible de redéfinir des éléments pour changer les comportement d'une variable ou d'un service. +Les dictionnaires sont chargés dans l'ordre des répertoires [définit avec le paramètre `dictionaries_dir` de la configuration](../dev/config.md). Chaque répertoire est chargé les uns après les autres. A l'intérieur de ces répertoires les fichiers YAML seront classés par ordre alphabétique. + +Il n'y a pas de classement par ordre alphabétique de l'ensemble des fichiers YAML de tous les répertoires. + +Il est également possible de redéfinir des éléments pour changer les comportement d'une famille ou d'une variable. ## L'espace de nom par défaut -L'espace de nom par défaut s'appelle "rougail" ([ce nom est personnalisable](../dev/config.md)). +Les familles et variables de ces dictionnaires sont classées, par défaut, dans l'espace de nom `rougail`. Il est possible de changer le nom de cet espace de nom [avec le paramètre `variable_namespace` de la configuration](../dev/config.md). -Cet espace de nom est un peu particulier : - -- le nom des variables et des familles doivent être unique pour l'ensemble de cet espace (même si ces variables ou familles sont dans des familles différentes) -- la valeur d'un cible, source, leader ou follower des contraintes peuvent être avec nom de la variable ou de la famille ou leurs chemins complet -- on peut déclarer des services dans cet espace de nom -- dans un template on peut utiliser cette variable sans le chemin complet (%%my_variable) ou avec (%%rougail.my_family.my_variable) +Cet espace de nom est un peu particulier, il peut accéder a des variables dans un autre espace de nom. diff --git a/doc/family/auto.md b/doc/family/auto.md index 6d2b3f7dc..dd16e57aa 100644 --- a/doc/family/auto.md +++ b/doc/family/auto.md @@ -1,46 +1,37 @@ # Famille crée dynamiquement Pour créer une famille dynamiquement, il faut créer une famille fictive lié à une variable. -Le nom et la description de la famille et des variables qu'elle contient sera en réalité le prefix du nouveau nom/description. Le suffix viendra de la variable liée. +Le nom et la description de la famille et des variables qu'elle contient sera en réalité le prefix du nouveau nom/description. Le suffix viendra de la valeur de la variable liée. Par exemple : -```xml - - val1 - val2 - - - - -``` - -En YAML : - ```yml -variables: -- variable: - name: variable - multi: true - value: - - text: 'val1' - - text: 'val2' -- family: - name: my_dyn_family_ - dynamic: varname - description: 'Describe ' - variables: - - variable: - name: my_dyn_var_ +--- +version: '1.0' +varname: + multi: true + default: + - val1 + - val2 +my_dyn_family_: + type: dynamic + variable: rougail.varname + description: 'Describe ' + my_dyn_var_: + type: string ``` Créera deux familles : -- la famille dynamique : "my_dyn_family_val1" avec la description "Describe val1" -- la famille dynamique : "my_dyn_family_val2" avec la description "Describe val2" +- la famille dynamique : "rougail.my_dyn_family_val1" avec la description "Describe val1" +- la famille dynamique : "rougail.my_dyn_family_val2" avec la description "Describe val2" -Dans la famille dynamique "my_dyn_family_val1" on retrouvera une variable "my_dyn_var_val1". +Dans la famille dynamique "rougail.my_dyn_family_val1" on retrouvera une variable "my_dyn_var_val1". -Bien évidement si le contenu de "varname" venait a évolué, de nouvelles familles dynamiques pouvent apparaitre ou des familles dynamiques peuvent disparaître. +Bien évidement si le contenu de "varname" venait a évoluer, de nouvelles familles dynamiques apparaitront ou disparaîtront. -Attention la variable lié à la famille doit être obligatoirement une variable multiple et il n'est pas possible de mettre une famille dans une famille dynamique. +A noter que : + +- la variable liée à la famille doit être obligatoirement une variable multiple ; +- il n'est pas possible de mettre une simple famille dans une famille dynamique ; +- il est possible de mettre [une famille meneuse](leadership.md) dans une famille dynamique. diff --git a/doc/family/leadership.md b/doc/family/leadership.md index bf35edb71..95f555b2e 100644 --- a/doc/family/leadership.md +++ b/doc/family/leadership.md @@ -1,14 +1,22 @@ # Variable meneuse ou suiveuse +## Un famille meneuse + +Les variables meneuses et suiveuses sont placées dans un famille meneuse. + +Une famille meneuse ne peut pas contenir d'autre famille. + +Le [mode](../variable/mode.md) par défaut de la famille meneuse est le mode de la variable meneuse. + ## Variable meneuse -Une variable meneuse est une variable qui va guider la longueur d'autre variables (appelé variables suiveuse). +Une variable meneuse est une variable qui va guider la longueur d'autres variables (appelé variables suiveuses). Une variable meneuse est une [variable](../variable/README.md) qui est obligatoirement de type multiple. Une variable meneuse peut être obligatoire. -Le [mode](../mode.md) par défaut correspond au plus petit mode définit par l'utilisateur des variables suiveuses. +Le [mode](../variable/mode.md) par défaut correspond au plus petit mode définit pour les variables suiveuses. ## Variable suiveuse @@ -23,63 +31,35 @@ Cette variable peut être de type multiple. Dans ce cas, pour un index determin Une variable suiveuse peut être obligatoire. Cela signifie que lorsqu'une variable meneuse est renseigné, il faut obligatoirement que la variable suiveuse est également une valeur à l'index considéré. Si aucune valeur n'est définit pour la variable meneuse, aucune valeur n'est a spécifié pour la variable suiveuse. -Le [mode](../mode.md) par défaut d'une variable suiveuse correspond au [mode](../mode.md) de la variable meneuse. +Le [mode](../variable/mode.md) par défaut d'une variable suiveuse correspond au [mode](../variable/mode.md) de la variable meneuse. Si une variable meneuse est caché ou désactivé, les variables suiveuses le seront également. ## Définition des variables meneuse et suiveuse -Les variables meneuses et suiveuses doivent dans une famille de type "leadership". +Une famille meneuse a un attribut type à "leadership". Le type est obligatoire. Voici un exemple de définition d'une variable meneuse et de deux variables meneuses : -```xml - - - - - - - -``` - -En YAML : - ```yml -variables: -- family: - name: family - leadership: true - variables: - - variable: - name: leader - multi: true - - variable: - name: follower1 - - variable: - name: follower2 - multi: true +--- +version: '1.0' +family: + type: leadership + leader: + multi: true + follower1: + follower2: + multi: true ``` ## Ajout d'une nouvelle variable suiveuse -Pour ajouter, dans un nouveau dictionnaire, une variable suiveuse à notre groupe, rien de plus simple, il suffit définir une ou des nouvelles variables dans la famille : - -```xml - - - - - -``` - -En YAML : +Pour ajouter une nouvelle variable suiveuse, dans un nouveau dictionnaire, il suffit de définir une ou des nouvelles variables dans la famille meneuse : ```yml -variables: -- family: - name: family - variables: - - variable: - name: follower3 +--- +version: '1.0' +family: + follower3: ``` diff --git a/doc/family/simple.md b/doc/family/simple.md index 89426357b..5de8edc72 100644 --- a/doc/family/simple.md +++ b/doc/family/simple.md @@ -1,128 +1,36 @@ +--- +gitea: none +include_toc: true +--- + # Une famille -Une famille est un conteneur de variables. Elle peut contenir également des familles. +## Synopsis -Pour décrire une famille il faut mettre au minimum un nom : +Une famille est un conteneur de variables et de sous-famille. -```xml - -``` +⚠️ Une famille sans sous-famille ni sous-variable sera automatiquement supprimée. -En YAML : +## Exemple ```yml -- family: - name: my_family +--- +version: '1.0' +my_family: + type: family + description: This is a great family + help: This is the help of a great family + mode: expert ``` -Cette famille doit être placé dans une balise [variables](../variables.md) : +## Paramètres -```xml - - - -``` - -En YAML : - -```yml -variables: -- family: - name: my_family -``` - -Ou dans une autre famille : - -```xml - - - - - -``` - -En YAML : - -```yml -variables: -- family: - name: my_family - variables: - - family: - name: second_family -``` - -Attention, une famille vide sera automatiquement supprimée. - -## Description et aide de la famille - -En plus d'un nom, il est possible de mettre une "description" à la famille. C'est une information "utilisateur" qui nous permettra d'avoir des informations complémentaires sur le contenu de cette famille : - -```xml - -``` - -En YAML : - -```yml -variables: -- family: - name: my_family - description: 'This is a great family' -``` - -En plus de la description, il est possible de préciser une aide complémentaire : - -```xml - -``` - -En YAML : - -```yml -variables: -- family: - name: my_family - help: 'This is a great family' -``` - -## Mode de la famille - -Le [mode](../mode.md) par défaut d'une famille correspond au [mode](../mode.md) du mode le plus petit entre la famille parente, les variables enfants ou des familles enfants qui sont contenu dans cette famille. - -Changer le [mode](../mode.md) d'une famille permet de définir le [mode](../mode.md) par défaut des variables ou des familles inclusent dans cette famille. - -Pour définir le [mode](../mode.md) : - -```xml - -``` - -En YAML : - -```yml -- family: - name: my_family - mode: expert -``` - -## Famille invisible - -Il est possible de cacher une famille, ainsi que toutes les variables et des familles inclusent dans cette famille. - -Cacher une famille signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service. -Par contre ces variables sont accessibles lorsqu'on va utiliser ces variables. - -Pour cacher une famille : - -```xml -