From efcdc496ec769a5c4ace04cf43a474cf05874f5a Mon Sep 17 00:00:00 2001 From: Emmanuel Garette Date: Sat, 6 Jun 2026 19:22:36 +0200 Subject: [PATCH] doc(condition) --- docs/concepts.rst | 4 + docs/structured_data.rst | 50 +++ docs/structured_data/calculation.rst | 1 - docs/structured_data/condition.rst | 416 +++++++++++---------- docs/structured_data/data_integrity.rst | 10 +- docs/structured_data/family.rst | 2 +- docs/structured_data/index.rst | 15 +- docs/structured_data/naming_convention.rst | 74 ---- docs/structured_data/validation.rst | 20 +- docs/structured_data/variable.rst | 21 +- docs/vac.rst | 2 +- 11 files changed, 327 insertions(+), 288 deletions(-) delete mode 100644 docs/structured_data/naming_convention.rst diff --git a/docs/concepts.rst b/docs/concepts.rst index 802dacdbc..9371d63c7 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -345,6 +345,8 @@ The properties can be defined permanently or according to the result of a calcul There are two main properties. +.. _hidden: + Hidden variable ~~~~~~~~~~~~~~~ @@ -354,6 +356,8 @@ This could be an internal variable used by the :term:`integrator` that is not su Or a variable that only makes sense in a particular context. Therefore, this variable can be hidden and then unhidden depending on the context. +.. _disabled: + Disabled variable ~~~~~~~~~~~~~~~~~ diff --git a/docs/structured_data.rst b/docs/structured_data.rst index ef18d232c..48704f01e 100644 --- a/docs/structured_data.rst +++ b/docs/structured_data.rst @@ -22,6 +22,56 @@ to generate configuration files. :term:`Families ` and :term:`variables ` can be defined in several structure files. These structure files are then aggregated. +File naming convention +-------------------------- + +.. _filenamingconvention: + +The structure files in a given folder +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For the sake of clarity, we put the structured data in separate files. +It's a good way to organize your rougail structures this way, +in the real world we need separate files for different topics. + +For example some files like this: + +A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml` + +:: + + . + └── firefox + ├── 00-proxy.yml + └── 10-manual.yml + +.. note:: We of course could have put everything in one file. + Again, it is better to separate the structures in different files + for reasons of ordering and clarity. + +Ordering your structure files +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The order in which files are loaded is important in Rougail. +In a given folder, files are loaded in alphabetical order. + +Furthermore, for better readability of the order in which files are +loaded into a folder, we have adopted a convention. +To facilitate classification, we have defined a standard notation for structure file names: + +:: + + XX-.yml + +Where `XX` is a two digits integer followed by an hyphen, and `` is a name that describes +the structure that is in this file. We advise you to adopt this convention as well. + +File naming convention +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The is no restriction to the `` name part of file name. But it is preferable to only use +lowercase ASCII letters, numbers and the `"_"` (undescore) character. + .. _namespace: Separation of structures into namespaces diff --git a/docs/structured_data/calculation.rst b/docs/structured_data/calculation.rst index f0e194bdb..f1d149ede 100644 --- a/docs/structured_data/calculation.rst +++ b/docs/structured_data/calculation.rst @@ -586,4 +586,3 @@ In a third dictionary, we even can delete the calculation if needed: my_calculated_variable: redefine: true default: null - diff --git a/docs/structured_data/condition.rst b/docs/structured_data/condition.rst index 3d1895639..a64257a4d 100644 --- a/docs/structured_data/condition.rst +++ b/docs/structured_data/condition.rst @@ -4,98 +4,188 @@ Calculated properties Synopsis ------------ -Calculated properties allow you to add or remove properties to a :term:`variable` -or a :term:`family` depending on the context. +Calculated properties allow you to add or remove properties to a :term:`variable` or a :term:`family` depending on the context. Here is the list of editable properties: -.. list-table:: +.. list-table:: :widths: 15 15 25 :header-rows: 1 - - * - **Attribute applicable on** - - **Property's name** + + * - Attribute applying to + - Property's name - Comment - + * - Variable - - Family + + Family - hidden - - Hides a variable or a family, in this case it is not accessible in `read-write` mode, - but remains accessible in a calculation or in `read-only` mode + - Hides a variable or a family, in this case it is not accessible in `read-write` mode, + but remains accessible in a calculation or in `read-only` mode. + + .. seealso:: :ref:`hidden access control `. + * - Variable - - Family + + Family - disabled - - Deactivates a variable or family, in this case it is never accessible + - Deactivates a variable or family, in this case it is never accessible. + + .. seealso:: :ref:`disabled access control `. + + * - Variable + - frozen + - A frozen variable is a variable that the :term:`operator` cannot change the value. + * - Variable - mandatory - - The variable expects a value other than `None` or `[]` for multiple variables + - The variable expects a value other than `null` (or `None` in Python) or `[]` for multiple variables. + + .. seealso:: for non multiple variables we call it a :ref:`nullable variable `. + + * - Variable + - empty + - The multiple variable allow the value `null` (or `None` in Python) + + .. seealso:: we call it a :ref:`nullable variable `. A property can be calculated. In this case we have two possibilities: -- calculation via Jinja -- calculation via a variable +- calculation via Jinja (see also the tutorial with a real world sample :doc:`variable jinja <../tutorial/jinja>`) +- calculation via a variable (see also the tutorial with a real world sample :doc:`variable calculation <../tutorial/properties>`) Parameters --------------- -.. list-table:: - :widths: 15 25 20 15 +Variable parameters +~~~~~~~~~~~~~~~~~~~ + +.. list-table:: :header-rows: 1 - - * - **Calculation type** - - **Parameter** - - **Comment** - - **Sample** - * - - - **type** - - `string` - - `mandatory` - - Calculation type, possible values are: jinja, variable, information, suffix or index - - jinja - * - Jinja - - **jinja** - - `string` - - `mandatory` - - Jinja template . For a multiple variable, each line represents a value. - - {% if rougail.variable %} - {{ rougail.variable }} + * - Parameter + - Comment + - Sample + + * - type - {% endif %} - * - Jinja - - **params** - - `list` - - Additional parameters passed to the Jinja template - - - * - Variable - - **variable** - `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. - - .. attention:: The variable must be of `boolean` type. - - 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 False. - **Default value**: `True` - - False + It's better to use :term:`relative path` notation. + - _.my_variable -In the case of a Jinja type calculation, it is possible to have parameters. + * - when/when_not + - Compare the value of the variable define in `variable` attribute. + + If the related variable is the boolean typed variable, the default value is `true` + - See the tutorial with a real world sample :doc:`when_not <../tutorial/properties>`) + + * - propertyerror + + `boolean` or `transitive` + - 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. + If the parameter is `false`, the calculated value is `false` in this condition. + If the parameter is `transitive`, the calculated is `true` if the variable raise propertyerror + or `false` otherwise. + + Default value: `true` + - transitive + + 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 "when the variable "xxxx" has the value "yyyy". + You can personnalize here the calculation description + - + +Jinja parameters +~~~~~~~~~~~~~~~~ + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Comment + - Sample + + * - type + + `string` + - The calculation type. + + This parameter is optional. It is deduced from the presence of the parameter "jinja" in calculation. + - jinja + + * - jinja + + `string` + + `mandatory` + - Jinja template. For a multiple variable, each line represents a value. + + It's better to use :term:`relative path` notation in Jinja template. + - .. code-block:: jinja + + {% if _.my_variable %} + {{ _.my_variable }} + {% endif %} + + * - params + + `dict` + - Additional parameters passed to the Jinja template + + See below to have params possibility. + - See the tutorial with a real world sample :doc:`params <../tutorial/jinja>`) + + * - return_type + + `string` + - Jinja template could return two type of value: + + - `string` (default): that means the Jinja template return an error message that explain why we don't have access to this variable + - `boolean`: the Jinja template return "true" or "false". The value true means that the properties is present. + + - See the tutorial with a real world sample :doc:`return_type <../tutorial/jinja>`) + + * - description + + `string` + `recommanded` + - Rougail engine cannot deduce what you want to do in Jinja template. You have to describe it for documentation purpose. + If return_type parameter is `boolean`, this description is used in error message. + - See the tutorial with a real world sample :doc:`description <../tutorial/jinja>`) + +In the case of a Jinja type calculation, it is possible to have parameters (`params`). There are two types of parameter: @@ -105,136 +195,82 @@ There are two types of parameter: - parameter via a variable - parameter via 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's 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. + - parameter via an identifier: in the case of a variable in a :term:`dynamically built family` + - parameter via an index: in the case of a variable in a :term:`sequence` + - parameter via the current :term:`namespace` + +Parameters for variable type `param` +'''''''''''''''''''''''''''''''''''' + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Comments + - Sample + + * - type - **Default value**: `True` - - False - * - 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` - + - Parameter's type + - variable + + * - variable + + `string` + + `mandatory` + - Variable's name + + 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. If the parameter is false, the parameter is not passed to the Jinja template. + + Default value: `true` + - false + + * - 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 + + * - whole + + `boolean` + - In :term:`sequence` family, only the value of the variable in the current element is propose. + This parameter allow you to have all values for all elements. + + Default value: `false`. + - true + +Parameters for information type `param` +''''''''''''''''''''''''''''''''''''''' + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Comments + - Sample + + * - information + + `string` + `mandatory` - Name of the information whose value we want to retrieve. - doc -Samples ------------- + * - variable -A Jinja-type calculated property -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is possible to write the condition in Jinja: - - -.. code-block:: yaml - - --- - version: '1.1' - condition: - default: 'do not hide!' - my_variable: - hidden: - type: jinja - jinja: | - {% if rougail.condition and rougail.condition == "hide!" %} - this rougail.condition value is 'hide!' - {% endif %} - - -In this case the variable is hidden if the value of the variable "rougail.condition" is `hide!` and it did not hide for any other value. Be careful, always take into consideration that "rougail.condition" can be equal to `None`. - -The message returned by the function is visible in the error message in the event of an access problem: - -.. code-block:: python - - >>> from rougail import Rougail, RougailConfig - >>> RougailConfig['dictionaries_dir'] = ['dict'] - >>> rougail = Rougail() - >>> config = rougail.get_config() - >>> config.property.read_write() - [..] - tiramisu.error.PropertiesOptionError: cannot access to option "my_variable" because has property "hidden" (this rougail.condition value is 'hide!') - -It is possible to use parameters when calculating properties as for calculating the `default` attribute. - -A calculated property of variable type -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A variable can therefore be calculated via the result of another variable. Please note, this other variable must be of `boolean` type: - -.. code-block:: yaml - - --- - version: '1.1' - condition: - type: boolean - my_variable: - hidden: - type: variable - variable: rougail.condition - -If the value of the variable "rougail.condition" is `True` then the variable "rougail.my_variable" is hidden. - -Redefintion -~~~~~~~~~~~~~~~~~ - -It may be that in a dictionary we decide to define a condition. - -To delete the calculation from a variable, simply do in a new dictionary: - -.. code-block:: yaml - - --- - version: '1.1' - my_variable: - redefine: true - hidden: + `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 diff --git a/docs/structured_data/data_integrity.rst b/docs/structured_data/data_integrity.rst index ed9be4a61..a0159381b 100644 --- a/docs/structured_data/data_integrity.rst +++ b/docs/structured_data/data_integrity.rst @@ -74,12 +74,18 @@ But we will also find a whole series of specialized types: - domainname - port - MAC -- choice - secret - ... .. seealso:: :doc:`the variable documentation ` +A variable with a list of possible values +''''''''''''''''''''''''''''''''''''''''' + +Sometimes a variable can only hold a finite list of possible values. We call it a variable with a list of possible values. + +.. seealso:: tutorial with a real world sample :doc:`variable with a list of possible values <../tutorial/choice>` + Type parameters ''''''''''''''' @@ -87,6 +93,8 @@ For certain types, there are a number of parameters that can be used to further .. seealso:: :doc:`the variable documentation ` +.. _nullable_variable: + Nullable variable ''''''''''''''''' diff --git a/docs/structured_data/family.rst b/docs/structured_data/family.rst index 5d5b33dae..c39e6951e 100644 --- a/docs/structured_data/family.rst +++ b/docs/structured_data/family.rst @@ -22,7 +22,7 @@ It is with its name that we will be able to interact with the family. .. seealso:: - Have a look at the :ref:`family naming convention ` + A family is a variable. So have a look at the :ref:`variable naming convention `. Parameters --------------- diff --git a/docs/structured_data/index.rst b/docs/structured_data/index.rst index d64b83b7b..2b3920a24 100644 --- a/docs/structured_data/index.rst +++ b/docs/structured_data/index.rst @@ -1,16 +1,17 @@ -Rougail format -=============== +The Rougail format +================== -Common informations about structured data +Now that we understand what can be described in a structured data file, let's see how to describe variables. + +The variable is described in Rougail format. .. toctree:: :titlesonly: :caption: Structured data - naming_convention variable family - calculation - Value validations - condition path + calculation + condition + validation diff --git a/docs/structured_data/naming_convention.rst b/docs/structured_data/naming_convention.rst deleted file mode 100644 index 2d1233b83..000000000 --- a/docs/structured_data/naming_convention.rst +++ /dev/null @@ -1,74 +0,0 @@ -Naming convention -===================== - -.. _filenamingconvention: - -File naming convention --------------------------- - -The structure files in a given folder -'''''''''''''''''''''''''''''''''''''''''' - -For the sake of clarity, we put the structure definitions in separate files. -It's a good way to organize your rougail structures this way, -in the real world we need separate files for different topics. - -For example some files like this: - -A file named :file:`firefox/00-proxy.yml` structure file and file named :file:`firefox/10-manual.yml` - -:: - - . - └── firefox - ├── 00-proxy.yml - └── 10-manual.yml - -.. note:: We of course could have put everything in one file. - Again, it is better to separate the structures in different files - for reasons of ordering and clarity. - -Ordering your structure files -''''''''''''''''''''''''''''''''' - -The order in which files are loaded is important in Rougail. -In a given folder, files are loaded in alphabetical order. - -Furthermore, for better readability of the order in which files are -loaded into a folder, we have adopted a convention. -To facilitate classification, we have defined a standard notation for structure file names: - -:: - - XX-.yml - -Where `XX` is a two digits integer followed by an hyphen, and `` is a name that describes -the structure that is in this file. We advise you to adopt this convention as well. - -File naming convention -''''''''''''''''''''''''''''' - -The is no restriction to the `` name part of file name. But it is preferable to only use -lowercase ASCII letters, numbers and the `"_"` (undescore) character. - -.. _namingconvention: - -Variable and family naming convention ---------------------------------------- - -The name of a variable and a family must be chosen carefully. -It is the path that will allow users to retrieve their defined values. -An obscure name will cause confusion. - -By design, you cannot use just any character to name your variable. - -The regular expression that validates our variable and family naming policy is: - -.. code-block:: python - - re.compile(r"^[a-z0-9_]*$") - -You can see that it is mandatory to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. -The snake case typographic convention is therefore used. - -.. attention:: The name must not starts with `_` character. diff --git a/docs/structured_data/validation.rst b/docs/structured_data/validation.rst index 192761521..f9170ab3e 100644 --- a/docs/structured_data/validation.rst +++ b/docs/structured_data/validation.rst @@ -1,5 +1,5 @@ -Verification function -========================== +Value validations +================= Synopsis ------------- @@ -117,7 +117,7 @@ Here is a simple example of validating values: .. code-block:: yaml --- - version: '1.1' + version: 1.1 my_variable: validators: - type: jinja @@ -142,7 +142,7 @@ In the constraint, it is possible to specify the error level and put it as a war .. code-block:: yaml --- - version: '1.1' + version: 1.1 my_variable: validators: - type: jinja @@ -161,7 +161,7 @@ Verification with parameters .. code-block:: yaml --- - version: '1.1' + version: 1.1 my_hidden_variable: disabled: true my_variable: @@ -189,7 +189,7 @@ An example with a suffix type parameter: .. code-block:: yaml --- - version: '1.1' + version: 1.1 varname: multi: true default: @@ -221,7 +221,7 @@ An example with an index type parameter: .. code-block:: yaml --- - version: '1.1' + version: 1.1 family: type: leadership leader: @@ -249,7 +249,7 @@ In a first dictionary, let's declare our variable and its verification function: .. code-block:: yaml --- - version: '1.1' + version: 1.1 my_variable: validators: - type: jinja @@ -263,7 +263,7 @@ In a second dictionary it is possible to redefine the calculation: .. code-block:: yaml --- - version: '1.1' + version: 1.1 my_variable: redefine: true validators: @@ -280,7 +280,7 @@ Here is a third dictionary in which we remove the validation: .. code-block:: yaml --- - version: '1.1' + version: 1.1 my_variable: redefine: true validators: diff --git a/docs/structured_data/variable.rst b/docs/structured_data/variable.rst index 895e9e46b..f1492a5ed 100644 --- a/docs/structured_data/variable.rst +++ b/docs/structured_data/variable.rst @@ -26,14 +26,29 @@ Synopsis But consitency handling system is is not just about strong typing. It is more than that. +.. _namingconvention: + Names ------ It is with its name that we will be able to interact with the variable. -.. seealso:: +The name of a variable must be chosen carefully. +It is the path that will allow users to retrieve their defined values. +An obscure name will cause confusion. - Have a look at the :ref:`variable naming convention ` +By design, you cannot use just any character to name your variable. + +The regular expression that validates our variable and family naming policy is: + +.. code-block:: python + + re.compile(r"^[a-z0-9_]*$") + +You can see that it is mandatory to only use lowercase ASCII letters, numbers and the `"_"` (undescore) character. +The snake case typographic convention is therefore used. + +.. attention:: The name must not starts with `_` character. Parameters ------------- @@ -248,7 +263,7 @@ Parameters `boolean` or :term:`calculation` - Read only variable. - Enables us to have an immutable variable. + Enables us to have an immutable variable's value. This means that the variable will be visible but user will not allowed to change the value. diff --git a/docs/vac.rst b/docs/vac.rst index cd70527c3..5674eb698 100644 --- a/docs/vac.rst +++ b/docs/vac.rst @@ -131,7 +131,7 @@ Let's imagine that the default value was originally `old_value` and is now `my_v `string `__ `mandatory` - It's my variable. - **Default**: :strike:`old_value` **myvalue** + **Default**: :strike:`old_value` :underline:`myvalue` Now it's time to export ~~~~~~~~~~~~~~~~~~~~~~~~~~