gnunux@silique.fr
e2d62211ec
Co-authored-by: Emmanuel Garette <egarette@silique.fr> Co-authored-by: gwen <gwenaelremond@free.fr> Reviewed-on: #20 Co-authored-by: gnunux@silique.fr <gnunux@silique.fr> Co-committed-by: gnunux@silique.fr <gnunux@silique.fr>
306 lines
9.1 KiB
ReStructuredText
306 lines
9.1 KiB
ReStructuredText
The variables
|
|
===================
|
|
|
|
Synopsis
|
|
------------
|
|
|
|
.. glossary::
|
|
|
|
variable
|
|
variables
|
|
|
|
A variable is an abstract black box (container) paired with an associated symbolic name, which contains some defined or undefined quantity of data referred to as a `value`.
|
|
|
|
.. discussion:: This definition, makes a heavy use of data typing.
|
|
Indeed, depending on the type system definition of the constistency handling system used, 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 this is not just about typing.
|
|
|
|
Name
|
|
-------------
|
|
|
|
Variable's associated symbolic name.
|
|
|
|
It's best to follow the :ref:`convention on variable names`.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
---
|
|
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 `number` 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`
|
|
* - **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:`dictionary` and change its behavior in a second :term:`dictionary`. 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:`dictionary` (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:`dictionary` 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 types
|
|
----------------
|
|
|
|
A variable **has a type**.
|
|
|
|
This type enables the variable to define the values that are accepted by this variable.
|
|
|
|
.. list-table::
|
|
:widths: 15 25 20 15
|
|
:header-rows: 1
|
|
|
|
* - Value
|
|
- Comments
|
|
- Parameters
|
|
- Samples
|
|
|
|
* - string
|
|
- character string (default type)
|
|
-
|
|
- test
|
|
|
|
"1"
|
|
|
|
"true"
|
|
* - number
|
|
- a number
|
|
- `min_number`: minimum number allowed
|
|
|
|
`max_number`: maximum number 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
|
|
-
|
|
-
|