doc(condition)

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
 ~~~~~~~~~~~~~~~~~
 

docs/structured_data.rst

@@ -22,6 +22,56 @@ to generate configuration files.
 
 :term:`Families <family>` and :term:`variables <variable>` 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-<name>.yml
+
+Where `XX` is a two digits integer followed by an hyphen, and `<name>` 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>` 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

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
-

docs/structured_data/condition.rst

@@ -4,8 +4,7 @@ Calculated properties
 Synopsis
 ------------
 
-Calculated properties allow you to add or remove properties to a :term:`variable`
+Calculated properties allow you to add or remove properties to a :term:`variable` or a :term:`family` depending on the context.
-or a :term:`family` depending on the context.
 
 Here is the list of editable properties:
 
@@ -13,8 +12,8 @@ Here is the list of editable properties:
    :widths: 15 15 25
    :header-rows: 1
 
-   * - **Attribute applicable on**
+   * - Attribute applying to
-     - **Property's name**
+     - Property's name
      - Comment
 
    * - Variable
@@ -22,80 +21,171 @@ Here is the list of editable properties:
        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
+       but remains accessible in a calculation or in `read-only` mode.
+
+       .. seealso:: :ref:`hidden access control <hidden>`.
+
    * - Variable
 
        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 <disabled>`.
+
+   * - 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 <nullable_variable>`.
+
+   * - Variable
+     - empty
+     - The multiple variable allow the value `null` (or `None` in Python)
+
+       .. seealso:: we call it a :ref:`nullable variable <nullable_variable>`.
 
 A property can be calculated. In this case we have two possibilities:
 
-- calculation via Jinja
+- calculation via Jinja (see also the tutorial with a real world sample :doc:`variable jinja <../tutorial/jinja>`)
-- calculation via a variable          
+- calculation via a variable (see also the tutorial with a real world sample :doc:`variable calculation <../tutorial/properties>`)
 
 Parameters
 ---------------
 
+Variable parameters
+~~~~~~~~~~~~~~~~~~~
+
 .. list-table::
-   :widths: 15 25 20 15
    :header-rows: 1
 
-   * - **Calculation type**
+   * - Parameter
-     - **Parameter**
+     - Comment
-     - **Comment**
+     - Sample
-     - **Sample**
+
-   * - 
+   * - type
-     - **type**
 
        `string`
+     - Calculation type.
 
-       `mandatory`
+       This parameter is optional. It is deduced from the presence of the parameter "variable" in a calculation.
-     - Calculation type, possible values are: jinja, variable, information, suffix or index  
+     - variable
-     - jinja
-   * - Jinja 
-     - **jinja**
 
-       `string`
+   * - variable
-       
-       `mandatory`
-     - Jinja template . 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
-     - **variable**
 
        `string`
 
        `mandatory`
      - Name of the associated variable.
 
-       .. attention:: The variable must be of `boolean` type.
+       It's better to use :term:`relative path` notation.
-     - rougail.variable 
+     - _.my_variable
-   * - Variable
-     - **propertyerror**
 
-       `boolean` 
+   * - 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.
-       If the attribute is `False`, the calculated value is False.
+       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`
+       Default value: `true`
-     - False
+     - transitive
 
-In the case of a Jinja type calculation, it is possible to have parameters.
+       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,59 +195,71 @@ 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 identifier: in the case of a variable in a :term:`dynamically built family`
-   - parameter via an index: in the case of a follower variable       
+   - 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::
-   :widths: 15 25 20 15
    :header-rows: 1
 
-   * - **Parameter's type**
+   * - Parameter
-     - **Parameter**
+     - Comments
-     - **Comments**
+     - Sample
-     - **Sample**
+
-   * - 
+   * - type
-     - **name**
+
+       `string`
+     - Parameter's type
+     - variable
+
+   * - variable
 
        `string`
 
        `mandatory`
-     - parameter's name 
+     - Variable's name
-     - my_param
-   * - 
-     - **type**
 
-       `string`
+       It's better to use :term:`relative path` notation.
+     - _.my_variable
 
-       `mandatory`
+   * - propertyerror
-     - 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.
+     - 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`
+       Default value: `true`
-     - False
+     - false
-   * - Variable
+
-     - **optional**
+   * - 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.
+     - 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`
+       Default value: `false`
-     - True
+     - 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
-     - **information**
 
        `string`
 
@@ -165,76 +267,10 @@ There are two types of parameter:
      - Name of the information whose value we want to retrieve.
      - doc
 
-Samples
+   * - variable
-------------
 
-A Jinja-type calculated property
+       `string`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+     - Variable's name. If not specified, the information is retrieve in :term:`Tiramisu` Config.
-
-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:
 
+       It's better to use :term:`relative path` notation.
+     - _.my_variable

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 <variable>`
 
+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 <variable>`
 
+.. _nullable_variable:
+
 Nullable variable
 '''''''''''''''''
 

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 <namingconvention>`
+   A family is a variable. So have a look at the :ref:`variable naming convention <namingconvention>`.
 
 Parameters
 ---------------

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 <validation>
-   condition
    path
+   calculation
+   condition
+   validation

docs/structured_data/naming_convention.rst

@@ -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-<name>.yml
-
-Where `XX` is a two digits integer followed by an hyphen, and `<name>` 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>` 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.

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:

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 <namingconvention>`
+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.
 

docs/vac.rst

@@ -131,7 +131,7 @@ Let's imagine that the default value was originally `old_value` and is now `my_v
        `string <https://rougail.readthedocs.io/en/latest/variable.html#variables-types>`__ `mandatory`
      - It's my variable.
 
-       **Default**: :strike:`old_value` **myvalue**
+       **Default**: :strike:`old_value` :underline:`myvalue`
 
 Now it's time to export
 ~~~~~~~~~~~~~~~~~~~~~~~~~~