rougail/docs/concepts.rst

Abstract presentation
=========================

Rougail, a powerful, free/open-source configuration language that combines declaration, data validation, and templating in a single, declarative syntax.

Why another configuration manager?
-------------------------------------

Using Rougail tansform end user consumer defined consistency rules into highly consistent business objects.
It's a configuration language designed to simplify and unify the way you define, validate, and generate configuration data.

In other word, making it easier to manage complex configurations across multiple environments.

Rougail is:

- a commandline
- a `Python <https://www.python.org/>`_ library
- a description language

What kind of configuration manager?
---------------------------------------------

At the time of the design of Rougail, there were structuring choices that defined the functioning of the tool.

The steps in Rougail can be explain as follows:

- loads the variable structure file
- loads the user data
- reads, validates, exports the data

Structure
~~~~~~~~~

.. glossary::

   structure file

       A structure file in the Rougail meaning is a YAML file that describes variables
       and their dependencies.
       There can be a lot of structure files located in many different folders.

       Rougail reads all the structure files and loads them into a single object
       that represents the whole :term:`context`.

User data
~~~~~~~~~

.. glossary::

    user data

        User datas, as opposed to structured datas, are datas that only concern the assignment of values
        and not the consistency of the variables between them.

        The variable's values are also called **user values**.
        
        The consistency field is outside of the user data scope.
        The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.

Here a some user data examples:

- configuration files
- environment variables
- external sources
- command-line options
- a form

Output
~~~~~~~

And some output examples:

Ensuite on pourra définir sous quelle forme on veut recueillir l'information (Outputs) :

- un objet Tiramisu
- une extraction JSON
- un export pour l'inventaire Ansible
- de la documetation
- ...
.. list-table::
   :widths: 15 45
   :header-rows: 1

   * - Step

   * - Structure

   * - User data

   * - Output

What kind of actor?
---------------------

It's clear that Rougail can be used in many contexts.

Here we'll define actor names. Obviously, these aren't the only possible actors. We're just defining the actors within the Rougail context. Choice your own actor name if you wish to personnalize in your specific context.

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

   * - Step
     - Description
     - Actor

   * - Structure
     - The actor who defines the structure
     - Integrator

   * - User data
     - The actor who sets the values
     - Operator

   * - Output
     - The actor who uses the variables with their values
     - Operator

.. glossary::

    integrator

        An integrator in the Rougail field is the person who writes the :term:`structure files <structure file>`\ .
        He has the responsibility of the integration process, that is,
        he defines the variables and the relationship between them, the variables that are allowed
        (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
        of the organisation of the variables between them.

.. glossary::

    operator

        An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables,
        his responsabilities are to set variable values correctly.

        The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated.
        The type validation is driven by the definitions in the :term:`structure file <structure file>`.

Variable lifetime
----------------------

Rougail's is a configuration language and data validation tool designed to simplify defining, validating, and generating structured configuration and data. 

Rougail aims to define variables.

Here we are talking about the variable lifetime.

The variable’s lifetime is the period between its creation and its destruction.

The lifecycle of a variable includes the generic stages (like, in the Python language):

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

   * - Creation
     - Initialization
     - Assignment
     - Reading
     - Destruction

   * - Variables are assigned a name and a type
     - Their first value is assigned
     - The variable's value is modified
     - The variable's value is used
     - The variable terminates upon the destruction of the object

But other concepts are included in the lifecycle:

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

   * - Documentation
     - Permission
     - Specialization

   * - Informations for variable documentation like description or help. Those informations are used to build documentation, changelog, ...
     - Properties describe access constraints
     - Define usage, selection,...


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

   * - Step
     - Actor
     - Lifetime

   * - Structure
     - Integrator
     - Creation + initialization

   * - User data
     - Operator
     - Assignment + permission

   * - Output
     - Operator
     - Reading + permission + documentation + specialization

Mutability
---------------

Structure
~~~~~~~~~~~~

When the integrator define the structure, variable are mutable.

Even if the default behavior is to conflict when multiple declarations for the same variable.

It's possible to explicitly allow to unifying (combined) multiple variables declarations.

There is no value, strictly speaking. It's a default value. As other parameter, the default value is explicitly mutable.

User data
~~~~~~~~~~

It's no more possible to modifying variable definition.

The value is now mutable.

Output
~~~~~~~

Variable definition and value setting are immutable.

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

   * - Step
     - Actor
     - Lifetime
     - Variable mutation
     - Value mutation

   * - Structure
     - Integrator
     - Creation + initialization
     - Mutable
     - N/A

   * - User data
     - Operator
     - Assignment + permission
     - Immutable
     - Mutable

   * - Output
     - Operator
     - Reading + permission + documentation + specialization
     - Immutable
     - Immutable

Read write or read only mode
-----------------------------

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

   * - Step
     - Actor
     - Lifetime
     - Variable mutation
     - Value mutation
     - Read/Write

   * - Structure
     - Integrator
     - Creation + initialization
     - Mutable
     - N/A
     - N/A

   * - User data
     - Operator
     - Assignment + permission
     - Immutable
     - Mutable
     - Read write

   * - Output
     - Operator
     - Reading + permission + documentation + specialization
     - Immutable
     - Immutable
     - Read only

Access control
-----------------

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

   * - Step
     - Actor
     - Lifetime
     - Variable mutation
     - Value mutation
     - Read/Write
     - Access control

   * - Structure
     - Integrator
     - Creation + initialization
     - Mutable
     - N/A
     - N/A
     - N/A

   * - User data
     - Operator
     - Assignment + permission
     - Immutable
     - Mutable
     - Read write
     - hidden + disabled

   * - Output
     - Operator
     - Reading + permission + documentation + specialization
     - Immutable
     - Immutable
     - Read only
     - disabled + mandatory