stove/rougail
3
0
Fork 0
Code Issues 10 Pull requests 1 Projects Releases Wiki Activity

doc for check

Browse source
This commit is contained in:
Emmanuel Garette 2021-02-15 15:17:23 +01:00
parent d1a39e5183
commit 5821b62f39
13 changed files with 135 additions and 149 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/README.md
View file

@ -19,6 +19,8 @@ Les familles et les variables peuvent être défini dans plusieurs dictionnaires
Il est également possible de redéfinir des éléments pour changer les comportement d'une variable ou d'un service.
FIXME expliquer les noms des variables dans les extras
### Les variables
- [Les familles](family/README.md)
@ -36,6 +38,7 @@ Il est également possible de redéfinir des éléments pour changer les comport
- [Les calcules automatiques](fill/README.md)
- [Les vérifications des valeurs](check/README.md)
- [Les conditions](condition/README.md)
- [Les variables meneuses ou suiveuses](variable/leadership.md)
## Les templates

6
doc/check/README.md
View file

@ -1,10 +1,4 @@
# Les vérifications des valeurs
- [Fonction de vérification](function.md)
- [Cible de la fonction](../target/variable.md)
- [Paramètre de la fonction](../param/README.md)
- [Réfinition](redefine.md)
FIXME
<!ATTLIST variable remove_check (True|False) "False">

135
doc/check/function.md
View file

@ -1,124 +1,53 @@
# Valeur calculée de la variable
# Fonction de vérification
## Variable avec une valeur par défaut calculée
## Vérification stricte des valeurs
Créons une variable dont la valeur est retournée par la fonction "return_no" :
Une fonction de vérification est une fonction complémentaire au type qui permet de valider plus précisement le contenu d'une variable.
Voici un exemple simple de validation des valeurs :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
<variable name="my_variable"/>
</variables>
<constraints>
<fill name="return_no">
<target>my_calculated_variable</target>
</fill>
<check name="islower">
<target>my_variable</target>
</check>
</constraints>
```
Puis créons la fonction "return_no" :
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 :
```
def return_no():
return 'no'
def islower(value):
if value is None:
return
if not value.islower():
raise ValueError(f'"{value}" is not lowercase string')
```
La [cible](../target/variable.md) du calcul est ici "my_calculated_variable".
Une fonction de vérification doit prendre en compte 2 aspects important :
Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "no"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable.
- 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.
Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" :
À partir de maintenant seule None et des valeurs en minuscule seront autorisés.
## Vérification des valeurs avec avertissement
Dans la contrainte, il est possible de spécifier le niveau d'erreur et le mettre en avertissement :
```
<variable name="my_calculated_variable">
<value>yes</value>
</variable>
<check name="islower" level="warning">
<target>my_variable</target>
</check>
```
Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur.
Dans ce cas une valeur avec une majuscule sera accepté, mais un message d'avertissement apparaitra.
Il est possible de définir des [paramètres](../param/README.md) à cette fonction.
## Variable avec une valeur calculée
En ajoutant le paramètre "hidden" à "True" dans la variable précédente, l'utilisateur n'aura plus la possibilité de modifié la valeur. La valeur de la variable sera donc systématiquement calculée :
```
<variable name="my_calculated_variable" hidden="True"/>
```
Si une condition "hidden_if_in" est spécifié à la variable, la valeur sera modifiable par l'utilisateur si elle n'est pas cachée mais elle sera systèmatiquement calculée (même si elle a déjà était modifiée) si la variable est cachée.
## Variable meneuse ou suiveuse avec valeur calculé
Une [variable suiveuse](../variable/leadership.md) ne peut pas être calculé automatiquement.
Une [variable meneuse](../variable/leadership.md) peut être calculé automatiquement.
Si la variable n'est pas multiple, il ne faut pas que le calcule retourne une liste.
## Variable dynamique avec une valeur calculée
Il est également possible de calculer [une variable d'une famille dynamique](../family/auto.md) à partir d'une variable standard :
```
<variables>
<family name='family'>
<variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
<value>val1</value>
<value>val2</value>
</variable>
<variable name="my_variable" type="string" description="My variable">
<value>val</value>
</variable>
</family>
<family name='dyn' dynamic="suffixes">
<variable name="my_calculated_variable_dyn_" type="string" description="My calculated variable"/>
<value>val</value>
</variable>
</family>
</variables>
<constraints>
<fill name="return_value">
<param type="variable">my_variable</param>
<target>my_calculated_variable_dyn_</target>
</fill>
</constraints>
```
Dans ce cas, les variables dynamiques "my_calculated_variable_dyn_" seront calculés à partir de la valeur de la variable "my_variable".
Que cela soit pour la variable "my_calculated_variable_dyn_val1" et "my_calculated_variable_dyn_val2".
Par contre, il n'est pas possible de faire un calcul pour une seule des deux variables issues de la variable dynamique.
Si c'est ce que vous cherchez à faire, il faudra prévoir un traitement particulier dans votre fonction.
Dans ce cas, il faut explicitement demander la valeur du suffix dans la fonction :
```
<constraints>
<fill name="return_value_suffix">
<param type="variable">my_variable</param>
<param type="suffix"/>
<target>my_calculated_variable_dyn_</target>
</fill>
</constraints>
```
Et ainsi faire un traitement spécifique pour ce suffix :
```
def return_value_suffix(value, suffix):
if suffix == 'val1':
return value
```
## Variable avec valeur calculée obligatoire
Par défaut les variables calculées ne sont pas des variables obligatoires.
Dans ce cas un calcul peut retourner "None" ou "", mais surtout un utilisateur peut spécifier une valeur nulle à cette variable. Dans ce cas le calcul ne sera plus réalisé.
<!ELEMENT check (param*)>
<!ATTLIST check name CDATA #REQUIRED>
<!ATTLIST check level (error|warning) "error">

61
doc/check/redefine.md Normal file
View file

@ -0,0 +1,61 @@
# Rédéfinition
## Redéfinition des vérification
Dans un premier dictionnaire déclarons notre variable et sa fonction de vérification :
```
<variables>
<variable name="my_variable"/>
</variables>
<constraints>
<check name="islower">
<target>my_variable</target>
</check>
</constraints>
```
Dans un second dictionnaire il est possible de redéfinir le calcul :
```
<variables>
<variable name="my_variable" redefine="True"/>
</variables>
<constraints>
<check name="isspace">
<target>my_variable</target>
</check>
</constraints>
```
Dans ce cas, la fonction "islower" exécuté. Si cette fonction ne retourne pas d'erreur, la seconde fonction "isspace" sera exécuté.
## Redéfinition avec suppression d'un calcul
Il se peut que dans un dictionnaire on décide de vérifier la valeur d'une variable.
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 :
```
<variables>
<variable name="my_variable"/>
</variables>
<constraints>
<check name="islower">
<target>my_variable</target>
</check>
</constraints>
```
Dans un second dictionnaire supprimer cette vérification :
```
<variables>
<family name="family">
<variable name="my_variable" redefine="True" remove_check="True"/>
</family>
</variables>
```

2
doc/fill/README.md
View file

@ -3,6 +3,4 @@
Une variable calculée est une variable donc sa valeur est le résultat d'une fonction python.
- [Valeur calculée de la variable](value.md)
- [Cible de la fonction](../target/variable.md)
- [Paramètre de la fonction](../param/README.md)
- [Réfinition](redefine.md)

16
doc/fill/redefine.md
View file

@ -6,9 +6,7 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
<variable name="my_calculated_variable"/>
</variables>
<constraints>
<fill name="return_no">
@ -21,9 +19,7 @@ Dans un second dictionnaire il est possible de redéfinir le calcul :
```
<variables>
<family name="family">
<variable name="my_calculated_variable" redefine="True"/>
</family>
<variable name="my_calculated_variable" redefine="True"/>
</variables>
<constraints>
<fill name="return_yes">
@ -44,9 +40,7 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
<variable name="my_calculated_variable"/>
</variables>
<constraints>
<fill name="return_no">
@ -59,8 +53,6 @@ Dans un second dictionnaire supprimer ce calcul :
```
<variables>
<family name="family">
<variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
</family>
<variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
</variables>
```

