stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

docs: add tutorial/variable_propertyerror.rst

Browse source
This commit is contained in:
egarette@silique.fr 2026-06-14 06:31:13 +02:00
parent 4c812ae299
commit 200a05f942
7 changed files with 144 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/abstract.rst
View file

@ -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?
---------------------

2
docs/structured_data/data_integrity.rst
View file

@ -33,6 +33,8 @@ Access control
mode
variable_properties
.. _overall_coherence:
Overall coherence
-----------------

2
docs/tutorial/calculated.rst
View file

@ -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
--------------------------------------------------

1
docs/tutorial/index.rst
View file

@ -67,4 +67,5 @@ Let's dive into this **configuration options validation** use case.
namespace
sequence
underscore_parameter
variable_propertyerror
whatsnext

10
docs/tutorial/preliminary.rst
View file

@ -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**

3
docs/tutorial/types.rst
View file

@ -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 <src/tag/v1.1_022/firefox/10-manual.yml>`
.. _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`
------------------------------

120
docs/tutorial/variable_propertyerror.rst Normal file
View file

@ -0,0 +1,120 @@
Variable calculation with propertyerror
=======================================
.. objectives:: Objectives
In a :ref:`variable-type calculation <tutorial_calc_variable>`, 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 <installation>` 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 <src/branch/1.1>`,
this workshop page corresponds to the tag :tutorial:`v1.1_220 <src/tag/v1.1_220/README.md>` 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 <tutorial_jinja>`, as we have :ref:`already seen <tutorial_propertyerror>`.
But it's not the most effective. It is preferable to perform a :ref:`variable-type calculation <tutorial_calc_variable>` using the property `propertyerror` to `false`.
This property allows you to disable errors in case of :ref:`access problems <access_control>`.
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 <tutorial_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 <tutorial_nullable>`, so the :ref:`overall coherence <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 <tutorial_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 <tutorial_namespace>` but not in the FoxyProxy :ref:`namespace <tutorial_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 <tutorial_namespace>` values are correctly copied into the FoxyProxy :ref:`namespace <tutorial_namespace>`.
.. keypoints:: Key points
We have seen that we can use the test `propertyerror` in Variable calculation.