stove/rougail
3
0
Fork 0
Code Issues 10 Pull requests 1 Projects Releases Wiki Activity

shorthand declaration #20

Merged
gremond merged 2 commits from shorthand into develop 2024-07-01 14:07:00 +02:00
Conversation 0 Commits 2 Files changed 127 +76 -75
1 changed files with 76 additions and 75 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit 6b34dd8678 - Show all commits

151
docs/variable.rst
View file

@ -10,17 +10,17 @@ Synopsis
variables 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`. 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. .. 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. 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. But this is not just about typing.
Name Name
------------- -------------
Variable's associated symbolic name. Variable's associated symbolic name.
It's best to follow the :ref:`convention on variable names`. It's best to follow the :ref:`convention on variable names`.
Shorthand declaration 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. 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. To declare a multi variable just add a list as default value.
By default, the description of the variable is the variable name. 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 .. code-block:: yaml
@ -47,42 +48,42 @@ If you add comment in same line of name, this comment is use has description.
Parameters Parameters
------------- -------------
.. list-table:: .. list-table::
:widths: 15 45 :widths: 15 45
:header-rows: 1 :header-rows: 1
* - Parameter * - Parameter
- Comments - Comments
* - **help** * - **help**
`string` `string`
- Additional help associated with the variable. - Additional help associated with the variable.
* - **default** * - **default**
- Default value(s) of the variable. - 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, ... 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. 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** * - **validators**
`list` `list`
- Value validators. - 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** * - **auto_save**
`boolean` `boolean`
- Variable with automatically modified value. - 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). 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. 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. 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. A :term:`leader` or :term:`follower` variable cannot have the `auto_save` property.
**Default value**: `false` **Default value**: `false`
@ -90,11 +91,11 @@ Parameters
`string` `string`
- Variable's mode. - Variable's mode.
**Default value**: The `default` mode of a variable is the mode of the parent family. **Default value**: The `default` mode of a variable is the mode of the parent family.
Special cases : Special cases :
- a variable with an automatically modified value or an automatic read-only variable is by default in `basic` mode - 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 - 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 - a :term:`mandatory` variable without default value (calculate or not) will have a `basic` mode
@ -112,19 +113,19 @@ Parameters
**Default value**: `false` **Default value**: `false`
* - **hidden** * - **hidden**
`boolean` or :term:`calculation` `boolean` or :term:`calculation`
- Invisible variable. - Invisible variable.
Enables us to *hide* a 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. 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. 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` **Default value**: `false`
* - **disabled** * - **disabled**
`boolean` or :term:`calculation` `boolean` or :term:`calculation`
- Disabled variable. - Disabled variable.
Allows us to deactivate a variable. Allows us to deactivate a variable.
@ -134,7 +135,7 @@ Parameters
**Default value**: `false`. **Default value**: `false`.
* - **mandatory** * - **mandatory**
`boolean` or :term:`calculation` `boolean` or :term:`calculation`
- Mandatory variable. - Mandatory variable.
Variable whose value is `required`. 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` - 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`. - 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` **Default value**: `null`
* - **test** * - **test**
`list` `list`
- The `test` attribute is a special attribute that allows :term:`dictionary` designers to influence a test robot by specifying useful values to test. - 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. Concretely, the content of this attribute is recorded in the `information` attribute of the corresponding `Tiramisu` option object.
Variables types Variables types
---------------- ----------------
A variable **has a type**. A variable **has a type**.
This type enables the variable to define the values that are accepted by this variable. This type enables the variable to define the values that are accepted by this variable.
.. list-table:: .. list-table::
:widths: 15 25 20 15 :widths: 15 25 20 15
:header-rows: 1 :header-rows: 1
* - Value * - Value
- Comments - Comments
- Parameters - Parameters
- Samples - Samples
* - string * - string
- character string (default type) - character string (default type)
- -
- test - test
"1" "1"
"true" "true"
* - number * - number
- a number - a number
- `min_number`: minimum number allowed - `min_number`: minimum number allowed
`max_number`: maximum number allowed `max_number`: maximum number allowed
- 1 - 1
* - float * - float
- a floating number - a floating number
- -
- 1.2 - 1.2
* - boolean * - 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 - 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` - `true`
`false` `false`
* - secret * - secret
- a secret (like a password, a private key, etc.) - a secret (like a password, a private key, etc.)
- -
- `hO_'hi` - `hO_'hi`
* - mail * - mail
- a mail address - a mail address
- -
- test@rougail.example - test@rougail.example
* - unix_filename * - unix_filename
- a file name in the Unix meaning - a file name in the Unix meaning
- -
- :file:`/etc/passwd` - :file:`/etc/passwd`
* - date * - date
- a date in the format `%Y-%m-%d` - a date in the format `%Y-%m-%d`
- -
- `2021-01-30` - `2021-01-30`
* - unix_user * - unix_user
- a user in the Unix meaning - a user in the Unix meaning
- -
- test - test
* - ip * - ip
- any kind of IPv4 address - 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 * - cidr
- any IPv4 address in the CIDR format - any IPv4 address in the CIDR format
- `private_only`: only private IPs (`false` by default) - `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` - `1.2.3.4/24`
* - netmask * - netmask
- mask of an IPv4 address - mask of an IPv4 address
- -
- `255.255.255.0` - `255.255.255.0`
* - network * - network
- network address - network address
- -
- `192.168.1.0` - `192.168.1.0`
* - network_cidr * - network_cidr
- network address in CIDR format - network address in CIDR format
- -
- `192.168.1.0/24` - `192.168.1.0/24`
* - broadcast * - broadcast
- broadcast address - broadcast address
- -
- `255.255.255.255` - `255.255.255.255`
* - netbios * - netbios
- netbios name - netbios name
- -
- machine - machine
* - domainname * - domainname
- domain name - domain name
- `allow_ip`: allows an IP rather than a domain name (`false` by default) - `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_cidr_network`: allows a CIDR type network address (`false` by default)
`allow_without_dot`: allows names without a dot (`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) `allow_startswith_dot`: allows starting with a point (`false` by default)
- `rougail.example` - `rougail.example`
* - hostname * - hostname
- host name - host name
- `allow_ip`: allows an IP rather than a domain name (`false` by default) - `allow_ip`: allows an IP rather than a domain name (`false` by default)
- machine - machine
* - web_address * - web_address
- web address - web address
- `allow_ip`: allows an IP rather than a domain name (`false` by default) - `allow_ip`: allows an IP rather than a domain name (`false` by default)
`allow_without_dot`: allows names without a dot (`true` by default) `allow_without_dot`: allows names without a dot (`true` by default)
- http://rougail.example - http://rougail.example
* - port * - port
- port - port
- `allow_range`: allows a port range, for example 80:85 (`false` by default) - `allow_range`: allows a port range, for example 80:85 (`false` by default)
`allow_zero`: allows port 0 (false by default) `allow_zero`: allows port 0 (false by default)
`allow_wellknown`: allows ports from 1 to 1023 (`true` 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_registred`: allows ports from 1024 to 49151 (`true` by default)
`allow_private`: allows ports greater than 49152 (`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) `allow_protocol`: allows the addition of the protocol, for example tcp:80 (`false` by default)
- 8080 - 8080
* - mac * - mac
- MAC address - MAC address
- -
- 11:11:11:11:11:11 - 11:11:11:11:11:11
* - unix_permissions * - unix_permissions
- access rights to the file, directory, etc. - access rights to the file, directory, etc.
- -
- 644 - 644
* - choice * - choice
- choice variable - choice variable
- -
- -