From 6c210f3c3373588ce8fbedbcbeb6a7e5db819083 Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Wed, 19 Nov 2025 15:57:55 +0100 Subject: [PATCH] fix: types --- caracteristique.md | 170 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 142 insertions(+), 28 deletions(-) diff --git a/caracteristique.md b/caracteristique.md index fe9ef120e..a214ec05a 100644 --- a/caracteristique.md +++ b/caracteristique.md @@ -11,6 +11,7 @@ Au moment de la conception de Rougail, il y a eu des choix structurant qui ont d Voici la liste des principales caractéristiques : + ## Logiciel libre Rougail est un logiciel libre (et Open Source) de gestion externe de variables. @@ -30,6 +31,7 @@ Rougail est composé : - différents sous projet pour étendre les fonctionnalités de base - un outil en ligne de commande pour facilité l'utilisation de la bibliothèque. + ## Les acteurs Rougail est destiné a séparer le cycle de vie de la variable entre 3 acteurs : @@ -52,8 +54,11 @@ Dans le cadre du développement d'une application : - l'utilisateur adapte les valeurs - l'application utilise les variables avec leurs valeurs + ## Cycle de vie des variables +Le but de Rougail est de gérer les variables et plus largement la configuration. + Rougail a pour but de définir les variables puis de gérer tout son cycle de vie. Dans le cycle de vie d'une variable, on inclut les étapes générique d'une variable (par exemple pour le langage C) : @@ -229,7 +234,7 @@ my_variable: ``` ```bash -rougail -m structure_default.yml structure_redefine.yml +rougail -m structure_default.yml structure_redefine.yml ╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ @@ -263,9 +268,9 @@ Mais on va retrouver également tout une série de type métier : - secret - ... -Voici quelques exemples : +Voici quelques exemples (dans le fichier `structure_type.yml`) : -```structure_type.yml +```yaml %YAML 1.2 --- version: 1.1 @@ -282,7 +287,8 @@ my_date: ... ``` -```rougail -m structure_type.yml +```bash +rougail -m structure_type.yml ╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ @@ -348,9 +354,9 @@ Par contre, comme l'exemple du typage fort le suggère, l'acteur qui adapte la v Le type peut être défini explicitement (comme dans le fichier structure_type.yml) ou déduit du typage des variables YAML. -Par exemple la variable avec une valeur par défaut à 1 est une variable de type "integer" : +Par exemple la variable avec une valeur par défaut à 1 est une variable de type "integer" (a mettre dans le fichier `structure_inference.yml`) : -```structure3.yml +```yaml %YAML 1.2 --- version: 1.1 @@ -359,7 +365,8 @@ my_variable: 1 ... ``` -```rougail -m structure3.yml +```bash +rougail -m structure_inference.yml ╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ @@ -368,7 +375,7 @@ Variables: ``` -### Valeur "nullable" +### Variable "nullable" Le type "null" (ou "None" en python) n'existe pas dans Rougail. "null" est une valeur. Tous les types peuvent accepter cette valeur, mais par défaut, ce n'est pas le cas. @@ -384,7 +391,7 @@ my_variable: ``` ```bash -rougail -m structure_nullable.yml +rougail -m structure_nullable.yml 🛑 ERRORS ┗━━ The following variables are mandatory but have no value: ┗━━ my_variable @@ -423,6 +430,111 @@ Variables: ``` +### Variable "liste" + +La liste n'est pas non plus un type. C'est une propriété d'une variable. Cela signifie qu'une liste ne peut pas contenir des valeurs de plusieurs types. + + +### Famille "objet" + +Une famille est une variable d'un type particuiler. C'est un conteneur destiné à accueillir des variables. + + +#### Un "objet" + +Ce qu'on appele "object" généralement est appeler dans Rougail des "familles". Donc au lieu de déclarer mes variables à la racine, je vais la déclarer dans une famille. + +Par exemple dans le fichier `structure_family.yml` je créé un famille my_object qui contient deux variables : + +```yaml +%YAML 1.2 +--- +version: 1.1 + +my_object: + + key1: value1 + + key2: value2 +... +``` + +Si j'exporte au format JSON j'ai bien un objet : + +```bash +rougail -m structure_family.yml -o json +{ + "my_object": { + "key1": "value1", + "key2": "value2" + } +} +``` + +Les familles gèrent l'arborescence. Il est possible de faire des sous-familles. + + +#### Liste d'"object" + +Une famille particulière, appeler "leadership" permet d'avoir une liste d'objet identique. + +Par exemple si je veux pouvoir créer un nombre non limité d'utilisateur associé à un mot de passe, je ne peux pas passer par des listes, je veux une liste d'objet. + +Voici le contenu du fichier `structure_leadership.yml` : + +```yaml +%YAML 1.2 +--- +version: 1.1 + +users: + type: leadership + + username: + type: unix_user + + password: + type: secret +... +``` + +Et le fichier `userdata_leadership.yml` : + +```yaml +--- +users: + - username: foo + password: SoSecr31 + - username: bar + password: SoSecr31 + - username: toot + password: SoSecr31 +... +``` + +J'ai bien une liste d'objet : + +```bash +rougail -m structure_leadership.yml -u yaml -yf userdata_leadership.yml -o json +{ + "users": [ + { + "username": "foo", + "password": "SoSecr31" + }, + { + "username": "bar", + "password": "SoSecr31" + }, + { + "username": "toot", + "password": "SoSecr31" + } + ] +} +``` + + ## Intégrité des données L'intégrité des données fait référence au fait que les données doivent être fiables et précises tout au long de leur cycle de vie. @@ -443,9 +555,9 @@ Mais cela ne suffit pas. #### Paramètres de type -Il existe, pour certains type, un certains nombres de paramètres qui vont pouvoir compléter le typage des variables : +Il existe, pour certains type, un certains nombres de paramètres qui vont pouvoir compléter le typage des variables (dans le fichier `structure_param_type.yml`) : -```structure_param_type.yml +```yaml %YAML 1.2 --- version: 1.1 @@ -460,7 +572,8 @@ my_percent: ... ``` -```rougail -m structure_param_type.yml +```bash +rougail -m structure_param_type.yml ╭─────── Caption ────────╮ │ Variable Default value │ ╰────────────────────────╯ @@ -478,7 +591,7 @@ my_percent: 120 ```bash rougail -m structure6.yml -u yaml -yf userdata1.yml 🔔 WARNINGS -┗━━ the value "120" is an invalid integer for "my_percent", value must be less than "100", it will be +┗━━ the value "120" is an invalid integer for "my_percent", value must be less than "100", it will be ignored when loading from the YAML file "userdata1.yml" ╭─────── Caption ────────╮ │ Variable Default value │ @@ -492,7 +605,7 @@ Ou pourra même généré une erreur : ```bash rougail -m structure6.yml -u yaml -yf userdata1.yml --cli.invalid_user_datas_error 🛑 ERRORS -┗━━ the value "120" is an invalid integer for "my_percent", value must be less than "100", it will be +┗━━ the value "120" is an invalid integer for "my_percent", value must be less than "100", it will be ignored when loading from the YAML file "userdata1.yml ``` @@ -501,7 +614,7 @@ rougail -m structure6.yml -u yaml -yf userdata1.yml --cli.invalid_user_datas_err Mais il est possible d'ajouter des validations complémentaires, par exemple ici vérifier que la variable est impaire (dans le fichier `structure_validators.yml`) : -```structure_validators.yml +```yaml %YAML 1.2 --- version: 1.1 @@ -515,12 +628,14 @@ my_odd_variable: ... ``` -```rougail -m structure7.yml +```bash +rougail -m structure7.yml 🛑 ERRORS ┗━━ "10" is an invalid integer for "my_odd_variable", not an odd integer ``` Par contre cela passe avec une valeur impaire (dans le fichier `userdata_validators.yml`) : + ```yaml --- my_odd_variable: 11 @@ -528,7 +643,7 @@ my_odd_variable: 11 ```bash -rougail -m structure_validators.yml -u yaml -ff userdata_validators.yml +rougail -m structure_validators.yml -u yaml -yf userdata_validators.yml ╭────────────── Caption ───────────────╮ │ Variable Modified value │ │ (⏳ Original default value) │ @@ -562,7 +677,7 @@ my_max_value: ``` ```bash -rougail -m structure_consistency.yml +rougail -m structure_consistency.yml 🛑 ERRORS ┗━━ "11" is an invalid integer for "my_max_value", must but upper than 11 (the value of "my_min_value") ``` @@ -575,14 +690,14 @@ my_max_value: 13 ``` ```bash -%YAML 1.2 ---- -version: 1.1 - -my_min_value: 11 - -my_max_value: - default: +%YAML 1.2 +--- +version: 1.1 + +my_min_value: 11 + +my_max_value: + default: variable: _.my_min_value validators: - jinja: |- @@ -593,7 +708,7 @@ my_max_value: ``` ```bash -rougail -m structure_consistency.yml -u yaml -ff userdata_consistency.yml +rougail -m structure_consistency.yml -u yaml -yf userdata_consistency.yml ╭────────────── Caption ───────────────╮ │ Variable Default value │ │ Modified value │ @@ -607,7 +722,6 @@ Variables: -Arborescent Inspiré par ABAC Spécialisation des variables Modèle de configuration