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

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

Библиотека функций для работы с файлами

```python
file.resolve(путь: str) -> str
```

Функция приводит запись `точка_входа:путь` (например `user:worlds/house1`) к обычному пути. (например `C://Users/user/.voxeng/worlds/house1`)

> [!NOTE]
> Функцию не нужно использовать в сочетании с другими функциями из библиотеки, так как они делают это автоматически

Возвращаемый путь не является каноническим и может быть как абсолютным, так и относительным.

```python
file.read(путь: str) -> str
```

Читает весь текстовый файл и возвращает в виде строки

```python
file.read_bytes(путь: str) -> array of integers
```

Читает файл в массив байт.

```python
file.write(путь: str, текст: str) -> nil
```

Записывает текст в файл (с перезаписью)

```python
file.write_bytes(путь: str, data: array of integers)
```

Записывает массив байт в файл (с перезаписью)

```python
file.length(путь: str) -> int
```

Возвращает размер файла в байтах, либо -1, если файл не найден

```python
file.exists(путь: str) -> bool
```

Проверяет, существует ли по данному пути файл или директория

```python
file.isfile(путь: str) -> bool
```

Проверяет, существует ли по данному пути файл

```python
file.isdir(путь: str) -> bool
```

Проверяет, существует ли по данному пути директория

```python
file.mkdir(путь: str) -> bool
```

Создает директорию. Возвращает true если была создана новая директория

```python
file.mkdirs(путь: str) -> bool
```

Создает всю цепочку директорий. Возвращает true если были созданы директории.

```python
file.find(путь: str) -> str
```

Ищет файл от последнего пака до res. Путь указывается без префикса. Возвращает путь с нужным префиксом. Если файл не найден, возвращает nil.

```python
file.remove(путь: str) -> bool
```

Удаляет файл. Возращает **true** если файл существовал. Бросает исключение при нарушении доступа.

```python
file.remove_tree(путь: str) -> int
```

Рекурсивно удаляет файлы. Возвращает число удаленных файлов.

## Библиотека 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 строку в таблицу.

## Библиотека 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}/...` возможна потеря данных при перезаписи мира.