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 de type "oui/non" donc la valeur est retournée par la fonction "return_no" :

    <variables>
        <family name="family">
            <variable name="my_calculated_variable" type="oui/non" description="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 'non'

Dans ce cas, la valeur par défaut est la valeur retournée par la fonction (ici "non"), 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" type="oui/non" description="My calculated variable">
        <value>oui</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" type="oui/non" description="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>non</param>
        </fill>
    </constraints>

Créons la fonction correspondante :

    def return_value(value):
        return value

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

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">non</param>
        </fill>
    </constraints>

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

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 'non'
        return 'oui'

La variable aura donc "non" 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" type="oui/non" description="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 "non".
Si la valeur de "my_variable" est différent de 1, la valeur par défaut de la variable "my_calculated_variable" sera "oui".

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" type="oui/non" description="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.


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" type="oui/non" description="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.