27
doc/fill/value.md
View file

@ -6,9 +6,7 @@ Créons une variable dont la valeur est retournée par la fonction "return_no" :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
<variable name="my_calculated_variable"/>
</variables>
<constraints>
<fill name="return_no">
@ -24,9 +22,9 @@ def return_no():
return 'no'
```
La [cible](../target/variable.md) du calcul est ici "my_calculated_variable".
La [cible (de type variable)](../target/variable.md) du calcul est ici "my_calculated_variable".
Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "no"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable.
Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "no"), elle sera calculée tant que l'utilisateur n'a pas de spécifié de valeur à cette variable.
Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" :
@ -61,17 +59,15 @@ Il est également possible de calculer [une variable d'une famille dynamique](..
```
<variables>
<family name='family'>
<variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
<value>val1</value>
<value>val2</value>
</variable>
<variable name="my_variable" type="string" description="My variable">
<value>val</value>
</variable>
</family>
<variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
<value>val1</value>
<value>val2</value>
</variable>
<variable name="my_variable" type="string" description="My variable">
<value>val</value>
</variable>
<family name='dyn' dynamic="suffixes">
<variable name="my_calculated_variable_dyn_" type="string" description="My calculated variable"/>
<variable name="my_calculated_variable_dyn\_" type="string" description="My calculated variable"/>
<value>val</value>
</variable>
</family>
@ -114,4 +110,3 @@ def return_value_suffix(value, suffix):
Par défaut les variables calculées ne sont pas des variables obligatoires.
Dans ce cas un calcul peut retourner "None" ou "", mais surtout un utilisateur peut spécifier une valeur nulle à cette variable. Dans ce cas le calcul ne sera plus réalisé.

