From 0af0e8a58d5d8b5e373e0e8068f6c95fd8166312 Mon Sep 17 00:00:00 2001 From: MihailRis Date: Fri, 27 Dec 2024 09:25:09 +0300 Subject: [PATCH 1/5] update byteutil --- src/logic/scripting/lua/libs/libbyteutil.cpp | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/logic/scripting/lua/libs/libbyteutil.cpp b/src/logic/scripting/lua/libs/libbyteutil.cpp index e4b20d8c..c221ad25 100644 --- a/src/logic/scripting/lua/libs/libbyteutil.cpp +++ b/src/logic/scripting/lua/libs/libbyteutil.cpp @@ -11,6 +11,7 @@ static size_t calc_size(const char* format) { switch (format[i]) { case 'b': case 'B': + case '?': outSize += 1; break; case 'h': @@ -43,8 +44,14 @@ static int pack(lua::State* L, const char* format, bool usetable) { for (int i = 0; format[i]; i++) { switch (format[i]) { case 'b': + builder.put(lua::tointeger(L, index)); + break; + case 'B': builder.put(lua::tointeger(L, index) & 0xFF); break; + case '?': + builder.put(lua::toboolean(L, index) ? 1 : 0); + break; case 'h': builder.putInt16(lua::tointeger(L, index), bigEndian); break; @@ -102,6 +109,7 @@ static int count_elements(const char* format) { switch (format[i]) { case 'b': case 'B': + case '?': case 'h': case 'H': case 'i': @@ -133,6 +141,12 @@ static int l_unpack(lua::State* L) { case 'b': lua::pushinteger(L, reader.get()); break; + case 'B': + lua::pushinteger(L, reader.get() & 0xFF); + break; + case '?': + lua::pushboolean(L, reader.get() != 0); + break; case 'h': lua::pushinteger(L, reader.getInt16(bigEndian)); break; From bb2cff5186ac3469fbcc80d56f693ae732c777a5 Mon Sep 17 00:00:00 2001 From: MihailRis Date: Fri, 27 Dec 2024 09:37:09 +0300 Subject: [PATCH 2/5] add byteutil docs --- doc/en/scripting/builtins/libbyteutil.md | 71 +++++++++++++++++++++++ doc/ru/scripting/builtins/libbyteutil.md | 72 ++++++++++++++++++++++++ 2 files changed, 143 insertions(+) create mode 100644 doc/en/scripting/builtins/libbyteutil.md create mode 100644 doc/ru/scripting/builtins/libbyteutil.md diff --git a/doc/en/scripting/builtins/libbyteutil.md b/doc/en/scripting/builtins/libbyteutil.md new file mode 100644 index 00000000..fce89eae --- /dev/null +++ b/doc/en/scripting/builtins/libbyteutil.md @@ -0,0 +1,71 @@ +# *byteutil* library + +The library provides functions for working with byte arrays represented as tables or Bytearrays. + +```lua +byteutil.pack(format: str, ...) -> Bytearray +byteutil.tpack(format: str, ...) -> table +``` + +Returns a byte array containing the provided values packed according to the format string. The arguments must exactly match the values required by the format. + +The format string consists of special characters and value characters. + +Special characters specify the byte order for the subsequent values: + +| Character | Byte Order | +| --------- | ------------------- | +| `@` | System | +| `=` | System | +| `<` | Little-endian | +| `>` | Big-endian | +| `!` | Network (big-endian)| + + +Value characters describe the type and size. + +| Character | C++ Equivalent | Lua Type | Size | +| --------- | -------------- | -------- | ------- | +| `b` | int8_t | number | 1 byte | +| `B` | uint8_t | number | 1 byte | +| `?` | bool | boolean | 1 byte | +| `h` | int16_t | number | 2 bytes | +| `H` | uint16_t | number | 2 bytes | +| `i` | int32_t | number | 4 bytes | +| `I` | uint32_t | number | 4 bytes | +| `l` | int64_t | number | 8 bytes | +| `L` | uint64_t | number | 8 bytes | + +> [!WARNING] +> Due to the absence of an integer type in Lua for values `l` and `L`, only an output size of 8 bytes is guaranteed; the value may differ from what is expected. + +Example: + +```lua +debug.print(byteutil.tpack('>iBH?', -8, 250, 2019, true)) +-- outputs: +-- debug.print( +-- { +-- 255, +-- 255, +-- 255, +-- 248, +-- 250, +-- 7, +-- 227, +-- 1 +-- } +-- ) + +local bytes = byteutil.pack('>iBH?', -8, 250, 2019, true) +debug.print(byteutil.unpack('>iBH?', bytes)) +-- outputs: +-- debug.print( +-- { +-- -8, +-- 250, +-- 2019, +-- true +-- } +--) +``` diff --git a/doc/ru/scripting/builtins/libbyteutil.md b/doc/ru/scripting/builtins/libbyteutil.md new file mode 100644 index 00000000..e7fb53bd --- /dev/null +++ b/doc/ru/scripting/builtins/libbyteutil.md @@ -0,0 +1,72 @@ +# Библиотека *byteutil* + +Библиотека предоставляет функции для работы с массивами байт, представленными в виде таблиц или Bytearray. + +```lua +byteutil.pack(format: str, ...) -> Bytearray +byteutil.tpack(format: str, ...) -> table +``` + +Возвращает массив байт, содержащий переданные значения, упакованные в соответствии со строкой формата. Аргументы должны точно соответствовать значениям, требуемым форматом. + +Строка формата состоит из специальных символов и символов значений. + +Специальные символы позволяют указать порядок байт для последующих значений: + +| Символ | Порядок байт | +| ------ | -------------------- | +| `@` | Системный | +| `=` | Системный | +| `<` | Little-endian | +| `>` | Big-endian | +| `!` | Сетевой (big-endian) | + + +Символы значений описывают тип и размер. + +| Символ | Аналог в С++ | Тип Lua | Размер | +| ------ | ------------ | -------- | ------- | +| `b` | int8_t | number | 1 байт | +| `B` | uint8_t | number | 1 байт | +| `?` | bool | boolean | 1 байт | +| `h` | int16_t | number | 2 байта | +| `H` | uint16_t | number | 2 байта | +| `i` | int32_t | number | 4 байта | +| `I` | uint32_t | number | 4 байта | +| `l` | int64_t | number | 8 байта | +| `L` | uint64_t | number | 8 байта | + +> [!WARNING] +> Из-за отсутствия в Lua целочисленного типа для значений `l` и `L` гарантируется +> только выходной размер в 8 байт, значение может отличаться от ожидаемого. + +Пример: + +```lua +debug.print(byteutil.tpack('>iBH?', -8, 250, 2019, true)) +-- выводит: +-- debug.print( +-- { +-- 255, +-- 255, +-- 255, +-- 248, +-- 250, +-- 7, +-- 227, +-- 1 +-- } +-- ) + +local bytes = byteutil.pack('>iBH?', -8, 250, 2019, true) +debug.print(byteutil.unpack('>iBH?', bytes)) +-- выводит: +-- debug.print( +-- { +-- -8, +-- 250, +-- 2019, +-- true +-- } +--) +``` From ee26b2a2b9b8a7b58490553251eec773422bf992 Mon Sep 17 00:00:00 2001 From: MihailRis Date: Fri, 27 Dec 2024 09:38:47 +0300 Subject: [PATCH 3/5] update doc/*/scripting.md --- doc/en/scripting.md | 2 ++ doc/ru/scripting.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/doc/en/scripting.md b/doc/en/scripting.md index b00930f1..c94a26ab 100644 --- a/doc/en/scripting.md +++ b/doc/en/scripting.md @@ -9,9 +9,11 @@ Subsections: - [UI properties and methods](scripting/ui.md) - [Entities and components](scripting/ecs.md) - [Libraries](#) + - [app](scripting/builtins/libapp.md) - [base64](scripting/builtins/libbase64.md) - [bjson, json, toml](scripting/filesystem.md) - [block](scripting/builtins/libblock.md) + - [byteutil](scripting/builtins/libbyteutil.md) - [cameras](scripting/builtins/libcameras.md) - [entities](scripting/builtins/libentities.md) - [file](scripting/builtins/libfile.md) diff --git a/doc/ru/scripting.md b/doc/ru/scripting.md index 63191ea8..0d880d78 100644 --- a/doc/ru/scripting.md +++ b/doc/ru/scripting.md @@ -9,9 +9,11 @@ - [Свойства и методы UI элементов](scripting/ui.md) - [Сущности и компоненты](scripting/ecs.md) - [Библиотеки](#) + - [app](scripting/builtins/libapp.md) - [base64](scripting/builtins/libbase64.md) - [bjson, json, toml](scripting/filesystem.md) - [block](scripting/builtins/libblock.md) + - [byteutil](scripting/builtins/libbyteutil.md) - [cameras](scripting/builtins/libcameras.md) - [entities](scripting/builtins/libentities.md) - [file](scripting/builtins/libfile.md) From 72394181c7c022f4f2ac51652825fa096c178111 Mon Sep 17 00:00:00 2001 From: MihailRis Date: Fri, 27 Dec 2024 09:58:02 +0300 Subject: [PATCH 4/5] add unpack function documentation --- doc/en/scripting/builtins/libbyteutil.md | 17 ++++++++--------- doc/ru/scripting/builtins/libbyteutil.md | 6 ++++++ src/logic/scripting/lua/libs/libbyteutil.cpp | 5 +---- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/doc/en/scripting/builtins/libbyteutil.md b/doc/en/scripting/builtins/libbyteutil.md index fce89eae..c0cf72d0 100644 --- a/doc/en/scripting/builtins/libbyteutil.md +++ b/doc/en/scripting/builtins/libbyteutil.md @@ -39,6 +39,12 @@ Value characters describe the type and size. > [!WARNING] > Due to the absence of an integer type in Lua for values `l` and `L`, only an output size of 8 bytes is guaranteed; the value may differ from what is expected. +```lua +byteutil.unpack(format: str, bytes: table|Bytearray) -> ... +``` + +Extracts values ​​from a byte array based on a format string. + Example: ```lua @@ -58,14 +64,7 @@ debug.print(byteutil.tpack('>iBH?', -8, 250, 2019, true)) -- ) local bytes = byteutil.pack('>iBH?', -8, 250, 2019, true) -debug.print(byteutil.unpack('>iBH?', bytes)) +print(byteutil.unpack('>iBH?', bytes)) -- outputs: --- debug.print( --- { --- -8, --- 250, --- 2019, --- true --- } ---) +-- -8 250 2019 true ``` diff --git a/doc/ru/scripting/builtins/libbyteutil.md b/doc/ru/scripting/builtins/libbyteutil.md index e7fb53bd..a5495e6c 100644 --- a/doc/ru/scripting/builtins/libbyteutil.md +++ b/doc/ru/scripting/builtins/libbyteutil.md @@ -40,6 +40,12 @@ byteutil.tpack(format: str, ...) -> table > Из-за отсутствия в Lua целочисленного типа для значений `l` и `L` гарантируется > только выходной размер в 8 байт, значение может отличаться от ожидаемого. +```lua +byteutil.unpack(format: str, bytes: table|Bytearray) -> ... +``` + +Извлекает значения из массива байт, ориентируясь на строку формата. + Пример: ```lua diff --git a/src/logic/scripting/lua/libs/libbyteutil.cpp b/src/logic/scripting/lua/libs/libbyteutil.cpp index c221ad25..a757712f 100644 --- a/src/logic/scripting/lua/libs/libbyteutil.cpp +++ b/src/logic/scripting/lua/libs/libbyteutil.cpp @@ -134,8 +134,6 @@ static int l_unpack(lua::State* L) { ByteReader reader(bytes); bool bigEndian = false; - int index = 1; - lua::createtable(L, count, 0); for (size_t i = 0; format[i]; i++) { switch (format[i]) { case 'b': @@ -185,9 +183,8 @@ static int l_unpack(lua::State* L) { default: continue; } - lua::rawseti(L, index++); } - return 1; + return count; } static int l_pack(lua::State* L) { From a5a0a2778a380d54464824c415717d86ddb74136 Mon Sep 17 00:00:00 2001 From: MihailRis Date: Fri, 27 Dec 2024 09:59:39 +0300 Subject: [PATCH 5/5] fix docs --- doc/ru/scripting/builtins/libbyteutil.md | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/doc/ru/scripting/builtins/libbyteutil.md b/doc/ru/scripting/builtins/libbyteutil.md index a5495e6c..2c675594 100644 --- a/doc/ru/scripting/builtins/libbyteutil.md +++ b/doc/ru/scripting/builtins/libbyteutil.md @@ -67,12 +67,5 @@ debug.print(byteutil.tpack('>iBH?', -8, 250, 2019, true)) local bytes = byteutil.pack('>iBH?', -8, 250, 2019, true) debug.print(byteutil.unpack('>iBH?', bytes)) -- выводит: --- debug.print( --- { --- -8, --- 250, --- 2019, --- true --- } ---) +-- -8 250 2019 true ```