rougail/docs/variable.rst

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

Synopsis
---------

.. glossary::

   variable

       A variable is an abstract black box (container) paired with an associated symbolic name, most often an option configuration, which 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
------

It is with its name that we will be able to interact with the variable.

.. seealso::

   Have a look at the :ref:`variable naming convention <namingconvention>`

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

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

   * - Parameter
     - Comments

   * - **description**

       `string`
     - Description of the variable.

       User information to understand the usefulness of the variable.

       .. seealso:: tutorial with a real world sample :doc:`description parameter <tutorial/preliminary>`

   * - **help**

       `string`
     - Additional help associated with the variable.

       .. seealso:: tutorial with a real world sample :doc:`help parameter <tutorial/examples>`

   * - **mode**

       `string`
     - Variable's mode.

       The mode is a way of classifying the importance, the level of expertise required, or the access rights to a variable.

       This parameter allows you to define the variable mode.

       .. attention:: Mode is not configured by default. You have to define mode level before use this parameter.

       **Default value**: The `default` mode of a variable is the mode of the parent family, but there is special cases:

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

       .. seealso:: tutorial with a real world sample :doc:`mode parameter <tutorial/mode>`

   * - **tags**

       `list of strings`
     - A tag allows you to specialize a variable.

       A tag can have several functions:

       - Additional information in the documentation
       - Variable exclusion
       - Variable selection
       - and so on

   * - **examples**

       `list`
     - List of examples to illustrate possible values for a variable

       .. seealso:: tutorial with a real world sample :doc:`examples parameter <tutorial/examples>`

   * - **test**

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

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

   * - **type**

       `string`
     - Type of the variable.

       See the list of available type below.

       .. seealso:: tutorial with a real world sample :doc:`type parameter <tutorial/types>`

   * - **params**

       `object`
     - Parameters to adjust type validation of the variable.

       See the list of available parameters for each type below.

       .. seealso:: tutorial with a real world sample :doc:`params parameter <tutorial/types>`

   * - **multi**

       `boolean`

     - The value of the variable is a list.

       **Default value**: mostly `false`, but there is special cases:

       - the default value is a list
       - a variable with a variable :term:`multiple <multi>` has default value

       It possible to adjust multi parameters with **params**:

       - 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

       .. seealso:: tutorial with a real world sample :doc:`multi parameter <tutorial/multiple>`

   * - **validators**

       `list`
     - Value validators.

       The value of the variable will be considered invalid if the Jinja template return an error.

       .. seealso:: tutorial with a real world sample :doc:`validators parameter <tutorial/validators>`

   * - **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 :term:`multiple <multi>` variable must be a `list` type, ...

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

       .. seealso:: tutorial with a real world sample :doc:`default parameter <tutorial/preliminary>`

   * - **secret_manager**
     - The variable use a secret manager to get value
       .. todo:: document it

   * - **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.

       **Default value**: `false`

       .. seealso:: tutorial with a real world sample :doc:`auto_save parameter <tutorial/autosave>`

   * - **mandatory**

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

       Variable whose value is `required`.

       For a :term:`multiple <multi>` variable, this means that the list shall not be empty (means `null` (`None`) or empty list for a i:term:`multiple <multi>`).

       **Default value**: `true`

       .. seealso:: tutorial with a real world sample :doc:`mandatory parameter <tutorial/nullable>`

   * - **empty**

       `boolean` or :term:`calculation`
     - The value `null` (`None`) is not allowed in :term:`multiple <multi>` variable.

       The `mandatory` control only if the length :term:`multiple <multi>` variable is not 0. But the `null` value is not allowed. With empty parameter we can allowed it.

       If `null` is an appropriate value, set empty: false.

       **Default value**: `true`

   * - **unique**

       `boolean`
     - The :term:`multiple <multi>` variable accepts the same value several times.

       If unique is set to `false`, a :term:`multiple <multi>` 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`

       .. seealso:: tutorial with a real world sample :doc:`hidden parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)

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

       **Default value**: `false`

       .. seealso:: tutorial with a real world sample :doc:`disabled parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)

   * - **frozen**

       `boolean` or :term:`calculation`
     - Read only variable.

       Enables us to have an immutable variable.

       This means that the variable will be visible but user will not allowed to change the value.

       **Default value**: `false`


   * - **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 parameter 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 parameter must be `true`
         - in conjunction with the `redefine` parameter set to `true`, only modifies the behavior if it is pre-existing, in which case the parameter's value must be `false`.

       **Default value**: `null`

   * - **choices**

       :term:`calculation` or a list of :term:`calculation` or data
     - Available choices.

       .. important:: This parameter is only available for variable with `choice` type.

   * - **regexp**

       `string`
     - Validation with a regular expressions.

       .. important:: This parameter is only available for variable with `regexp` type.

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

Shorthand declaration is a way to declare a variable in a condenced number of line.

To create a variable, just add a key with it's name:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1

    my_variable:
    ...

You can add a default value:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1

    my_variable: my_value
    ...

Or a multi default value:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1

    my_variable:
      - my_value_1
      - my_value_2
    ...

By default, the description of the variable is the variable name.
It's a best practice to description a variable. Just add comment in same line of name, this comment is use as description:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1

    my_variable: my_value  # This is a great variable
    ...

But in shorthand notation, you can only define variable name, default value, multi and description.

.. attention:: Any other parameters will create extra variables or families

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


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

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.

Primitive Types
'''''''''''''''''''

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

   * - Value
     - Comments
     - Parameters
     - Samples

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

       "1"

       "true"

   * - integer
     - a integer
     - `min_integer`: minimum integer allowed (unlimited by default)

       `max_integer`: maximum integer allowed (unlimited by default)
     - 42

   * - float
     - a floating number
     -
     - 1.42

   * - 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

       .. seealso:: tutorial with a real world sample :doc:`boolean type variable <tutorial/types>`
     -
     - `true`

       `false`

Specialized type
''''''''''''''''''

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

   * - Value
     - Comments
     - Parameters
     - Samples

   * - secret
     - a secret (like a password, a private key, etc.)

       .. seealso:: tutorial with a real world sample :doc:`secret type variable <tutorial/redefine>`
     - `min_len`: minimum characters length for the secret (unlimited by default)

       `max_len`: maximum characters length for the secret (unlimited by default)

       `forbidden_char`: forbidden characters (no character default)
     - `hO_'hi`

   * - mail
     - a mail address
     -
     - test@rougail.example

   * - unix_filename
     - a file name in the Unix meaning
     - `allow_relative`: this filename could be a relative path (`false` by default)

       `test_existence`: this file must exist (`false` by default)

       `types`: "file type allowed ("file", "directory")
     - :file:`/etc/passwd`

   * - date
     - a date in the format `%Y-%m-%d`
     -
     - `2021-01-30`

   * - unix_user
     - a user in the Unix meaning

       .. seealso:: tutorial with a real world sample :doc:`unix type variable <tutorial/redefine>`
     -
     - test

   * - ip
     - any kind of IPv4 address
     - `private_only`: only private IPs (`false` by default)

       `allow_reserved`: allows reserved IPs (`true` by default)

       `cidr`: IP must be in CIDR format (`false` by default)
     - `1.2.3.4`

   * - netmask
     - mask of an IPv4 address
     -
     - `255.255.255.0`

   * - network
     - network address
     - `cidr`: network must be in CIDR format (`false` by default)

       `private_only`: private network are allowed (`false` by default)
       
       `allow_reserved`: reserved network are allowed (`false` by default)
     - `192.168.1.0`

   * - broadcast
     - broadcast address
     -
     - `1.1.1.255`

   * - domainname
     - domain name
     - `type`: type of domain name (`domainname` (by default), `netbios`, `hostname`)

       `allow_ip`: the domain name can be an IP (`false` by default)

       `allow_cidr_network`: the domain name can be network in CIDR format (`false` by default)

       `allow_without_dot`: the domain name can be a hostname (`false` by default)

       `allow_startswith_dot`: the domain name can starts by a dot (`false` by default)

       `test_existence`: the domain name must exist (`false` by default)

       .. seealso:: tutorial with a real world sample :doc:`domainname type variable <tutorial/types>` or :doc:`a more complet domainname type variable <tutorial/multiple>`
     - `rougail.example`

   * - web_address
     - web address
     - `type`: type of domain name (`domainname` (by default), `netbios`, `hostname`)

       `allow_ip`: the domain name can be an IP (`false` by default)

       `allow_cidr_network`: the domain name can be network in CIDR format (`false` by default)

       `allow_without_dot`: the domain name can be a hostname (`false` by default)

       `allow_startswith_dot`: the domain name can starts by a dot (`false` by default)

       `test_existence`: the domain name must exist (`false` by default)

       `allow_range`: can be range of port, for example 80:85 (`false` by default)

       `allow_zero`: port 0 is allowed (false by default)

       `allow_wellknown`: well-known ports (1 to 1023) are allowed (`true` by default)

       `allow_registred`: registred ports (1024 to 49151) are allowed (`true` by default)

       `allow_private`: private ports (greater than 49152) are allowed (`false` by default)

       .. seealso:: tutorial with a real world sample :doc:`web_address type variable <tutorial/webaddress>`
     - http://rougail.example

   * - port
     - port
     - `allow_range`: can be range of port, for example 80:85 (`false` by default)

       `allow_zero`: port 0 is allowed (false by default)

       `allow_wellknown`: well-known ports (1 to 1023) are allowed (`true` by default)

       `allow_registred`: registred ports (1024 to 49151) are allowed (`true` by default)

       `allow_private`: private ports (greater than 49152) are allowed (`false` by default)

       .. seealso:: tutorial with a real world sample :doc:`port type variable <tutorial/types>`
     - 8080

   * - mac
     - MAC address
     -
     - 11:11:11:11:11:11

   * - unix_permissions
     - access rights to the file, directory, etc.
     -
     - 644

   * - choice
     - available choices

       .. seealso:: tutorial with a real world sample :doc:`choice type variable <tutorial/choice>`
     -
     -

   * - regexp
     - Validation with a regular expressions
       
       .. seealso:: tutorial with a real world sample :doc:`regexp type variable <tutorial/regexp>`
     -
     - r"^#(?:[0-9a-f]{3}){1,2}$"

Default type
''''''''''''''

If the `type` parameter is not set, Rougail has to define a logical type to valid correctly values:

- if `choices` or `regexp` parameter is set, Rougail will set the `choice` or `regexp` type

.. seealso:: tutorial with a real world sample :doc:`choice deducted type <tutorial/choice>` or :doc:`regexp deducted type <tutorial/regexp>`

- if a default value is define, Rougail will infers default value type and set a primitive type to the variable

.. seealso:: tutorial with a real world sample :doc:`type inference <tutorial/types>`

- if a variable calculation is define as default value, Rougail copy the type

.. seealso:: tutorial with a real world sample :doc:`type copying <tutorial/calculated>`

- the default type is `string`