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_variable:
Synopsis
-----------
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 information
- calculation via a suffix: in the case of a variable in a dynamic family
- calculation via an index: in the case of a follower variable
- calculation via an information
- calculation via a identifier: in a :term:`dynamically built family` returns the current identifier
- 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.
@ -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.
.. seealso:: The tutorial with a real world sample :ref:`calculation <tutorial_calc_variable>`
Parameters
--------------
Depending on the types of calculation, the parameters will be different:
Jinja template
~~~~~~~~~~~~~~
.. list-table::
:widths: 15 25 20 15
:header-rows: 1
* - Calculation type
- Parameter
* - **Calculation type**
- **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
- Sample
* -
- **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**
* - information
`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.
- 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.
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
- 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
Variable params
"""""""""""""""
.. list-table::
:widths: 15 25 20 15
:header-rows: 1
* - Parameter type
- Parameter
- Comments
- Sample
* - **Parameter**
- **Comments**
- **Sample**
* -
- **name**
* - **type**
`string`
- Type of parameter, which is variable.
- variable
* - **variable**
`string`
`mandatory`
- parameter's name
- my_param
* -
- **type**
- Variable's path.
- my_variable
`string`
`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**
* - **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 parameter is not passed to the Jinja template.
- **Default value**: `True`
* - Variable
- **optional**
- 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.
**Default value**: `false`
- `true`
* - **optional**
`boolean`
- The variable may not exist depending on YAML file imports.
If the optional parameter is `True`, the parameter will simply be deleted if the variable does not exist.
- If the variable is not defined the value is always `null`.
Default value : `False`
- True
* - Information
- **information**
**Default value**: `false`
- `true`
* - **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`
@ -158,90 +233,13 @@ There are two types of parameter:
- Name of the information whose value we want to retrieve.
- 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`.
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
Sample
-----------
Calculation via a Jinja template
@ -251,51 +249,59 @@ Let's start with an example from a simple Jinja template:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_calculated_variable:
default:
type: jinja
jinja: 'no'
...
Here is a second example with a boolean variable:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_calculated_variable:
type: boolean
default:
type: jinja
jinja: 'false'
...
And a multiple value of the integer type:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_calculated_variable:
type: integer
multi: true
default:
type: jinja
jinja: |
1
2
3
...
Let's create a variable whose value is returned by a python function:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_calculated_variable:
default:
type: jinja
jinja: '{{ return_no() }}'
...
Then let's create the `return_no` function:
@ -308,12 +314,13 @@ An example with parameters:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_calculated_variable:
description: my description
default:
type: jinja
jinja: |
{{ param1 }}{% if param2 is defined %}_{{ param2 }}{% endif %}_{{ param3 }}
params:
@ -326,50 +333,48 @@ An example with parameters:
type: information
information: doc
variable: _.my_calculated_variable
...
An example with a `suffix` type parameter:
An example with a `identifier` type parameter:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
varname:
multi: true
default:
version: 1.1
my_dyn_family_{{ identifier }}:
dynamic:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
description: 'Describe {{ identifier }}'
my_dyn_var:
type: string
default:
type: jinja
jinja: 'the suffix is: {{ param1 }}'
jinja: 'the identifier is: {{ param1 }}'
params:
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:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
family:
type: sequence
leader:
multi: true
default:
- val1
- val2
- val1
- val2
follower1:
default:
type: jinja
@ -377,6 +382,7 @@ An example with an index type parameter:
params:
param1:
type: index
...
Calculation via a variable
-----------------------------
@ -385,30 +391,35 @@ Copy a variable in another:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_variable:
multi: true
default:
- val1
- val2
my_calculated_variable:
multi: true
default:
type: 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.
.. code-block:: yaml
%YAML 1.2
---
version: 1.1
my_variable:
multi: true
type: domainname
params:
allow_ip: true
my_calculated_variable:
default:
type: variable
@ -420,169 +431,133 @@ Copy one variable to another if the source has no `property` problem:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
my_variable:
default: val1
disabled: true
my_calculated_variable:
multi: true
default:
type: variable
variable: _.my_variable
propertyerror: false
...
Copy two non-multiple variables into a multiple variable:
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
my_variable_1:
default: val1
my_variable_2:
default: val2
version: 1.1
my_variable_1: val1
my_variable_2: val2
my_calculated_variable:
multi: true
default:
- type: variable
variable: _.my_variable_1
- type: variable
variable: _.my_variable_2
- variable: _.my_variable_1
- 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
%YAML 1.2
---
version: '1.1'
version: 1.1
varname:
multi: true
default:
- val1
- val2
my_dyn_family_{{ identifier }}:
dynamic:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
description: 'Describe {{ identifier }}'
my_dyn_var_{{ identifier }}:
default:
type: suffix
type: identifier
all_dyn_var:
default:
type: variable
variable: _.my_dyn_family_val1.my_dyn_var_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
%YAML 1.2
---
version: '1.1'
version: 1.1
varname:
multi: true
default:
my_dyn_family_{{ identifier }}:
dynamic:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
description: 'Describe {{ identifier }}'
my_dyn_var_{{ identifier }}:
default:
type: suffix
type: identifier
all_dyn_var:
multi: true
default:
type: variable
variable: _.my_dyn_family_.my_dyn_var_
...
In this case, we recover the `val1` and `val2` list.
Calculation via a suffix
---------------------------
Calculation via a identifier
----------------------------
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
varname:
multi: true
default:
version: 1.1
my_dyn_family_{{ identifier }}:
dynamic:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
description: 'Describe {{ identifier }}'
my_dyn_var_{{ identifier }}:
type: string
default:
type: suffix
type: identifier
...
Calculation via an index
--------------------------
.. code-block:: yaml
%YAML 1.2
---
version: '1.1'
version: 1.1
family:
type: sequence
leader:
multi: true
default:
- val1
- val2
- val1
- val2
follower1:
type: integer
default:
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 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 :ref:`the current namespace name <namespace>`