mirror of
https://github.com/MihailRis/voxelcore.git
synced 2026-10-07 12:01:50 +00:00
Improved docs (#708)
* начало переписи доков * extensions update * libapp update * libfile update * io_stream update * Update io_stream.md * io_stream update x3 * io_stream update x4 * libtime update * libgui update + make bytearray.md * libinput update * Update libapp.md * Update libapp.md * libgui update * events.md ru fix * да ну не надо так делать --> не имеет смысла, ибо гитхаб -> показывает адекватно * types refactoring * fixes * Update libblock.md * Update libblock.md * Update libbyteutil.md
This commit is contained in:
Xertis
MihailRis
parent
8b31bdeb78
commit
ac02bc0c8e
43 changed files with 1107 additions and 1314 deletions
|
|
@ -2,182 +2,182 @@
|
|||
|
||||
Класс, предназначенный для работы с потоками
|
||||
|
||||
## Содержание
|
||||
- [Режимы](#режимы)
|
||||
- [general](#general)
|
||||
- [flush](#flush)
|
||||
- [binary](#binary)
|
||||
- Методы
|
||||
- [режимы и их состояния](#методы-режимов-и-их-состояний)
|
||||
- [I/O](#io-методы)
|
||||
- [Buffered-методы](#методы-buffered-режима)
|
||||
- [Методы потока](#методы-контроля-состояния-потока)
|
||||
|
||||
## Режимы
|
||||
|
||||
Поток имеет три различных вида режима:
|
||||
- Режим общего поведения (`general` / `mode`)
|
||||
|
||||
**general** - Общий режим работы I/O
|
||||
**binary** - Формат записи и чтения I/O
|
||||
**flush** - Режим работы flush
|
||||
- Режим сброса (`flush` / `flushMode`)
|
||||
|
||||
- Двоичный режим (`binary`)
|
||||
|
||||
### general
|
||||
|
||||
Имеет три режима:
|
||||
Определяет, как поток обрабатывает чтение и запись,
|
||||
имеет три подрежима:
|
||||
|
||||
**default** - Дефолтный режим работы потока. При read может вернуть только часть от требуемых данных, при write сразу записывает данные в поток.
|
||||
|
||||
**yield** - Почти тоже самое, что и **default**, но всегда будет возвращать все требуемые данные. Пока они не будут прочитаны, будет вызывать `coroutine.yield()`. Предназначен для работы в корутинах.
|
||||
|
||||
**buffered** - Буферизирует записываемые и читаемые данные.
|
||||
|
||||
При вызове `available`/`read` обновляет буфер чтения.
|
||||
|
||||
После обновления в `read`, если буфер чтения переполнен, то бросает ошибку `buffer overflow`.
|
||||
|
||||
Если требуемого кол-ва байт недостаточно в буфере для чтения, то бросает ошибку `buffer-underflow`.
|
||||
|
||||
При вызове `write` записывает итоговые байты в буфер для записи. Если он переполнен, то бросает ошибку `buffer overflow`.
|
||||
|
||||
При вызове `flush` проталкивает данные из буфера для записи в напрямую в поток
|
||||
| Режим | Описание |
|
||||
|---------------|--------|
|
||||
| `"default"` | Прямой режим. `read` может вернуть меньше байт, чем запрошено. `write` сразу отправляет данные в низкоуровневый дескриптор. Нет буферизации. |
|
||||
| `"yield"` | Как `default`, но при нехватке данных в `read(n)` поток будет вызывать `coroutine.yield()`, пока не соберёт ровно `n` байт. Удобно для корутин. |
|
||||
| `"buffered"` | Включает внутренние буферы чтения и записи. `read` берёт данные из буфера, `write` — складывает в буфер. При превышении `maxBufferSize` — ошибка `buffer overflow`. |
|
||||
|
||||
### flush
|
||||
|
||||
**all** - Сначала проталкивает данные из буфера напрямую в поток (если используется **buffered** режим), а после вызывает `flush` напрямую из библиотеки
|
||||
Работает только в режиме `"buffered"`,
|
||||
имеет два подрежима:
|
||||
|
||||
**buffer** - Только проталкивает данные из буфера в поток (если используется **buffered** режим)
|
||||
| Режим | Что делает `flush()` |
|
||||
|------------------|----------------------|
|
||||
| `"all"` (по умолчанию) | Сначала сбрасывает буфер записи → низкоуровневый `write`, затем вызывает `ioLib.flush(descriptor)` |
|
||||
| `"buffer"` | Сбрасывает только буфер записи, без вызова системного `flush` |
|
||||
|
||||
## Методы
|
||||
|
||||
Методы, позволяющие изменить или получить различные режимы поведения потока
|
||||
### binary
|
||||
**Независимый флаг** (включается через `set_binary_mode(true)` или при создании потока).
|
||||
Определяет, в каком виде методы `read` и `write` принимают и возвращают данные:
|
||||
|
||||
| binary = true | binary = false (по умолчанию) |
|
||||
|-----------------------------------------|----------------------------------------|
|
||||
| Данные — это **байты** (`Bytearray`, таблица чисел 0..255) | Данные — это **текстовые строки** |
|
||||
| `read(n)` → `Bytearray` или `table<number>`| `read()` → одна строка |
|
||||
| `read("i4 f")` → распаковка через `byteutil.unpack` | `read(n)` → n строк в таблице |
|
||||
| `write(Bytearray)` → запись байтов | `write("hello")` → строка + `\n` |
|
||||
| `write("i4", 42)` → `byteutil.pack` | `write({"a","b"})` → две строки с `\n`|
|
||||
|
||||
`read_line` / `write_line` — работают как в текстовом режиме
|
||||
|
||||
> [!WARNING]
|
||||
> Важно: даже в `binary = true` методы `read_line()` и `write_line()` остаются текстовыми — они всегда работают со строками.
|
||||
|
||||
## Методы режимов и их состояний
|
||||
|
||||
```lua
|
||||
-- Возвращает true, если поток используется в двоичном режиме
|
||||
io_stream:is_binary_mode() --> bool
|
||||
io_stream:is_binary_mode() -> boolean
|
||||
|
||||
-- Включает или выключает двоичный режим
|
||||
io_stream:set_binary_mode(bool)
|
||||
io_stream:set_binary_mode(boolean)
|
||||
|
||||
-- Возвращает режим работы потока
|
||||
io_stream:get_mode() --> string
|
||||
io_stream:get_mode() -> string
|
||||
|
||||
-- Задаёт режим работы потока. Выбрасывает ошибку, если передан неизвестный режим
|
||||
io_stream:set_mode(string)
|
||||
|
||||
-- Возвращает режим работы flush
|
||||
io_stream:get_flush_mode() --> string
|
||||
io_stream:get_flush_mode() -> string
|
||||
|
||||
-- Задаёт режим работы flush
|
||||
io_stream:set_flush_mode(string)
|
||||
```
|
||||
|
||||
I/O методы
|
||||
## I/O методы
|
||||
|
||||
```lua
|
||||
|
||||
--[[
|
||||
Читает данные из потока
|
||||
|
||||
В двоичном режиме:
|
||||
Если arg - number, то читает из потока arg байт и возвращает ввиде Bytearray или таблицы, если useTable = true
|
||||
|
||||
Если arg - int, то читает из потока arg байт и возвращает ввиде Bytearray или таблицы, если useTable = true
|
||||
|
||||
Если arg - string, то функция интерпретирует arg как шаблон для byteutil. Прочитает кол-во байт, которое определено шаблоном, передаст их в byteutil.unpack и вернёт результат
|
||||
|
||||
|
||||
Если arg - string, то функция интерпретирует arg как шаблон для byteutil. Прочитает кол-во байт, которое определено шаблоном, передаст их в byteutil.unpack и вернёт результат
|
||||
В текстовом режиме:
|
||||
Если arg - number, то читает нужное кол-во строк с окончанием CRLF/LF из arg и возвращает ввиде таблицы. Также, если trimEmptyLines = true, то удаляет пустые строки с начала и конца из итоговой таблицы
|
||||
|
||||
Если arg - int, то читает нужное кол-во строк с окончанием CRLF/LF из arg и возвращает ввиде таблицы. Также, если trimEmptyLines = true, то удаляет пустые строки с начала и конца из итоговой таблицы
|
||||
|
||||
Если arg не определён, то читает одну строку с окончанием CRLF/LF и возвращает её.
|
||||
Если arg не определён, то читает одну строку с окончанием CRLF/LF и возвращает её.
|
||||
--]]
|
||||
io_stream:read(
|
||||
[опционально] arg: int | string,
|
||||
[опционально] useTable | trimEmptyLines: bool
|
||||
) --> Bytearray | table<int> | string | table<string> | ...
|
||||
[опционально] arg: number | string,
|
||||
[опционально] useTable | trimEmptyLines: boolean
|
||||
) -> Bytearray | table<number> | string | table<string> | ...
|
||||
|
||||
--[[
|
||||
Записывает данные в поток
|
||||
|
||||
В двоичном режиме:
|
||||
Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток
|
||||
|
||||
Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток
|
||||
|
||||
Если arg - Bytearray | table<int>, то записывает байты в поток
|
||||
Если arg - Bytearray | table<number>, то записывает байты в поток
|
||||
|
||||
В текстовом режиме:
|
||||
Если arg - string, то записывает строку в поток (вместе с окончанием LF)
|
||||
|
||||
Если arg - string, то записывает строку в поток (вместе с окончанием LF)
|
||||
|
||||
Если arg - table<string>, то записывает каждую строку из таблицы отдельно
|
||||
Если arg - table<string>, то записывает каждую строку из таблицы отдельно
|
||||
--]]
|
||||
io_stream:write(
|
||||
arg: Bytearray | table<int> | string | table<string>,
|
||||
arg: Bytearray | table<number> | string | table<string>,
|
||||
[опционально] ...
|
||||
)
|
||||
|
||||
-- Читает одну строку с окончанием CRLF/LF из потока вне зависимости от двоичного режима
|
||||
io_stream:read_line() --> string
|
||||
io_stream:read_line() -> string
|
||||
|
||||
-- Записывает одну строку с окончанием LF в поток вне зависимости от двоичного режима
|
||||
io_stream:write_line(string)
|
||||
|
||||
--[[
|
||||
|
||||
В двоичном режиме:
|
||||
|
||||
Читает все доступные байты из потока и возвращает ввиде Bytearray или table<int>, если useTable = true
|
||||
Читает все доступные байты из потока и возвращает ввиде Bytearray или table<number>, если useTable = true
|
||||
|
||||
В текстовом режиме:
|
||||
|
||||
Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет
|
||||
Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет
|
||||
|
||||
--]]
|
||||
io_stream:read_fully(
|
||||
[опционально] useTable: bool
|
||||
) --> Bytearray | table<int> | table<string> | string
|
||||
[опционально] useTable: boolean
|
||||
) -> Bytearray | table<number> | table<string> | string
|
||||
```
|
||||
|
||||
Методы, имеющие смысл в использовании только в buffered режиме
|
||||
## Методы Buffered-режима
|
||||
|
||||
```lua
|
||||
--[[
|
||||
|
||||
Если length определён, то возвращает true, если length байт доступно к чтению. Иначе возвращает false
|
||||
|
||||
Если не определён, то возвращает количество байт, которое можно прочитать
|
||||
|
||||
--]]
|
||||
io_stream:available(
|
||||
[опционально] length: int
|
||||
) --> int | bool
|
||||
[опционально] length: number
|
||||
) -> number | boolean
|
||||
|
||||
-- Возвращает максимальный размер буферов
|
||||
io_stream:get_max_buffer_size() --> int
|
||||
io_stream:get_max_buffer_size() -> number
|
||||
|
||||
-- Задаёт новый максимальный размер буферов
|
||||
io_stream:set_max_buffer_size(max_size: int)
|
||||
io_stream:set_max_buffer_size(max_size: number)
|
||||
```
|
||||
|
||||
Методы, контролирующие состояние потока
|
||||
## Методы контроля состояния потока
|
||||
|
||||
```lua
|
||||
|
||||
-- Возвращает true, если поток открыт на данный момент
|
||||
io_stream:is_alive() --> bool
|
||||
io_stream:is_alive() -> bool
|
||||
|
||||
-- Возвращает true, если поток закрыт на данный момент
|
||||
io_stream:is_closed() --> bool
|
||||
io_stream:is_closed() -> bool
|
||||
|
||||
-- Закрывает поток
|
||||
io_stream:close()
|
||||
|
||||
--[[
|
||||
|
||||
Записывает все данные из write-буфера в поток в buffer/all flush-режимах
|
||||
Вызывает ioLib.flush() в all flush-режиме
|
||||
|
||||
--]]
|
||||
-- Записывает все данные из write-буфера в поток в buffer/all flush-режимах
|
||||
-- Вызывает ioLib.flush() в all flush-режиме
|
||||
io_stream:flush()
|
||||
```
|
||||
|
||||
Создание нового потока
|
||||
|
||||
```lua
|
||||
--[[
|
||||
|
||||
Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
|
||||
|
||||
--]]
|
||||
-- Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
|
||||
io_stream.new(
|
||||
descriptor: int,
|
||||
binaryMode: bool,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue