diff --git a/docs/tutorial/types.rst b/docs/tutorial/types.rst index 40c8e3e25..a9ee65a49 100644 --- a/docs/tutorial/types.rst +++ b/docs/tutorial/types.rst @@ -442,7 +442,7 @@ Let's run the Rougail CLI: .. rougail -m firefox/ -u yaml -yf config/02/config.yml -the result is: +The result is: .. raw:: html :class: output diff --git a/docs/tutorial/validators.rst b/docs/tutorial/validators.rst index d96b2edf9..e7d3726e9 100644 --- a/docs/tutorial/validators.rst +++ b/docs/tutorial/validators.rst @@ -61,4 +61,67 @@ We call it a :term:`validator`. :language: yaml :caption: The :file:`firefox/60-dns_over_https.yml` with the jinja validator +Here we can see that the validation code is: + +.. code-block:: jinja + + {{ _.custom_dns_url.startswith("http://") }} + + +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. + +In this case we see that we have specified the `return_type parameter`, which +specifies that the Jinja code shall return a boolean value. + +The validator's `description` parameter serves two purposes: + +- it does, of course, have a string function for documenting validation, +- since the `return_type` parameter is set to boolean, + the error message contains this description's string. + +.. type-along:: example with `http://` in the user data + +Now, let's try with incorrect user data, containing `http://` and not `https://` + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_170/config/03/config.yml + :language: yaml + :caption: A :file:`config/03/config.yml` user data file containing `http://` + +.. + --- + dns_over_https: + enable_dns_over_https: true + provider: Custom + custom_dns_url: http://dns.net + + +Let's run the Rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_170/config/03/cmd_ro.txt + +.. + rougail -m firefox/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/03/config.yml + +The result is: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_170/config/03/output_ro.html + +The warning indicates that the validator did not allow an HTTP protocol to pass: + +:: + + ┃ the value "http://dns.net" is an invalid URL, must starts with + ┃ 'https://' only, it will be ignored when loading from the YAML file + ┃ "config/03/config.yml" + +.. keypoints:: Let's review the key points + + We explained the use of validations to refine the type definition of a variable. + + The variable's parameter is `validator`.