From 200a05f942582ba96f3c22c2f627091628c2504d Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sun, 14 Jun 2026 06:31:13 +0200 Subject: [PATCH] docs: add tutorial/variable_propertyerror.rst --- docs/abstract.rst | 15 +++ docs/structured_data/data_integrity.rst | 2 + docs/tutorial/calculated.rst | 2 + docs/tutorial/index.rst | 1 + docs/tutorial/preliminary.rst | 10 +- docs/tutorial/types.rst | 3 + docs/tutorial/variable_propertyerror.rst | 120 +++++++++++++++++++++++ 7 files changed, 144 insertions(+), 9 deletions(-) create mode 100644 docs/tutorial/variable_propertyerror.rst diff --git a/docs/abstract.rst b/docs/abstract.rst index 3456e7899..d4fa33e3a 100644 --- a/docs/abstract.rst +++ b/docs/abstract.rst @@ -125,6 +125,21 @@ Here are some output examples: * - **Output** +.. _configuration: + +Configuration +~~~~~~~~~~~~~ + +We've been talking about `configuration` for a while now. It's time to define what a configuration is. + +.. glossary:: + + configuration + + The configuration represents the set of variables and their values loaded in a tree-like fashion into memory from structural data, user data and any modifications during its lifecycle. + + In practice, it's :term:`Tiramisu` who manages this part. + What kind of actor? --------------------- diff --git a/docs/structured_data/data_integrity.rst b/docs/structured_data/data_integrity.rst index c8f12daa4..ba4b24f0a 100644 --- a/docs/structured_data/data_integrity.rst +++ b/docs/structured_data/data_integrity.rst @@ -33,6 +33,8 @@ Access control mode variable_properties +.. _overall_coherence: + Overall coherence ----------------- diff --git a/docs/tutorial/calculated.rst b/docs/tutorial/calculated.rst index 47fb76dc1..d5a0e09a0 100644 --- a/docs/tutorial/calculated.rst +++ b/docs/tutorial/calculated.rst @@ -76,6 +76,8 @@ Now we are going to define an address and a port in the `https_proxy` family: type: port default: 8080 +.. _tutorial_calc_variable: + A default value calculated from another variable -------------------------------------------------- diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index c1d0e4225..073b91679 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -67,4 +67,5 @@ Let's dive into this **configuration options validation** use case. namespace sequence underscore_parameter + variable_propertyerror whatsnext diff --git a/docs/tutorial/preliminary.rst b/docs/tutorial/preliminary.rst index f314cc81e..632f3c9f4 100644 --- a/docs/tutorial/preliminary.rst +++ b/docs/tutorial/preliminary.rst @@ -353,7 +353,7 @@ here we are talking about roles and not necessarily about people. .. type-along:: User data files are where the user values live -We need to set the values ​​in separate files, called `user data files`. +We need to set the values in separate files, called `user data files`. .. glossary:: @@ -366,14 +366,6 @@ We need to set the values ​​in separate files, called `user data files`. see also :term:`user data` -.. glossary:: - - configuration - - We call configuration the whole system structure and user values, - and when we speak of consistency, it is in relation to this whole set. - It's a state, a possibility of state for the system, a situation. - .. keypoints:: Key points progress **Keywords** diff --git a/docs/tutorial/types.rst b/docs/tutorial/types.rst index 14250f57d..4a3c7e446 100644 --- a/docs/tutorial/types.rst +++ b/docs/tutorial/types.rst @@ -41,6 +41,7 @@ We have an `http_proxy` family with an `address` variable in it. :tutorial:`Download this file from the rougail-tutorials git repository ` +.. _tutorial_domainname: A variable with type `domainname` ----------------------------------- @@ -269,6 +270,8 @@ We have this output: We can see that the IP address value has been accepted. +.. _tutorial_port: + A variable with type `port` ------------------------------ diff --git a/docs/tutorial/variable_propertyerror.rst b/docs/tutorial/variable_propertyerror.rst new file mode 100644 index 000000000..9f1a6e695 --- /dev/null +++ b/docs/tutorial/variable_propertyerror.rst @@ -0,0 +1,120 @@ +Variable calculation with propertyerror +======================================= + +.. objectives:: Objectives + + In a :ref:`variable-type calculation `, it is possible to test if a variable is accessible (there is no :ref:`access_control` problem). + +.. prerequisites:: Prerequisites + + - We assume that Rougail's library is :ref:`installed ` on your computer. + + - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step + by checking out the corresponding tag of the `rougail-tutorials` git repository. + Each tag corresponds to a stage of progress in the tutorial. + Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. + + If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, + this workshop page corresponds to the tag :tutorial:`v1.1_220 ` in the repository: + + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git switch --detach v1.1_220 + +We have now to add three new variables: + +- :ref:`tutorial_domainname` `address` that allow IP and hostname, this variable is accessible in type HTTP, HTTPS/SSL, SOCKS4 or SOCKS5 +- :ref:`tutorial_port`, this variable is accessible in type HTTP, HTTPS/SSL, SOCKS4 or SOCKS5 +- :ref:`tutorial_web_address` URL, this variable is accessible in type PAC URL or WPAD + +.. image:: images/foxyproxy.png + +There is a particularity to these three variables. +We want to copy the values of the equivalent variables available in Firefox. +The reason is obvious; it simplifies data entry. + +Variables are not always available. It is possible to test their presence in a :ref:`Jinja template `, as we have :ref:`already seen `. +But it's not the most effective. It is preferable to perform a :ref:`variable-type calculation ` using the property `propertyerror` to `false`. + +This property allows you to disable errors in case of :ref:`access problems `. + +Let's start by modifying the structure file: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/foxyproxy/00-foxyproxy.yml + :language: yaml + :caption: The :file:`foxyproxy/00-foxyproxy.yml` + +If the variable is accessible, there's no question about it; the variable retrieves its value. But what happens if the variable is not accessible? + +In this case, the value of the variable is `null`. + +Don't just take my word for it, let's do a test. + +Now let's test with the following user data file: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/02/config.yml + :linenos: + :language: yaml + :caption: The :file:`config/02/config.yml` user data + +The proxy in the Firefox :ref:`namespace ` is not defined, so the address and port variables are not accessible. + +A proxy is configured in FoxyProxy, but also without address or port. + +If we launch the Rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/02/cmd_ro.txt + + +We have this output: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/02/output_ro.html + +As expected, calculating the default value works without issue even though the variables involved in the calculations are inaccessible. + +The values are therefore `null`. These variables are not :ref:`nullable `, so the :ref:`overall coherence ` of the :ref:`configuration` is not guaranteed. + +Now try it in the :term:`read write mode` with the Rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/02/cmd_rw.txt + +The variables has really the value `null`: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/02/output_rw.html + +Now let's configure the variables in the Firefox :ref:`namespace `: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/04/config.yml + :linenos: + :language: yaml + :caption: The :file:`config/04/config.yml` user data + +As you can see, the address and port are defined in the Firefox :ref:`namespace ` but not in the FoxyProxy :ref:`namespace `. + +If we launch the Rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/04/cmd_ro.txt + +We have this output: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_220/config/04/output_ro.html + +As expected, the Firefox :ref:`namespace ` values are correctly copied into the FoxyProxy :ref:`namespace `. + +.. keypoints:: Key points + + We have seen that we can use the test `propertyerror` in Variable calculation. +