rougail/doc/fill.md

# Les variables calculées

Une variable calculée est une variable donc sa valeur est le résultat d'une fonction python.

## Variable avec une valeur par défaut calculée

Créons une variable dont la valeur est retournée par la fonction "return_no" :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable"/>
    </family>
</variables>
<constraints>
    <fill name="return_no" target="my_calculated_variable"/>
</constraints>
```

Puis créons la fonction "return_no" :

```
def return_no():
    return 'no'
```

Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "no"), elle sera calculée tant que l'utilisateur n'a pas de spécifié une valeur à cette variable.

Si l'utilisateur à définit une valeur par défaut à "my_calculated_variable" :

```
<variable name="my_calculated_variable">
    <value>yes</value>
</variable>
```

Cette valeur par défaut sera complètement ignorée.

## Variable avec une valeur calculée

En ajoutant le paramètre "hidden" à "True" dans la variable précédente, l'utilisateur n'aura plus la possibilité de modifié la valeur. La valeur de la variable sera donc systématiquement calculée :

```
<variable name="my_calculated_variable" hidden="True"/>
```

Si une condition "hidden_if_in" est spécifié à la variable, la valeur sera modifiable par l'utilisateur si elle n'est pas cachée mais elle sera systèmatiquement calculée (même si elle a déjà était modifiée) si la variable est cachée.

## Variable avec valeur calculée obligatoire

Par défaut les variables calculées ne sont pas des varibles obligatoires.
Dans ce cas un calcul peut retourner None, mais surtout un utilisateur peut spécifier une valeur nulle à cette variable. Dans ce cas le calcul ne sera pas réalisé.

## Fonction avec une valeur fixe comme paramètre positionnel

Déclarons un calcul avec paramètre :

```
<constraints>
    <fill name="return_value" target="my_calculated_variable">
        <param>no</param>
    </fill>
</constraints>
```

Créons la fonction correspondante :

```
def return_value(value):
    return value
```

La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "no".

## Paramètre nommée

Déclarons une contrainte avec un paramètre nommée :

```
<constraints>
    <fill name="return_value" target="my_calculated_variable">
        <param name="valeur">no</param>
    </fill>
</constraints>
```

Dans ce cas la fonction return_value sera exécuté avec le paramètre nommé "valeur" dont sa valeur sera "no".

## Paramètre avec un nombre

Déclarons un calcul avec paramètre avec un nombre :

```
<constraints>
    <fill name="return_value_with_number" target="my_calculated_variable">
        <param type="number">1</param>
    </fill>
</constraints>
```

Créons la fonction correspondante :

```
def return_value_with_number(value):
    if value == 1:
        return 'no'
    return 'yes'
```

La variable aura donc "no" comme valeur puisque le paramètre aura la valeur fixe "1".

## Paramètre dont la valeur est issue d'une autre variable

Créons deux variables avec une contrainte de type variable qui contient le nom de la variable dont sa valeur sera utilisé comme paramètre :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable"/>
        <variable name="my_variable" type="number" description="My variable">
            <value>1</value>
        </variable>
    </family>
</variables>
<constraints>
    <fill name="return_value_with_number" target="my_calculated_variable">
        <param type="variable">my_variable</param>
    </fill>
</constraints>
```

Si l'utilisateur laisse la valeur 1 à "my_variable", la valeur par défault de la variable "my_calculated_variable" sera "no".
Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "yes".

## Paramètre dont la valeur est issue d'une information de la configuration

Créons une variable et la contrainte :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable" type="string" description="My calculated variable"/>
    </family>
</variables>
<constraints>
    <fill name="return_value" target="my_calculated_variable">
        <param type="information">server_name</param>
    </fill>
</constraints>
```

Dans ce cas, l'information de la configuration "server_name" sera utilisé comme valeur de la variable "my_calculated_variable".
Si l'information n'existe pas, la paramètre aura la valeur "None".

## Paramètre avec variable potentiellement non existante

Suivant le contexte une variable peut exister ou ne pas exister.

Un paramètre de type "variable" peut être "optional" :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable"/>
    </family>
</variables>
<constraints>
    <fill name="return_value" target="my_calculated_variable">
        <param type="variable" optional="True">unknow_variable</param>
    </fill>
</constraints>
```

