diff --git a/docs/tutorial/choice.rst b/docs/tutorial/choice.rst index 3050745e6..145880a5a 100644 --- a/docs/tutorial/choice.rst +++ b/docs/tutorial/choice.rst @@ -1,18 +1,37 @@ -A variable with a list of possible values -========================================= +A variable with predefined values +================================== +.. objectives:: Objectives + We will learn how to define variables with a list of available values. -.. type-along:: Defining a choice type +.. prerequisites:: Prerequisites -In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type: + - We assume that Rougail's library is :ref:`installed ` on your computer. + - If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`, + this workshop page corresponds to the tags :tutorial:`v1.1_004 ` to :tutorial:`FIXME ` + in the repository: -.. seealso:: Have a look at the definition of the :term:`choice type variable ` + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git checkout v1.1_004 + +Limits the possible values for the variable +--------------------------------------------- + +In the firefox browser, the proxy mode can be defined this way: + +.. image:: images/firefox_02.png + +A list of possible values for the `proxy_mode` variable ​​is proposed. +With rougail there is the possibility of defining a list of available values +with the `choice` parameter: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml :linenos: :language: yaml - :caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type + :caption: The `proxy_mode` variable with the `choice` parameter :name: RougailDictionaryChoiceType .. @@ -29,12 +48,12 @@ In our firefox use case, the real type of the `proxy_mode` variable will be now :tutorial:`Download this file from the rougail-tutorials git repository ` -- Let's run the Rougail CLI +Let's run the Rougail CLI with this new structure file: .. code-block:: text :class: terminal - rougail -v 1.1 -m firefox/ + rougail -m firefox/ We have an output like this one: @@ -53,14 +72,17 @@ We have an output like this one: ┗━━ 📓 proxy_mode: No proxy -The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable. +The `proxy_mode` variable requires a value, that's why we have set a `No proxy` default value. -As we set the `proxy_mode` variable as `No proxy` by default, we actually have specified a value, and the value appears in yellow, which means : "set by default". +.. note:: As we have set the `proxy_mode`'s value as `No proxy` by default, we have set a value + which appears in yellow in the rougail CLI output, which means : "value set by default". The constraints that come with the `choice` type ---------------------------------------------------- -We say that the `proxy_mode` variable is *constrained* (by the `choice` type). +We say that the `proxy_mode` variable is *constrained* by the `choice` parameter. + +FIXME continuer ici .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml :linenos: @@ -76,6 +98,8 @@ If we run the rougail CLI with this user datas, we have: rougail -m firefox -u yaml -ff config/03/config.yml +FIXME: this output is not the expected output + We have this output: .. raw:: html @@ -95,7 +119,7 @@ As we set the `proxy_mode` variable from a user data file, we now have specified a value which is **not** a default value, and the value appears in green, which means : "user data value". -.. FIXME: verifier que cette sortie est bonne (on a des valeurs différentes) +FIXME: verifier que cette sortie est bonne (on a des valeurs différentes) .. type-along:: The constraints that come with the `choice` property @@ -109,6 +133,8 @@ We have the list of the possible (authorized) values: - `Manual proxy configuration` - `Automatic proxy configuration URL` +FIXME : essayer de fixer un value qui n'est pas dans la liste et voir le résultat + .. keypoints:: Key points progress Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`).