Класс io_stream

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

Содержание

Режимы
- general
- flush
- binary
Методы

Режимы

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

Режим общего поведения (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<int>`	`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 - int, то читает из потока arg байт и возвращает ввиде Bytearray или таблицы, если useTable = true

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

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

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

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

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

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

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

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

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

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

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

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

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

В не буферизированном режиме потока может всегда возвращать 0 или false, если поток не поддерживает available.
--]]
io_stream:available(
    [опционально] length: int
) -> int | boolean

--[[
Устанавливает позицию в потоке (всегда в байтах)
Режимы:
    b - Задаёт позицию относительно начало файла
    c - Задаёт позицию относительно текущей позиции
    e - Задаёт позицию относительно конца файла
    
Может бросать ошибку, если поток не поддерживает seek.
--]]
io_stream:seek(
    mode: string
    offset: int
)

-- Возвращает текущую позицию в потоке от начала.
-- Может бросать ошибку, если поток не поддерживает tell.
io_stream:tell() -> int

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

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

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

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

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

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

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

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

-- Создаёт новый поток из Bytearray.
-- Может использоваться одновременно как для чтения, так и для записи.
-- Результат записи будет записан в тот же Bytearray, что был передан в функцию.
io_stream.wrap_bytearray(
  buffer: Bytearray,
  
  -- по-умолчанию равен true, поскольку функция из вводных аргументов
  -- будет использоваться преимущественно для работы с двоичными данными.
  [опционально] binaryMode: boolean = true
 ) -> io_stream

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

11 KiB Raw Blame History Unescape Escape