2
doc/param/positional.md
View file

@ -13,7 +13,7 @@ def return_value(value):
return value
```
La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
La variable "value" de la fonction "return_value" aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
# Paramètre nommée

11
doc/param/simple.md
View file

@ -1,12 +1,11 @@
# Paramètre de type "texte"
Dans l'exemple précédent :
Déclarons un paramètre avec une string :
```
<param type="string">no</param>
```
Le paramètre est de type texte (ou "string").
C'est le type par défaut pour un paramètre.
# Paramètre de type "nombre"
@ -28,6 +27,14 @@ def return_value_with_number(value):
La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1".
# Paramètre de type "booléen"
Déclarons un paramètre avec un booléen :
```
<param type="boolean">True</param>
```
# Paramètre de type "nil"
Le paramètre peut être une valeur null (None en python) :

2
doc/param/variable.md
View file

@ -6,7 +6,7 @@ Imaginons que la variable "my_variable" pré-existe. La valeur de la variable se
<param type="variable">my_variable</param>
```
[Les variables meneuses ou suiveuses](../variable/leadership.md) peuvent être utilisé sans soucis commme paramètre.
[Les variables meneuses ou suiveuses](../variable/leadership.md) peuvent être utilisé sans soucis comme paramètre.
## Paramètre avec variable potentiellement non existante

8
doc/service/file.md
View file

@ -4,7 +4,7 @@
La gestion des fichiers se fait dans un conteneur de [service](service.md).
La déclaration du fichier met de générer un fichier à partir d'un template pour le déposer à l'endroit prévu dans la déclaration de cette élément.
La déclaration du fichier permet de générer un fichier à partir d'un template pour le déposer à l'endroit prévu dans la déclaration de cette élément.
Il est nécessaire, au minimum, de spécifier le chemin complet du fichier :
@ -16,7 +16,7 @@ Il est nécessaire, au minimum, de spécifier le chemin complet du fichier :
</services>
```
Dans ce cas, le nom du template est déduit du nom du fichier, ici ca sera "squid.conf".
Dans ce cas, le nom du template est déduit du nom du fichier, ici cela sera "squid.conf".
Si le template a un nom différent (par exemple si plusieurs template se retrouve avec le même nom), il est possible de changer le nom du template avec l'attribut source :
@ -43,7 +43,7 @@ Il est possible également de définir le nom du fichier dans une variable :
Dans le cas des fichiers dynamique, la source est obligatoire.
Et même de définir une variable de type multiple, ce qui génèrera plusiers fichiers :
Il est même possible de définir une variable de type multiple, ce qui génèrera plusiers fichiers :
```
<services>
@ -95,6 +95,8 @@ Attention : les deux variables "my_variable1" et "my_variable2" doivent être mu
Par défaut les droits du fichier généré sont "0644" avec comme utilisateur "root" et groupe "root".
Il est possible de définir une autre valeur à un ou plusieurs de ces attributs :
```
<file name="/etc/squid/squid.conf" mode="0640" owner="nobody" group="squid"/>
```

2
doc/variable/leadership.md
View file

@ -2,6 +2,8 @@
## 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](simple.md) qui est obligatoirement de type multiple.
Une variable meneuse peut être obligatoire.

9
doc/variable/simple.md
View file

@ -182,7 +182,7 @@ Parfois on veut pouvoir redéfinir une variable mais seulement dans le cas où e
## Variable à valeur automatiquement modifiée
Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand le serveur sera déployé.
Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand la propriété global "force_store_value" de Tiramisu est mise.
Voici une variable a valeur automatiquement modifiée :
@ -201,18 +201,21 @@ Une [variable meneuse ou suiveuse](leadership.md) ne peut pas avoir la propriét
## Variable à valeur en lecture seule automatique
Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand le serveur sera déployé.
Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand la [variable "instanciated_module" passe à "True"](../dev/config.md).
Voici un variable à valeur en lecture seule automatique :
```
<variable name="instanciated_module" type="boolean">
<value>False</value>
</variable>
<variable name="my_variable" auto_freeze="True"/>
```
Dans ce cas la valeur est fixée à la valeur actuelle et elle ne sera plus modifiable par l'utilisateur.
Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.
Ces variables sont généralement des variables obligatoires. En effet ces variable ne sont en lecteur seul que si elles sont une valeurs.
Ces variables sont généralement des variables obligatoires. En effet ces variable ne sont en lecteur seul que si elles ont une valeurs.
Une [variable meneuse ou suiveuse](leadership.md) ne peut pas avoir la propriété auto_freeze.