stove/rougail
3
0
Fork 0
Code Issues 10 Pull requests 1 Projects Releases Wiki Activity
rougail/docs/fill.rst
Emmanuel Garette e99d0fde3c copy type/params and multi if default value is a variable calculation (#9, #31 and #34) 
Reviewed-on: #34
Co-authored-by: Emmanuel Garette <egarette@silique.fr>
Co-committed-by: Emmanuel Garette <egarette@silique.fr>
2024-09-04 16:31:45 +02:00

585 lines
13 KiB
ReStructuredText
Raw Permalink Blame History

Calculated default values
==============================
Synopsis
-----------
A value can be calculated. In this case we have four possibilities:
- calculation via Jinja
- 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
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.
Parameters
--------------
Depending on the types of calculation, the parameters will be different:
.. list-table::
:widths: 15 25 20 15
:header-rows: 1
* - Calculation type
- 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**
`string`
`mandatory`
- Name of the information whose value we want to retrieve.
- doc
In the case of a Jinja type calculation, it is possible to have parameters.
There are two types of parameter:
- the standard parameters (string, boolean, integer, null), in this case just do: "key: value"
- the advanced settings:
- 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
.. list-table::
:widths: 15 25 20 15
:header-rows: 1
* - Parameter type
- Parameter
- Comments
- Sample
* -
- **name**
`string`
`mandatory`
- parameter's name
- my_param
* -
- **type**
`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**
`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**
`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.
Default value : `False`
- True
* - Information
- **information**
`string`
`mandatory`
- Name of the information whose value we want to retrieve.
- doc
The variable path
-----------------
Normal family
~~~~~~~~~~~~~
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 is 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
~~~~~~~~~~~~~~~~~~
Hire is a dynamic family "{{ suffix }}":
.. 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Let's start with an example from a simple Jinja template:
.. code-block:: yaml
---
version: '1.1'
my_calculated_variable:
default:
type: jinja
jinja: 'no'
Here is a second example with a boolean variable:
.. code-block:: yaml
---
version: '1.1'
my_calculated_variable:
type: boolean
default:
type: jinja
jinja: 'false'
And a multiple value of the number type:
.. code-block:: yaml
---
version: '1.1'
my_calculated_variable:
type: number
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
---
version: '1.1'
my_calculated_variable:
default:
type: jinja
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
---
version: '1.1'
my_calculated_variable:
description: my description
default:
type: jinja
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 `suffix` type parameter:
.. code-block:: yaml
---
version: '1.1'
varname:
multi: true
default:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var:
type: string
default:
type: jinja
jinja: 'the suffix is: {{ param1 }}'
params:
param1:
type: suffix
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`.
The value of the variable inside this family 'this suffix is: ' + the value of the suffix (`val1` and `val2` respectively).
An example with an index type parameter:
.. code-block:: yaml
---
version: '1.1'
family:
type: leadership
leader:
multi: true
default:
- 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
---
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
---
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
---
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
---
version: '1.1'
my_variable_1:
default: val1
my_variable_2:
default: val2
my_calculated_variable:
multi: true
default:
- type: variable
variable: _.my_variable_1
- type: variable
variable: _.my_variable_2
A variable in a dynamic family can also be used in a calculation.
For example using the variable for a particular suffix:
.. code-block:: yaml
---
version: '1.1'
varname:
multi: true
default:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
default:
type: suffix
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:
.. code-block:: yaml
---
version: '1.1'
varname:
multi: true
default:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
default:
type: suffix
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
---------------------------
.. code-block:: yaml
---
version: '1.1'
varname:
multi: true
default:
- val1
- val2
my_dyn_family_:
type: dynamic
dynamic:
type: variable
variable: _.varname
description: 'Describe '
my_dyn_var_:
type: string
default:
type: suffix
Calculation via an index
--------------------------
.. code-block:: yaml
---
version: '1.1'
family:
type: leadership
leader:
multi: true
default:
- val1
- val2
follower1:
type: number
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
Reference in a new issue View git blame Copy permalink