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`.
If the `type` parameter is not set, Rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.
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 :ref:`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 :ref:`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 :ref:`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 :ref:`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
The value of the variable will be considered invalid if the Jinja template return an error.
..seealso:: tutorial with a real world sample :ref:`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 :ref:`default parameter <tutorial/preliminary>`
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.
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>`).
..seealso:: tutorial with a real world sample :ref:`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.
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.
..seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
..seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>` (the tutorial focuses on family, but the principle is the same for a variable)
- 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.
- 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`.
