# Документация на 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_SUCCES``` из ```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
```