563 lines
11 KiB
ReStructuredText
563 lines
11 KiB
ReStructuredText
.. _calculated_variable:
|
||
|
||
Calculated default values
|
||
==============================
|
||
|
||
Synopsis
|
||
-----------
|
||
|
||
A value can be calculated. In this case we have four possibilities:
|
||
|
||
- calculation via Jinja template
|
||
- calculation via a 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.
|
||
|
||
On the other hand, if the variable is hidden (with the `hidden` parameter), it is the default value that is used and not the value customized by the user.
|
||
|
||
.. note:: A follower variable cannot be calculated automatically.
|
||
|
||
.. seealso:: The tutorial with a real world sample :ref:`calculation <tutorial_calc_variable>`
|
||
|
||
Parameters
|
||
--------------
|
||
|
||
Jinja template
|
||
~~~~~~~~~~~~~~
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **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
|
||
|
||
* - information
|
||
|
||
`string`
|
||
|
||
`mandatory`
|
||
- 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 params:
|
||
|
||
- the standard parameters (string, boolean, integer, float or null), in this case just do: "key: value"
|
||
- advanced settings (with something like "key: {}":
|
||
|
||
- 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>`
|
||
|
||
Variable params
|
||
"""""""""""""""
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
|
||
* - **Parameter**
|
||
- **Comments**
|
||
- **Sample**
|
||
|
||
* - **type**
|
||
|
||
`string`
|
||
- Type of parameter, which is variable.
|
||
- variable
|
||
|
||
* - **variable**
|
||
|
||
`string`
|
||
|
||
`mandatory`
|
||
- Variable's path.
|
||
- 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.
|
||
If the attribute is `false`, the parameter is not passed to the Jinja template.
|
||
|
||
**Default value**: `false`
|
||
- `true`
|
||
|
||
* - **optional**
|
||
|
||
`boolean`
|
||
- If the variable is not defined the value is always `null`.
|
||
|
||
**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`
|
||
|
||
`mandatory`
|
||
- Name of the information whose value we want to retrieve.
|
||
- doc
|
||
|
||
* - **variable**
|
||
|
||
`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
|
||
|
||
Sample
|
||
-----------
|
||
|
||
Calculation via a Jinja template
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
Let's start with an example from a simple Jinja template:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_calculated_variable:
|
||
default:
|
||
jinja: 'no'
|
||
...
|
||
|
||
Here is a second example with a boolean variable:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_calculated_variable:
|
||
type: boolean
|
||
default:
|
||
jinja: 'false'
|
||
...
|
||
|
||
And a multiple value of the integer type:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_calculated_variable:
|
||
type: integer
|
||
multi: true
|
||
default:
|
||
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
|
||
|
||
my_calculated_variable:
|
||
default:
|
||
jinja: '{{ return_no() }}'
|
||
...
|
||
|
||
Then let's create the `return_no` function:
|
||
|
||
.. code-block:: python
|
||
|
||
def return_no():
|
||
return 'no'
|
||
|
||
An example with parameters:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_calculated_variable:
|
||
description: my description
|
||
default:
|
||
jinja: |
|
||
{{ param1 }}{% if param2 is defined %}_{{ param2 }}{% endif %}_{{ param3 }}
|
||
params:
|
||
param1: value
|
||
param2:
|
||
type: variable
|
||
variable: _.unknown_variable
|
||
optional: true
|
||
param3:
|
||
type: information
|
||
information: doc
|
||
variable: _.my_calculated_variable
|
||
...
|
||
|
||
An example with a `identifier` type parameter:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_dyn_family_{{ identifier }}:
|
||
dynamic:
|
||
- val1
|
||
- val2
|
||
description: 'Describe {{ identifier }}'
|
||
|
||
my_dyn_var:
|
||
default:
|
||
jinja: 'the identifier is: {{ param1 }}'
|
||
params:
|
||
param1:
|
||
type: identifier
|
||
|
||
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 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
|
||
|
||
family:
|
||
type: sequence
|
||
|
||
leader:
|
||
- val1
|
||
- val2
|
||
|
||
follower1:
|
||
default:
|
||
type: jinja
|
||
jinja: 'the index is: {{ param1 }}'
|
||
params:
|
||
param1:
|
||
type: index
|
||
...
|
||
|
||
Calculation via a variable
|
||
-----------------------------
|
||
|
||
Copy a variable in another:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_variable:
|
||
default:
|
||
- val1
|
||
- val2
|
||
|
||
my_calculated_variable:
|
||
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
|
||
variable: _.var1
|
||
|
||
Here my_calculated_variable is a domainname variable with parameter allow_ip=True and multi to true.
|
||
|
||
Copy one variable to another if the source has no `property` problem:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_variable:
|
||
default: val1
|
||
disabled: true
|
||
|
||
my_calculated_variable:
|
||
multi: true
|
||
default:
|
||
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: val1
|
||
|
||
my_variable_2: val2
|
||
|
||
my_calculated_variable:
|
||
default:
|
||
- variable: _.my_variable_1
|
||
- variable: _.my_variable_2
|
||
|
||
A variable in a :term:`dynamically built family` can also be used in a calculation.
|
||
|
||
For example using the variable for a particular identifier:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
varname:
|
||
- val1
|
||
- val2
|
||
|
||
my_dyn_family_{{ identifier }}:
|
||
dynamic:
|
||
- val1
|
||
- val2
|
||
description: 'Describe {{ identifier }}'
|
||
my_dyn_var_{{ identifier }}:
|
||
default:
|
||
type: identifier
|
||
|
||
all_dyn_var:
|
||
default:
|
||
variable: _.my_dyn_family_val1.my_dyn_var_val1
|
||
|
||
In this case, we recover the value `val1`.
|
||
|
||
Second example using the variable for all identifieres:
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
varname:
|
||
my_dyn_family_{{ identifier }}:
|
||
dynamic:
|
||
- val1
|
||
- val2
|
||
description: 'Describe {{ identifier }}'
|
||
|
||
my_dyn_var_{{ identifier }}:
|
||
default:
|
||
type: identifier
|
||
|
||
all_dyn_var:
|
||
multi: true
|
||
default:
|
||
variable: _.my_dyn_family_.my_dyn_var_
|
||
...
|
||
|
||
In this case, we recover the `val1` and `val2` list.
|
||
|
||
Calculation via a identifier
|
||
----------------------------
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
my_dyn_family_{{ identifier }}:
|
||
dynamic:
|
||
- val1
|
||
- val2
|
||
description: 'Describe {{ identifier }}'
|
||
|
||
my_dyn_var_{{ identifier }}:
|
||
type: string
|
||
default:
|
||
type: identifier
|
||
...
|
||
|
||
Calculation via an index
|
||
--------------------------
|
||
|
||
.. code-block:: yaml
|
||
|
||
%YAML 1.2
|
||
---
|
||
version: 1.1
|
||
|
||
family:
|
||
type: sequence
|
||
|
||
leader:
|
||
- val1
|
||
- val2
|
||
|
||
follower1:
|
||
type: integer
|
||
default:
|
||
type: index
|
||
...
|