593 lines
18 KiB
ReStructuredText
593 lines
18 KiB
ReStructuredText
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`
|