microconflib/DOCS.md

Документация на Microconf

• Формат файла
• Библиотека
• Формат запроса
• Формат структуры настроек
• Формат ответа на запрос
• Формат обработчика запроса
• Пример обработчика
• Готовый обработчик
• Общий пример
• Компиляция примера

Описание формата файла

Формат значений

# Это комментарий
имя_ключа::имя_значения

Ключ и значение могут содержать пробелы, они не будут удалены, например:

Имя Фамилия :: Иван Иванович

Warning

Пробелы по краям от текста будут удалены, например:

     Имя Фамилия    ::    Иван Иванович    

Будет:

$/home/user> ./microconf
Key=Имя Фамилия Value=Иван Иванович

Формат комментариев

# Это тоже
Имя::Значение # Это комментарий

Библиотека

Подключается файл microconf.h. Файл handler.h содержит встроенный обработчик.

Формат запроса

Для обработки и парсинга файла к библиотеке необходимо сделать запрос:

/*
 * Функция отправки запроса: 
 *
 *  int microconf_compile (
 *      файловая_структура, 
 *      обработчик_ввода, 
 *      структура_настроек
 * ); 
 * 
 */

Функция требует файл (тип FILE*), функцию-обработчик и структуру настроек.

Note

Проверка целостности файла реализована, однако закрыть файл необходимо вручную.

Формат структуры настроек

Структура настроек имеет тип config_info_t:

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.

Формат обработчика запроса

Функция вызывает обработчик:

save_data_t имя_обработчика(unsigned long);

Параметром обработчика является порядковый номер пары ключ-значение. Обработчик должен вернуть структуру типа save_data_t. Структура:

typedef struct { 
    char* key; 
    char* value; 
} save_data_t;

В key нужно передать адрес строки для сохранения ключа, в value - адрес строки значения. Если не нужно сохранять значения или ключи, то можно вместо них передать NULL. Значение или ключ не будет сохранен.

Пример обработчика запроса

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 описан готовый обработчик. Ему требуется передать массив ключей и значений:

/* Массивы */

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 нужно перед подключение библиотеки!

Пример

#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.

cd ~
git clone https://gitlabor.ru/German/microconflib.git
cd microconflib
make clear
make
make run