rougail/doc/check/README.md

# Fonction de vérification

## Synopsis

Une fonction de vérification est une fonction complémentaire au type qui permet de valider plus précisement le contenu d'une variable.

Un validateur est forcement un calcul de type Jinja.

## Paramètres

Suivant les types de calcul les paramètres vont être différents :

| Type de calcul | Paramètre | Commentaires | Exemple |
|----------------|-----------|--------------|---------|
| | **type**<br/>`string`<br/>`mandatory` | Type du calcul, la seule valeur possible est : jinja | jinja |
| **jinja**<br/>`string`<br/>`mandatory` | Template Jinja. | {% if rougail.variable == 'not\_allowed' %}not allowed!{% endif %} |
| **params**<br/>`list` | Paramètres complémentaire passé au template Jinja | |

Il existe deux types de paramètre :

- les paramètres standards (string, boolean, integer, null), dans ce il suffit de faire : "key: value"
- les paramètres avancés :

  - paramètre via une variable
  - paramètre via une information
  - paramètre via un suffix : dans le cas d'une variable dans une famille dynamique
  - paramètre via un index : dans le cas d'une variable suiveuse

| Type du paramètre | Paramètre | Commentaires | Exemple |
|-------------------|-----------|--------------|---------|
| | **name**<br/>`string`<br/>`mandatory` | Le nom du paramètre | my\_param |
| | **type**<br/>`string`<br/>`mandatory` | Type du paramètre, les valeurs possible sont : variable, information, suffix ou index| suffix |
| Variable | **variable**<br/>`string`<br/>`mandatory` | Nom de la variable | rougail.variable |
| Variable (`mandatory`)<br/>Information | **propertyerror**<br/>`boolean` | Si l'accès à la variable n'est pas possible à cause d'une propriété (par exemple `disabled`) par défaut une erreur est retournée. Si l'attribut est à False, le paramètre n'est pas passé au template Jinja.<br/>**Valeur par défaut :** True | False |
| Variable | **optional**<br/>`boolean` | La variable peut ne pas exister suivant les importations de fichier YAML. Si le paramètre optional est à True, le paramètre sera tout simplement supprimer si la variable n'existe pas.<br/>**Valeur par défaut :** False | True |
| Information | **information**<br/>`string`<br/>`mandatory` | Nom de l'information dont on veut récupérer la valeur. | doc |

## Exemples

### Vérification stricte des valeurs


Voici un exemple simple de validation des valeurs :

```yml
---
version: '1.0'
my_variable:
  validators:
    - type: jinja
      jinja: |
        {% if rougail.my_variable and not rougail.my_variable.islower() %}
        {{ rougail.my_variable }} is not lowercase string
        {% endif %}        
```

Une fonction de vérification doit prendre en compte 2 aspects important :

- la valeur peut ne pas être renseigné (même si la variable est obligatoire), la valeur None doit être prise en compte
- si la valeur est invalide, il faut renvoyer une phrase avec un message explicite.

À partir de maintenant seule None et des valeurs en minuscule seront autorisés.

### Vérification des valeurs avec avertissement

Dans la contrainte, il est possible de spécifier le niveau d'erreur et le mettre en avertissement :

```yml
---
version: '1.0'
my_variable:
  validators:
    - type: jinja
      jinja: |+
        {% if rougail.my_variable and not rougail.my_variable.islower() %}
        {{ rougail.my_variable }} is not lowercase string
        {% endif %}        
      params:
        warnings_only: true
```

Dans ce cas une valeur avec une majuscule sera accepté, mais un message d'avertissement apparaitra.


### Vérification avec paramètres :

```yml
---
version: '1.0'
my_hidden_variable:
  disabled: true
my_variable:
  validators:
    - type: jinja
      jinja: |
        {% if param1 is defined and rougail.my_variable == param1 %}
        has same value as rougail.unknown_variable
        {% endif %}
        {% if param2 is defined and rougail.my_variable == param2 %}
        has same value as rougail.my_hidden_variable
        {% endif %}        
      params:
        param1:
          type: variable
          variable: rougail.unknown_variable
          optional: true
        param2:
          type: variable
          variable: rougail.my_hidden_variable
          propertyerror: false
```

Un exemple avec un paramètre de type suffix :

##FIXME##

```yml
---
version: '1.0'
varname:
  multi: true
  default:
    - val1
    - val2
my_dyn_family_:
  type: dynamic
  variable: rougail.varname
  description: 'Describe '
  my_dyn_var_:
    type: string
    validators:
      - type: jinja
        jinja: |
          {% if rougail.my_dyn_family_.my_dyn_var_ == param1 %}
          forbidden!
          {% endif %}          
        params:
          param1:
            type: suffix
```

Un exemple avec un paramètre de type index :

```yml
---
version: '1.0'
family:
  type: leadership
  leader:
    multi: true
    default:
      - val1
      - val2
  follower1:
    type: number
    validators:
      - type: jinja
        jinja: |
          {% if rougail.family.follower1 == param1 %}
          forbidden!
          {% endif %}          
        params:
          param1:
            type: index
```

### Rédéfinition

Dans un premier dictionnaire déclarons notre variable et sa fonction de vérification :

```yml
---
version: '1.0'
my_variable:
  validators:
    - type: jinja
      jinja: |
        {% if rougail.my_variable and not rougail.my_variable.islower() %}
        {{ rougail.my_variable }} is not lowercase string
        {% endif %}        
```

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

```yml
---
version: '1.0'
my_variable:
  redefine: true
  validators:  
    - type: jinja
      jinja: |
        {% if rougail.my_variable and ' ' in rougail.my_variable %}
        {{ rougail.my_variable }} has a space
        {% endif %}        
```

Dans ce cas seule ce validateur sera exécuté.

Voici un troisième dictionnaire dans lequel on supprime la validation :

```yml
---
version: '1.0'
my_variable:
  redefine: true
  validators:
```