rougail/docs/tutorial/proxymode.rst

The `proxy` family
====================


.. objectives:: Objectives

   We will learn how to:

   - create a :term:`family`
   - gather variables into a family
   - make a variable in a variable, which is a family too


.. type-along:: Reminders

    - As a prerequisite we have an idea of what a :term:`structure file description <dictionary>` is.
    - We have a :file:`firefox` folder and we are putting all the structure description files in it.
    - We had at the :term:`structure description file <structure file>`

A `manual` family
--------------------

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
   :linenos:
   :language: yaml
   :caption: A family structure file description named `manual` in the :file:`firefox/10-manual.yml` file
   :name: RougailFirstDictionary

..
    ---
    manual:
      description: Manual proxy configuration
      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 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. If we make a YAML block
(that is, if we indent), the Rougail's type inference engine will implicitely make it a family.

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

A family inside a family
----------------------------

Creating a family hierarchy is very easy, here is an example

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml
   :linenos:
   :language: yaml
   :caption: A rougail structure description file with a hierarchy.
   :name: RougailFirstFamilyHierarchy

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

      http_proxy:
        description: HTTP Proxy
        type: family

Here the `http_proxy` family lives inside the `manual` family.

Put a variable inside a family or a sub family
--------------------------------------------------

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/tag/v1.1_022/firefox/10-manual.yml
   :linenos:
   :language: yaml
   :caption: An `address` variable in the `http_proxy` family
   :name: RougailVariableInSubFamily

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

      http_proxy:
        description: HTTP Proxy
        type: family

        address:
          description: HTTP address

The :term:`operator` can then set :term:`a value <value>` to the :confval:`adress` variable


.. confval:: address
   :type: `string` (a *domain name*)
   :default: None

   This is a setting that controls the value of the answer.


.. keypoints:: Key points progress

    **Keywords**

    - :term:`family`, and sub families
    - variables defined in a family