# Файловая система и сериализация

## Библиотека *file*

См. [библиотека file](builtins/libfile.md)

## Библиотека json

Библиотека содержит функции для сериализации и десериализации таблиц:

```python
json.tostring(object: table, human_readable: bool=false) -> str
```

Сериализует объект в JSON строку. При значении второго параметра **true** будет использовано многострочное форматирование, удобное для чтения человеком, а не компактное, использующееся по-умолчанию.

```python
json.parse(code: str) -> table
```

Парсит JSON строку в таблицу.

## Библиотека toml

Библиотека содержит функции для сериализации и десериализации таблиц:

```python
toml.tostring(object: table) -> str
```

Сериализует объект в TOML строку.

```python
toml.parse(code: str) -> table
```

Парсит TOML строку в таблицу.

## Библиотека yaml

Библиотека содержит функции для сериализации и десериализации таблиц:

```python
yaml.tostring(object: table) -> str
```

Сериализует объект в YAML строку.

```python
yaml.parse(code: str) -> table
```

Парсит YAML строку в таблицу.

## Библиотека xml

Библиотека содержит функции для сериализации и десериализации XML:

Далее XML как тип данных обозначает Lua-таблицу со следующей структурой:
- Тег элемента доступен по ключу `#`
- XML-аттрибуты доступны как пары ключ = значение
- Вложенные элементы доступны по индексу

Таблица используется как словарь, так и массив.

Пример:

```xml
<panel size='400' color='0' interval='1' context='menu'>
    <button onclick='menu.page="worlds"'>@Worlds</button>
</panel>
```

Эквивалентная Lua-таблица:

```lua
{
    ['#'] = "panel",
    size = "400",
    color = "0",
    interval = "1",
    context = "menu",
    {
        ['#'] = "button",
        onclick = 'menu.page="worlds"',
        {
            "@Worlds"
        }
    }
}
```

Соответственно, элемент button доступен как `элемент_panel[1]`.

```lua
-- Сериализует дерево в формате XML
-- multiline - использовать ли многострочное форматирование
xml.tostring(data: XML, multiline: bool = true) -> str

-- Парсит XML
xml.parse(code: str) -> XML

-- Парсит формат VCD (VoxelCore Declaration), используемый форматами VCM и VCA.
-- root_tag - будет неявно создан корневой элемент с указанным тегом,
-- содержащий все корневые элементы
xml.parse_vcd(code: str, root_tag: str | nil = nil) -> XML
```

## Библиотека bjson

Библиотека содержит функции для работы с двоичным форматом обмена данными [vcbjson](../../specs/binary_json_spec.md).

```lua
-- Кодирует таблицу в массив байт
bjson.tobytes(
    -- кодируемая таблица
    value: table, 
    -- сжатие
    [опционально] compression: bool=true
) -> Bytearray

-- Декодирует массив байт в таблицу
bjson.frombytes(bytes: table | Bytearray) -> table
```

## Сохранение данных в мире

При сохранении данных пака в мире следует использовать функцию  
```python
pack.data_file(id_пака: str, имя_файла: str) -> str
```

Функция возвращает путь к файлу данных по типу: `world:data/id_пака/имя_файла`
и создает недостающие директории в пути.

При использовании путей не соответствующим `data/{packid}/...` возможна потеря данных при перезаписи мира.