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

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

## Содержание
- [Основные методы](#основные-методы)
- [Файлы](#файлы)
- [Директории](#директории)
- [Контент-паки](#контент-паки)
- [Zip-архивы](#zip-архивы)
- [IO-Stream](#io-stream)

## Основные методы
```lua
-- Возвращает размер файла в байтах, либо -1, если файл не найден
file.length(путь: string) -> number

-- Проверяет, существует ли по данному пути файл или директория
file.exists(путь: string) -> boolean

-- Возвращает список файлов и директорий в указанной.
file.list(путь: string) -> table<string>

-- Возвращает список файлов и директорий в указанной без указания конкретной точки входа.
file.list_all_res(путь: string) -> table<string>

-- Возвращает путь на уровень выше. Пример: `world:data/base/config.toml` -> `world:data/base`
file.parent(путь: string) -> string

-- Соединяет путь. Пример: `file.join("world:data", "base/config.toml")` -> `world:data/base/config.toml`
file.join(директория: string, путь: string) -> string

-- Ищет файл или директорию от последнего пака до res. Путь указывается без префикса. Возвращает путь с нужным префиксом. Если файл не найден, возвращает nil.
file.find(путь: string) -> string

-- Создаёт файловую систему в памяти, возвращает имя точки входа. Удаляется при выгрузке контента.
-- * Следует использовать данную функцию вместо конкатенации с `/`, так как `префикс:/путь` не является валидным.
file.create_memory_device() -> string

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

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

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

## Файлы
```lua
-- Читает весь текстовый файл и возвращает в виде строки
file.read(путь: string) -> string

-- Читает весь текстовый файл и делит его на строки по символу \n
-- Возвращает массив строк файла
file.readlines(путь: string) -> table<string>

-- Читает файл в массив байт. При значении usetable = false возвращает Bytearray вместо table.
file.read_bytes(путь: string, [опционально] usetable: boolean=false) -> Bytearray | table<number>

-- Записывает текст в файл (с перезаписью)
file.write(путь: string, текст: string) -> nil

-- Записывает массив байт в файл (с перезаписью)
file.write_bytes(путь: string, data: table<number>)

-- Удаляет файл. Возращает true если файл существовал. Бросает исключение при нарушении доступа.
file.remove(путь: string) -> boolean

-- Проверяет, существует ли по данному пути файл
file.isfile(путь: string) -> boolean

-- Извлекает имя файла из пути. Пример: `world:data/base/config.toml` -> `config.toml`.
file.name(путь: string) -> string

-- Извлекает имя файла из пути, удаляя расширение. Пример: `world:data/base/config.toml` -> `config`.
file.stem(путь: string) -> string

-- Извлекает расширение из пути. Пример: `world:data/base/config.toml` -> `toml`.
file.ext(путь: string) -> string
```

## Директории
```lua
-- Создает директорию. Возвращает true если была создана новая директория
file.mkdir(путь: string) -> boolean

-- Создает всю цепочку директорий. Возвращает true если были созданы директории.
file.mkdirs(путь: string) -> boolean

-- Рекурсивно удаляет файлы. Возвращает число удаленных файлов.
file.remove_tree(путь: string) -> number

-- Проверяет, доступно ли право записи по указанному пути.
file.is_writeable(путь: string) -> boolean

-- Проверяет, существует ли по данному пути директория
file.isdir(путь: string) -> boolean

-- Извлекает точку входа (префикс) из пути. Пример: `world:data/base/config.toml` -> `world`.
file.prefix(путь: string) -> string

-- Убирает точку входа (префикс) из пути. Пример: `world:data/base/config.toml` -> `data/base/config.toml`
file.path(путь: string) -> string
```

## Контент-паки
```lua
-- Совмещает массивы из JSON файлов разных паков.
file.read_combined_list(путь: string) -> table

-- Совмещает объекты из JSON файлов разных паков.
file.read_combined_object(путь: string) -> table
```

## Zip-архивы
```lua
-- Монтирует ZIP-архив как файловой системе. Возвращает имя точки входа.
file.mount(путь: string) -> string

-- Размонтирует точку входа.
file.unmount(точка_входа: string) -> string

-- Создаёт ZIP-архив из содержимого указанной директории.
file.create_zip(директория: string, выходной_файл: string) -> string
```

## IO-Stream

### Режимы
- `r` - Чтение из файла
- `w` - Запись в файл
- `b` - Открыть поток в двоичном режиме (см. [io_stream.md](../io_stream.md))
- `+` - Работает совместно с `w`. Добавляет к существующим данным новые (`append-mode`)

Режимы также можно комбинировать

### Методы
```lua
-- Открывает поток для записи/чтения в файл по пути.
-- * Аргумент `режим` это список отдельных режимов, в котором каждый режим обозначается одним символом
file.open(путь: string, режим: string) -> io_stream

-- Открывает поток для записи/чтения в Named Pipe по пути `путь`
-- * `/tmp/` или `\\\\.\\pipe\\` добавлять не нужно - движок делает это автоматически.
-- * Недоступен режим с `+`
file.open_named_pipe(имя: string, режим: string) -> io_stream
```