Firefox tutorial: the `mode_proxy` variable
------------------------------------------------

The `proxy` family
-------------------

Let's create our first :term:`dictionary`.

.. prerequisites:: Let's create a folder named `dict` and a dictionary file inside

We will put our dictionary files in this folder.

Then let's put our first dictionary file in this folder, named :file:`00-proxy.yml`

.. code-block:: yaml
   :caption: the :file:`00-proxy.yml` file
   :linenos:

    ---
    version: '1.1'
    proxy:
      description: Proxy configuration in order to have access to the internet
      type: family

We can see that we have defined a :term:`family` here, and this family is *empty*
(that is, the family container contains no variable yet).

.. admonition:: If a family is empty

    We need to specify the :term:`family` type (line 5) here because if we don't,
    the Rougail's type engine will infer it by default as a :term:`variable`.

It's because we don't have set any :term:`variable` inside.


.. note:: The variables will be created in several files for educational purposes.
          Obviously all the variables can be put in the same file.


The proxy's configuration type
----------------------------------

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`).

Let's create a variable in its family with a description and a default value.
The type of this variable is a `choice` type:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_006/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: A rougail dictionnary file with a choice variable named `proxy_mode`, with a default value and a description.
   :name: RougailDictionaryFirstVariableChoiceType

.. glossary::

    mandatory

        A variable is mandatory when a value is required, that is, `None` is not an option.

The `proxy_mode` variable here, implicitely requires a value. It is a mandatory variable.

It shall have a value, but what if the user *does not* specify any value?
There is a possibility of setting a default value, wich is set as `No proxy` by default.

.. glossary::

    choice type

        The `proxy_mode` setting is "choice" (`type: choice`) means that
        there is a list of available values that can be selected.

We say that the `proxy_mode` variable is *constrained* (by the `choice` type).

We have the list of the possible (authorized) values:

- `No proxy`
- `Auto-detect proxy settings for this network`
- `Use system proxy settings`
- `Manual proxy configuration`
- `Automatic proxy configuration URL`

Now let's test our first two dictionaries:

>>> from rougail import Rougail, RougailConfig
>>> from pprint import pprint
>>> RougailConfig['dictionaries_dir'] = ['dict']
>>> rougail = Rougail()
>>> config = rougail.get_config()
>>> config.property.read_only()
>>> pprint(config.value.get(), sort_dicts=False)
{'rougail.proxy.proxy_mode': 'No proxy'}