The variables
==============

Synopsis
---------

.. glossary::

   variable

       A variable is an abstract black box (container) paired with an associated symbolic name, most often an option configuration, hich contains some defined or undefined data setting referred to as a :term:`value`.

   value

       A value is a variable's setting.
       Variable can have a default value, that is a setting defined in the :term:`structure file`,
       or no value at all, then the value needs to be define later by the :term:`operator`.

.. discussion:: Discussion

    The variable is, by definition, strongly typed.
    Rougail uses static type definition and even type inference.
    Indeed, the constistency handling system heavyly relies on the type system definition.
    Variables may only be able to store a specified data type.
    OK, variables are the containers for storing the values. It has something to do with typing.

    But consitency handling system is is not just about strong typing. It is more than that.

Names
------

Variable name

    Variable's associated symbolic name.

.. seealso::

    Have a look at the :ref:`convention on variable naming link <convention on variable names>`.

Variable's types
-----------------

.. type-along:: type inference

If the `type` attribute is not set, Rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.

.. type-along:: integer type

If the operator sets an option value for example with the `integer` type, like this:

.. code-block:: yaml

    ---
    example_var:
      description: This is an example variable
      type: integer

Then Rougail will expect a `int` as a value for the `example_var` variable.

.. type-along:: the choice type

.. glossary::

   choice type

       A choice type variable is a variable where the content is constrained by a list
       
       When a variable's setting is "choice" (`type: choice`), it means that
       there is a list of available values that can be selected.

Shorthand declaration
----------------------------

Shorthand declaration is a way to declare a variable in a single line. But you can only define variable name, description, multi or default value.

.. glossary::

    short-hand notation
    
        A short-hand notation in Rougail is the ability to define a variable in 
        a short-hand way, there are several example: 
        
        - a default value: 
        
        .. code-block:: yaml
        
            my_var: true 
            
        instead of:
        
        .. code-block:: yaml
        
            my_var:
              default: true

To create a variable, just add a key with it's name and default value as value.
Be careful not to declare any other attributes.

To declare a multi variable just add a list as default value.

By default, the description of the variable is the variable name.
If you add a comment in the same line of the name, this comment will be used has a description.

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1

    my_variable: 1  # This is a great integer variable

    my_multi_variable:  # This is a great multi string variable
      - value1
      - value2
    ...

Parameters
-------------

