rougail/docs/tutorial/underscore_parameter.rst

Name and parameter conflict
================================

.. objectives:: Objectives

   When a variable name conflicts with a family parameter, 
   do we have to abandon the variable name choice we made?
   No because having a suitable variable name is really important.
   The variable name you chose is undoubtedly the best.

   Sometimes, the choice of a variable's name may correspond very exactly 
   to an parameter of the family in which that variable is placed...

   In this section, we will learn how to create a variable name that conflict with a defined parameter name.

.. 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_210 <src/tag/v1.1_210/README.md>`
    in the repository.

    ::

       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach v1.1_210

.. type-along:: Let's recap how far we've come

FIXME: changer le nom leadership

We have this leadership family in its structure definition file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_202/foxyproxy/00-foxyproxy.yml
   :linenos:
   :language: yaml
   :caption: The `proxies` family with `leadership` type in the :file:`foxyproxy/00-foxyproxy.yml` structure file

The variable "type" that conflits with the family parameter "type"
----------------------------------------------------------------------------

Choice a good variable name is important. It's with this name that user will interact with here value.

The user has to define the type of the new proxy. So instinctively the name of the variable will be `type`.

But in the current family we have already the parameter `type` with the `leadership` value.
YAML do not permit to have two key with the same name.
Maybe we could choice an other variable name like `proxy_type` but the full path will be `proxies.proxy_type`.
Repeating the word proxy is not appropriate.

So the best way it to rename the `type` parameter to `_type`

Let's create a family named `manual` which obviously corresponds to the proxy's manual configuration choice.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_210/foxyproxy/00-foxyproxy.yml
   :language: yaml
   :caption: The `proxies` family with `leadership` type and a variable with the name `type` in the :file:`foxyproxy/00-foxyproxy.yml` structure file

Technically it's possible to put `_` at the beginning of each parameter name, but it's still less readable.

.. keypoints:: Let's review the key points

    **Keywords**

    - parameters could start by "_" character or not
    - do not add `_` in front of all parameters name