Dans ce cas la fonction "return_value" est exécuté sans paramètre.

## Paramètre avec variable potentiellement désactivée

FIXME : <!ATTLIST param notraisepropertyerror (True|False) "False">

Il n'y a pas spécialement de test !

## Les variables suiveuses

FIXME : 

- tests/flattener_dicos/10leadership_append/00-base.xml
- tests/flattener_dicos/10leadership_auto/00-base.xml
- tests/flattener_dicos/10leadership_autoleader/00-base.xml
- tests/flattener_dicos/10leadership_autoleader_expert/00-base.xml

## Les variables dynamiques

### Paramètre avec variable dynamique

Il est possible de faire un calcul avec comme paramètre une variable dynamique mais pour une suffix particulier :

```
<variables>
    <family name='family'>
        <variable name='suffixes' type='string' description="Suffixes of dynamic family" multi="True">
            <value>val1</value>
            <value>val2</value>
        </variable>
        <variable name="my_calculated_variable" type="string" description="My calculated variable"/>
    </family>
    <family name='dyn' dynamic="suffixes">
        <variable name='vardyn' type='string' description="Dynamic variable">
            <value>val</value>
        </variable>
    </family>
</variables>
<constraints>
    <fill name="return_value" target="my_calculated_variable">
        <param type="variable">vardynval1</param>
    </fill>
</constraints>
```

Dans ce cas, valeur du paramètre de la fonction "return_value" sera la valeur de la variable "vardyn" avec le suffix "val1".

### Calcule d'une variable dynamique

Il est également possible de calculer une variable dynamique à partir d'une variable standard :

```
<variables>
    <family name='family'>
        <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>
    <family name='dyn' dynamic="suffixes">
        <variable name="my_calculated_variable_dyn_" type="string" description="My calculated variable"/>
            <value>val</value>
        </variable>
    </family>
</variables>
<constraints>
    <fill name="return_value" target="my_calculated_variable_dyn_">
        <param type="variable">my_variable</param>
    </fill>
</constraints>
```

Dans ce cas, les variables dynamiques "my_calculated_variable_dyn_" seront calculés à partir de la valeur de la variable "my_variable".
Que cela soit pour la variable "my_calculated_variable_dyn_val1" et "my_calculated_variable_dyn_val2".

Par contre, il n'est pas possible de faire un calcul pour une seule des deux variables issues de la variable dynamique.
Si c'est ce que vous cherchez à faire, il faudra prévoir un traitement particulier dans votre fonction.

Dans ce cas, il faut explicitement demander la valeur du suffix dans la fonction :

```
<constraints>
    <fill name="return_value_suffix" target="my_calculated_variable_dyn_">
        <param type="variable">my_variable</param>
        <param type="suffix"/>
    </fill>
</constraints>
```

Et ainsi faire un traitement spécifique pour ce suffix :

```
def return_value_suffix(value, suffix):
    if suffix == 'val1':
        return value
```

## Redéfinition des calcules

Dans un premier dictionnaire déclarons notre variable et notre calcule :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable"/>
    </family>
</variables>
<constraints>
    <fill name="return_no" target="my_calculated_variable"/>
</constraints>
```

Dans un second dictionnaire il est possible de redéfinir le calcul :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable" redefine="True"/>
    </family>
</variables>
<constraints>
    <fill name="return_yes" target="my_calculated_variable"/>
</constraints>
```

Dans ce cas, à aucun moment la fonction "return_no" ne sera exécuté. Seul la fonction "return_yes" le sera.

## Redéfinition avec suppression d'un calcul

Il se peut que dans un dictionnaire on décide de définir une valeur par défaut à une variable via un calcul.

Dans un second dictionnaire il est possible de supprimer ce calcul.

Dans un premier dictionnaire déclarons notre variable et notre calcule :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable"/>
    </family>
</variables>
<constraints>
    <fill name="return_no" target="my_calculated_variable"/>
</constraints>
```

Dans un second dictionnaire supprimer ce calcul :

```
<variables>
    <family name="family">
        <variable name="my_calculated_variable" redefine="True" remove_fill="True"/>
    </family>
</variables>
```