.. list-table::
   :widths: 15 45
   :header-rows: 1

   * - Parameter
     - Comments

   * - **help**

       `string`
     - Additional help associated with the variable.

   * - **default**
     - Default value(s) of the variable.

       This value is typed, you must correctly fill out the YAML file to avoid defining a value with an incorrect type. For example, a `integer` must be a digit type, a multiple variable must be a `list` type, ...

       For a non :term:`leading` multiple variable, the first value defined in the list will also be the default value proposed if a new value is added to this variable.

   * - **validators**

       `list`
     - Value validators.

       Jinja template list. The value of the variable will be considered invalid if the template has a return value.
   * - **auto_save**

       `boolean`
     - Variable with automatically modified value.

       A variable with automatically modified value is a variable whose value will be considered as *modified* (that is, it is no longer the variable's default value).

       For example, if the value of this variable comes from a calculation, the value will no longer be recalculated.

       These variables are usually :term:`required` variables. In fact, these variables are only automatically modified if they have a value.

       A :term:`leader` or :term:`follower` variable cannot have the `auto_save` property.

       **Default value**: `false`
   * - **mode**

       `string`
     - Variable's mode.

       **Default value**: The `default` mode of a variable is the mode of the parent family.

       Special cases :

       - a variable with an automatically modified value or an automatic read-only variable is by default in `basic` mode
       - if the variable is not in a family, the variable will have a `standard` mode by default
       - a :term:`mandatory` variable without default value (calculate or not) will have a `basic` mode
   * - **multi**

       `boolean`
     - The value of the variable is a list.

       **Default value**: `false`

       **Parameters**:

       - multi_length: number of expected values for a multiple variable
       - multi_min_length: maximum number of expected values for a multiple variable
       - multi_max_length: minimum number of expected values for a minimum variable
   * - **unique**

       `boolean`
     - The :term:`multiple` type variable accepts the same value several times. If unique is set to `false`, a :term:`multiple` variable only accepts the same value once in the list.

       **Default value**: `false`
   * - **hidden**

       `boolean` or :term:`calculation`
     - Invisible variable.

       Enables us to *hide* a variable.

       This means that the variable will no longer be visible in `read-write` mode, but only for calculations or in `read-only` mode.

       When a variable is made invisible, the user will not be able to modify its value; if he has already succeeded in modifying it, this value will not be taken into account.

       **Default value**: `false`
   * - **disabled**

       `boolean` or :term:`calculation`
     - Disabled variable.

       Allows us to deactivate a variable.

       This means that the variable will no longer be visible to the user but also to a :term:`calculation`.

       **Default value**: `false`.
   * - **mandatory**

       `boolean` or :term:`calculation`
     - Mandatory variable.

       Variable whose value is `required`.

       For a multiple variable, this means that the list shall not be empty.

       **Default value**: `true`
   * - **redefine**

       `boolean`
     - It is possible to define a variable in one :term:`structure file` and change its behavior in a second :term:`structure file`. In this case you must explicitly redefine the variable.

       **Default value**: `false`
   * - **exists**

       `boolean`
     - This attribute does two things:

         - creates a variable if it does not exist in another :term:`structure file` (otherwise do nothing), in this case the value of the attribute must be `true`
         - in conjunction with the `redefine` attribute set to `true`, only modifies the behavior if it is pre-existing, in which case the attribute's value must be `false`.

       **Default value**: `null`
   * - **test**

       `list`
     - The `test` attribute is a special attribute that allows :term:`structure file` designers to influence a test robot by specifying useful values to test.

       Concretely, the content of this attribute is recorded in the `information` attribute of the corresponding `Tiramisu` option object.

Variables type list
--------------------

A variable **always has a type**. The system is **strongly** typed.

Depending on the definition of the variable type, the defined variable will accept values ​​of the associated type.

.. list-table::
   :widths: 15 25 20 15
   :header-rows: 1

   * - Value
     - Comments
     - Parameters
     - Samples

   * - string
     - character string (default type)
     -
     - test

       "1"

       "true"
   * - integer
     - a integer
     - `min_integer`: minimum integer allowed

       `max_integer`: maximum integer allowed
     - 1
   * - float
     - a floating number
     -
     - 1.2
   * - boolean
     - A boolean, if no value is defined the default value of this variable will be `true`, the variable will also be :term:`mandatory` by default
     -
     - `true`

       `false`
   * - secret
     - a secret (like a password, a private key, etc.)
     -
     - `hO_'hi`
   * - mail
     - a mail address
     -
     - test@rougail.example
   * - unix_filename
     - a file name in the Unix meaning
     -
     - :file:`/etc/passwd`
   * - date
     - a date in the format `%Y-%m-%d`
     -
     - `2021-01-30`
   * - unix_user
     - a user in the Unix meaning
     -
     - test
   * - ip
     - any kind of IPv4 address
     - `private_only`: only private IPs (`false` by default)

       `allow_reserved`: allows reserved IPs (`true` by default)
     - `1.2.3.4`
   * - cidr
     - any IPv4 address in the CIDR format
     - `private_only`: only private IPs (`false` by default)

       `allow_reserved`: allows reserved IPs (`false` by default)
     - `1.2.3.4/24`
   * - netmask
     - mask of an IPv4 address
     -
     - `255.255.255.0`
   * - network
     - network address
     -
     - `192.168.1.0`
   * - network_cidr
     - network address in CIDR format
     -
     - `192.168.1.0/24`
   * - broadcast
     - broadcast address
     -
     - `255.255.255.255`
   * - netbios
     - netbios name
     -
     - machine
   * - domainname
     - domain name
     - `allow_ip`: allows an IP rather than a domain name (`false` by default)

       `allow_cidr_network`: allows a CIDR type network address (`false` by default)

       `allow_without_dot`: allows names without a dot (`false` by default)

       `allow_startswith_dot`: allows starting with a point (`false` by default)
     - `rougail.example`
   * - hostname
     - host name
     - `allow_ip`: allows an IP rather than a domain name (`false` by default)
     - machine
   * - web_address
     - web address
     - `allow_ip`: allows an IP rather than a domain name (`false` by default)

       `allow_without_dot`: allows names without a dot (`true` by default)
     - http://rougail.example
   * - port
     - port
     - `allow_range`: allows a port range, for example 80:85 (`false` by default)

       `allow_zero`: allows port 0 (false by default)

       `allow_wellknown`: allows ports from 1 to 1023 (`true` by default)

       `allow_registred`: allows ports from 1024 to 49151 (`true` by default)

       `allow_private`: allows ports greater than 49152 (`true` by default)

        `allow_protocol`: allows the addition of the protocol, for example tcp:80 (`false` by default)

     - 8080
   * - mac
     - MAC address
     -
     - 11:11:11:11:11:11
   * - unix_permissions
     - access rights to the file, directory, etc.
     -
     - 644
   * - choice
     - choice variable
     -
     -
