voxelcore/doc/ru/scripting/io_stream.md

Класс io_stream

Класс, предназначенный для работы с потоками

Содержание

• Режимы
  • general
  • flush
  • binary
• Методы
  • режимы и их состояния
  • I/O
  • Buffered-методы
  • Методы потока

Режимы

Поток имеет три различных вида режима:

• Режим общего поведения (general / mode)

• Режим сброса (flush / flushMode)

• Двоичный режим (binary)

general

Определяет, как поток обрабатывает чтение и запись, имеет три подрежима:

Режим	Описание
"default"	Прямой режим. read может вернуть меньше байт, чем запрошено. write сразу отправляет данные в низкоуровневый дескриптор. Нет буферизации.
"yield"	Как default, но при нехватке данных в read(n) поток будет вызывать coroutine.yield(), пока не соберёт ровно n байт. Удобно для корутин.
"buffered"	Включает внутренние буферы чтения и записи. read берёт данные из буфера, write — складывает в буфер. При превышении maxBufferSize — ошибка buffer overflow.

flush

Работает только в режиме "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() остаются текстовыми — они всегда работают со строками.

Методы режимов и их состояний

-- Возвращает true, если поток используется в двоичном режиме
io_stream:is_binary_mode() -> boolean

-- Включает или выключает двоичный режим
io_stream:set_binary_mode(boolean)

-- Возвращает режим работы потока
io_stream:get_mode() -> string

-- Задаёт режим работы потока. Выбрасывает ошибку, если передан неизвестный режим
io_stream:set_mode(string)

-- Возвращает режим работы flush
io_stream:get_flush_mode() -> string

-- Задаёт режим работы flush
io_stream:set_flush_mode(string)

I/O методы

--[[
Читает данные из потока
В двоичном режиме:
    Если arg - number, то читает из потока arg байт и возвращает ввиде Bytearray или таблицы, если useTable = true

    Если arg - string, то функция интерпретирует arg как шаблон для byteutil. Прочитает кол-во байт, которое определено шаблоном, передаст их в byteutil.unpack и вернёт результат
В текстовом режиме:
    Если arg - number, то читает нужное кол-во строк с окончанием CRLF/LF из arg и возвращает ввиде таблицы. Также, если trimEmptyLines = true, то удаляет пустые строки с начала и конца из итоговой таблицы

    Если arg не определён, то читает одну строку с окончанием CRLF/LF и возвращает её.
--]]
io_stream:read(
    [опционально] arg: number | string,
    [опционально] useTable | trimEmptyLines: boolean
) -> Bytearray | table<number> | string | table<string> | ...

--[[
Записывает данные в поток
В двоичном режиме:
    Если arg - string, то функция интерпретирует arg как шаблон для byteutil, передаст его и ... в byteutil.pack и результат запишет в поток

    Если arg - Bytearray | table<number>, то записывает байты в поток

В текстовом режиме:
    Если arg - string, то записывает строку в поток (вместе с окончанием LF)

    Если arg - table<string>, то записывает каждую строку из таблицы отдельно
--]]
io_stream:write(
    arg: Bytearray | table<number> | string | table<string>,
    [опционально] ...
)

-- Читает одну строку с окончанием CRLF/LF из потока вне зависимости от двоичного режима
io_stream:read_line() -> string

-- Записывает одну строку с окончанием LF в поток вне зависимости от двоичного режима
io_stream:write_line(string)

--[[
В двоичном режиме:
    Читает все доступные байты из потока и возвращает ввиде Bytearray или table<number>, если useTable = true

В текстовом режиме:
    Читает все доступные строки из потока в table<string> если useTable = true, или в одну строку вместе с окончаниями, если нет

--]]
io_stream:read_fully(
    [опционально] useTable: boolean
) -> Bytearray | table<number> | table<string> | string

Методы Buffered-режима

--[[
Если length определён, то возвращает true, если length байт доступно к чтению. Иначе возвращает false

Если не определён, то возвращает количество байт, которое можно прочитать

--]]
io_stream:available(
    [опционально] length: number
) -> number | boolean

-- Возвращает максимальный размер буферов
io_stream:get_max_buffer_size() -> number

-- Задаёт новый максимальный размер буферов
io_stream:set_max_buffer_size(max_size: number)

Методы контроля состояния потока

-- Возвращает true, если поток открыт на данный момент
io_stream:is_alive() -> bool

-- Возвращает true, если поток закрыт на данный момент
io_stream:is_closed() -> bool

-- Закрывает поток
io_stream:close()

-- Записывает все данные из write-буфера в поток в buffer/all flush-режимах
-- Вызывает ioLib.flush() в all flush-режиме
io_stream:flush()


-- Создаёт новый поток с переданным дескриптором и использующим переданную I/O библиотеку. (Более подробно в core:io_stream.lua)
io_stream.new(
    descriptor: int,
    binaryMode: bool,
    ioLib: table,
    [опционально] mode: string = "default",
    [опционально] flushMode: string = "all"
) -> io_stream