rougail/docs/tutorial/variable_propertyerror.rst

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.