Libs-dev/libini/ru

INI файлы — структурированные текстовые файлы, легко воспринимаемые человеком. Каждый файл состоит из нескольких секций, в каждой из которых находится несколько ключей со значениями. Вот пример такого файла:

[цвета фруктов]
банан = жёлтый
апельсин = оранжевый
клубника = красный

[цвета овощей]
огурец = зелёный

Имена секций заключены в квадратные скобки, пишутся в одну строку и могут состоять из любых символов. Секции разделяют файл на части, в которых находятся ключи и соответствующие им значения. В начале файла (перед первой секцией) также могут находится ключи и значения, не принадлежащие ни одной из секций. Ключи и значения также пишутся в одну строку и разделяются друг от друга символом равенства "=". Имя ключа, конечно же, не может содержать символ "=". Значение ключа — строка от первого найденного символа "=" до конца строки.

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

Если каждая секция определяет набор ключей, то каждый ключ, в свою очередь, определяет одно значение. Имена секций и ключей не обязаны быть уникальными, однако если найдётся два ключа (в пределах одной секции) с одинаковым именем, значения будут читаться и записываться в тот из них, что находится ближе к началу файла.

Для всех файловых операций, libini использует libio.

Функции (перебор сущностей)

ini_enum_sections

Перебрать секции, вызывая пользовательскую функцию для каждого из них.

Прототип:

proc ini.enum_sections _f_name, _callback

Аргументы:

_f_name → asciiz

путь к INI файлу

_callback

адрес пользовательской функции: func(f_name, sec_name), где

f_name → asciiz

путь к INI файлу (совпадает с переданным в функцию)

sec_name → asciiz

имя найденной секции

Результат:

eax → dword

-1 (ошибка) / 0

ini_enum_keys

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

Прототип:

proc ini.enum_keys _f_name, _sec_name, _callback

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_callback

адрес пользовательской функции: func(f_name, sec_name, key_name, key_value), где

f_name → asciiz

путь к INI файлу (совпадает с переданным в функцию)

sec_name → asciiz

имя секции (совпадает с переданным в функцию)

key_name → asciiz

имя найденного ключа

key_value → asciiz

значение найденного ключа

Результат:

eax → dword

-1 (ошибка) / 0

Функции (получение и установка значений)

Все функции получения значений безопасны, возвращая переданное значение по умолчанию при любой ошибке.

ini_get_str

Прочитать строку.

Прототип:

proc ini.get_str _f_name, _sec_name, _key_name, _buffer, _buf_len, _def_val

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_buffer → byte*

буфер для записи полученного значения

_buf_len → dword

размер буфера (максимальное количество байт для чтения)

_def_val → asciiz

возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

Результат:

eax → dword

-1 (ошибка) / 0

[_buffer] → asciiz

[_def_val] (ошибка) / найденное значение ключа

ini_set_str

Записать строку.

Прототип:

proc ini.set_str _f_name, _sec_name, _key_name, _buffer, _buf_len

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_buffer → byte*

буфер, содержащий записываемое значение

_buf_len → dword

размер буфера (количество байт для записи)

Результат:

eax → dword

-1 (ошибка) / 0

ini_get_int

Прочитать целое число.

Прототип:

proc ini.get_int _f_name, _sec_name, _key_name, _def_val

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_def_val → dword

возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

Результат:

eax → dword

[_def_val] (ошибка) / найденное значение ключа

ini_set_int

Записать целое число.

Прототип:

proc ini.set_int _f_name, _sec_name, _key_name, _val

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_val → dword

значение

Результат:

eax → dword

-1 (ошибка) / 0

ini_get_color

Прочитать цвет.

Прототип:

proc ini.get_color _f_name, _sec_name, _key_name, _def_val

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_def_val → dword

возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

Результат:

eax → dword

[_def_val] (ошибка) / найденное значение ключа

ini_set_color

Записать цвет.

Прототип:

proc ini.set_color _f_name, _sec_name, _key_name, _val

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_val → dword

значение

Результат:

eax → dword

-1 (ошибка) / 0

ini_get_shortcut

Прочитать клавишу быстрого доступа.

Строка для ini_get_shortcut - произвольное количество модификаторов Ctrl/Alt/Shift/LCtrl/LAlt/LShift/RCtrl/RAlt/RShift, после которых следует латинская буква/цифра/имя клавиши (имена собственные имеют Home, End, PgUp, PgDn, Ins=Insert, Del=Delete, Tab, Plus, Esc, Enter, Backspace, Space, Left, Right, Up, Down). Строку можно писать с любым регистром символов. Части пишутся либо слитно, либо разделяются плюсом. Например: Ctrl+Alt+Backspace, RCtrl+RShift, ShiftA, f10, shiftalt5

Прототип:

proc ini.get_shortcut _f_name, _sec_name, _key_name, _def_val, _modifiers

Аргументы:

_f_name → asciiz

путь к INI файлу

_sec_name → asciiz

имя секции

_key_name → asciiz

имя ключа

_def_val → dword

возвращаемое значение по умолчанию, если ключ, секция или файл не будут найдены

_modifiers → dword*

адрес переменной типа dword, получающей значение модификаторов для передачи функции 66.4

Результат:

eax → dword

[_def_val] (ошибка) / скан-код клавиши быстрого доступа

[[_modifiers]] → dword

неизменно (ошибка) / состояние модификаторов клавиши быстрого доступа

Примеры использования

Этот пример перебирает секции, а потом в пользовательской функции перебирает ключи каждой найденной секции. Заметьте, что мы используем "invoke", так как вызов функции — косвенный.

; ...

        invoke  ini_enum_sections, filename, ini_section_callback

; ...

proc ini_section_callback _filename, _section_name
        ; эта функция вызывается библиотекой для каждой найденной в файле секции

        invoke  ini_enum_keys, [_filename], [_section_name], ini_key_callback

        ; ...

        ret
endp 

proc ini_key_callback _filename, _section_name, _key_name, _key_value
        ; эта функция вызывается библиотекой для каждого найденного в файле ключа каждой секции

        ; ...

        ret
endp

; ...

filename db '/hd0/1/a.ini', 0