diff --git a/docs/variable.rst b/docs/variable.rst index daafb7a50..1eab898dc 100644 --- a/docs/variable.rst +++ b/docs/variable.rst @@ -10,17 +10,17 @@ Synopsis 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. + 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 @@ -28,12 +28,13 @@ 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. Attention, do not declare any other attributs. +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 comment in same line of name, this comment is use has description. +If you add a comment in the same line of the name, this comment will be used has a description. .. code-block:: yaml @@ -47,42 +48,42 @@ If you add comment in same line of name, this comment is use has description. Parameters ------------- -.. list-table:: +.. list-table:: :widths: 15 45 :header-rows: 1 - + * - Parameter - Comments - + * - **help** - `string` + `string` - Additional help associated with the variable. - - * - **default** + + * - **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. + + Jinja template list. The value of the variable will be considered invalid if the template has a return value. * - **auto_save** - `boolean` + `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` @@ -90,11 +91,11 @@ Parameters `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 @@ -112,19 +113,19 @@ Parameters **Default value**: `false` * - **hidden** - `boolean` or :term:`calculation` + `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` + `boolean` or :term:`calculation` - Disabled variable. Allows us to deactivate a variable. @@ -134,7 +135,7 @@ Parameters **Default value**: `false`. * - **mandatory** - `boolean` or :term:`calculation` + `boolean` or :term:`calculation` - Mandatory variable. Variable whose value is `required`. @@ -155,74 +156,74 @@ Parameters - 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:: +.. 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 + - 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 - - + * - mail + - a mail address + - - test@rougail.example * - unix_filename - a file name in the Unix meaning - - + - - :file:`/etc/passwd` - * - date + * - date - a date in the format `%Y-%m-%d` - - + - - `2021-01-30` * - unix_user - - a user in the Unix meaning - - + - a user in the Unix meaning + - - test * - ip - any kind of IPv4 address @@ -233,73 +234,73 @@ This type enables the variable to define the values that are accepted by this va * - cidr - any IPv4 address in the CIDR format - `private_only`: only private IPs (`false` by default) - - `allow_reserved`: allows reserved 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 - - + - netbios name + - - machine * - domainname - - domain name + - 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 + * - 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 + * - 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 - - - - + * - choice + - choice variable + - + -