206 lines
7.2 KiB
Markdown
206 lines
7.2 KiB
Markdown
# Документация на Microconf
|
||
- [Формат файла](#описание-формата-файла)
|
||
- [Библиотека](#библиотека)
|
||
- [Формат запроса](#формат-запроса)
|
||
- [Формат структуры настроек](#формат-структуры-настроек)
|
||
- [Формат ответа на запрос](#формат-ответа-на-запрос)
|
||
- [Формат обработчика запроса](#формат-обработчика-запроса)
|
||
- [Пример обработчика](#пример-обработчика-запроса)
|
||
- [Готовый обработчик](#готовый-обработчик)
|
||
- [Общий пример](#пример)
|
||
- [Компиляция примера](#компиляция-примера)
|
||
## Описание формата файла
|
||
### Формат значений
|
||
```ini
|
||
# Это комментарий
|
||
имя_ключа::имя_значения
|
||
```
|
||
Ключ и значение могут содержать пробелы, они не будут удалены, например:
|
||
```ini
|
||
Имя Фамилия :: Иван Иванович
|
||
```
|
||
> [!WARNING]
|
||
> Пробелы по краям от текста будут удалены, например:
|
||
> ```ini
|
||
> Имя Фамилия :: Иван Иванович
|
||
> ```
|
||
> Будет:
|
||
> ```bash
|
||
> $/home/user> ./microconf
|
||
> Key=Имя Фамилия Value=Иван Иванович
|
||
> ```
|
||
### Формат комментариев
|
||
```ini
|
||
# Это тоже
|
||
Имя::Значение # Это комментарий
|
||
```
|
||
## Библиотека
|
||
Подключается файл ```microconf.h```.
|
||
Файл ```handler.h``` содержит встроенный обработчик.
|
||
## Формат запроса
|
||
Для обработки и парсинга файла к библиотеке необходимо сделать запрос:
|
||
```c
|
||
/*
|
||
* Функция отправки запроса:
|
||
*
|
||
* int microconf_compile (
|
||
* файловая_структура,
|
||
* обработчик_ввода,
|
||
* структура_настроек
|
||
* );
|
||
*
|
||
*/
|
||
```
|
||
Функция требует файл (тип ```FILE*```), функцию-обработчик и структуру настроек.
|
||
> [!NOTE]
|
||
> Проверка целостности файла реализована, однако закрыть файл необходимо вручную.
|
||
## Формат структуры настроек
|
||
Структура настроек имеет тип ```config_info_t```:
|
||
```c
|
||
typedef struct {
|
||
size_t max_len_key;
|
||
size_t max_len_val;
|
||
ulong max_cnt;
|
||
} config_info_t;
|
||
```
|
||
Параметр ```max_len_key``` - максимальная длина ключа (в байтах).
|
||
Параметр ```max_len_val``` - максимальная длина значения (в байтах).
|
||
Параметр ```max_cnt``` - максимальное количество пар **ключ-значение**.
|
||
## Формат ответа на запрос
|
||
Функция ```microconf_compile``` возвращает значение типа ```int```. Это значение является статусом завершения.
|
||
Статус может быть константой ```EXIT_FAILURE``` или ```EXIT_SUCCESS``` из ```stdlib.h```.
|
||
## Формат обработчика запроса
|
||
Функция вызывает обработчик:
|
||
```c
|
||
save_data_t имя_обработчика(unsigned long);
|
||
```
|
||
Параметром обработчика является порядковый номер пары **ключ-значение**.
|
||
Обработчик должен вернуть структуру типа ```save_data_t```.
|
||
Структура:
|
||
```c
|
||
typedef struct {
|
||
char* key;
|
||
char* value;
|
||
} save_data_t;
|
||
```
|
||
В ```key``` нужно передать адрес строки для сохранения ключа, в ```value``` - адрес строки значения.
|
||
Если не нужно сохранять значения или ключи, то можно вместо них передать ```NULL```. Значение или ключ не будет сохранен.
|
||
## Пример обработчика запроса
|
||
```c
|
||
char keys[...][...] = {""};
|
||
char vals[...][...] = {""};
|
||
|
||
save_data_t my_handler(unsigned long num) {
|
||
save_data_t t;
|
||
t.key = keys[num];
|
||
t.value = vals[num];
|
||
return t;
|
||
}
|
||
...
|
||
```
|
||
## Готовый обработчик
|
||
В файле ```handler.h``` описан готовый обработчик.
|
||
Ему требуется передать массив ключей и значений:
|
||
```c
|
||
/* Массивы */
|
||
|
||
char vals[VALS_COUNT][LEN_MAX_VAL] = {""};
|
||
char keys[VALS_COUNT][LEN_MAX_KEY] = {""};
|
||
|
||
/* Готовый обработчик, требует только имена массивов */
|
||
|
||
#define INPUT_KEYS_NUM keys
|
||
#define INPUT_VALS_NUM vals
|
||
|
||
#include "handler.h"
|
||
...
|
||
```
|
||
> [!WARNING]
|
||
> Определить константы ```INPUT_KEYS_NUM``` и ```INPUT_VALS_NUM``` нужно **перед** подключение библиотеки!
|
||
# Пример
|
||
```c
|
||
#include "microconf.h"
|
||
|
||
/* Настройки */
|
||
|
||
#define TEST_FILE "microconf_test.conf"
|
||
#define LEN_MAX_VAL 20
|
||
#define LEN_MAX_KEY 10
|
||
#define VALS_COUNT 3
|
||
|
||
/* Массивы */
|
||
|
||
char vals[VALS_COUNT][LEN_MAX_VAL] = {""};
|
||
char keys[VALS_COUNT][LEN_MAX_KEY] = {""};
|
||
|
||
/* Готовый обработчик, требует только имена массивов */
|
||
|
||
#define INPUT_KEYS_NUM keys
|
||
#define INPUT_VALS_NUM vals
|
||
|
||
#include "handler.h"
|
||
|
||
/*
|
||
*
|
||
* Можно определить свой обработчик, например:
|
||
*
|
||
* save_data_t my_handler(unsigned long num) {
|
||
* save_data_t t;
|
||
* t.key = keys[num];
|
||
* t.value = vals[num];
|
||
* return t;
|
||
* }
|
||
*
|
||
*/
|
||
|
||
int main(void) {
|
||
/* Отрыть файл */
|
||
file_t fp = fopen(TEST_FILE, "r");
|
||
/*
|
||
* Структура данных:
|
||
*
|
||
* {
|
||
* максимальная_длинна_ключа,
|
||
* максимальная_длинна_значения,
|
||
* максимальное_количество_ключей
|
||
* };
|
||
*
|
||
*/
|
||
config_info_t st = {LEN_MAX_KEY, LEN_MAX_VAL, VALS_COUNT};
|
||
/*
|
||
* Функция отправки запроса:
|
||
*
|
||
* int microconf_compile (
|
||
* файловая_структура,
|
||
* обработчик_ввода,
|
||
* структура
|
||
* );
|
||
*
|
||
*/
|
||
int status = microconf_compile(fp, microconf_std_handler, st);
|
||
/* При ошибке - аварийно завершить */
|
||
if (status == EXIT_FAILURE) return status;
|
||
/* Вывести в консоль */
|
||
unsigned char num_read = 0;
|
||
while (num_read < 3) {
|
||
char* key = keys[num_read];
|
||
char* val = vals[num_read];
|
||
printf("Key=%s Value=%s\n", key, val);
|
||
num_read ++;
|
||
}
|
||
/* Закрытие файла и успешное завершение программы */
|
||
fclose(fp);
|
||
return EXIT_SUCCESS;
|
||
}
|
||
```
|
||
## Компиляция примера
|
||
С помощью **Git**.
|
||
```bash
|
||
cd ~
|
||
git clone https://gitlabor.ru/German/microconflib.git
|
||
cd microconflib
|
||
make clear
|
||
make
|
||
make run
|
||
```
|