Verification function
==========================
Synopsis
-------------
A verification is a complementary validation to the type which allows the content of a variable to be validated more precisely.
A :term:`validator` is necessarily a Jinja type calculation.
Parameters
--------------
Depending on the types of calculation, the parameters will be different:
.. list-table::
:widths: 15 25 20 15
:header-rows: 1
* - **Calculation type**
- **Parameter**
- **Comments**
- **Sample**
* -
- **type**
`string`
`mandatory`
- Type of calculation, the only possible value is: jinja
- jinja
* - **jinja**
`string`
`mandatory`
- Jinja template
- {% if rougail.variable == 'not_allowed' %}not allowed!{% endif %}
-
* - **params**
`list`
- Additional parameters passed to the Jinja template
-
-
There are two types of parameter:
- the standard parameters (string, boolean, integer, null), in this case just do: "key: value"
- advanced settings:
- parameter via a variable
- parameter via an information
- parameter via a suffix: in the case of a variable in a dynamic family
- parameter via an index: in the case of a :term:`follower` variable
.. list-table::
:widths: 15 25 20 15
:header-rows: 1
* - **Parameter's type**
- **Parameter**
- **Comments**
- **Sample**
* -
- **name**
`string`
`mandatory`
- Parameter's name
- my_param
* -
- **type**
`string`
`mandatory`
- Type of parameter, possible values are: variable, information, suffix or index
- suffix
* - Variable
- **variable**
`string`
`mandatory`
- variable's name
- rougail.variable
* - Variable (`mandatory`) information
- **propertyerror**
`boolean`
- If access to the variable is not possible due to a property
(for example `disabled`) by default an error is returned.
If the attribute is `False`, the parameter is not passed to the Jinja template.
**Default value**: `True`
- True
* - Information
- **information**
`string`
`mandatory`
- Name of the information whose value we want to retrieve.
- doc
Samples
--------------
Strict verification of values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here is a simple example of validating values:
.. code-block:: yaml
---
version: '1.1'
my_variable:
validators:
- type: jinja
jinja: |
{% if rougail.my_variable and not rougail.my_variable.islower() %}
{{ rougail.my_variable }} is not lowercase string
{% endif %}
A verification function must take into account 2 important aspects:
- the value may not be entered (even if the variable is mandatory), the None value must be taken into account
- if the value is invalid, a sentence must be returned with an explicit message.
From now on only `None` and lowercase values will be allowed.
Checking values with warning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In the constraint, it is possible to specify the error level and put it as a warning:
.. code-block:: yaml
---
version: '1.1'
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
In this case a value with a capital letter will be accepted, but a warning message will appear.
Verification with parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: yaml
---
version: '1.1'
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
An example with a suffix type parameter:
.. code-block:: yaml
---
version: '1.1'
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
In this example, we see a dynamic family. Two families will be created: `rougail.my_dyn_family_val1.my_dyn_var` and `rougail.my_dyn_family_val2.my_dyn_var`.
The value of the variable within this family cannot be equal to the value
of the suffix (`val1` and `val2` respectively).
An example with an index type parameter:
.. code-block:: yaml
---
version: '1.1'
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
Redefinition
---------------
In a first dictionary, let's declare our variable and its verification function:
.. code-block:: yaml
---
version: '1.1'
my_variable:
validators:
- type: jinja
jinja: |
{% if rougail.my_variable and not rougail.my_variable.islower() %}
{{ rougail.my_variable }} is not lowercase string
{% endif %}
In a second dictionary it is possible to redefine the calculation:
.. code-block:: yaml
---
version: '1.1'
my_variable:
redefine: true
validators:
- type: jinja
jinja: |
{% if rougail.my_variable and ' ' in rougail.my_variable %}
{{ rougail.my_variable }} has a space
{% endif %}
In this case only this validator will be executed.
Here is a third dictionary in which we remove the validation:
.. code-block:: yaml
---
version: '1.1'
my_variable:
redefine: true
validators: