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

Rougail is a robust and powerful, free/open-source configuration manager.

Rougail is:

- a CLI (command line interface) utility
- a `Python <https://www.python.org/>`_ library
- a YAML based description language

The language combines declaration, data validation, and templating in a single, declarative syntax.

It will be useful to:

- define variables (the structure) easily and their constraints
- loads those variables
- generate variables documentation
- loads variables' values
- validate the variables and the overall consistency handling system
- generate custom table views
- export to different common format (YAML, Ansible, ...)
- ...

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

Using Rougail tansforms 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.

You might tell me that other configuration management tools do the same thing. And that's partly true.

But Rougail adds interesting features in variable management that other projects don't have.
We are of course referring to the documentation management included directly in the configuration manager.

Your configuration is therefore consistent, easily accessible, and modifiable.

Not to mention the always up-to-date documentation and the information you provide to your users regarding changes to variables.

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 explained as follows:

- loading the variable's :term:`structured data`
- loading the :term:`user data`
- reading, validating, exporting, documenting (and so on...) the data

Structured data
~~~~~~~~~~~~~~~~~

Structured data is also called the Rougail format.

.. glossary::

   structured data

       A variable-first :term:`DSL` (Domain-Specific Language) designed for describing variables, consistency
       and describe the relationships between variables in a declarative style.

       The language is a mix of YAML and Jinja Templating.

       It goes beyond traditional schema languages (like `JSON Schema <https://json-schema.org/>`_,
       `OpenAPI <https://www.openapis.org/>`_, `Cuelang <https://cuelang.org/>`_)
       by combinig type systems, powerful validation, consistency of the configuration and documentation.

Structured data are commonly placed in :term:`structure files <structure file>`.

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

.. glossary::

    user data

        User data, as opposed to structured data, are data 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 data <structured data>`\ 's scope.

Here a some user data examples:

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

Output
~~~~~~~

.. glossary::

   output

        Structured and user data form a coherent configuration useful for different purposes.

        Output is here to define what kind of data we want.

Here are some output examples:

- :term:`Tiramisu` object
- JSON extraction
- Ansible inventory extraction
- documentation
- custom table views

.. list-table::
   :header-rows: 1

   * - **Step**

   * - **Structured data**

   * - **User data**

   * - **Output**

.. _configuration:

Configuration
~~~~~~~~~~~~~

We've been talking about `configuration` for a while now. It's time to define what a configuration is.

.. glossary::

    configuration

        The configuration represents the set of variables and their values loaded in a tree-like fashion into memory from structural data, user data and any modifications during its lifecycle.

        In practice, it's :term:`Tiramisu` who manages this part.

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.

.. glossary::

    integrator

        An integrator in the Rougail field is the person who writes the :term:`structured <structured data>`\ .
        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 :term:`operator`, are of course type validated.
        The type validation is driven by the definitions in the :term:`structure file <structure file>`.

Here is a reminder of the different steps:

- the :term:`integrator` defines the structure
- the :term:`operator` sets the value
- the :term:`integrator` and/or the :term:`operator` use the output

.. list-table::
   :header-rows: 1

   * - **Step**
     - Actor

   * - **Structured data**
     - Integrator

   * - **User data**
     - Operator

   * - **Output**
     - - Operator
       - Integrator

Variable lifecyle
----------------------

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

Rougail aims at defining variables.

Here we are talking about the variable lifecyle.

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

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

- Creation: variables are assigned a name and a type
- Initialization: they are assigned their first value (we call it :term:`default value`)
- Assignment: the variable's value is modified
- Reading: the variable's value is used
- Destruction: the variable terminates upon the destruction of the object

.. note:: No other concept is included in the lifecycle (ni particular the access control, with properties describing access constraints).

.. list-table::
   :header-rows: 1

   * - **Step**
     - Actor
     - Lifecyle

   * - **Structured data**
     - Integrator
     - - Creation
       - Initialization

   * - **User data**
     - Operator
     - - Reading
       - Assignment
       - Access control


   * - **Output**
     - - Operator
       - Integrator
     - - Reading
       - Access control

.. _variable_mutability:

Variable mutability
---------------------

.. _structured_data:

Structured data
~~~~~~~~~~~~~~~~

When the :term:`integrator` defines the structure, variables are mutable.

Even if the default behavior is inconsistent, like when there is a conflict between multiple declarations for the same variable,

it's possible to explicitly allow to unify (combine) multiple variables declarations.

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

At the user data level, it's no more possible to modify any variable definition.
Here we are just talking about variable's values.

Output
~~~~~~~

Variable definition settings are immutable.

.. list-table::
   :header-rows: 1

   * - **Step**
     - Actor
     - Lifecyle
     - Mutability

   * - **Structured data**
     - Integrator
     - - Creation
       - Initialization
     - Mutable

   * - **User data**
     - Operator
     - - Reading
       - Assignment
       - Access control
     - Immutable

   * - **Output**
     - - Operator
       - Integrator
     - - Reading
       - Access control
     - Immutable

Value access
-------------

In the :term:`structured data` step, there is no value, strictly speaking. 
The values set are default values.
Like other parameters, the default value is explicitly mutable.

In the `user data` step, we can modify the values. That's precisely the purpose of this step.
The configuration is said to be in :term:`read write mode`.

But at the `output` step, it is obviously no longer possible to modify the value.
The configuration is said to be in :term:`read only mode`.

.. attention::
   It is important not to confuse `value` and `calculated value`.
   The result of a calculation can change over time.
   In this case, the value does indeed correspond to the result of the calculation.

.. list-table::
   :header-rows: 1

   * - **Step**
     - Actor
     - Lifecyle
     - Mutability
     - Value

   * - **Structured data**
     - Integrator
     - - Creation
       - Initialization
     - Mutable
     - Mutable default value

   * - **User data**
     - Operator
     - - Reading
       - Assignment
       - Access control
     - Immutable
     - Read write

   * - **Output**
     - - Operator
       - Integrator
     - - Reading
       - Access control
     - Immutable
     - Read only
