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

fill's documentation

Browse source
This commit is contained in:
Emmanuel Garette 2021-02-10 08:19:33 +01:00
parent 6f05c22a3d
commit 8d47923abe
19 changed files with 368 additions and 210 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
doc/README.md
View file

@ -7,7 +7,15 @@
## Les services ## Les services
- [Les services](service/README.md)
- [La gestion d'un service](service/service.md)
- [La gestion d'un fichier](service/file.md)
- [La gestion d'un fichier de service systemd](service/override.md)
- [La gestion d'un port](service/port.md)
- [La gestion d'une ip](service/ip.md)
## Les contraintes ## Les contraintes
- [Les calcules automatiques](fill/README.md) - [Les calcules automatiques](fill/README.md)
- [Les vérifications des valeurs](check/README.md) - [Les vérifications des valeurs](check/README.md)
- [Les conditions](condition/README.md)

10
doc/check/README.md Normal file
View file

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

124
doc/check/function.md Normal file
View file

@ -0,0 +1,124 @@
# 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</target>
</fill>
</constraints>
```
Puis créons la fonction "return_no" :
```
def return_no():
return 'no'
```
La [cible](../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.
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.
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">

3
doc/fill/README.md
View file

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

197
doc/fill/param.md
View file

@ -1,197 +0,0 @@
# 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".
[Les variables meneuses ou suiveuses](../variable/leadership.md) peuvent être utilisé sans soucis commme paramètre.
### 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
Si une variable est désactivé, l'utilisation de cette variable peut poser problème.
Il est possible de ne pas générer d'erreur si une variable est désactivé en utilisant le paramètre "propertyerror" :
```
<variables>
<family name="general">
<variable name="condition">
<value>no</value>
</variable>
<variable name="variable1" disabled="True"/>
<variable name="variable2"/>
</family>
</variables>
<constraints>
<fill name="calc_val" target="variable2">
<param type="variable" propertyerror="False">variable1</param>
</fill>
</constraints>
```
Dans ce cas, le paramètre n'est jamais donnée à la fonction de destination.
### 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".

12
doc/fill/redefine.md
View file

@ -11,7 +11,9 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
</family> </family>
</variables> </variables>
<constraints> <constraints>
<fill name="return_no" target="my_calculated_variable"/> <fill name="return_no">
<target>my_calculated_variable</target>
</fill>
</constraints> </constraints>
``` ```
@ -24,7 +26,9 @@ Dans un second dictionnaire il est possible de redéfinir le calcul :
</family> </family>
</variables> </variables>
<constraints> <constraints>
<fill name="return_yes" target="my_calculated_variable"/> <fill name="return_yes">
<target>my_calculated_variable</target>
</fill>
</constraints> </constraints>
``` ```
@ -45,7 +49,9 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
</family> </family>
</variables> </variables>
<constraints> <constraints>
<fill name="return_no" target="my_calculated_variable"/> <fill name="return_no">
<target>my_calculated_variable"</target>
</fill>
</constraints> </constraints>
``` ```

18
doc/fill/value.md
View file

@ -11,7 +11,9 @@ Créons une variable dont la valeur est retournée par la fonction "return_no" :
</family> </family>
</variables> </variables>
<constraints> <constraints>
<fill name="return_no" target="my_calculated_variable"/> <fill name="return_no">
<target>my_calculated_variable</target>
</fill>
</constraints> </constraints>
``` ```
@ -22,6 +24,8 @@ def return_no():
return 'no' return 'no'
``` ```
La [cible](../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é une valeur à cette variable.
Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" : Attention, si une valeur par défaut est définit dans la variable "my_calculated_variable" :
@ -31,9 +35,10 @@ Attention, si une valeur par défaut est définit dans la variable "my_calculate
<value>yes</value> <value>yes</value>
</variable> </variable>
``` ```
Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur. Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur.
Il est possible de définir des [paramètres](../param/README.md) à cette fonction.
## Variable avec une valeur calculée ## 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 : 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 :
@ -50,10 +55,9 @@ Une [variable suiveuse](../variable/leadership.md) ne peut pas être calculé au
Une [variable meneuse](../variable/leadership.md) peut ê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. Si la variable n'est pas multiple, il ne faut pas que le calcule retourne une liste.
## Variable dynamique avec une valeur calculé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 : Il est également possible de calculer [une variable d'une famille dynamique](../family/auto.md) à partir d'une variable standard :
``` ```
<variables> <variables>
@ -73,8 +77,9 @@ Il est également possible de calculer [une variable d'une famille dynamique](fa
</family> </family>
</variables> </variables>
<constraints> <constraints>
<fill name="return_value" target="my_calculated_variable_dyn_"> <fill name="return_value">
<param type="variable">my_variable</param> <param type="variable">my_variable</param>
<target>my_calculated_variable_dyn_</target>
</fill> </fill>
</constraints> </constraints>
``` ```
@ -89,9 +94,10 @@ Dans ce cas, il faut explicitement demander la valeur du suffix dans la fonction
``` ```
<constraints> <constraints>
<fill name="return_value_suffix" target="my_calculated_variable_dyn_"> <fill name="return_value_suffix">
<param type="variable">my_variable</param> <param type="variable">my_variable</param>
<param type="suffix"/> <param type="suffix"/>
<target>my_calculated_variable_dyn_</target>
</fill> </fill>
</constraints> </constraints>
``` ```

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

@ -0,0 +1,7 @@
# Paramètre de la fonction
- [Paramètre positionnel ou nommée](positional.md)
- [Type de paramètre simple](simple.md)
- [Type de paramètre "variable"](variable.md)
- [Type de paramètre "information"](information.md)

10
doc/param/information.md Normal file
View file

@ -0,0 +1,10 @@
# Paramètre de type information
Le paramètre peut être la valeur est issue d'une information de la configuration.
```
<param type="information">server_name</param>
```
Dans ce cas, l'information de la configuration "server_name" sera utilisé comme valeur du paramètre.
Si l'information n'existe pas, la paramètre aura la valeur "None".

26
doc/param/positional.md Normal file
View file

@ -0,0 +1,26 @@
# Paramètre positionnel
Déclarons un paramètre positionnel :
```
<param>no</param>
```
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 maintenant un paramètre nommée :
```
<param name="valeur">no</param>
```
Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no".

37
doc/param/simple.md Normal file
View file

@ -0,0 +1,37 @@
# Paramètre de type "texte"
Dans l'exemple précédent :
```
<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"
Déclarons un paramètre avec un nombre :
```
<param type="number">1</param>
```
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 "nil"
Le paramètre peut être une valeur null (None en python) :
```
<param type="nil"/>
```

55
doc/param/variable.md Normal file
View file

@ -0,0 +1,55 @@
# Paramètre de type "variable"
Imaginons que la variable "my_variable" pré-existe. La valeur de la variable sera utilisé comme paramètre :
```
<param type="variable">my_variable</param>
```
[Les variables meneuses ou suiveuses](../variable/leadership.md) peuvent être utilisé sans soucis commme paramètre.
## 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" :
```
<param type="variable" optional="True">unknow_variable</param>
```
Si la variable "unknow_variable" n'existe pas, le paramètre ne sera pas passé à la fonction.
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
Si une variable est désactivé, l'utilisation de cette variable peut poser problème.
Il est possible de ne pas générer d'erreur si une variable est désactivé en utilisant le paramètre "propertyerror" :
```
<param type="variable" propertyerror="False">variable1</param>
```
Dans ce cas, si la variable est désactivé, le paramètre n'est jamais donnée à la fonction de destination.
## 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.
Par exemple :
```
<param type="variable">vardynval1</param>
```
Dans ce cas, la valeur du paramètre de la fonction sera la valeur de la variable "vardyn" pour la famille ayant le suffix "val1".
Il peut être utile de récupérer la valeur du suffix dans la fonction, pour cela il suffit de mettre un paramètre de type suffix :
```
<param type="suffix"/>
```
Dans l'exemple précédent la valeur de ce paramètre sera "val1".

9
doc/service/README.md Normal file
View file

@ -0,0 +1,9 @@
# Les services
<!ELEMENT services (service*)>
<!ELEMENT service ((port* | ip* | file* | override*)*) >
<!ATTLIST service name CDATA #REQUIRED>
<!ATTLIST service manage (True|False) "True">

18
doc/service/file.md Normal file
View file

@ -0,0 +1,18 @@
# Fichier
FIXME
<!ELEMENT file EMPTY>
<!ATTLIST file name CDATA #REQUIRED >
<!ATTLIST file file_type (UnicodeOption|variable) "UnicodeOption">
<!ATTLIST file variable CDATA #IMPLIED>
<!ATTLIST file variable_type (variable) "variable">
<!ATTLIST file source CDATA #IMPLIED>
<!ATTLIST file mode CDATA "0644">
<!ATTLIST file owner CDATA "root">
<!ATTLIST file group CDATA "root">
<!ATTLIST file filelist CDATA #IMPLIED >
<!ATTLIST file redefine (True|False) "False">
<!ATTLIST file templating (True|False) "True">

11
doc/service/ip.md Normal file
View file

@ -0,0 +1,11 @@
# IP
FIXME
<!ELEMENT ip (#PCDATA)>
<!ATTLIST ip iplist CDATA #IMPLIED >
<!ATTLIST ip ip_type (NetworkOption|variable) "NetworkOption">
<!ATTLIST ip interface_type (UnicodeOption|variable) "UnicodeOption">
<!ATTLIST ip interface CDATA #REQUIRED>
<!ATTLIST ip netmask_type (NetmaskOption|variable) "NetmaskOption">
<!ATTLIST ip netmask CDATA "255.255.255.255">

7
doc/service/override.md Normal file
View file

@ -0,0 +1,7 @@
# Override
FIXME
<!ELEMENT override EMPTY>
<!ATTLIST override source CDATA #IMPLIED >
<!ATTLIST override templating (True|False) "True">

7
doc/service/port.md Normal file
View file

@ -0,0 +1,7 @@
# Port
<!ELEMENT port (#PCDATA)>
<!ATTLIST port port_type (PortOption|variable) "PortOption">
<!ATTLIST port portlist CDATA #IMPLIED >
<!ATTLIST port protocol (tcp|udp) "tcp">

13
doc/target/variable.md Normal file
View file

@ -0,0 +1,13 @@
# Cible de la fonction de type "variable"
Par défaut une cible est de type variable.
```
<target>my_variable</target>
```
Mais une target peut être optionnelle. C'est à dire que si la variable n'existe pas, l'action ne sera pas associé à cette variable.
```
<target optional='True'>my_variable</target>
```

2
src/rougail/data/rougail.dtd
View file

@ -45,7 +45,7 @@
<!ELEMENT services (service*)> <!ELEMENT services (service*)>
<!ELEMENT service ((port* | tcpwrapper* | ip* | interface* | package* | file* | override*)*) > <!ELEMENT service ((port* | ip* | file* | override*)*) >
<!ATTLIST service name CDATA #REQUIRED> <!ATTLIST service name CDATA #REQUIRED>
<!ATTLIST service manage (True|False) "True"> <!ATTLIST service manage (True|False) "True">