rougail/doc/variable/simple.md

# Variable

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

## Un variable

Une variable est déjà un nom.
C'est à dire qu'on pourra utiliser plus tard la variable via ce nom.

```yml
---
version: '1.0'
my_variable:
```

Il est recommander de n'utiliser que des lettres, chiffres et '\_' dans le nom des variables. Le nom ne pas commencé par le caractère "\_".

## 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 de cette variable sera "True", ces variables sont également obligatoire par défaut
- secret : un secret (comme un mot de passe, une clef privée, ...)
- 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
- domainname : nom de domaine
- hostname : nom d'hôte
- web_address : adresse web (http://www.silique.fr/)
- port : port
- mac : adresse MAC
- unix_permissions : droit d'accès au fichier, répertoire, ...
- [choix](choice.md)

Pour définir le type d'une variable :

```yml
---
version: '1.0'
my_variable:
  type: number
```

Dans certain ce cas, il n'est pas possible de distinger une variable d'une famille. Le type est donc obligatoire.
Il faudra dans ce cas mettre le type par défaut :

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

## Description et aide sur la variable

En plus d'un nom et du type, 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 :

```yml
---
version: '1.0'
my_variable:
  type: string
  description: This is a good variable
```

En plus de la description, il est possible de préciser une aide complémentaire :

```yml
---
version: '1.0'
my_variable:
  type: string
  help: This is a good variable
```

Cette aide peut être utilisé à tout moment comme valeur [d'un paramètre](../param/information.md).

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

```yml
---
version: '1.0'
my_variable:
  multi: true
```

Par défaut, les variables multiples ne peuvent pas avoir deux fois la même valeur.
Si vous voulez pouvoir mettre plusieurs fois la même valeur, il faut utiliser l'attribut `unique` :

```yml
---
version: '1.0'
my_variable:
  multi: true
  unique: false
```

## Les propriétés

### Variable invisible

Il est possible de cacher une variable.

Cacher une variable signifie qu'elle ne sera pas visible lorsqu'on modifie la configuration.
Par contre cette variable sera accessibles lorsqu'on va l'utiliser.

Pour cacher une variable :

```yml
---
version: '1.0'
my_variable:
  type: string
  hidden: true
```

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.

[La valeur de cet attribut peut être fixé par un calcul](../condition/README.md).

### 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 mais également lorsqu'on va l'utiliser.

Pour désactiver une variable :

```yml
---
version: '1.0'
my_variable:
  type: string
  disabled: true
```

[La valeur de cet attribut peut être fixé par un calcul](../condition/README.md).

### Variable obligatoire

Variable dont une valeur est requise :

```yml
---
version: '1.0'
my_variable:
  type: string
  mandatory: true
```

Les variables booléans sont par défaut obligatoire. Pour qu'une variable booléan ne soit pas obligatoire il faut le préciser explicitement :

```yml
---
version: '1.0'
my_variable:
  type: boolean
  mandatory: false
```

Les variables avec une valeur par défaut (non calculée) sont également automatiquement obligatoire.

[La valeur de cet attribut peut être fixé par un calcul](../condition/README.md).

## Valeur par défaut d'une variable

Il est possible de fixer les valeurs par défaut d'une variable :

```yml
---
version: '1.0'
my_variable:
  default: value
```

Pour une variable multiple, la valeur par défaut doit être une liste et il est possible de préciser plusieurs valeurs :

```yml
---
version: '1.0'
my_variable:
  multi: true
  default:
    - value
my_variable:
  multi: true
  default:
    - value1
    - value2
```

Par défaut, les variables multiples ne peuvent pas avoir deux fois la même valeur.
Si vous voulez pouvoir mettre plusieurs fois la même valeur, il faut utiliser l'attribut "unique" :

```yml
---
version: '1.0'
my_variable:
  multi: true
  unique: false
  default:
    - value1
    - value2
    - value2
```

Si la variable n'est pas pas une [variable meneuse](../family/leadership.md), la première valeur défini dans cette liste sera également la valeur par défaut proposé si on ajoute une nouvelle valeur à cette 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.

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

Il est parfois utile de créer une variable si elle n'existe pas dans un autre dictionnaire :

```yml
---
version: '1.0'
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à :

```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à.

## Variable à valeur automatiquement modifiée

Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié par l'utilisateur (ce n'est plus une valeur par défaut).

Voici une variable a valeur automatiquement modifiée :

```yml
---
version: '1.0'
my_variable:
  auto_save: true
  default: my_value
```

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.

Une [variable meneuse ou suiveuse](../family/leadership.md) ne peut pas avoir la propriété `auto_save`.

## Information "test"

L'attribut "test" est un attribut spécial qui permet aux concepteurs d'un dictionnaire d'influancer le robot de test en précisant de valeurs utile à tester.

Concrêtement, le contenu de cet attribut est enregister dans une "information" de l'option Tiramisu correspondante.

Exemple :

```yml
---
version: '1.0'
my_variable:
  test: 'yes'
```

Il est possible de préciser plusieurs valeurs avec le séparateur "|" :

```yml
---
version: '1.0'
my_variable:
  test: 'yes|no'
```

Cette valeur peut être utilisé à tout moment comme valeur [d'un paramètre](../param/information.md).

## Mode de la variable

Le [mode](../mode.md) par défaut d'une variable correspond au [mode](../mode.md) de la [famille](../family/README.md).

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".

Pour définir le [mode](../mode.md) :

```yml
---
version: '1.0'
my_variable:
  type: string
  mode: expert
```