History

Emmanuel Garette d8d3f89fd6 feat: new format 1.0		2023-12-16 19:22:52 +01:00
..
README.md	feat: new format 1.0	2023-12-16 19:22:52 +01:00

README.md

Table of Contents

Variable

Synopsis
Paramètres
Les types des variables
Les modes des variables
Exemples

Quelques variables de base
Redéfinition d'une variable
Créer une variable inexistante

Redéfinir une variable si elle existe
Une variable à choix
Un variable à choix provenant de variable
Un variable à choix provenant d'un template Jinja

Variable

Synopsis

Une variable est un conteneur qui contiendra une ou plusieurs valeurs.

Paramètres

Paramètre	Commentaires
name `string` `mandatory`	Nom de la variable. C'est avec ce nom qu'on va pouvoir interagir avec la variable. Il est préférable de suivre la convention sur les noms de variable.
type `string`	Type de la variable. Ce type définit la validation par défaut de la variable Valeur par défaut : string
params `list`	Liste de paramètre permettant d'adapté la validation de type.
description `string`	La description de la variable. Information utilisateur permettant de comprendre l'utilité de la variable. Valeur par défaut : le nom
help `string`	Aide complémentaire associée à la variable.
default	Valeur(s) par défaut de la variable. 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, ... Pour une variable multiple non meneuse, 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 `list`	Validateurs de valeur. . Liste de template Jinja. La valeur de la variable sera considérée comme invalide si le template retourne quelque chose.
auto_save `boolean`	Variable à valeur automatiquement modifiée. 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). 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 variables ne sont automatiquement modifiées que si elles ont une valeurs. Une variable meneuse ou suiveuse ne peut pas avoir la propriété `auto_save`.
mode `string`	Mode de la variable. Valeur par défaut : Le mode par défaut d'une variable est le mode de la famille parente. Cas particuliers : - une variable à valeur automatiquement modifiée ou une variable en lecture seule automatique est par défaut en mode "basic" - si la variable n'est pas dans une famille, la variable aura le mode "normal" par défaut - une variable obligatoire sans valeur par défaut (calculer ou non) aura le mode "basic"
muli `boolean`	La variable a pour valeur une liste. Valeur par défaut : false
unique `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 `boolean` ou `calcul`	Variable invisible. Permet de cacher une variable. Cela signifie que la variable ne sera plus visible en lecture écriture, mais uniquement pour des calculs ou en mode lecture seule. 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 `boolean` ou `calcul`	Variable désactivée. Permet de désactiver une variable. Cela signifie que la variable ne sera plus visible pour l'utilisateur mais également pour un calcul. Valeur par défaut : false
mandatory `boolean` ou `calcul`	Variable obligatoire. Variable dont une valeur est requise. Pour une variable multiple, cela signifie que la liste ne doit pas être vide. 📝 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 `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 `boolean`	Cette attribut permet deux choses : - 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` - 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`. Valeur par défaut : null
test `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. 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 "1" "true"
number	un nombre	`min_number` : nombre minimum autorisé `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 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) `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) `allow_cidr_network` : autorise une adresse réseau de type CIDR (false par défaut) `allow_without_dot` : autorise les noms sans point (false par défault) `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) `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) `allow_zero` : autorise le port 0 (false par défaut) `allow_wellknown` : autorise les ports de 1 à 1023 (true par défaut) `allow_registred` : autorise les ports de 1024 à 49151 (true par défaut) `allow_private` : autorise les ports supérieurs à 49152 (true par défaut) `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

Exemples

Quelques variables de base

---
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 :

---
version: '1.0'
my_variable:
  type: string

Et redéfinisons là :

---
version: '1.0'
my_variable:
  redefine: true
  description: New description

Créer une variable inexistante

---
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à :

---
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 :

---
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é :

---
version: '1.0'
my_variable:
  type: choice
  choices:
    - val1
    - val2
    - val3
  default: val1

Une variable à choix est typée :

Les choix sont typés :

---
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 :

---
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 :

def trange(min, max):
    return range(min, max)

On va récupérer ici les valeurs de 0 à 9 :

---
version: '1.0'
my_variable:
  type: choice
  default: 9
  choices:
    type: jinja
    jinja: |
      {% for item in trange(0, 10) %}
      {{ item }}
      {%- endfor %}      
    return_type: number