rougail/README.md

![Logo Rougail](logo.png "logo rougail")

# Rougail

## Description

Rougail is a free full-featured configuration manager library written in python3.

The configuration is describe in YAML ou XML dictionary files.

Those dictionaries are converted into [Tiramisu](https://framagit.org/tiramisu/tiramisu) objects and can generates configuration files with template written in [Cheetah](https://cheetahtemplate.org/) or [Jinja](https://jinja.palletsprojects.com/).

Rougail can be incorporated with other technologies and stacks regardless of whether they’re written in Python or not.

## Simple example

Create directories:

```bash
# mkdir dict tmpl tmp dest
```

### Dictionary

A dictionary is a services and a variables description file.

Create the file `dict/dictionary.yml`:

```yml
version: '0.10'

# describe a first service with a single file
services:
- service:
  - name: my_service
    file:
    - engine: jinja
      text: /etc/filename

# describe a variable my_first_variable
# and a family with a variable my_second_variable
variables:
- variable:
  - name: my_first_variable
    value:
    - text: my_value
- family:
  - name: my_family
    variables:
    - variable:
      - name: my_second_variable
        type: number
        mandatory: true
        value:
        - text: 1
```

### Template

Create a [Jinja](https://jinja.palletsprojects.com/) template `tmpl/filename`:

```
My first value: {{ my_first_variable }}
My second value: {{ my_second_variable }}
```

### Generate template

#### With default value:

Here is a python3 example file:

```python
from rougail import Rougail, RougailConfig
from asyncio import run

async def main():
    RougailConfig['dictionaries_dir'] = ['dict']
    RougailConfig['templates_dir'] = ['tmpl']
    RougailConfig['tmp_dir'] = 'tmp'
    RougailConfig['destinations_dir'] = 'dest'
    rougail = Rougail()
    await rougail.template()

run(main())
```

The destination file is generated:

```bash
# cat dest/etc/filename
My first value: my_value
My second value: 1
```

#### With modified value

Remove old generated file:

```bash
# rm -f dest/etc/filename
```

Use [Tiramisu](https://framagit.org/tiramisu/tiramisu) API to change values:

```python
from rougail import Rougail, RougailConfig
from asyncio import run

async def main():
    RougailConfig['dictionaries_dir'] = ['dict']
    RougailConfig['templates_dir'] = ['tmpl']
    RougailConfig['tmp_dir'] = 'tmp'
    RougailConfig['destinations_dir'] = 'dest'
    rougail = Rougail()
    config = await rougail.get_config()
    await config.option('rougail.my_first_variable').value.set('modified_value')
    await config.option('rougail.my_family.my_second_variable').value.set(2)
    await rougail.template()


run(main())
```

The destination file is generated with new values:

```bash
# cat dest/etc/filename
My first value: modified_value
My second value: 2
```

# Link

* [Documentation (french)](doc/README.md)
* [Licence ](LICENSE)

# Related projects

* [Tiramisu](https://framagit.org/tiramisu/tiramisu)
* [Risotto](https://cloud.silique.fr/gitea/risotto/risotto)