247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
---
|
|
gitea: none
|
|
include_toc: true
|
|
---
|
|
|
|
# Variable
|
|
|
|
## Synopsis
|
|
|
|
Une variable est un conteneur qui contiendra une ou plusieurs valeurs.
|
|
|
|
## Paramètres
|
|
|
|
| Paramètre | Commentaires |
|
|
|-----------|--------------|
|
|
| **name**<br/>`string`<br/>`mandatory` | Nom de la variable.<br/>C'est avec ce nom qu'on va pouvoir interagir avec la variable.<br/>Il est préférable de suivre la [convention sur les noms de variable](convention.md). |
|
|
| **type**<br/>`string` | Type de la variable.<br/>Ce type définit la validation par défaut de la variable<br/>**Valeur par défaut :** string |
|
|
| **params**<br/>`list` | Liste de paramètre permettant d'adapté la validation de type. |
|
|
| **description**<br/>`string` | La description de la variable.<br/>Information utilisateur permettant de comprendre l'utilité de la variable.<br/>**Valeur par défaut :** le nom |
|
|
| **help**<br/>`string` | Aide complémentaire associée à la variable. |
|
|
| **default** | Valeur(s) par défaut de la variable.<br/>Cette valeur est typée, il faut remplir correctement le fichier YAML pour ne pas définir une valeur avec un type incorrect. Par exemple, un "number" doit êre un chiffre, une variable multiple doit être une liste, ...<br/>Pour une variable multiple non [meneuse](../family/leadership.md), la première valeur défini dans la liste sera également la valeur par défaut proposée si on ajoute une nouvelle valeur à cette variable. |
|
|
| **validators**<br/>`list` | Validateurs de valeur.<br/>. Liste de template Jinja. La valeur de la variable sera considérée comme invalide si le template retourne quelque chose. |
|
|
| **auto_save**<br/>`boolean` | Variable à valeur automatiquement modifiée.<br/>Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considérée comme modifiée (ce n'est plus une valeur par défaut).<br/>Par exemple, si la valeur de cette variable est issue d'un calcul, la valeur ne sera plus recalculée.<br/>Ces variables sont généralement des variables obligatoires. En effet ces variables ne sont automatiquement modifiées que si elles ont une valeurs.<br/>Une [variable meneuse ou suiveuse](../family/leadership.md) ne peut pas avoir la propriété `auto_save`. |
|
|
| **mode**<br/>`string` | Mode de la variable.<br/>**Valeur par défaut :** Le mode par défaut d'une variable est le mode de la famille parente.<br/>Cas particuliers :<br/>- une variable à valeur automatiquement modifiée ou une variable en lecture seule automatique est par défaut en mode "basic"<br/>- si la variable n'est pas dans une famille, la variable aura le mode "normal" par défaut<br/>- une variable obligatoire sans valeur par défaut (calculer ou non) aura le mode "basic" |
|
|
| **muli**<br/>`boolean` | La variable a pour valeur une liste. **Valeur par défaut** : false |
|
|
| **unique**<br/>`boolean` | La variable multiple accepte plusieurs fois la même valeur. Si unique est à `false` une variable multiple n'accepte qu'une seule fois la même valeur dans la liste. **Valeur par défaut :** false |
|
|
| **hidden**<br/>`boolean` ou [`calcul`](../condition/README.md) | Variable invisible.<br/>Permet de cacher une variable.<br/>Cela signifie que la variable ne sera plus visible en lecture écriture, mais uniquement pour des calculs ou en mode lecture seule.<br/>Lorsqu'on rend invisible une variable l'utilisateur ne pourra pas modifier sa valeur, il s'il a déjà réussi à la modifier, cette valeur ne sera pas prise en compte. **Valeur par défaut :** false |
|
|
| **disabled**<br/>`boolean` ou [`calcul`](../condition/README.md) | Variable désactivée.<br/>Permet de désactiver une variable.<br/>Cela signifie que la variable ne sera plus visible pour l'utilisateur mais également pour un calcul. **Valeur par défaut :** false |
|
|
| **mandatory**<br/>`boolean` ou [`calcul`](../condition/README.md) | Variable obligatoire.<br/>Variable dont une valeur est requise.<br/>Pour une variable multiple, cela signifie que la liste ne doit pas être vide.<br/>📝 Une variable avec une valeur par défaut non calculée ou de type "boolean" sont automatiquement considéré comme obligatoire, si ce n'est pas le comportement voulu, il mettre le préciser comme cela : "mandatory: false". **Valeur par défaut :** false |
|
|
| **redefine**<br/>`boolean` | Il est possible de définir une variable dans un dictionnaire et de changer son comportement dans une second dictionnaire. Dans ce cas il faut explicitement redéfinir la variable. **Valeur par défaut :** false|
|
|
| **exists**<br/>`boolean` | Cette attribut permet deux choses :<br/>- créer une variable si elle n'existe pas dans un autre dictionnaire (sinon ne rien faire), dans ce cas la valeur de l'attribut doit être `true`<br/>- en conjonction avec l'attribut redefine à la valeur true, ne modifie le comportement si elle est préexistante, dans ce cas la valeur de l'attribut doit être `false`.<br/>**Valeur par défaut :** null |
|
|
| **test**<br/>`list` | L'attribut "test" est un attribut spécial qui permet aux concepteurs d'un dictionnaire d'influencer un robot de test en précisant de valeurs utiles à tester.<br/>Concrêtement, le contenu de cet attribut est enregister dans une "information" de l'option Tiramisu correspondante. |
|
|
|
|
## Les types des variables
|
|
|
|
Une variable a un type.
|
|
|
|
Ce type permet de définir les valeurs acceptées par cette variable.
|
|
|
|
| valeur | Commentaires | Paramètres | Exemples |
|
|
|--------|--------------|------------|----------|
|
|
| string | chaine de caractère (type par défaut) | | test<br/>"1"<br/>"true" |
|
|
| number | un nombre | `min_number` : nombre minimum autorisé<br/>`max_number` : nombre maximal autorisé | 1 |
|
|
| float | un chiffre flottant | | 1.2 |
|
|
| boolean | Un booléen, si aucune valeur n'est défini la valeur par défaut de cette variable sera "true", la variable sera également obligatoire par défaut | | true<br/>false |
|
|
| secret | un secret (comme un mot de passe, une clef privée, ...) | | hO_'hi |
|
|
| mail | une adresse mail | | test@rougail.example |
|
|
| filename | nom de fichier au sens Unix | | /etc/passwd |
|
|
| date | une date au format "%Y-%m-%d" | | 2021-01-30
|
|
| unix\_user | nom d'utilisateur au sens Unix | | test |
|
|
| ip | n'importe quelle adresse IPv4 | `private_only` : seule des IP privée (false par défaut)<br/>`allow_reserved` : autorise les IP réservées (true par défaut) | 1.2.3.4 |
|
|
| cidr | n'importe quelle adresse IPv4 au format CIDR | `private_only` : seule des IP privée (false par défaut) `allow_reserved` : autorise les IP réservées (false par défaut) | 1.2.3.4/24 |
|
|
| netmask | masque d'une adresse IPv4 | | 255.255.255.0 |
|
|
| network | adresse réseau | | 192.168.1.0 |
|
|
| network\_cidr | adresse réseau au format CIDR | | 192.168.1.0/24 |
|
|
| broadcast | adresse de diffusion | | 255.255.255.255 |
|
|
| netbios | nom netbios | | machine |
|
|
| domainname | nom de domaine | `allow_ip` : autorise une IP plutôt qu'un nom de domaine (false par défaut)<br/>`allow_cidr_network` : autorise une adresse réseau de type CIDR (false par défaut)<br/>`allow_without_dot` : autorise les noms sans point (false par défault)<br/>`allow_startswith_dot` : autorise de commencer par un point (false par défault) | rougail.example |
|
|
| hostname | nom d'hôte | `allow_ip` : autorise une IP plutôt qu'un nom de domaine (false par défaut) | machine |
|
|
| web\_address | adresse web | `allow_ip` : autorise une IP plutôt qu'un nom de domaine (false par défaut)<br/>`allow_without_dot` : autorise les noms sans point (true par défault) | http://rougail.example |
|
|
| port | port | `allow_range` : autorise un interval de port, par exemple 80:85 (false par défaut)<br/>`allow_zero` : autorise le port 0 (false par défaut)<br/>`allow_wellknown` : autorise les ports de 1 à 1023 (true par défaut)<br/>`allow_registred` : autorise les ports de 1024 à 49151 (true par défaut) `allow_private` : autorise les ports supérieurs à 49152 (true par défaut)<br/>`allow_protocol` : autorise l'ajout du protocole, par exemple tcp:80 (false par défaut) | 8080 |
|
|
| mac | adresse MAC | | 11:11:11:11:11:11 |
|
|
| unix\_permissions | droit d'accès au fichier, répertoire, ... | | 644 |
|
|
| choice | variable à choix | | |
|
|
|
|
## Les modes des variables
|
|
|
|
Par défault, il existe trois "mode" dans Rougail :
|
|
|
|
- basic : variables indispensables à la mise en place d'un service
|
|
- normal : variables couramment modifié par l'utilisateur
|
|
- expert : variables a manipuler avec précausion et en toutes connaissances de cause
|
|
|
|
Il est possible de personnaliser les modes dans la [configuration de rougail](../dev/config.md)
|
|
|
|
## Exemples
|
|
|
|
### Quelques variables de base
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
type: string
|
|
description: This is a good variable
|
|
help: This is the help of a good variable
|
|
default: value
|
|
my_variable_multi_1:
|
|
multi: true
|
|
default:
|
|
- value
|
|
my_variable_multi_2:
|
|
multi: true
|
|
default:
|
|
- value1
|
|
- value2
|
|
version: '1.0'
|
|
my_variable_multi_not_unique:
|
|
multi: true
|
|
unique: false
|
|
default:
|
|
- value1
|
|
- value2
|
|
- value2
|
|
```
|
|
|
|
### Redéfinition d'une variable
|
|
|
|
Créons notre variable :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
type: string
|
|
```
|
|
|
|
Et redéfinisons là :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
redefine: true
|
|
description: New description
|
|
```
|
|
|
|
### Créer une variable inexistante
|
|
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
exists: false
|
|
```
|
|
|
|
## 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à :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
exists: true
|
|
hidden: true
|
|
```
|
|
|
|
Dans ce cas la variable ne sera pas créé mais uniquement cachée si elle existe déjà.
|
|
|
|
## Une variable à choix
|
|
|
|
Il est possible d'imposer une liste de valeur pour une variable particulière :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
type: choice
|
|
choices:
|
|
- val1
|
|
- val2
|
|
- val3
|
|
```
|
|
|
|
Dans ce cas, seules les valeurs proposées sont possibles pour cette variable.
|
|
Cette variable n'est pas obligatoire donc il est possible de mettre la valeur "None".
|
|
|
|
Si la variable est obligatoire ou si une valeur est précisée (la variable passe obligatoire) alors la valeur "None" n'est plus autorisé :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
type: choice
|
|
choices:
|
|
- val1
|
|
- val2
|
|
- val3
|
|
default: val1
|
|
```
|
|
|
|
Une variable à choix est typée :
|
|
|
|
Les choix sont typés :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
type: choice
|
|
choices:
|
|
- val1
|
|
- 3
|
|
- true
|
|
default: val1
|
|
```
|
|
|
|
dans ce cas, le chiffre 3 est autorisé mais pas la chaine de caractère "3".
|
|
|
|
## Un variable à choix provenant de variable
|
|
|
|
Les choix d'une variable peuvent provenir d'une autre variable multiple :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
source_variable:
|
|
multi: true
|
|
default:
|
|
- val1
|
|
- val2
|
|
my_variable:
|
|
type: choice
|
|
choices:
|
|
type: variable
|
|
variable: rougail.source_variable
|
|
```
|
|
|
|
Dans ce cas, toutes les valeurs de la variable ou des variables seront des choix utilisables par l'utilisateur.
|
|
|
|
## Un variable à choix provenant d'un template Jinja
|
|
|
|
Faisons d'abord une fonction `trange` dans le fichier functions.py :
|
|
|
|
```python
|
|
def trange(min, max):
|
|
return range(min, max)
|
|
```
|
|
|
|
On va récupérer ici les valeurs de 0 à 9 :
|
|
|
|
```yml
|
|
---
|
|
version: '1.0'
|
|
my_variable:
|
|
type: choice
|
|
default: 9
|
|
choices:
|
|
type: jinja
|
|
jinja: |
|
|
{% for item in trange(0, 10) %}
|
|
{{ item }}
|
|
{%- endfor %}
|
|
return_type: number
|
|
```
|