rougail/docs/family.rst

The families
=============

Synopsis
---------

.. glossary::

   family
   subfamily
   
       A family (or a subfamily) is simply a collection of variables that refer to
       the same business model category. It's just a variables container.
       Think of it as a container as well as a namespace.

.. attention:: A family without a subfamily or subvariable will be automatically deleted.

Naming
---------

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

Shorthand declaration
----------------------------

Shorthand declaration is a way to declare a family in a single line.

To create a family, just add a key with it's name and variables as values.

Here is a simple example:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1
    my_family:

      variable:
    ...

By default, the description of the variable is the family name.
It's a best practice to description a family. Just add comment in same line of name, this comment is use as description.

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1
    my_family:  # This is a great family

      variable:
    ...

But in shorthand notation, you can only define family name and description.

.. attention:: Any other parameters will be considered as a variable. Do not use shorthand in this case.

Parameters
---------------

.. list-table::
   :widths: 15 45
   :header-rows: 1

   * - Parameter
     - Comments

   * - description, _description

       `string`
     - Description of the family.

       User information to understand the usefulness of the family.

   * - help, _help

       `string`
     - Additional help associated with the family.

       .. seealso:: tutorial with a real world sample :ref:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)

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

       .. seealso:: tutorial with a real world sample :ref:`mode parameter <tutorial/mode>` (the tutorial focuses on variable, but the principle is the same for a family)

   * - type, _type

       `string`

     - possible values:

       - `family` (**default value**)
       - `dynamic`
       - `leadership`

   * - hidden, _hidden

       `boolean` or `calculation`
     - 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.

       The default value is `false`.

       .. seealso:: tutorial with a real world sample :ref:`hidden parameter <tutorial/properties>`

   * - disabled, _disabled

       `boolean` or `calculation`

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

       The default value is `false`.

       .. seealso:: tutorial with a real world sample :ref:`disabled parameter <tutorial/properties>`

   * - dynamic, _dynamic

       `calculation` or a list of `calculation` or `string`

     - Dynamic identifiers.

       .. important:: this parameter is only available for dynamically built family

.. note::

   If a subfamily or a subvariable already has the name of a parameter it is possible to use the "_<parameter>" name.
   You can have a look at the tutorial with a real world sample :ref:`of parameter with "_" <tutorial/underscore_parameter>`.

A family
---------

Here is a simple example:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1
    my_family:
      description: This is a great family
      help: This family is great because we have great variables inside

      variable:
    ...

.. seealso::

   You can have a look at the tutorial with a real world sample:

   - :ref:`family <tutorial/family>`
   - :ref:`help parameter <tutorial/examples>` (the tutorial focuses on variable, but the principle is the same for a family)

A dynamically built family
-----------------------------

To create a family dynamically, you must create a fictitious family linked to a list of uniq identifiers.
This list could be hard coded or resulting from a calculation

In this case if the result of calculation were to evolve, new dynamic families will appear or disappear.

The name of this family is particular. You have to add `{{ identifier }}` string inside. It will be replace by each identifiers.

Here is an simple example:

.. code-block:: yaml

    %YAML 1.2
    ---
    version: 1.1
    
    my_{{ identifier }}_family:
      description: 'A family for {{ identifier }}'
      dynamic:
        - one thing
        - another

      variable:
        description: 'A variable for {{ identifier }}'
    ...

This will dynamically create two families:

- "my_one_thing_family"
- "my_another_family"

.. seealso::

   You can have a look at the tutorial with a real world sample :ref:`dynamically built family <tutorial/dynfam>`

Similar object sequence
-------------------------

A family with `type` set to `leadership` is a sequence of similar object.

Let's start the explanation with a concrete example:

.. code-block:: yaml

   %YAML 1.2
   ---
   version: 1.1

   accounts:
     description: All accounts
     type: leadership

     login:
       description: Account login
       type: unix_user

     secret:
       description: Account secret
       type: secret
   ...

What is expected, it's something like:

.. code-block:: yaml

    ---
    accounts:
      - login: foo
        secret: 0hM%G0dW4a7ASecr3t
      - login: bar
        secret: NotGoodSecret

It's what we call a sequence of similar object.

.. attention:: A sequence cannot contain other families.

.. seealso::

   You can have a look at the tutorial with a real world sample :ref:`similar object sequence <tutorial/sequence>`

A custom type family
----------------------

In short, a custom type is nothing more than a kind of a template for a family.
Define a custom type family is much like defining families.

This custom type family can be used as many times as desired and customized as you wish.

.. seealso::

   You can have a look at the tutorial with a real world sample :ref:`family custom type <tutorial/family>`