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

doc(calculation)

Browse source
This commit is contained in:
egarette@silique.fr 2026-06-15 22:13:26 +02:00
parent 3be1324da3
commit 2557e9e2da
2 changed files with 289 additions and 314 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

601
docs/format_content/calculation.rst
View file

@ -1,18 +1,19 @@
.. _calculated_variable:
Calculated default values Calculated default values
============================== ==============================
.. _calculated_variable:
Synopsis Synopsis
----------- -----------
A value can be calculated. In this case we have four possibilities: A value can be calculated. In this case we have four possibilities:
- calculation via Jinja - calculation via Jinja template
- calculation via a variable - calculation via a variable
- calculation via information - calculation via an information
- calculation via a suffix: in the case of a variable in a dynamic family - calculation via a identifier: in a :term:`dynamically built family` returns the current identifier
- calculation via an index: in the case of a follower variable - calculation via an index: in the case of a :term:`follower` variable returns the current index
- calculation via :ref:`the current namespace name <namespace>`
If the user modifies the value of the variable, the default value is no longer used, so the calculation is no longer carried out. This is also the case if the variable has the `auto_save` attribute. If the user modifies the value of the variable, the default value is no longer used, so the calculation is no longer carried out. This is also the case if the variable has the `auto_save` attribute.
@ -20,66 +21,112 @@ On the other hand, if the variable is hidden (with the `hidden` parameter), it i
.. note:: A follower variable cannot be calculated automatically. .. note:: A follower variable cannot be calculated automatically.
.. seealso:: The tutorial with a real world sample :ref:`calculation <tutorial_calc_variable>`
Parameters Parameters
-------------- --------------
Depending on the types of calculation, the parameters will be different: Jinja template
~~~~~~~~~~~~~~
.. list-table:: .. list-table::
:widths: 15 25 20 15
:header-rows: 1 :header-rows: 1
* - Calculation type * - **Calculation type**
- Parameter - **Comment**
* - **type**
`string`
- The value is `jinja`
* - **jinja**
`string`
`mandatory`
- Please set a Jinja template.
* - **params**
`dict`
- Additional parameters passed to the Jinja template (see below).
* - **description**
`string`
- Additional information for the :ref:`documentation <data_documentation>` and the error message in case of return_type is a boolean.
Variable
~~~~~~~~
.. list-table::
:header-rows: 1
* - Parameter
- Comment
- Sample
* - type
`string`
- Calculation type.
This parameter is optional. It is deduced from the presence of the parameter "variable" in a calculation.
- variable
* - variable
`string`
`mandatory`
- Name of the associated variable.
It's better to use :term:`relative path` notation.
- _.my_variable
* - propertyerror
`boolean`
- If access to the variable is not possible due to a property
(for example `disabled`) by default an error is returned.
The overall coherence is not guaranteed.
Default value: `true`
- false
* - optional
`boolean`
- The variable in calculation may not exist. This generates an error. Overall coherence is not guaranteed.
To avoid this set the optional parameter to `true`. In this case, if variable in calculation is not exists, the variable is always accessible.
- true
* - default
`boolean`
- If optional parameter is set to `true` and the variable in calculation is not exist, the variable is accessible.
If you do not want this behavior, set this parameter to `false`.
- false
* - description
`string`
- Rougail engine create a description like "depends on a calculation".
You can personnalize here the calculation description
-
Information
~~~~~~~~~~~
.. list-table::
:header-rows: 1
* - Parameter
- Comments - Comments
- Sample - Sample
* - * - information
- **type**
`string`
`mandatory`
- Type of calculation, possible values are: jinja, variable, information, suffix or index
- jinja
* - Jinja
- **jinja**
`string`
`mandatory`
- Template Jinja. For a multiple variable, each line represents a value.
- `{% if rougail.variable %}`
`{{ rougail.variable }}`
`{% endif %}`
* - Jinja
- **params**
`list`
- Additional parameters passed to the Jinja template
-
* - Variable (`mandatory`)
Information
- **variable**
`string`
- Name of associated variable
- rougail.variable
* - Variable
- **propertyerror**
`boolean`
- If access to the variable is not possible due to a property (for example `disabled`) by default an error is returned. If the attribute is `false`, the calculated value is empty.
**Default value:** `true`
- false
* - Information
- **information**
`string` `string`
@ -87,70 +134,98 @@ Depending on the types of calculation, the parameters will be different:
- Name of the information whose value we want to retrieve. - Name of the information whose value we want to retrieve.
- doc - doc
* - variable
`string`
- Variable's name. If not specified, the information is retrieve in :term:`Tiramisu` Config.
It's better to use :term:`relative path` notation.
- _.my_variable
Params
~~~~~~
In the case of a Jinja type calculation, it is possible to have parameters. In the case of a Jinja type calculation, it is possible to have parameters.
There are two types of parameter: There are two types of params:
- the standard parameters (string, boolean, integer, null), in this case just do: "key: value" - the standard parameters (string, boolean, integer, float or null), in this case just do: "key: value"
- advanced settings (with something like "key: {}":
- the advanced settings: - parameter via a variable
- parameter via an information
- parameter via an identifier: in a :term:`dynamically built family` returns the current identifier
- parameter via an index: in the case of a :term:`follower` variable returns the current index
- parameter via :ref:`the current namespace name <namespace>`
- parameter via a variable Variable params
- parameter via an information """""""""""""""
- parameter via a suffix: in the case of a variable in a dynamic family
- parameter via an index: in the case of a follower variable
.. list-table:: .. list-table::
:widths: 15 25 20 15
:header-rows: 1 :header-rows: 1
* - Parameter type * - **Parameter**
- Parameter - **Comments**
- Comments - **Sample**
- Sample
* - * - **type**
- **name**
`string`
- Type of parameter, which is variable.
- variable
* - **variable**
`string` `string`
`mandatory` `mandatory`
- parameter's name - Variable's path.
- my_param - my_variable
* -
- **type**
`string` * - **propertyerror**
`mandatory`
- parameter's type, possible values are: variable, information, suffix or index
- suffix
* - Variable
- **variable**
`string`
`mandatory`
- Variable's name
- rougail.variable
* - Variable (`mandatory`) information
- **propertyerror**
`boolean` `boolean`
- If access to the variable is not possible due to a property (for example `disabled`) by default an error is returned. If the attribute is `False`, the parameter is not passed to the Jinja template. - If access to the variable is not possible due to a property
- **Default value**: `True` (for example `disabled`) by default an error is returned.
* - Variable If the attribute is `false`, the parameter is not passed to the Jinja template.
- **optional**
**Default value**: `false`
- `true`
* - **optional**
`boolean` `boolean`
- The variable may not exist depending on YAML file imports. - If the variable is not defined the value is always `null`.
If the optional parameter is `True`, the parameter will simply be deleted if the variable does not exist.
Default value : `False` **Default value**: `false`
- True - `true`
* - Information
- **information** * - **whole**
`boolean`
- In :term:`dynamically built family` only the value of the current index is retrieve. If this parameter is set to `true` it returns all
If this parameter is set to `true`, it returns the set of values for all indices.
**Default value**: `false`
- `true`
Information params
~~~~~~~~~~~~~~~~~~
.. list-table::
:header-rows: 1
* - **Parameter**
- **Comments**
- **Sample**
* - **type**
`string`
- Type of parameter, which is information
- information
* - **information**
`string` `string`
@ -158,90 +233,13 @@ There are two types of parameter:
- Name of the information whose value we want to retrieve. - Name of the information whose value we want to retrieve.
- doc - doc
The variable path * - **variable**
-----------------
Normal family `string`
~~~~~~~~~~~~~ - By default, the information is a context information. It is possible to get a variable information. In this case just specify a path.
- my_variable
The default namespace is defined in `RougailConfig["variable_namespace"]` with the default value `rougail`. Sample
In addition, there are extras namespaces defined with in `RougailConfig["extra_dictionaries"]`.
Inside those namespaces we can add families and variables.
Here is an hierarchic examples:
.. code-block::
rougail
├── variable1
├── family1
│ ├── variable2
│ └── variable3
└── family2
└── subfamily1
└── variable4
extra1
└── family3
├── variable5
└── variable6
In `calculation` we can use other variables.
Here are all paths:
- `rougail.variable1`
- `rougail.family1.variable2`
- `rougail.family1.variable3`
- `rougail.family2.subfamily1.variable4`
- `extra1.family3.variable5`
- `extra1.family3.variable6`
Inside a variable's `calculation` we can use relative path. "_" means that other variable is in same family. "__" means that other variables are in parent family, and so on...
For example, in variable2's `calculation`, we can use relative path:
- `__.variable1`
- `_.variable3`
- `__.family2.subfamily1.variable4`
But we cannot access to extra1 variables with relative path.
Dynamic family
~~~~~~~~~~~~~~~~~~
Here is a `{{ suffix }}` dynamic family:
.. code-block::
rougail
├── variable1: ["val1", "val2"]
├── {{ suffix }}
│ ├── variable2
│ └── variable3
└── family
└── variable4
For `variable2`'s calculation, we can use:
- `rougail.{{ suffix }}.variable3`
- `_.variable3`
In this case, we get value for "variable3" with the same suffix as "variable2".
For variable4's calculation, we have two possibility:
- retrieves all values with all suffixes:
- `rougail.{{ suffix }}.variable3`
- `__.{{ suffix }}.variable3`
- retrieves a value for a specified suffix:
- `rougail.val1.variable3`
- `__.val1.variable3`
Examples
----------- -----------
Calculation via a Jinja template Calculation via a Jinja template
@ -251,51 +249,59 @@ Let's start with an example from a simple Jinja template:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_calculated_variable: my_calculated_variable:
default: default:
type: jinja
jinja: 'no' jinja: 'no'
...
Here is a second example with a boolean variable: Here is a second example with a boolean variable:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_calculated_variable: my_calculated_variable:
type: boolean type: boolean
default: default:
type: jinja
jinja: 'false' jinja: 'false'
...
And a multiple value of the integer type: And a multiple value of the integer type:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_calculated_variable: my_calculated_variable:
type: integer type: integer
multi: true multi: true
default: default:
type: jinja
jinja: | jinja: |
1 1
2 2
3 3
...
Let's create a variable whose value is returned by a python function: Let's create a variable whose value is returned by a python function:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_calculated_variable: my_calculated_variable:
default: default:
type: jinja
jinja: '{{ return_no() }}' jinja: '{{ return_no() }}'
...
Then let's create the `return_no` function: Then let's create the `return_no` function:
@ -308,12 +314,13 @@ An example with parameters:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_calculated_variable: my_calculated_variable:
description: my description description: my description
default: default:
type: jinja
jinja: | jinja: |
{{ param1 }}{% if param2 is defined %}_{{ param2 }}{% endif %}_{{ param3 }} {{ param1 }}{% if param2 is defined %}_{{ param2 }}{% endif %}_{{ param3 }}
params: params:
@ -326,50 +333,48 @@ An example with parameters:
type: information type: information
information: doc information: doc
variable: _.my_calculated_variable variable: _.my_calculated_variable
...
An example with a `suffix` type parameter: An example with a `identifier` type parameter:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
varname:
multi: true my_dyn_family_{{ identifier }}:
default: dynamic:
- val1 - val1
- val2 - val2
my_dyn_family_: description: 'Describe {{ identifier }}'
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var: my_dyn_var:
type: string
default: default:
type: jinja jinja: 'the identifier is: {{ param1 }}'
jinja: 'the suffix is: {{ param1 }}'
params: params:
param1: param1:
type: suffix type: identifier
In this example, we see a dynamic family. Two families will be created: `rougail.my_dyn_family_val1.my_dyn_var` and `rougail.my_dyn_family_val2.my_dyn_var`. In this example, we see a :term:`dynamically built family`. Two families will be created: `my_dyn_family_val1.my_dyn_var` and `my_dyn_family_val2.my_dyn_var`.
The value of the variable inside this family 'this suffix is: ' + the value of the suffix (`val1` and `val2` respectively). The value of the variable inside this family 'this identifier is: ' + the value of the identifier (`val1` and `val2` respectively).
An example with an index type parameter: An example with an index type parameter:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
family: family:
type: sequence type: sequence
leader: leader:
multi: true - val1
default: - val2
- val1
- val2
follower1: follower1:
default: default:
type: jinja type: jinja
@ -377,6 +382,7 @@ An example with an index type parameter:
params: params:
param1: param1:
type: index type: index
...
Calculation via a variable Calculation via a variable
----------------------------- -----------------------------
@ -385,30 +391,35 @@ Copy a variable in another:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_variable: my_variable:
multi: true
default: default:
- val1 - val1
- val2 - val2
my_calculated_variable: my_calculated_variable:
multi: true
default: default:
type: variable type: variable
variable: _.my_variable variable: _.my_variable
...
Copy the default value from a variable, means copy type, params and multi attribute too if not define in second variable. Copy the default value from a variable, means copy type, params and multi attribute too if not define in second variable.
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: 1.1 version: 1.1
my_variable: my_variable:
multi: true multi: true
type: domainname type: domainname
params: params:
allow_ip: true allow_ip: true
my_calculated_variable: my_calculated_variable:
default: default:
type: variable type: variable
@ -420,169 +431,133 @@ Copy one variable to another if the source has no `property` problem:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_variable: my_variable:
default: val1 default: val1
disabled: true disabled: true
my_calculated_variable: my_calculated_variable:
multi: true multi: true
default: default:
type: variable
variable: _.my_variable variable: _.my_variable
propertyerror: false propertyerror: false
...
Copy two non-multiple variables into a multiple variable: Copy two non-multiple variables into a multiple variable:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
my_variable_1:
default: val1 my_variable_1: val1
my_variable_2:
default: val2 my_variable_2: val2
my_calculated_variable: my_calculated_variable:
multi: true
default: default:
- type: variable - variable: _.my_variable_1
variable: _.my_variable_1 - variable: _.my_variable_2
- type: variable
variable: _.my_variable_2
A variable in a dynamic family can also be used in a calculation. A variable in a :term:`dynamically built family` can also be used in a calculation.
For example using the variable for a particular suffix: For example using the variable for a particular identifier:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
varname: varname:
multi: true - val1
default: - val2
my_dyn_family_{{ identifier }}:
dynamic:
- val1 - val1
- val2 - val2
my_dyn_family_: description: 'Describe {{ identifier }}'
type: dynamic my_dyn_var_{{ identifier }}:
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
default: default:
type: suffix type: identifier
all_dyn_var: all_dyn_var:
default: default:
type: variable
variable: _.my_dyn_family_val1.my_dyn_var_val1 variable: _.my_dyn_family_val1.my_dyn_var_val1
In this case, we recover the value `val1`. In this case, we recover the value `val1`.
Second example using the variable for all suffixes: Second example using the variable for all identifieres:
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
varname: varname:
multi: true my_dyn_family_{{ identifier }}:
default: dynamic:
- val1 - val1
- val2 - val2
my_dyn_family_: description: 'Describe {{ identifier }}'
type: dynamic
dynamic: my_dyn_var_{{ identifier }}:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
default: default:
type: suffix type: identifier
all_dyn_var: all_dyn_var:
multi: true multi: true
default: default:
type: variable
variable: _.my_dyn_family_.my_dyn_var_ variable: _.my_dyn_family_.my_dyn_var_
...
In this case, we recover the `val1` and `val2` list. In this case, we recover the `val1` and `val2` list.
Calculation via a suffix Calculation via a identifier
--------------------------- ----------------------------
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
varname:
multi: true my_dyn_family_{{ identifier }}:
default: dynamic:
- val1 - val1
- val2 - val2
my_dyn_family_: description: 'Describe {{ identifier }}'
type: dynamic
dynamic: my_dyn_var_{{ identifier }}:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string type: string
default: default:
type: suffix type: identifier
...
Calculation via an index Calculation via an index
-------------------------- --------------------------
.. code-block:: yaml .. code-block:: yaml
%YAML 1.2
--- ---
version: '1.1' version: 1.1
family: family:
type: sequence type: sequence
leader: leader:
multi: true - val1
default: - val2
- val1
- val2
follower1: follower1:
type: integer type: integer
default: default:
type: index type: index
...
Redefinition
----------------
In a first dictionary, let's declare our variable and our calculation:
.. code-block:: yaml
---
version: '1.1'
my_calculated_variable:
default:
type: jinja
jinja: 'the value is calculated'
In a second dictionary, it is possible to redefine the calculation:
.. code-block:: yaml
---
version: '1.1'
my_calculated_variable:
redefine: true
default:
type: jinja
jinja: 'the value is redefined'
In a third dictionary, we even can delete the calculation if needed:
.. code-block:: yaml
---
version: '1.1'
my_calculated_variable:
redefine: true
default: null

2
docs/format_content/validation.rst
View file

@ -74,7 +74,7 @@ There are two types of params:
- parameter via a variable - parameter via a variable
- parameter via an information - parameter via an information
- parameter via an identifier: in a dynamic family returns the current identifier - parameter via an identifier: in a :ref:`dynamically built family` returns the current identifier
- parameter via an index: in the case of a :term:`follower` variable returns the current index - parameter via an index: in the case of a :term:`follower` variable returns the current index
- parameter via :ref:`the current namespace name <namespace>` - parameter via :ref:`the current namespace name <namespace>`