rougail/doc/variable

Variable

Un variable

Une variable est forcement dans variables ou dans une famille.

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

<variables>
  <variable name="my_variable"/>
  <family name="my_family">
    <variable name="my_family_variable"/>
  </variable>
</variables>

En YAML :

variables:
- variable:
    name: my_variable
- family:
    name: my_family
    variables:
    - variable:
        name: my_family_variable

Description et aide sur la variable

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

<variable name="my_variable" description="This is a good variable"/>

En YAML :

variables:
- variable:
    name: my_variable
    description: This is a good variable

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

<variable name="my_variable" help="This is a good variable"/>

En YAML :

variables:
- variable:
    name: my_variable
    help: This is a good variable

Cette aide peut être utilisé à tout moment comme valeur d'un paramètre.

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 (ou password mais est obsolète) : 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
• domain : nom de domaine
• hostname : nom d'hôte
• web_address : adresse web (http://www.cadoles.com/)
• port : port
• mac : adresse MAC
• schedule : périodicité du schedule, les valeurs possibles sont "none", "daily", "weekly" ou "monthly"
• schedulemod : type de schedule, les valeurs possibles sont "pre" ou "post"

Pour définir le type d'une variable :

<variable name="my_variable" type="number"/>

En YAML :

- variable:
    name: my_variable
    type: number

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 :

<variable name="my_variable" multi="True"/>

En YAML :

- variable:
    name: 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" :

<variable name="my_variable" multi="True" unique="False"/>

En YAML :

- variable:
    name: my_variable
    multi: true
    unique: false

Variable invisible

Il est possible de cacher une variable.

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

Pour cacher une variable :

<variable name="my_variable" hidden="True"/>

En YAML :

- variable:
    name: my_variable
    hidden: true

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

Pour désactiver une variable :

<variable name="my_variable" disabled="True"/>

En YAML :

- variable:
    name: my_variable
    disabled: true

Variable obligatoire

Variable dont une valeur est requise :

<variable name="my_variable" mandatory="True"/>

En YAML :

- variable:
    name: my_variable
    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 :

<variable name="my_variable" type="boolean" mandatory="False"/>

En YAML :

- variable:
    name: my_variable
    type: boolean
    mandatory: false

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

Valeur par défaut d'une variable

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

<variable name="my_variable">
  <value>value</value>
</variable>

En YAML :

- variable:
    name: my_variable
    value:
    - text: value

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>
</variable>

En YAML :

- variable:
    name: my_variable
    multi: true
    value:
    - text: value 1
    - text: value 2

Si la variable n'est pas pas une variable meneuse, 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.

Redéfinir une variable

Il est possible de définir une variable dans un dictionnaire et de changer son comportement dans une second dictionnaire.

Attention trois attributs ne sont redéfinisable :

• name
• type
• multi

Créons notre variable :

<variable name="my_variable"/>

En YAML :

- variable:
    name: my_variable

Et redéfinisons là :

<variable name="my_variable" redefine="True" description="New description"/>

En YAML :

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

<variable name="my_variable" exists="False"/>

En YAML :

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

<variable name="my_variable" redefine="True" exists="True" hidden="True"/>

En YAML :

- variable:
    name: my_variable
    exists: true
    hidden: true

Variable à valeur automatiquement modifiée

Une variable avec valeur automatiquement modifiée est une variable dont la valeur sera considéré comme modifié quand la propriété global "force_store_value" de Tiramisu est mise.

Voici une variable a valeur automatiquement modifiée :

<variable name="my_variable" auto_save="True">
  <value>my_value</value>
</variable>

En YAML :

- variable:
    name: my_variable
    auto_save: true
    value:
    - text: 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 ne peut pas avoir la propriété auto_save.

Variable à valeur en lecture seule automatique

Une variable avec valeur en lecture seule automatique est une variable dont la valeur ne sera plus modifiable par l'utilisateur quand la variable "server_deployed" passe à "True".

Voici un variable à valeur en lecture seule automatique :

<variable name="server_deployed" type="boolean">
  <value>False</value>
</variable>
<variable name="my_variable" auto_freeze="True"/>

En YAML :

- variable:
    name: server_deployed
    type: boolean
    value:
    - text: 'False
- variable:
    name: my_variable
    auto_freeze: true

Dans ce cas la valeur est fixée à la valeur actuelle et elle ne sera plus modifiable par l'utilisateur. 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 en lecteur seul que si elles ont une valeurs.

Une variable meneuse ou suiveuse ne peut pas avoir la propriété auto_freeze.

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 :

<variable name="my_variable" test="yes"/>

En YAML :

- variable:
    name: my_variable
    test: yes

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

<variable name="my_variable" test="yes|no"/>

En YAML :

- variable:
    name: my_variable
    test: yes|no

Cette valeur peut être utilisé à tout moment comme valeur d'un paramètre.

Mode de la variable

Le mode par défaut d'une variable correspond au mode de la famille.

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 :

<variable name="my_variable" mode="expert"/>

En YAML :

- variable:
    name: my_variable
    mode: expert

Les variables qui fournissent des valeurs

Il peut être intéressant de retrouver facilement des variables sans connaitre le chemin complet mais en utilisant le contenu du paramètre "provider". C'est particulièrement utile si un service peut être fournit par plusieurs services. Les variables n'auront donc pas le même nom. Utiliser ce paramètre, permet donc de retrouver facilement la variable.

Pour déclarer :

<variable name="my_variable" provider="my_function"/>

En YAML :

- variable:
    name: my_variable
    provider: my_variable

Dans le code de l'application, on pourra retrouver le chemin de la variable en faisant :

print(await config.information.get('provider:my_function'))

Pour les variables inclusent dans une famille dynamique, le chemin de la variable sera un template comme ceci "rougail.family_{suffix}.my_variable_{suffix}". Il vous suffit de remplacer "{suffix}" par le suffix voulu de la famille dynamique.