gnunux@silique.fr
e2d62211ec
Co-authored-by: Emmanuel Garette <egarette@silique.fr> Co-authored-by: gwen <gwenaelremond@free.fr> Reviewed-on: #20 Co-authored-by: gnunux@silique.fr <gnunux@silique.fr> Co-committed-by: gnunux@silique.fr <gnunux@silique.fr>
262 lines
7.1 KiB
ReStructuredText
262 lines
7.1 KiB
ReStructuredText
A family
|
|
============
|
|
|
|
Synopsis
|
|
---------
|
|
|
|
A family is a container of variables and subfamily.
|
|
|
|
.. attention:: A family without a subfamily or subvariable will be automatically deleted.
|
|
|
|
Name
|
|
-------------
|
|
|
|
It is with this name that we will be able to interact with the family.
|
|
|
|
It's best to follow the :ref:`convention on variable names`.
|
|
|
|
Shorthand declaration
|
|
----------------------------
|
|
|
|
Shorthand declaration is a way to declare a family in a single line. But you can only define family name and description.
|
|
|
|
To create a family, just add a key with it's name and variables as values. Attention, do not declare any other attributs.
|
|
|
|
By default, the description of the variable is the family name.
|
|
If you add comment in same line of name, this comment is use as description:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
version: '1.1'
|
|
my_family: # This is a great family
|
|
variable:
|
|
|
|
Parameters
|
|
---------------
|
|
|
|
.. FIXME: faire une page sur la "convention on variable names"
|
|
|
|
.. list-table::
|
|
:widths: 15 45
|
|
:header-rows: 1
|
|
|
|
* - Parameter
|
|
- Comments
|
|
|
|
* - type, _type
|
|
|
|
`string`
|
|
|
|
- possile values:
|
|
|
|
- `family` (**default value**)
|
|
- `leadership`
|
|
- `dynamic`
|
|
|
|
.. note:: If a subfamily or a subvariable already has the name `"type"`, it is possible to use the `"_type"` attribute.
|
|
|
|
* - description, _description
|
|
|
|
`string`
|
|
- Description of the family.
|
|
|
|
User information to understand the usefulness of the family.
|
|
|
|
..note:: If a subfamily or subvariable already has the name "description" it is possible to use the "_description" attribute.
|
|
|
|
* - help, _help
|
|
|
|
`string`
|
|
- Additional help associated with the family.
|
|
|
|
.. note:: If a subfamily or a subvariable already has the name "help" it is possible to use the "_help" attribute.
|
|
|
|
* - mode, _mode
|
|
|
|
`string`
|
|
- Family mode.
|
|
|
|
The default mode of a family is the smallest mode of the parent families, child variables, or child families that are contained in that family.
|
|
|
|
This mode also allows you to define the default mode for variables or families included in this family.
|
|
|
|
.. note:: If a subfamily or a subvariable already has the name "mode" it is possible to add the "_mode" attribute.
|
|
|
|
* - hidden, _hidden
|
|
|
|
`string`
|
|
- Invisible family.
|
|
|
|
Allows you to hide a family as well as the variables or families included in this family.
|
|
|
|
This means that the family will no longer be visible in `read-write` mode, but only for calculations or in `read-only` mode.
|
|
|
|
.. note:: If a subfamily or a subvariable already has the name "hidden" it is possible to add the "_hidden" attribute.
|
|
|
|
* - disabled, _disabled
|
|
|
|
`string`
|
|
|
|
- Disabled family.
|
|
|
|
Allows you to deactivate a family as well as the variables or families included in this family.
|
|
|
|
This means that the family will no longer be visible to the user but also to a :term:`calculation`.
|
|
|
|
.. note:: If a subfamily or a subvariable already has the name "disabled" it is possible to use the "_disabled" attribute.
|
|
|
|
Dynamically created family
|
|
-----------------------------
|
|
|
|
To create a family dynamically, you must create a fictitious family linked to a calculation.
|
|
The family name will actually be the prefix of the new name. Alternativly you can specify the suffix in the name, ie `my_{{ suffix }}_name`.
|
|
The suffix will come from the calculation.
|
|
|
|
Obviously if the result of calculation were to evolve, new dynamic families will appear or disappear.
|
|
|
|
Leader or follower variable
|
|
-----------------------------
|
|
|
|
A leader family has a typical attribute of “leadership”. The type is required.
|
|
|
|
A leader family
|
|
----------------
|
|
|
|
The leader and follower variables are placed in a leader family.
|
|
|
|
A leader family cannot contain other families.
|
|
|
|
The default mode of the leader family is the mode of the leader variable.
|
|
|
|
Leader variable
|
|
----------------
|
|
|
|
A leader variable is a variable that will guide the length of other variables (called follower variables).
|
|
|
|
A leader variable is a :doc:`variable` that must have the `multiple` type.
|
|
|
|
A leader variable may be mandatory.
|
|
|
|
The default mode corresponds to the smallest mode defined for the follower variables.
|
|
|
|
Follower variable
|
|
--------------------
|
|
|
|
A follower variable is a variable whose length is not determined by itself, but is identical to that of the leader variable on which it depends.
|
|
|
|
A follower variable is a variable placed just behind a leader variable or another follower variable.
|
|
|
|
The order in which the tracking variables are defined is important.
|
|
|
|
This variable can be of multiple type. In this case, for a determined index of the leading variable, it is possible to put several values to the same variable.
|
|
|
|
A follower variable may be required. This means that when a leader variable is entered, the follower variable must also be a value at the index considered. If no value is defined for the leader variable, no value is specified for the follower variable.
|
|
|
|
The default mode of a follower variable corresponds to the mode of the leader variable.
|
|
|
|
If a leader variable is hidden or disabled, the follower variables will be hidden or disabled as well.
|
|
|
|
Examples
|
|
----------
|
|
|
|
Simple family:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
version: '1.1'
|
|
my_family:
|
|
type: family
|
|
description: This is a great family
|
|
help: This is the help of a great family
|
|
mode: expert
|
|
|
|
Dynamically created family
|
|
----------------------------
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
version: '1.1'
|
|
varname:
|
|
multi: true
|
|
default:
|
|
- val1
|
|
- val2
|
|
my_dyn_family_:
|
|
type: dynamic
|
|
dynamic:
|
|
type: variable
|
|
variable: rougail.varname
|
|
description: 'Describe'
|
|
my_dyn_var:
|
|
type: string
|
|
description: 'Variable description'
|
|
|
|
This will dynamically create two families:
|
|
|
|
- "rougail.my_dyn_family_val1"
|
|
- "rougail.my_dyn_family_val2"
|
|
|
|
In the dynamic family "rougail.my_dyn_family_val1" we will find a variable "my_dyn_var".
|
|
|
|
Here is a second example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
version: '1.1'
|
|
varname:
|
|
multi: true
|
|
default:
|
|
- val1
|
|
- val2
|
|
my_dyn_{{ suffix }}_family:
|
|
type: dynamic
|
|
dynamic:
|
|
type: variable
|
|
variable: rougail.varname
|
|
description: 'Describe'
|
|
my_dyn_var:
|
|
type: string
|
|
description: 'Variable description'
|
|
|
|
This will dynamically create two families:
|
|
|
|
- "rougail.my_dyn_val1_family"
|
|
- "rougail.my_dyn_val2_family"
|
|
|
|
In the dynamic family "rougail.my_dyn_val1_family" we will find a variable "my_dyn_var".
|
|
|
|
Leader or follower variable
|
|
-------------------------------
|
|
|
|
Definition of leader and follower variables
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Here is an example of defining a leading variable and two following variables:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
version: '1.1'
|
|
family:
|
|
type: leadership
|
|
leader:
|
|
multi: true
|
|
follower1:
|
|
follower2:
|
|
multi: true
|
|
|
|
Adding a new follower variable
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To add a new follower variable, in a new dictionary, simply define one or more new variables in the leader family:
|
|
|
|
.. code-block:: yaml
|
|
|
|
---
|
|
version: '1.1'
|
|
family:
|
|
follower3:
|