361 lines
11 KiB
ReStructuredText
361 lines
11 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, 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.
|
||
|
||
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
|
||
-
|
||
-
|