rougail/README.md

141 lines
3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

![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 theyre 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)