rougail/docs/format_content/calculation.rst

.. _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
    ...