doc: example for fill and conventions

This commit is contained in:
Emmanuel Garette 2021-12-11 16:33:55 +01:00
parent 8cf8c9b8eb
commit 3dca1349a8
22 changed files with 287 additions and 222 deletions

View File

@ -11,6 +11,7 @@ Rougail est un bibliothèque python3 qui permet de charger des dictionnaires (fi
- [Les dictionnaires](dictionary/rougail.md)
- [Les dictionnaires extra](dictionary/extra.md)
- [Convention d'écriture d'un dictionnaire](dictionary/convention.md)
### Les variables

View File

@ -8,12 +8,12 @@ Voici un exemple simple de validation des valeurs :
```
<variables>
<variable name="my_variable"/>
<variable name="my_variable"/>
</variables>
<constraints>
<check name="islower">
<target>my_variable</target>
</check>
<check name="islower">
<target>my_variable</target>
</check>
</constraints>
```
@ -46,7 +46,7 @@ Dans la contrainte, il est possible de spécifier le niveau d'erreur et le mettr
```
<check name="islower" level="warning">
<target>my_variable</target>
<target>my_variable</target>
</check>
```

View File

@ -6,12 +6,12 @@ Dans un premier dictionnaire déclarons notre variable et sa fonction de vérifi
```
<variables>
<variable name="my_variable"/>
<variable name="my_variable"/>
</variables>
<constraints>
<check name="islower">
<target>my_variable</target>
</check>
<check name="islower">
<target>my_variable</target>
</check>
</constraints>
```
@ -19,12 +19,12 @@ Dans un second dictionnaire il est possible de redéfinir le calcul :
```
<variables>
<variable name="my_variable" redefine="True"/>
<variable name="my_variable" redefine="True"/>
</variables>
<constraints>
<check name="isspace">
<target>my_variable</target>
</check>
<check name="isspace">
<target>my_variable</target>
</check>
</constraints>
```
@ -40,12 +40,12 @@ Dans un premier dictionnaire déclarons notre variable et notre fonction de vér
```
<variables>
<variable name="my_variable"/>
<variable name="my_variable"/>
</variables>
<constraints>
<check name="islower">
<target>my_variable</target>
</check>
<check name="islower">
<target>my_variable</target>
</check>
</constraints>
```
@ -53,9 +53,9 @@ Dans un second dictionnaire supprimer cette vérification :
```
<variables>
<family name="family">
<variable name="my_variable" redefine="True" remove_check="True"/>
</family>
<family name="family">
<variable name="my_variable" redefine="True" remove_check="True"/>
</family>
</variables>
```

View File

@ -10,15 +10,15 @@ La condition hidden_if_in permet de cacher une variable où une famille à l'uti
```
<variables>
<variable name="condition" type="boolean"/>
<variable name="my_variable"/>
<variable name="condition" type="boolean"/>
<variable name="my_variable"/>
</variables>
<constraints>
<condition name="hidden_if_in" source="condition">
<param>True</param>
<target>my_variable</target>
</condition>
<condition name="hidden_if_in" source="condition">
<param>True</param>
<target>my_variable</target>
</condition>
</constraints>
```
@ -34,16 +34,16 @@ Il est également possible de mettre plusieurs paramètre :
```
<variables>
<variable name="condition"/>
<variable name="my_variable"/>
<variable name="condition"/>
<variable name="my_variable"/>
</variables>
<constraints>
<condition name="hidden_if_in" source="condition">
<param>yes</param>
<param>maybe</param>
<target>my_variable</target>
</condition>
<condition name="hidden_if_in" source="condition">
<param>yes</param>
<param>maybe</param>
<target>my_variable</target>
</condition>
</constraints>
```
@ -69,8 +69,8 @@ Exemple :
```
<condition name="hidden_if_in" source="condition" optional="True", apply_on_fallback="False">
<param>yes</param>
<param>maybe</param>
<target>my_variable</target>
<param>yes</param>
<param>maybe</param>
<target>my_variable</target>
</condition>
```

View File

@ -8,15 +8,15 @@ Dans un premier dictionnaire déclarons notre variable et notre calcule :
```
<variables>
<variable name="condition" type="boolean"/>
<variable name="my_variable"/>
<variable name="condition" type="boolean"/>
<variable name="my_variable"/>
</variables>
<constraints>
<condition name="hidden_if_in" source="condition">
<param>True</param>
<target>my_variable</target>
</condition>
<condition name="hidden_if_in" source="condition">
<param>True</param>
<target>my_variable</target>
</condition>
</constraints>
```
@ -24,6 +24,6 @@ Dans un second dictionnaire supprimer ce calcul :
```
<variables>
<variable name="condition" redefine="True" remove_condition="True"/>
<variable name="condition" redefine="True" remove_condition="True"/>
</variables>
```

View File

@ -13,11 +13,11 @@ Voici un premier dictionnaire /srv/rougail/dictionaries/00-base.xml :
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<variables>
<variable name="my_variable">
<value>my_value</value>
</variable>
</variables>
<variables>
<variable name="my_variable">
<value>my_value</value>
</variable>
</variables>
</rougail>
```
@ -39,11 +39,11 @@ En plus du dictionnaire précédent, créons un dictionnaire extra /srv/rougail/
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<variables>
<variable name="my_variable_extra">
<value>my_value_extra</value>
</variable>
</variables>
<variables>
<variable name="my_variable_extra">
<value>my_value_extra</value>
</variable>
</variables>
</rougail>
```
@ -65,11 +65,11 @@ Nous créons un dictionnaire complémentaire pour ajouter notre template /srv/ro
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<services>
<service name="example">
<file name="/etc/example.conf"/>
</service>
</services>
<services>
<service name="example">
<file name="/etc/example.conf"/>
</service>
</services>
</rougail>
```
@ -163,11 +163,11 @@ Nous créons un dictionnaire complémentaire pour ajouter un calcul à la variab
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<constraints>
<fill name="return_no">
<target>my_variable</target>
</fill>
</constraints>
<constraints>
<fill name="return_no">
<target>my_variable</target>
</fill>
</constraints>
</rougail>
```

View File

@ -0,0 +1,13 @@
# Convention de rédaction d'un dictionnaire
## Ordonnancement du dictionnaire
L'ordre des informations mise dans le dictionnaire est idéalement :
- services
- variables
- constraintes
## Le nom d'espace
Le nom d'espace dans un dictionnaire est de deux espaces.

View File

@ -7,11 +7,11 @@ Par exemple :
```
<variable name='varname' multi="True">
<value>val1</value>
<value>val2</value>
<value>val1</value>
<value>val2</value>
</variable>
<family name="my_dyn_family_" dynamic="varname" description="Describe ">
<variable name="my_dyn_var_"/>
<variable name="my_dyn_var_"/>
</family>
```

View File

@ -35,11 +35,11 @@ Voici un exemple de définition d'une variable meneuse et de deux variables mene
```
<variables>
<family name="family" leadership='True'>
<variable name="leader" multi='True'/>
<variable name="follower1"/>
<variable name="follower2" multi='True'/>
</family>
<family name="family" leadership='True'>
<variable name="leader" multi='True'/>
<variable name="follower1"/>
<variable name="follower2" multi='True'/>
</family>
</variables>
```
@ -49,8 +49,8 @@ Pour ajouter, dans un nouveau dictionnaire, une variable suiveuse à notre group
```
<variables>
<family name="family">
<variable name="follower3"/>
</family>
<family name="family">
<variable name="follower3"/>
</family>
</variables>
```

View File

@ -12,7 +12,7 @@ Cette famille doit être placé dans une balise [variables](../variables.md) :
```
<variables>
<family name="my_family"/>
<family name="my_family"/>
</variables>
```
@ -20,9 +20,9 @@ Ou dans une autre famille :
```
<variables>
<family name="my_family">
<family name="second_family"/>
</family>
<family name="my_family">
<family name="second_family"/>
</family>
</variables>
```

View File

@ -4,3 +4,4 @@ Une variable calculée est une variable donc sa valeur est le résultat d'une fo
- [Valeur calculée de la variable](value.md)
- [Réfinition](redefine.md)
- [Exemples de calcule](examples.md)

48
doc/fill/examples.md Normal file
View File

@ -0,0 +1,48 @@
# Exemples de calcule
## Calculer les noms de modèle à généré à partir d'une variable
Créeons deux variables multiples, une pour accueillir la liste des éléments du nom variable (ici `zones_list`), la seconde étant le nom du fichier calculé (ici `netwokd_configurations`) :
```
<variables>
<variable name="zones_list" type="string" multi="True">
<value>zone1</value>
<value>zone2</value>
<value>zone3</value>
</variable>
<variable name="netwokd_configurations" type="filename" multi="True" hidden="True"/>
</variables>
```
Calculons la valeur de la seconde variable à partir de la première :
```
<constraints>
<fill name="calc_value">
<param>/systemd/network/10-</param>
<param type="variable">zones_list</param>
<param>-risotto.network</param>
<param name="join"></param>
<param name="multi" type="boolean">True</param>
<target>netwokd_configurations</target>
</fill>
</constraints>
```
Le contenu de la variable `netwokd_configurations` sera alors :
- /systemd/netword/10-zone1/risotto.network
- /systemd/netword/10-zone2/risotto.network
- /systemd/netword/10-zone3/risotto.network
Enfin déclarer une balise file en utilisant ces deux variables :
```
<services>
<service name="systemd-networkd">
<file file_type="variable" source="network" variable="zones_list">netwokd_configurations</file>
</service>
</services>
```

View File

@ -6,12 +6,12 @@ Créons une variable dont la valeur est retournée par la fonction "return_no" :
```
<variables>
<variable name="my_calculated_variable"/>
<variable name="my_calculated_variable"/>
</variables>
<constraints>
<fill name="return_no">
<target>my_calculated_variable</target>
</fill>
<fill name="return_no">
<target>my_calculated_variable</target>
</fill>
</constraints>
```
@ -30,7 +30,7 @@ Attention, si une valeur par défaut est définit dans la variable "my_calculate
```
<variable name="my_calculated_variable">
<value>yes</value>
<value>yes</value>
</variable>
```
Cette valeur par défaut sera complètement ignorée. C'est le calcul qui en définira la valeur.
@ -59,24 +59,24 @@ Il est également possible de calculer [une variable d'une famille dynamique](..
```
<variables>
<variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
<value>val1</value>
<value>val2</value>
<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"/>
<value>val</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"/>
<value>val</value>
</variable>
</family>
</family>
</variables>
<constraints>
<fill name="return_value">
<param type="variable">my_variable</param>
<target>my_calculated_variable_dyn_</target>
</fill>
<fill name="return_value">
<param type="variable">my_variable</param>
<target>my_calculated_variable_dyn_</target>
</fill>
</constraints>
```
@ -90,11 +90,11 @@ 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>
<fill name="return_value_suffix">
<param type="variable">my_variable</param>
<param type="suffix"/>
<target>my_calculated_variable_dyn_</target>
</fill>
</constraints>
```

View File

@ -11,9 +11,9 @@ Il faut, à la création du service, préciser son nom :
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<services>
<service name="squid"/>
</services>
<services>
<service name="squid"/>
</services>
</rougail>
```
@ -69,7 +69,7 @@ Il est possible de désactiver un service. Pour cela il faut rajouter l'attribut
```
<services>
<service name="test" disabled="True"/>
<service name="test" disabled="True"/>
</services>
```
@ -79,17 +79,17 @@ Il est possible de définir une [condition](../condition/README.md) de type "dis
```
<services>
<service name="test" servicelist="test">
</service>
<service name="test" servicelist="test">
</service>
</services>
<variables>
<variable name="condition" type="boolean"/>
<variable name="condition" type="boolean"/>
</variables>
<constraints>
<condition name="disabled_if_in" source="condition">
<param>False</param>
<target type="servicelist">test</target>
</condition>
<condition name="disabled_if_in" source="condition">
<param>False</param>
<target type="servicelist">test</target>
</condition>
</constraints>
```

View File

@ -10,9 +10,9 @@ Il est nécessaire, au minimum, de spécifier le chemin complet du fichier :
```
<services>
<service name="squid">
<file>/etc/squid/squid.conf</file>
</service>
<service name="squid">
<file>/etc/squid/squid.conf</file>
</service>
</services>
```
@ -30,14 +30,14 @@ Il est possible également de définir le nom du fichier dans une variable :
```
<services>
<service name="squid">
<file file_type="variable" source="squid.conf">my_variable</file>
</service>
<service name="squid">
<file file_type="variable" source="squid.conf">my_variable</file>
</service>
</services>
<variables>
<variable name="my_variable">
<value>/etc/squid/squid.conf</value>
</variable>
<variable name="my_variable">
<value>/etc/squid/squid.conf</value>
</variable>
</variables>
```
@ -49,15 +49,15 @@ Il est même possible de définir une variable de type multiple, ce qui génère
```
<services>
<service name="squid">
<file file_type="variable" source="squid.conf">my_variable</file>
</service>
<service name="squid">
<file file_type="variable" source="squid.conf">my_variable</file>
</service>
</services>
<variables>
<variable name="my_variable" multi="True">
<value>/etc/squid1/squid.conf</value>
<value>/etc/squid2/squid.conf</value>
</variable>
<variable name="my_variable" multi="True">
<value>/etc/squid1/squid.conf</value>
<value>/etc/squid2/squid.conf</value>
</variable>
</variables>
```
@ -73,19 +73,19 @@ En effet, il est possible de passer le contenu d'une variable au template :
```
<services>
<service name="squid">
<file file_type="variable" source="squid.conf" variable="my_variable2">my_variable1</file>
</service>
<service name="squid">
<file file_type="variable" source="squid.conf" variable="my_variable2">my_variable1</file>
</service>
</services>
<variables>
<variable name="my_variable1" multi="True">
<value>/etc/squid1/squid.conf</value>
<value>/etc/squid2/squid.conf</value>
</variable>
<variable name="my_variable2" multi="True">
<value>squid1</value>
<value>squid2</value>
</variable>
<variable name="my_variable1" multi="True">
<value>/etc/squid1/squid.conf</value>
<value>/etc/squid2/squid.conf</value>
</variable>
<variable name="my_variable2" multi="True">
<value>squid1</value>
<value>squid2</value>
</variable>
</variables>
```
@ -117,18 +117,18 @@ Il est aussi possible de définir une [condition](../condition/README.md) de typ
```
<services>
<service name="test">
<file filelist="squid">/etc/squid/squid.conf</file>
</service>
<service name="test">
<file filelist="squid">/etc/squid/squid.conf</file>
</service>
</services>
<variables>
<variable name="condition" type="boolean"/>
<variable name="condition" type="boolean"/>
</variables>
<constraints>
<condition name="disabled_if_in" source="condition">
<param>False</param>
<target type="filelist">squid</target>
</condition>
<condition name="disabled_if_in" source="condition">
<param>False</param>
<target type="filelist">squid</target>
</condition>
</constraints>
```

View File

@ -28,19 +28,19 @@ Il est possible de définir une [condition](../condition/README.md) de type "dis
```
<services>
<service name="test">
<ip iplist="test_ip">variable_ip</ip>
</service>
<service name="test">
<ip iplist="test_ip">variable_ip</ip>
</service>
</services>
<variables>
<variable name="condition" type="boolean"/>
<variable name="variable_ip" type="ip"/>
<variable name="condition" type="boolean"/>
<variable name="variable_ip" type="ip"/>
</variables>
<constraints>
<condition name="disabled_if_in" source="condition">
<param>False</param>
<target type="iplist">test_ip</target>
</condition>
<condition name="disabled_if_in" source="condition">
<param>False</param>
<target type="iplist">test_ip</target>
</condition>
</constraints>
```

View File

@ -10,9 +10,9 @@ Il suffit d'avoir un template dont le nom est par défaut le nom du service avec
```
<services>
<service name="squid">
<override/>
</service>
<service name="squid">
<override/>
</service>
</services>
```

View File

@ -7,7 +7,7 @@ Il est placé à la racine du dictionnaire :
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<services/>
<services/>
</rougail>
```

View File

@ -8,10 +8,10 @@ Une variable est déjà un nom. C'est à dire qu'on pourra utiliser plus tard la
```
<variables>
<variable name="my_variable"/>
<family name="my_family">
<variable name="my_family_variable"/>
</variable>
<variable name="my_variable"/>
<family name="my_family">
<variable name="my_family_variable"/>
</variable>
</variables>
```
@ -123,7 +123,7 @@ Il est possible de fixer les valeurs par défaut d'une variable :
```
<variable name="my_variable">
<value>value</value>
<value>value</value>
</variable>
```
@ -131,8 +131,8 @@ 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>
<value>value 1</value>
<value>value 2</value>
</variable>
```
@ -152,7 +152,9 @@ Attention trois attributs ne sont redéfinisable :
Créons notre variable :
<variable name="my_variable"/>
```
<variable name="my_variable"/>
```
Et redéfinisons là :
@ -186,7 +188,7 @@ Voici une variable a valeur automatiquement modifiée :
```
<variable name="my_variable" auto_save="True">
<value>my_value</value>
<value>my_value</value>
</variable>
```
@ -205,7 +207,7 @@ Voici un variable à valeur en lecture seule automatique :
```
<variable name="server_deployed" type="boolean">
<value>False</value>
<value>False</value>
</variable>
<variable name="my_variable" auto_freeze="True"/>
```

View File

@ -6,9 +6,9 @@ Il est possible d'imposer une liste de valeur pour une variable particulière :
```
<variable name="my_variable" type="choice">
<choice>val1</choice>
<choice>val2</choice>
<choice>val3</choice>
<choice>val1</choice>
<choice>val2</choice>
<choice>val3</choice>
</variable>
```
@ -19,10 +19,10 @@ Si la variable est obligatoire ou si une valeur est précisée (la variable pass
```
<variable name="my_variable" type="choice">
<choice>val1</choice>
<choice>val2</choice>
<choice>val3</choice>
<value>val1</value>
<choice>val1</choice>
<choice>val2</choice>
<choice>val3</choice>
<value>val1</value>
</variable>
```
@ -32,11 +32,11 @@ Par défaut les choix sont de type "string". Il est possible de préciser des no
```
<variable name="my_variable" type="choice">
<choice>val1</choice>
<choice type="string">val2</choice>
<choice type="number">3</choice>
<choice type="boolean">True</choice>
<choice type="nil"/>
<choice>val1</choice>
<choice type="string">val2</choice>
<choice type="number">3</choice>
<choice type="boolean">True</choice>
<choice type="nil"/>
</variable>
```
@ -48,7 +48,7 @@ Pour ajouter un choix à une variable à choix existante, rien de plus simple, j
```
<variable name="my_variable" redefine="True">
<choice>val4</choice>
<choice>val4</choice>
</variable>
```
@ -58,8 +58,8 @@ Si on veut supprimer un choix ou redéfinir complètement la liste, il faut red
```
<variable name="my_variable" redefine="True" remove_choice="True">
<choice>val1</choice>
<choice>val2</choice>
<choice>val1</choice>
<choice>val2</choice>
</variable>
```
@ -71,7 +71,7 @@ Une variable à valeur multiple peut servir de source des choix :
```
<variable name="my_variable" type="choice">
<choice type="variable">other_variable</choice>
<choice type="variable">other_variable</choice>
</variable>
```
@ -82,10 +82,10 @@ Seul un choice de type "variable" est possible par variable.
```
<variable name="my_variable" type="choice">
<choice type="function" name="trange">
<param type="number">0</param>
<param type="number">10</param>
</choice>
<value type="number">9</value>
<choice type="function" name="trange">
<param type="number">0</param>
<param type="number">10</param>
</choice>
<value type="number">9</value>
</variable>
```

View File

@ -33,17 +33,17 @@ Voici un exemple de définition d'une variable meneuse et de deux variables mene
```
<variables>
<family name="family">
<variable name="leader" multi='True'/>
<variable name="follower1"/>
<variable name="follower2" multi='True'/>
</family>
<family name="family">
<variable name="leader" multi='True'/>
<variable name="follower1"/>
<variable name="follower2" multi='True'/>
</family>
</variables>
<constraints>
<group leader="leader">
<follower>follower1</follower>
<follower>follower2</follower>
</group>
<group leader="leader">
<follower>follower1</follower>
<follower>follower2</follower>
</group>
</constraints>
```
@ -53,10 +53,10 @@ Il est possible d'en définit d'autres :
```
<constraints>
<group leader="leader" name="leadership" description="My leadership">
<follower>follower1</follower>
<follower>follower2</follower>
</group>
<group leader="leader" name="leadership" description="My leadership">
<follower>follower1</follower>
<follower>follower2</follower>
</group>
</constraints>
```
@ -66,17 +66,17 @@ Voici un exemple de définition d'une variable meneuse et de deux variables mene
```
<variables>
<family name="family">
<variable name="leader" multi='True'/>
<variable name="follower1"/>
<variable name="follower2" multi='True'/>
</family>
<family name="family">
<variable name="leader" multi='True'/>
<variable name="follower1"/>
<variable name="follower2" multi='True'/>
</family>
</variables>
<constraints>
<group leader="example.family.leader">
<follower>follower1</follower>
<follower>follower2</follower>
</group>
<group leader="example.family.leader">
<follower>follower1</follower>
<follower>follower2</follower>
</group>
</constraints>
```
@ -90,13 +90,13 @@ Pour ajouter, dans un nouveau dictionnaire, une variable suiveuse à notre group
```
<variables>
<family name="family">
<variable name="follower3"/>
</family>
<family name="family">
<variable name="follower3"/>
</family>
</variables>
<constraints>
<group leader="leader">
<follower>follower3</follower>
</group>
<group leader="leader">
<follower>follower3</follower>
</group>
</constraints>
```

View File

@ -7,6 +7,6 @@ Il est placé à la racine du dictionnaire :
```
<?xml version='1.0' encoding='UTF-8'?>
<rougail>
<variables/>
<variables/>
</rougail>
```