reorganise

This commit is contained in:
Emmanuel Garette 2021-02-06 17:36:43 +01:00
parent 5420c522d8
commit 0c0d1416d6
8 changed files with 571 additions and 3 deletions

View file

@ -1,6 +1,6 @@
# Une famille # Une famille
Une famille est un conteneur de variables. Une famille est un [conteneur de variables](variables.md).
Pour décrire une famille il faut mettre au minimum un nom : Pour décrire une famille il faut mettre au minimum un nom :
@ -8,7 +8,7 @@ Pour décrire une famille il faut mettre au minimum un nom :
<family name="my_family"/> <family name="my_family"/>
``` ```
Cette famille doit être placé dans une balise "variables" : Cette famille doit être placé dans une balise [variables](variables.md) :
``` ```
<variables> <variables>

7
doc/fill/README.md Normal file
View file

@ -0,0 +1,7 @@
# Les variables calculées
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)
- [Paramètre de la fonction](param.md)
- [Réfinition](redefine.md)

186
doc/fill/param.md Normal file
View file

@ -0,0 +1,186 @@
# Paramètre de la fonction
## Paramètre positionnel
Déclarons un calcul avec paramètre :
```
<constraints>
<fill name="return_value" target="my_calculated_variable">
<param>no</param>
</fill>
</constraints>
```
Créons la fonction correspondante :
```
def return_value(value):
return value
```
La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".
## Paramètre nommée
Déclarons une contrainte avec un paramètre nommée :
```
<constraints>
<fill name="return_value" target="my_calculated_variable">
<param name="valeur">no</param>
</fill>
</constraints>
```
Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no".
## Paramètre de type texte
Dans l'exemple précédent :
```
<constraints>
<fill name="return_value" target="my_calculated_variable">
<param>no</param>
</fill>
</constraints>
```
Le paramètre est de type texte (ou "string").
## Paramètre de type nombre
Déclarons un calcul avec paramètre avec un nombre :
```
<constraints>
<fill name="return_value_with_number" target="my_calculated_variable">
<param type="number">1</param>
</fill>
</constraints>
```
Créons la fonction correspondante :
```
def return_value_with_number(value):
if value == 1:
return 'no'
return 'yes'
```
La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1".
## Paramètre de type variable
Créons deux variables avec une contrainte de type variable qui contient le nom de la variable dont sa valeur sera utilisé comme paramètre :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
<variable name="my_variable" type="number" description="My variable">
<value>1</value>
</variable>
</family>
</variables>
<constraints>
<fill name="return_value_with_number" target="my_calculated_variable">
<param type="variable">my_variable</param>
</fill>
</constraints>
```
Si l'utilisateur laisse la valeur 1 à "my_variable", la valeur par défault de la variable "my_calculated_variable" sera "no".
Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "yes".
### Paramètre avec variable potentiellement non existante
Suivant le contexte une variable peut exister ou ne pas exister.
Un paramètre de type "variable" peut être "optional" :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
</variables>
<constraints>
<fill name="return_value" target="my_calculated_variable">
<param type="variable" optional="True">unknow_variable</param>
</fill>
</constraints>
```
Dans ce cas la fonction "return_value" est exécuté sans paramètre.
Si maintenant on créé un nouveau dictionnaire en créant cette variable, la fonction sera exécuté avec le paramètre.
### Paramètre avec variable potentiellement désactivée
FIXME : <!ATTLIST param notraisepropertyerror (True|False) "False">
Il n'y a pas spécialement de test !
### Paramètre avec variable suiveuse
[variable suiveuse](variable/leadership.md)
FIXME :
- tests/flattener_dicos/10leadership_append/00-base.xml
- tests/flattener_dicos/10leadership_auto/00-base.xml
- tests/flattener_dicos/10leadership_autoleader/00-base.xml
- tests/flattener_dicos/10leadership_autoleader_expert/00-base.xml
### Paramètre avec variable dynamique
Il est possible de faire un calcul avec comme paramètre [une variable d'une famille dynamique](family/auto.md) mais pour une suffix particulier :
```
<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_calculated_variable" type="string" description="My calculated variable"/>
</family>
<family name='dyn' dynamic="suffixes">
<variable name='vardyn' type='string' description="Dynamic variable">
<value>val</value>
</variable>
</family>
</variables>
<constraints>
<fill name="return_value" target="my_calculated_variable">
<param type="variable">vardynval1</param>
</fill>
</constraints>
```
Dans ce cas, valeur du paramètre de la fonction "return_value" sera la valeur de la variable "vardyn" avec le suffix "val1".
## Paramètre de type information
Le paramètre peut être la valeur est issue d'une information de la configuration.
Créons une variable et la contrainte :
```
<variables>
<family name="family">
<variable name="my_calculated_variable" type="string" description="My calculated variable"/>
</family>
</variables>
<constraints>
<fill name="return_value" target="my_calculated_variable">
<param type="information">server_name</param>
</fill>
</constraints>
```
Dans ce cas, l'information de la configuration "server_name" sera utilisé comme valeur de la variable "my_calculated_variable".
Si l'information n'existe pas, la paramètre aura la valeur "None".

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

@ -0,0 +1,61 @@
# Rédéfinition
## Redéfinition des calcules
Dans un premier dictionnaire déclarons notre variable et notre calcule :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
</variables>
<constraints>
<fill name="return_no" target="my_calculated_variable"/>
</constraints>
```
Dans un second dictionnaire il est possible de redéfinir le calcul :
```
<variables>
<family name="family">
<variable name="my_calculated_variable" redefine="True"/>
</family>
</variables>
<constraints>
<fill name="return_yes" target="my_calculated_variable"/>
</constraints>
```
Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera.
## Redéfinition avec suppression d'un calcul
Il se peut que dans un dictionnaire on décide de définir une valeur par défaut à une variable via un calcul.
Dans un second dictionnaire il est possible de supprimer ce calcul.
Dans un premier dictionnaire déclarons notre variable et notre calcule :
```
<variables>
<family name="family">
<variable name="my_calculated_variable"/>
</family>
</variables>
<constraints>
<fill name="return_no" target="my_calculated_variable"/>
</constraints>
```
Dans un second dictionnaire supprimer ce calcul :
```
<variables>
<family name="family">
<variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
</family>
</variables>
```

104
doc/fill/value.md Normal file
View file

@ -0,0 +1,104 @@
# Valeur calculée de la variable
## Variable avec une valeur par défaut calculée
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>
</variables>
<constraints>
<fill name="return_no" target="my_calculated_variable"/>
</constraints>
```
Puis créons la fonction "return_no" :
```
def return_no():
return 'no'
```
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.
Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" :
```
<variable name="my_calculated_variable">
<value>yes</value>
</variable>
```
Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur.
## 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 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" target="my_calculated_variable_dyn_">
<param type="variable">my_variable</param>
</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" target="my_calculated_variable_dyn_">
<param type="variable">my_variable</param>
<param type="suffix"/>
</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é.

6
doc/variable/README.md Normal file
View file

@ -0,0 +1,6 @@
# Variable
- [Une variable](simple.md)
- [Variable meneuse ou suiveuse](leadership.md)
FIXME <!ATTLIST variable test CDATA #IMPLIED>

204
doc/variable/simple.md Normal file
View file

@ -0,0 +1,204 @@
# Variable
## Un variable
Une variable est forcement dans une famille. Il faut donc déjà avoir créer une famille.
Une variable est déjà un nom. C'est à dire qu'on pourra utiliser plus tard la variable via ce nom.
```
<variable name="my_variable"/>
```
## Description et aide sur la variable
En plus d'un nom, il est possible de mettre une "description" à la variable. C'est une information "utilisateur" qui nous permettra d'avoir des informations complémentaires sur le contenu de cette variable :
```
<variable name="my_variable" description="This is a greate variable"/>
```
En plus de la description, il est possible de préciser une aide complémentaire :
```
<variable name="my_variable" help="This is a greate variable"/>
```
## Le type de la variable
Une variable a un type. Ce type permet de définir les valeurs acceptées par cette variable :
- string : chaine de caractère (type par défaut)
- number : un nombre
- float : un chiffre flottant
- boolean : True ou False si aucune valeur n'est défini la valeur par défaut cette variable sera True
- password : un mot de passe
- mail : une adresse mail
- filename : nom de fichier au sens Unix (exemple : '/etc/passwd')
- date : une date au format "%Y-%m-%d" (exemple : "2021-01-30")
- unix_user : nom d'utilisateur au sens Unix
- ip : n'importe quelle adresse IPv4
- cidr : n'importe quelle adresse IPv4 au format CIDR
- local_ip : adresse IPv4 sur un réseau local, si l'adresse IPv4 n'est pas local, un warning sera afficher mais la valeur sera accepté tout de même
- netmask : masque d'une adresse IPv4
- network : adresse réseau
- network_cidr : adresse réseau au format CIDR
- broadcast : adresse de diffusion
- netbios : nom netbios
- domain : nom de domaine
- hostname : nom d'hôte
- web_address : adresse web (http://www.cadoles.com/)
- port : port
- mac : adresse MAC
- schedule : périodicité du schedule, les valeurs possibles sont "none", "daily", "weekly" ou "monthly"
- schedulemod : type de schedule, les valeurs possibles sont "pre" ou "post"
Pour définir le type d'une variable :
```
<variable name="my_variable" type="number"/>
```
## Variable à valeur multiple
Par défaut une variable ne peut acceuillir qu'une seule valeur. Il peut être utile de pouvoir spécifier plusieurs valeurs à une même variable.
Pour définir une variable à valeur multiple :
```
<variable name="my_variable" multi="True"/>
```
## Mode de la variable
Le [mode](./mode.md) par défaut d'une variable correspond au [mode](./mode.md) de la famille.
Pour définir le [mode](./mode.md) :
```
<variable name="my_variable" mode="expert"/>
```
## Variable invisible
Il est possible de cacher une variable.
Cacher une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service.
Par contre cette variable sont accessibles lorsqu'on va l'utiliser.
Pour cacher une variable :
```
<variable name="my_variable" hidden="True"/>
```
## Variable désactive
Il est possible de désactiver une variable.
Désactiver une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration du service mais également lorsqu'on va l'utiliser.
Pour désactiver une variable :
```
<variable name="my_variable" disabled="True"/>
```
## Variable obligatoire
Variable dont une valeur est requise :
```
<variable name="my_variable" mandatory="True"/>
```
## Valeur par défaut d'une variable
Il est possible de fixer les valeurs par défaut d'une variable :
```
<variable name="my_variable">
<value>value</value>
</variable>
```
Pour une variable multiple, il est possible de préciser plusieurs valeurs :
```
<variable name="my_variable" multi="True">
<value>value 1</value>
<value>value 2</value>
</variable>
```
Une valeur par défaut peut également être [une valeur calculer](fill/README.md).
## Redéfinir une variable
Il est possible de définir une variable dans un dictionnaire et de changer son comportement dans une second dictionnaire.
Attention trois attributs ne sont redéfinisable :
- name
- type
- multi
Créons notre variable :
<variable name="my_variable"/>
Et redéfinisons là :
```
<variable name="my_variable" redefine="True" description="New description"/>
```
## Créer une variable inexistante
Il est parfois utile de créer une variable si elle n'existe pas dans un autre dictionnaire :
```
<variable name="my_variable" exists="False"/>
```
Si cette variable existe dans un autre dictionnaire, elle ne sera pas modifié ni recréé
## Redéfinir une variable si elle existe
Parfois on veut pouvoir redéfinir une variable mais seulement dans le cas où elle existe déjà :
```
<variable name="my_variable" redefine="True" exists="True" hidden="True"/>
```
## 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é.
Voici une variable a valeur automatiquement modifiée :
```
<variable name="my_variable" auto_save="True">
<value>my_value</value>
</variable>
```
Dans ce cas la valeur est fixée à la valeur actuelle.
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 automatiquement modifiées que si elles ont une valeurs.
## 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é.
Voici un variable à valeur en lecture seule automatique :
```
<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.

View file

@ -1,6 +1,6 @@
# Le conteneur des variables # Le conteneur des variables
La balise "variables" est le conteneur de l'ensemble des familles dans laquelle on pourra placer des variables : La balise "variables" est le conteneur de l'ensemble des [familles](family/README.md) dans laquelle on pourra placer des [variables](variable/README.md) :
``` ```
<?xml version='1.0' encoding='UTF-8'?> <?xml version='1.0' encoding='UTF-8'?>