diff --git a/docs/format_content/validation.rst b/docs/format_content/validation.rst index aefb0ccca..35b0c7477 100644 --- a/docs/format_content/validation.rst +++ b/docs/format_content/validation.rst @@ -6,106 +6,159 @@ 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. +The purpose of validation is to verify that the variable is of :ref:`good quality ` and/or that the variable is :ref:`consistent `. + +.. glossary:: + + validator + + A validator is a Jinja code that parses a variable's value and checks + that this value corresponds to some stated criteria. + This is a `validator` parameter of our variable, and another `jinja` sub-parameter + contains validation code for the variable's value. + +.. seealso:: The tutorial with a real world sample :ref:`validators ` Parameters -------------- Depending on the types of calculation, the parameters will be different: -.. list-table:: - :widths: 15 25 20 15 +.. list-table:: :header-rows: 1 - + * - **Calculation type** - - **Parameter** - - **Comments** - - **Sample** - - * - - - **type** - + - **Comment** + + * - **type** + `string` - - `mandatory` - - Type of calculation, the only possible value is: jinja - - jinja - * - **jinja** - + - The value is `jinja` + + * - **jinja** + `string` - + `mandatory` - - Jinja template - - {% if rougail.variable == 'not_allowed' %}not allowed!{% endif %} - - + - Please set a Jinja template. + * - **params** - - `list` - - Additional parameters passed to the Jinja template - - - - -There are two types of parameter: + `dict` + - Additional parameters passed to the Jinja template (see below). + + * - **return_type** + + `string` + - A validation could returns the error message directly, so return_type is `string` (the default behavior). + Or a `boolean`, in this case if it's return `true` this means that the value is not valid. + + * - **description** + + `string` + - Additional information for the :ref:`documentation ` and the error message in case of return_type is a boolean. + + * - **warnings** + + `boolean` + - If `true` the validation did not raise, it only display a warning. + + +Params +~~~~~~ + +There are two types of params: + +- the standard parameters (string, boolean, integer, float or null), in this case just do: "key: value" +- advanced settings (with something like "key: {}": -- 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 + - parameter via an identifier: in a dynamic family returns the current identifier + - parameter via an index: in the case of a :term:`follower` variable returns the current index + - parameter via :ref:`the current namespace name ` + +Variable params +""""""""""""""" + +.. list-table:: :header-rows: 1 - - * - **Parameter's type** - - **Parameter** + + * - **Parameter** - **Comments** - **Sample** - * - - - **name** - + + * - **type** + `string` - - `mandatory` - - Parameter's name - - my_param - * - - - **type** - + - Type of parameter, which is variable. + - variable + + * - **variable** + `string` - + `mandatory` - - Type of parameter, possible values are: variable, information, suffix or index - - suffix - * - Variable - - **variable** - - `string` - - `mandatory` - - variable's name + - Variable's path. - rougail.variable - * - Variable (`mandatory`) information - - **propertyerror** - + + * - **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** - + - 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**: `false` + - `true` + + * - **optional** + + `boolean` + - If the variable is not defined the value is always `null`. + + **Default value**: `false` + - `true` + + * - **whole** + + `boolean` + - In :term:`dynamically built family` only the value of the current index is retrieve. If this parameter is set to `true` it returns all + If this parameter is set to `true`, it returns the set of values for all indices. + + **Default value**: `false` + - `true` + +Information params +~~~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - **Parameter** + - **Comments** + - **Sample** + + * - **type** + `string` - + - Type of parameter, which is information + - information + + * - **information** + + `string` + `mandatory` - Name of the information whose value we want to retrieve. - doc + * - **variable** + + `string` + - By default, the information is a context information. It is possible to get a variable information. In this case just specify a path. + - rougail.variable + Samples -------------- @@ -116,23 +169,24 @@ 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 %} - + %YAML 1.2 + --- + version: 1.1 + + my_variable: + validators: + - jinja: |- + {% if my_variable is not none and not my_variable.islower() %} + {{ 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. +- if return_type is `string` and the value is invalid, a sentence must be returned with an explicit message. -From now on only `None` and lowercase values will be allowed. +From now on only `null` and lowercase values will be allowed. Checking values with warning ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -141,17 +195,19 @@ In the constraint, it is possible to specify the error level and put it as a war .. 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 + %YAML 1.2 + --- + version: 1.1 + + my_variable: + validators: + - jinja: |- + {% if my_variable is not none and not my_variable.islower() %} + {{ my_variable }} is not lowercase string + {% endif %} + params: + warnings: true + ... In this case a value with a capital letter will be accepted, but a warning message will appear. @@ -160,127 +216,88 @@ 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 + %YAML 1.2 + --- + version: 1.1 -An example with a suffix type parameter: + my_hidden_variable: + disabled: true + + my_variable: + validators: + - type: jinja + jinja: |- + {% if param1 is defined and my_variable == param1 %} + has same value as unknown_variable + {% endif %} + {% if param2 is defined and my_variable == param2 %} + has same value as my_hidden_variable + {% endif %} + params: + param1: + variable: unknown_variable + optional: true + param2: + variable: my_hidden_variable + propertyerror: false + ... + +An example with an identifier 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 + %YAML 1.2 + --- + version: 1.1 -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`. + my_dyn_family_{{ identifier }}: + type: dynamic + dynamic: + - val1 + - val2 + description: 'Describe {{ identifier }}' -The value of the variable within this family cannot be equal to the value -of the suffix (`val1` and `val2` respectively). + my_dyn_var: + validators: + - jinja: | + {% if my_dyn_family_.my_dyn_var == param1 %} + forbidden! + {% endif %} + params: + param1: + type: identifier + ... + +In this example, we see a :term:`dynamically built family`. Two families will be created: `my_dyn_family_val1.my_dyn_var` and `my_dyn_family_val2.my_dyn_var`. + +The value of the variable within this family cannot be equal to the value +of the identifier (`val1` and `val2` respectively). An example with an index type parameter: .. code-block:: yaml - --- - version: 1.1 - family: - type: sequence - leader: - multi: true - default: - - val1 - - val2 - follower1: - type: integer - validators: - - type: jinja - jinja: | - {% if rougail.family.follower1 == param1 %} - forbidden! - {% endif %} - params: - param1: - type: index + %YAML 1.2 + --- + version: 1.1 -Redefinition ---------------- + family: + type: sequence -In a first dictionary, let's declare our variable and its verification function: + leader: + default: + - val1 + - val2 -.. 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: + follower1: + type: integer + validators: + - type: jinja + jinja: |- + {% if family.follower1 == param1 %} + forbidden! + {% endif %} + params: + param1: + type: index + ... diff --git a/docs/structured_data/data_integrity.rst b/docs/structured_data/data_integrity.rst index 6a4587185..e87c0215e 100644 --- a/docs/structured_data/data_integrity.rst +++ b/docs/structured_data/data_integrity.rst @@ -51,6 +51,7 @@ Overall coherence which will validate the value of a variable in relation to others. But it also depends on the availability of the variable depending on the context. +.. _consistency: Consistency ~~~~~~~~~~~ diff --git a/docs/structured_data/documentation.rst b/docs/structured_data/documentation.rst index 47a282e2a..806f1f74b 100644 --- a/docs/structured_data/documentation.rst +++ b/docs/structured_data/documentation.rst @@ -1,3 +1,5 @@ +.. _data_documentation: + Data documentation ================== diff --git a/docs/structured_data/typing.rst b/docs/structured_data/typing.rst index 99e9fe2a9..091a3c054 100644 --- a/docs/structured_data/typing.rst +++ b/docs/structured_data/typing.rst @@ -145,6 +145,8 @@ It is possible to create subfamilies. .. seealso:: :doc:`the family documentation ` +.. _dynamically_built_family: + The dynamically built family ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorial/regexp.rst b/docs/tutorial/regexp.rst index ab95a27c2..17860011b 100644 --- a/docs/tutorial/regexp.rst +++ b/docs/tutorial/regexp.rst @@ -27,7 +27,7 @@ Regexp type with calculation A regexp variable ----------------- -We have already seen the :ref:`validator mechanism ` for managing the :ref:`quality of data values `. +We have already seen the :ref:`validator mechanism ` for managing the :ref:`quality of data values `. This mechanism is undeniably interesting and powerful. But for strings that can be validated using a regular expression, it is preferable to use this type. @@ -89,7 +89,7 @@ Why not offer a default value to the user? If the user has a specific color in mind, they can specify it. Otherwise, Rougail will suggest a default value. -We've already seen how to use :ref:`Jinja ` for :ref:`validation ` and :ref:`access control ` calculations. +We've already seen how to use :ref:`Jinja ` for :ref:`validation ` and :ref:`access control ` calculations. We've also seen how to calculate the default value by :ref:`retrieving the value of another variable `. diff --git a/docs/tutorial/validators.rst b/docs/tutorial/validators.rst index 0e42c1929..fd0044018 100644 --- a/docs/tutorial/validators.rst +++ b/docs/tutorial/validators.rst @@ -1,4 +1,4 @@ -.. _tutorial_validator: +.. _tutorial_validators: Validating a variable's value ================================ @@ -49,15 +49,6 @@ It is possible, instead of creating a new type, to add custom validation of the We call it a :term:`validator`. -.. glossary:: - - validator - - A validator is a Jinja code that parses a variable's value and checks - that this value corresponds to some stated criteria. - This is a `validator` parameter of our variable, and another `jinja` sub-parameter - contains validation code for the variable's value. - .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_170/firefox/60-dns_over_https.yml :language: yaml :caption: The :file:`firefox/60-dns_over_https.yml` with the jinja validator @@ -68,6 +59,7 @@ Here we can see that the validation code is: {{ _.custom_dns_url.startswith("http://") }} +First of all, you can see that we use the path of the current variable for validation. A validator can return a string, in fact it is its default behavior. If it returns a string of characters, it indicates the validation error.