Helpers

Helpers - набор вспомогательных Lua-функций для комфортной работы в проекте.

Эти helper-функции значительно расширяют стандартные возможности Lua и упрощают разработку.

---

• string
• table
• math

• debug
• exception
• global

• io
• os

String

• string:lower()
• string:upper()
• string:is_one_of()
• string:first_to_upper()
• string:title()/:to_headline()
• string:starts_with()
• string:ends_with()

• string:contains()
• string:replace()
• string:remove()
• string:reg_escape()
• string:vxr_split()
• string.or_nil()

Методы, поставляемые Luanti:

• string.split()
• string.trim()

• string.pack()
• string.unpack()
• string.packsize()

string:lower()

Преобразование строки в нижний регистр с поддержкой кириллицы.

print(('ПРИВЕТ МИР'):lower())  -- 'привет мир'

string:upper()

Преобразование строки в верхний регистр с поддержкой кириллицы.

print(string.upper('привет мир'))  -- 'ПРИВЕТ МИР'

string:is_one_of(table)

Проверяет, является ли строка одним из значений в переданном массиве.
(семантический аналог table.contains, который проверяет содержится ли строка в переданном массиве.)

local text = 'hello'
local options = { 'hello', 'world', 'lua' }
print(text:is_one_of(options))  -- true

string:first_to_upper()

Преобразует первую букву в верхний регистр.

local text = 'hello world'
print(text:first_to_upper())  -- 'Hello world'

string :title()/:to_headline()

Преобразует первую букву каждого слова в заглавный регистр.
Альтернативное название: string:to_headline()

local text = 'hello world from lua'
print(text:title())           -- 'Hello World From Lua'
print(text:to_headline())     -- 'Hello World From Lua'

string:starts_with(prefix)

Проверяет, начинается ли строка с указанного префикса.

local filename = 'config.json'
print(filename:starts_with('config'))    -- true
print(filename:starts_with('settings'))  -- false

string:ends_with(suffix)

Проверяет, заканчивается ли строка на указанный суффикс.

local filename = 'config.json'
print(filename:ends_with('.json'))    -- true
print(filename:ends_with('.conf'))    -- false

string:contains(sub_string)

Проверяет наличие подстроки.

local text = 'Hello, World !!!'
print(text:contains('World'))   -- true
print(text:contains('world'))   -- false (учитывается регистр)

string:replace(pattern, replacement, n?)

Замена подстроки (аналог gsub, но возвращает только строку без количества замен).
См. документацию string.gsub и Patterns

local text = 'Hello, World, World!'
local result = text:replace('World', 'Lua')
print(result)  -- 'Hello, Lua, Lua!'

-- Замена только первого вхождения
local result2 = text:replace('World', 'Lua', 1)
print(result2)  -- 'Hello, Lua, World!'

string:remove(pattern, n?)

Удаление подстроки.
См. документацию string.gsub и Patterns

local text = 'Hello, World!'
print(text:remove(', '))        -- 'HelloWorld!'
print(text:remove('o', 1))      -- 'Hell, Wrld!' (удалить только первую 'o')

string:reg_escape()

Экранирует спецсимволы для регулярных выражений.
См. Patterns

local pattern = 'file.txt'
print(pattern:reg_escape())      -- 'file%.txt'

local pattern2 = '^$()%.[]*+-?)'
print(pattern2:reg_escape())     -- '%^%$()%.%[%]%*%+%-%?)'

string:vxr_split(delimiter?, processor?)

Разделение строки по указанному delimiter с возможностью обработки частей.

Luanti имеет свой метод string.split, но он не поддерживает обработку частей.
Этот метод добавляет возможность обрабатывать части строки.

-- Без обработки
('hello world'):vxr_split()             -- { 'hello', 'world' }
('apple,banana,cherry'):vxr_split(',')  -- { 'apple', 'banana', 'cherry' }

-- С обработкой
local numbers = '1,2,3,4,5'
local squared = numbers:vxr_split(',', function(x)
    return tonumber(x)^2 
end)
print(squared[1], squared[2], squared[3], squared[4], squared[5])
-- 1 4 9 16 25

string.or_nil(value)

Преобразует в строку или возвращает nil.

print(string.or_nil('hello'))     -- 'hello'
print(string.or_nil(42))          -- '42'
print(string.or_nil(nil))         -- nil
print(tostring(nil))              -- 'nil' (сравнение)

---

Методы, поставляемые Luanti:

Luanti string.split()

Также см.: string.vxr_split(delimiter?, processor?)

Разделяет строку на части по указанному разделителю. Возвращает массив строк. Аргументы:

• separator? разделитель, по умолчанию: ","
• include_empty? по умолчанию: false
• max_splits? если отрицательное, разделений не ограничено, по умолчанию: -1
• sep_is_pattern? является ли разделитель обычной строкой или паттерном (regex), по умолчанию: false

local text = 'apple,banana,cherry'
local parts = text.split(',')
print(parts[1], parts[2], parts[3])  -- 'apple', 'banana', 'cherry'

-- Разделение по пробелам
local words = 'hello world lua'.split(' ')
print(words[1], words[2], words[3])  -- 'hello', 'world', 'lua'

Luanti string.trim()

Удаляет пробельные символы в начале и конце строки.

print(("\n \t\tfoo bar\t "):trim())  -- 'foo bar'

Luanti string.pack()

Упаковывает значения в бинарную строку согласно формату.
Backport из Lua 5.4.

-- Упаковка целых чисел
local packed = string.pack('i4', 42)
print(#packed)  -- 4 (размер в байтах)

-- Упаковка нескольких значений
local data = string.pack('i4f8', 100, 3.14)
print(#data)  -- 12 (4 + 8 байт)

Luanti string.unpack()

Распаковывает бинарную строку в значения согласно формату.
Backport из Lua 5.4.

local packed = string.pack('i4f8', 100, 3.14)
local num, float, next_pos = string.unpack('i4f8', packed)
print(num, float)      -- 100, 3.14
print(next_pos)        -- 13 (позиция после распаковки)

-- Распаковка с указанной позиции
local value = string.unpack('i4', packed, 5)
print(value)            -- 3.14 (как float)

Luanti string.packsize()

Возвращает размер строки, которая будет создана string.pack.
Backport из Lua 5.4.

local size = string.packsize('i4f8')
print(size)  -- 12 (4 + 8 байт)

-- Для сложных форматов
local complex_size = string.packsize('i4c10f8')
print(complex_size)  -- 22 (4 + 10 + 8 байт)

Table

• table.keys()
• table.values()
• table.has_key()
• table.contains/.has_value()
• table.keys_of()
• table.has_any_key()

---

• table.equals()
• table.is_empty()
• table.is_position()
• table.each_value_is()

---

• table.count()
• table.generate_sequence()

• table.only()
• table.except()
• table.merge()
• table.join()
• table.overwrite()
• table.merge_values()

---

• table.map()
• table.walk()/.each()

---

• table.multiply_each_value()
• table.add_values()
• table.sub_values()
• table.mul_values()
• table.div_values()

Методы, поставляемые Luanti:

• table.copy()
• table.copy_with_metatables()
• table.insert_all()

• table.indexof()
• table.keyof()
• table.key_value_swap()
• table.shuffle()

table.keys(table)

Возвращает массив ключей таблицы.

local data = { name = 'Alek', age = 25, city = 'Владивосток' }

local keys = table.keys(data)
-- `keys` содержит `{ 'name', 'age', 'city' }` (порядок может отличаться)

table.values(table)

Возвращает массив значений таблицы.

local data = { name = 'Alek', age = 25, city = 'Владивосток' }

local values = table.values(data)
-- `values` содержит { 'Alek', 25, 'Владивосток' }

table.has_key(table, key)

Проверяет наличие ключа в таблице.

local data = { name = 'Alek', age = 25 }
print(table.has_key(data, 'name'))   -- true
print(table.has_key(data, 'city'))   -- false

table .contains/has_value(table, value)

Проверяет наличие значения в таблице.

local fruits = { 'apple', 'banana', 'cherry' }
print(table.contains(fruits, 'banana'))  -- true
print(table.contains(fruits, 'orange'))  -- false

Также можно использовать string:is_one_of():

print('banana':is_one_of(fruits))  -- true
print('orange':is_one_of(fruits))  -- false

Альтернативное называние: table.has_value

local data = { x = 10, y = 20 }
print(table.has_value(data, 10))     -- true
print(table.has_value(data, 30))     -- false

table.keys_of(table, value)

Возвращает таблицу с ключами из указанной таблицы, которые имеют указанное значение.

local data = { a = 10, b = 20, c = 10, d = 30 }
local keys = table.keys_of(data, 10)
print(dump(keys))  -- { 'a', 'c' }

local keys2 = table.keys_of(data, 99)
print(keys2)  -- nil (нет таких ключей)

table.has_any_key(table, find_keys)

Проверяет, есть ли в ключах таблицы хотя бы одно значение из указанного массива.

local data = { name = 'test', age = 25, active = true }
local find_keys = { 'name', 'email', 'phone' }

print(table.has_any_key(data, find_keys))   -- true (ключ 'name' есть в find_keys)

local find_keys2 = { 'email', 'phone', 'address' }
print(table.has_any_key(data, find_keys2))  -- false

table.equals(table1, table2)

Рекурсивно сравнивает две таблицы на полное равенство.

local table1 = { a = 1, b = { c = 2, d = 3 } }
local table2 = { a = 1, b = { c = 2, d = 3 } }
local table3 = { a = 1, b = { c = 2, d = 4 } }

print(table.equals(table1, table2))  -- true
print(table.equals(table1, table3))  -- false

table.is_empty(table)

Проверяет, пуста ли таблица.

print(table.is_empty({}))           -- true
print(table.is_empty({ a = 1 }))    -- false

table.is_position(table)

Проверяет, является ли таблица координатами.

print(table.is_position({ x = 10, y = 20, z = 30 }))  -- true
print(table.is_position({ x = 10, y = 20 }))          -- false
print(table.is_position({ a = 1, b = 2, c = 3 }))     -- false

table.each_value_is(table, value)

Проверяет, что все элементы таблицы равны указанному значению. По умолчанию проверяет на true.

local data1 = { true, true, true }
print(table.each_value_is(data1))  -- true

local data2 = { 5, 5, 5, 5 }
print(table.each_value_is(data2, 5))  -- true

local data3 = { 1, 2, 3 }
print(table.each_value_is(data3, 1))  -- false

table.count(table)

Подсчитывает количество элементов в таблице.

NOTE

Для таблиц с целочисленными ключами используйте #table.
Т.к. оператор # не работает на таблицах с не-целочисленными ключами, для них используйте table.count.

local data = { a = 1, b = 2, c = 3 }
print(table.count(data))  -- 3
print(#data)              -- 0, т.к. оператор `#` не работает с не-целочисленными ключами.

local array = { 1, 2, 3, 4, 5 }
print(#array) -- 5

table.generate_sequence(max, start_from?, step?)

Генерирует последовательность чисел.

local seq1 = table.generate_sequence(5)
print(dump(seq1))  -- { 1, 2, 3, 4, 5 }

local seq2 = table.generate_sequence(10, 2, 2)
print(dump(seq2))  -- { 2, 4, 6, 8, 10 }

local seq3 = table.generate_sequence(1, 5, -1)
print(dump(seq3))  -- { 5, 4, 3, 2, 1 }

table.only(table, only)

Возвращает новую таблицу, содержащую данные только с указанными ключами.

local data = { name = 'Alek', age = 25, city = 'Владивосток', country = 'Russia' }
local filtered = table.only(data, { 'name', 'age' })
-- `filtered` содержит `{ name = 'Alek', age = 25 }`
print(filtered.name, filtered.age)    -- 'Alek', 25
print(filtered.city)                  -- nil

table.except(table, keys)

Возвращает новую таблицу, содержащую данные без указанных ключей.
(копирует таблицу, исключая указанные ключи)

local data = { name = 'Alek', age = 25, city = 'Владивосток', country = 'Russia' }
local filtered = table.except(data, { 'age', 'country' })
-- `filtered` содержит `{ name = 'Alek', city = 'Владивосток' }`
print(filtered.name, filtered.city)      -- 'Alek', 'Владивосток'
print(filtered.age,  filtered.country)   -- nil, nil

table.merge(table1, table2, overwrite?)

Рекурсивно объединяет таблицы.

По умолчанию первая таблица не перезаписывается, а создается новая.

local defaults = { theme = 'dark', font = { size = 12, family = 'Arial' } }
local user_config = { font = { size = 16 }, language = 'en' }

local merged = table.merge(defaults, user_config)
print(dump(merged))
-- {
--     theme = "dark",
--     font = {
--         size = 16,
--         family = "Arial",
--     },
--     language = "en",
-- }

Перезаписать первую таблицу:

table.merge(defaults, user_config, true)

TIP

Лучше использовать table.overwrite() для лучшей читаемости.

table.join(table1, table2, recursively?)

Добавляет отсутствующие ключи из table2 в table1.
Значения, которые являются таблицами, копируются с помощью table.copy().

local base     = { a = 1, b =  2        }
local addition = {        b = 10, c = 3 }

table.join(base, addition)
print(dump(base))  -- { a = 1, b = 2, c = 3 }

Если recursively равен true, функция будет применяться рекурсивно только для тех значений, которые являются таблицами в обоих table1 и table2.

local base     = { a = 1, b = { c = 2          } }
local addition = {        b = { c = 10, d = 20 } }

table.join(base, addition, true)
print(dump(base))
-- {
--     a = 1,
--     b = {
--         c = 2,
--         d = 20,
--     },
-- }

table.overwrite(table1, table2)

Полностью перезаписывает table1 значениями из table2.

Семантичный вариант для table.merge(table1, table2, true).

table.merge_values(table1, table2)

Объединяет значения из двух таблиц в одну, удаляя дубликаты.
Порядок сохраняется — сначала значения из table1, затем из table2, которых не было в table1.

local table1 = { 'apple', 'banana', 'cherry' }
local table2 = { 'banana', 'date', 'apple', 'elderberry' }

local merged = table.merge_values(table1, table2)
print(dump(merged))  -- { 'apple', 'banana', 'cherry', 'date', 'elderberry' }

table.map(table, callback, overwrite?)

Применяет функцию к каждому элементу таблицы.
callback: fun(value: any, key: any): any - принимает значение и ключ, возвращает новое значение.

По умолчанию возвращает новую таблицу.

local numbers = { 1, 2, 3, 4, 5 }
local squared = table.map(numbers, function(x) return x * x end)
print(dump(squared))
-- { 1, 4, 9, 16, 25 }

local data = { a = 10, b = 20 }
local doubled = table.map(data, function(value, key)
	print(key, value)
	return value * 2
end)
-- a       10
-- b       20
print(dump(doubled))
-- { a = 20, b = 40 }

Если overwrite равен true, то функция изменяет исходную таблицу.

local data = { a = 10, b = 20 }
table.map(data, function(value, key) return value * 2 end, true)
print(dump(data))  -- { a = 20, b = 40 }

table .walk/.each(table, callback)

Итерируется по таблице с применением функции (не изменяет таблицу).
callback: fun(value: any, key: any): void - принимает значение и ключ; не возвращает ничего.

local data = { a = 10, b = 20, c = 30 }
table.walk(data, function(value, key)
    print(key, value)
end)
-- a       10
-- c       30
-- b       20

Альтернативное называние: table.each()

local data = { a = 10, b = 20, c = 30 }
table.each(data, function(value, key)
    data[key] = value * 2
    -- Никто не отменял обращение к upvalue `data`. Теперь `data` перезаписан.
end)
print(dump(data))  -- { a = 20, b = 40, c = 60 }

table.multiply_each_value(table, multiplier_table)

Умножает каждое значение таблицы на соответствующее значение из multiplier_table по ключу.

local data = { a = 10, b = 20, c = 30 }
local multipliers = { a = 2, b = 0.5, c = 3 }

local result = table.multiply_each_value(data, multipliers)
print(dump(result))  -- { a = 20, b = 10, c = 90 }
-- Ключи без множителя остаются без изменений

table.add_values(table1, table2, empty_value?, overwrite?)

Складывает значения с одинаковыми ключами из двух таблиц.

local table1 = { a = 10, b = 20 }
local table2 = { b = 5, c = 15 }

local result = table.add_values(table1, table2)
print(dump(result))  -- { a = 10, b = 25, c = 15 }

-- С указанием пустого значения для отсутствующих ключей
local result2 = table.add_values(table1, table2, 0)
print(dump(result2))  -- { a = 10, b = 25, c = 15 }

table.sub_values(table1, table2, empty_value?, overwrite?)

Вычитает значения table2 из table1 для одинаковых ключей.

local table1 = { a = 10, b = 20, c = 30 }
local table2 = { b = 5, c = 10, d = 5 }

local result = table.sub_values(table1, table2)
print(dump(result))  -- { a = 10, b = 15, c = 20, d = -5 }

table.mul_values(table1, table2, empty_value?, overwrite?)

Перемножает значения с одинаковыми ключами из двух таблиц.

local table1 = { a = 2, b = 3 }
local table2 = { b = 4, c = 5 }

local result = table.mul_values(table1, table2)
print(dump(result))  -- { a = 2, b = 12, c = 5 }

table.div_values(table1, table2, empty_value?, overwrite?)

Делит значения table1 на значения table2 для одинаковых ключей.

local table1 = { a = 10, b = 20, c = 30 }
local table2 = { b = 5, c = 10, d = 2 }

local result = table.div_values(table1, table2)
print(dump(result))  -- { a = 10, b = 4, c = 3, d = 0.5 }

Math

• math.limit/clamp()
• math.is_within()
• math.is_among()
• math.is_in_range()
• math.is_near()

• math.quadratic_equation_roots()
• math.point_on_circle()

math .limit/.clamp(value, min, max)

Ограничивает значение в указанном диапазоне.
Альтернативное название: math.clamp().

local health = 150
local max_health = 100
local clamped_health = math.limit(health, 0, max_health)
print(clamped_health)  -- 100

math.is_within(value, min, max)

Проверяет, что значение строго внутри диапазона (min < value < max).

print(math.is_within(5, 1, 10))   -- true
print(math.is_within(1, 1, 10))   -- false (границы не включены)
print(math.is_within(10, 1, 10))  -- false

math.is_among(value, min, max)

Проверяет, что значение внутри диапазона, включая границы (min <= value <= max).

print(math.is_among(5, 1, 10))   -- true
print(math.is_among(1, 1, 10))   -- true
print(math.is_among(10, 1, 10))  -- true

math.is_in_range(value, min, max)

Проверяет, что значение внутри полуоткрытого интервала (min, max] (min < value <= max).

print(math.is_in_range(5, 1, 10))   -- true
print(math.is_in_range(1, 1, 10))   -- false (равно минимуму)
print(math.is_in_range(10, 1, 10))  -- true (равно максимуму)

math.is_near(value, near, gap?)

Проверяет, что значение близко к указанному (|value - near| <= gap).

print(math.is_near(10, 12))        -- false (gap = 1 по умолчанию)
print(math.is_near(11, 12))        -- true
print(math.is_near(10, 12, 3))     -- true (gap = 3)

math.quadratic_equation_roots(a, b, c)

Решает квадратное уравнение вида y = a*x^2 + b*x + c.

local root1, root2 = math.quadratic_equation_roots(1, -5, 6)
print(root1, root2)  -- 3, 2

-- Нет действительных корней
local r1, r2 = math.quadratic_equation_roots(1, 0, 1)
print(r1, r2)  -- nil, nil

math.point_on_circle(radius, angle)

Вычисляет точку на окружности.

local x, z = math.point_on_circle(5, math.pi/4)
print(x, z)  -- координаты точки на окружности радиусом 5 под углом 45°

Debug

• __FILE__()
• __LINE__()
• __FILE_LINE__()
• __DIR__()
• __FUNC__()
• print_dump() / pd() / pdt()

• debug.get_stack_frames()
• debug.render_backtrace()
• debug.print_backtrace()
• debug.measure()
• debug.measure_print()

__FILE__(depth?, full?)

Возвращает имя текущего файла или файла вызывающей функции в зависимости от глубины стека.

• depth? - глубина стека вызовов (по умолчанию 0)
• full? - показывать полный путь (по умолчанию false)

-- Получить относительный путь файла
print(__FILE__())  -- 'mods/Voxrame/helpers/src/lua_ext/debug.lua'

-- Получить полный путь файла
print(__FILE__(0, true))  -- '/home/alek13/projects/my-game/mods/Voxrame/helpers/src/lua_ext/debug.lua'

-- Получить файл на 2 уровня вверх по стеку вызовов
print(__FILE__(2))  -- файл функции, которая вызвала вызывающую функцию

__LINE__(depth?)

Возвращает номер текущей строки или строки вызывающей функции в зависимости от глубины стека.

print(__LINE__())  -- 57

-- Получить номер строки вызывающей функции
print(__LINE__(1))  -- номер строки в файле вызова

__FILE_LINE__(depth?, full?)

Возвращает файл и строку в формате "относительный/путь/к/файлу:строка".

print(__FILE_LINE__())  -- 'mods/Voxrame/helpers/src/lua_ext/debug.lua:65'

-- С полным путем
print(__FILE_LINE__(0, true))  -- '/home/alek13/projects/my-game/mods/Voxrame/helpers/src/lua_ext/debug.lua:65'

__DIR__(depth?)

Возвращает директорию текущего файла или директорию файла вызывающей функции в зависимости от глубины стека.

print(__DIR__())  -- 'mods/Voxrame/helpers/src/lua_ext/'

__FUNC__(depth?)

Возвращает имя текущей функции.

function my_function()
    print(__FUNC__())  -- 'my_function'
end

print_dump(depth, with_trace, ...)

Выводит сожержимое всех переданных параметров ....
Перед выводом добавляет имя файла и строку @ <file>:<line>.

Если with_trace равно true, дополнительно выводит трассировку стека.

NOTE

Если ваш терминал поддерживает ссылки, каждая @ <file>:<line> будет привязана к открытию IDE, смотрите readme.md для настройки.

TIP

Используйте pd() и pdt() для более краткого синтаксиса. См. примеры ниже.

pd(...)

Сокращение от print_dump. Вызывает print_dump с with_trace == false.

local player_name = 'test_player'
local position = { x = 10, y = 20, z = 30 }

pd(player_name, position)

output:

@ lord/mods/Voxrame/map/src/map/Corridor.lua:14
player_name: "test_player"
   position: {
    x = 10,
    y = 20,
    z = 30,
}

pdt(...)

Сокращение от print_dump traced. Вызывает print_dump с with_trace == true.

local player_name = 'test_player'
local position = { x = 10, y = 20, z = 30 }

pdt(player_name, position)

output:

@ lord/mods/Voxrame/map/src/map/Corridor.lua:14
   1   @ [C]: in dofile
   2   @ lord/mods/Voxrame/builtin_ext/src/mod/require.lua:29: in require
   3   @ lord/mods/Voxrame/map/src/map.lua:9: in main
   4   @ [C]: in dofile
   5   @ lord/mods/Voxrame/builtin_ext/src/mod/require.lua:29: in require
   6   @ lord/mods/Voxrame/map/init.lua:4: in mod_init_function
   7   @ lord/mods/Voxrame/builtin_ext/src/mod.lua:80: in mod
   8   @ lord/mods/Voxrame/map/init.lua:3: in main
player_name: "test_player"
   position: {
    x = 10,
    y = 20,
    z = 30,
}

debug.get_stack_frames(depth?)

Возвращает стек вызовов в виде массива кадров: от самого вложенного к самому внешнему.

Каждый кадр — таблица:

Поле	Тип	Описание
file	string	файл с исходным кодом функции (=[C] для функций на C)
line	integer	текущая строка в файле (-1 для функций на C)
name	string?	имя функции, если известно
what	string	Lua, C, main или tail

depth — сколько уровней пропустить; по умолчанию 0 — первый кадр это функция, вызвавшая get_stack_frames().

local function on_click()
    local frames = debug.get_stack_frames()
    pd(frames)
end

output (при включенном debug):

@ lord/mods/my_mod/src/on_click.lua:13
frames: {
    {
        file = "mods/my_mod/src/on_click.lua",
        line = 12,
        name = "on_click",
        what = "Lua",
    },
    {
        file = "mods/my_mod/init.lua",
        line = 30,
        name = "main",
        what = "main",
    },
    {
        file = "[C]",
        line = -1,
        what = "C",
    },
}

NOTE

file — абсолютный путь. Сокращать его (или оформлять иначе) можно самостоятельно, либо это сделает debug.render_backtrace().

debug.render_backtrace(frames, plain?)

Превращает кадры из debug.get_stack_frames() (или из :catch()) в многострочную строку, по строке на кадр.

По умолчанию строка оформлена для терминала (цвета и ссылки). Если передать plain = true, стилей и ссылок не будет, поэтому такую строку безопасно писать в лог:

local function on_click()
    local frames = debug.get_stack_frames()

    -- в терминал:
    print(debug.render_backtrace(frames))

    -- в лог-файл (например, в проде):
    core.log('error', debug.render_backtrace(frames, true))
end

output (print(debug.render_backtrace(frames))):

   1   @ lord/mods/my_mod/src/on_click.lua:12: in on_click
   2   @ lord/mods/my_mod/init.lua:30: in main
   3   @ [C]: in dofile

в логах (при plain = true):

   1   @ mods/my_mod/src/on_click.lua:12: in on_click
   2   @ mods/my_mod/init.lua:30: in main
   3   @ [C]: in dofile

NOTE

Если ваш терминал поддерживает ссылки, каждый @ <file>:<line> будет ссылкой для открытия в IDE, настройку см. в readme.md.

debug.print_backtrace(frames)

Печатает кадры в терминал (со стилями и ссылками). Для быстрого просмотра при отладке.

Сокращение от Voxrame.terminal.print(debug.render_backtrace(frames)).

TIP

Не используйте в проде, для лога пишите через debug.render_backtrace(frames, true).

debug.measure(name, callback, print_result?)

Измеряет время выполнения функции.

local function heavy_calculation()
    local sum = 0
    for i = 1, 2000000 do
        sum = sum + math.random(1, 100) + math.sin(i)
    end
end

-- Измерить с выводом результата
debug.measure('calculation', heavy_calculation, true)
debug.measure('calculation', heavy_calculation, true)
debug.measure('calculation', heavy_calculation, true)
debug.measure('calculation', heavy_calculation, true)
debug.measure('calculation', heavy_calculation, true)
-- output:
-- Measure of [calculation]:  Time:    42 ms ;  Average:    42 ms
-- Measure of [calculation]:  Time:    58 ms ;  Average:    50 ms
-- Measure of [calculation]:  Time:    58 ms ;  Average:    53 ms
-- Measure of [calculation]:  Time:    35 ms ;  Average:    48 ms
-- Measure of [calculation]:  Time:    33 ms ;  Average:    45 ms


-- Измерить без вывода
local time, avg, count = debug.measure('calculation', heavy_calculation)
print(time, avg, count)
local time, avg, count = debug.measure('calculation', heavy_calculation)
print(time, avg, count)
-- output:
-- 33.075  43.170833333333 6
-- 33.135  41.737142857143 7

debug.measure_print(name)

Выводит статистику предыдущих измерений name, полученных вызовами debug.measure(name, ....).

debug.measure_print('calculation')
-- output:
-- Measure of [calculation]: Average time:    42 ms ; Last time:    33 ms ; Count of measures:     7

Exception

• exception.try()
• :catch()

Удобный try/catch, как вы привыкли в других языках.

local try = Voxrame.exception.try

try(function()
    player:right_click(node)
end):catch(function(error, traceback)
    core.log('error', tostring(error) .. '\n' .. debug.render_backtrace(traceback, true))
end)

exception.try(callback)

Сразу вызывает callback() в защищённом режиме и возвращает объект с методом :catch().

WARNING

Ошибки не пробрасываются дальше. Без :catch() ошибка будет молча проглочена.

Стектрейс собирается только при возникновении ошибки (в момент ошибки, до раскрутки стека), поэтому успешный вызов почти ничего не стоит.

:catch(handler)

Вызывает handler(error, traceback), если callback, переданный до этого в try(), упал. Иначе ничего не делает.

• error — то, что выбросил error(). Обычно это string, но error() может выбросить любое значение.
• traceback — стек вызовов в момент ошибки, массив кадров из debug.get_stack_frames(), от самого вложенного.

Примеры обработки/использования traceback:

try(function()
    error('Something went wrong')
end):catch(function(error, traceback)
    -- при разработке: в терминал
    debug.print_backtrace(traceback)

    -- в проде: в лог
    core.log('error', tostring(error) .. '\n' .. debug.render_backtrace(traceback, true))
end)

debug.print_backtrace(traceback) (при включенном debug):

   1   @ [C]: in error
   2   @ lord/mods/my_mod/init.lua:12: in function
   3   @ [C]: in xpcall
   4   @ lord/mods/Voxrame/helpers/src/exception/FlowControl.lua:64: in try
   5   @ lord/mods/Voxrame/helpers/src/exception.lua:19: in try
   6   @ lord/mods/my_mod/init.lua:11: in main

debug.render_backtrace(traceback, true):

   1   @ [C]: in error
   2   @ mods/my_mod/init.lua:12: in function
   3   @ [C]: in xpcall
   4   @ mods/Voxrame/helpers/src/exception/FlowControl.lua:64: in try
   5   @ mods/Voxrame/helpers/src/exception.lua:19: in try
   6   @ mods/my_mod/init.lua:11: in main

NOTE

traceback содержит все кадры, включая внутренние (xpcall, try) в конце.

TIP

:catch() возвращает тот же объект, поэтому можно объединять несколько :catch() в цепочку.

Global

• errorf(message, ...)
• errorlf(message, level, ...)
• assertf(condition, message, ...)

errorf(message, ...)

Аналогичен error() в Lua, но message может быть строкой-шаблоном с указанными параметрами, аналогично string.format().

local player_name = nil
errorf('Player `%s` not found', player_name)
-- Ошибка: Player `nil` not found

output (при включенном debug):

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
ERROR:
  Player `nil` not found

Stack trace:
   1   @ [C]: in error
   2   @ lord/mods/Voxrame/helpers/src/lua_ext/global.lua:9: in errorf
   3   @ lord/mods/Voxrame/map/src/map/Corridor.lua:14: in main
   4   @ [C]: in dofile
   5   @ lord/mods/Voxrame/builtin_ext/src/mod/require.lua:29: in require
   6   @ lord/mods/Voxrame/map/src/map.lua:9: in main
   7   @ [C]: in dofile
   8   @ lord/mods/Voxrame/builtin_ext/src/mod/require.lua:29: in require
   9   @ lord/mods/Voxrame/map/init.lua:4: in mod_init_function
  10   @ lord/mods/Voxrame/builtin_ext/src/mod.lua:80: in mod
  11   @ lord/mods/Voxrame/map/init.lua:3: in main

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Обработка ошибок в Luanti

WARNING

В стек трейсе будет присутствовать лишние строки, т.к. Luanti не передаёт указанный level в core.error_handler().

errorlf(message, level, ...)

Как и в errorf() вы можете передать строку-формат и параметры, а также указать уровень трассировки.

errorlf('Ошибка в данных', 3, 'значение: %d', 42)
-- Ошибка с трассировкой на 3 уровня вверх

см. обработка ошибок в Luanti

assertf(condition, message, ...)

Аналогичен assert() в Lua, но в качестве message можно указать строку-формат с параметрами, аналогично string.format().

Вызывает errorf() если условие condition не выполнено.

-- Продолжает выполнение если player существует, иначе ошибка
local player = nil
assertf(player, 'Игрок `%s` не найден', player)

IO

• io.file_exists()
• io.dirname()

• io.write_to_file()
• io.read_from_file()
• io.get_file_error()

io.file_exists(name)

Проверяет существование файла.

if io.file_exists('config.txt') then
    print('Файл конфигурации найден')
else
    print('Файл конфигурации отсутствует')
end

io.dirname(path)

Возвращает директорию из пути.

print(io.dirname('/home/user/project/file.txt'))  -- '/home/user/project'
print(io.dirname('relative/path/file.txt'))       -- 'relative/path'
print(io.dirname('file.txt'))                     -- '.'

io.write_to_file(filepath, content, mode?)

Записывает содержимое в файл.

local success, error_code, error_message = io.write_to_file('data.txt', 'Hello, World!')

if success then
    print('Данные успешно записаны')
else
    print('Ошибка записи:', error_code, error_message)
end

-- Дозапись в конец файла
io.write_to_file('log.txt', 'Новая запись\n', 'a')

io.read_from_file(filepath, mode?)

Читает всё содержимое из файла.
Возвращает строку с содержимым файла в случае успеха или false, error_code, error_message в случае ошибки.

local content = io.read_from_file('config.json')
if content then
    print('Содержимое файла:', content)
else
    print('Ошибка чтения файла')
end

Обработка ошибок

local success, error_code, error_message = io.read_from_file('nonexistent.txt')
if not success then
    print('Ошибка:', error_code, error_message)
end
-- Ошибка: 2       nonexistent.txt: No such file or directory

или:

local success = io.read_from_file('nonexistent.txt')
if not success then
    local error_code, error_message = io.get_file_error()
    print('Ошибка:', error_code, error_message)
end
-- Ошибка: 2       nonexistent.txt: No such file or directory

Чтение в бинарном режиме

local binary_content = io.read_from_file('image.png', 'rb')
if binary_content then
    print('Размер файла:', #binary_content, 'байт')
end

io.get_file_error()

Возвращает код и сообщение последней ошибки из функций io.read_from_file() или io.write_to_file().

local success = io.read_from_file('nonexistent.txt')
if not success then
    local error_code, error_message = io.get_file_error()
    print('Ошибка:', error_code, error_message)
end
-- Вывод: Ошибка: 2       nonexistent.txt: No such file or directory

local success = io.write_to_file('/readonly/file.txt', 'data')
if not success then
    local error_code, error_message = io.get_file_error()
    print('Ошибка записи:', error_code, error_message)
end
-- Вывод: Ошибка записи: 13       /readonly/file.txt: Permission denied

OS

os.DIRECTORY_SEPARATOR

Разделитель директорий для текущей ОС.

local DS = os.DIRECTORY_SEPARATOR

print(DS)  -- '/' на Linux/Mac, '\' на Windows
print('folder' .. DS .. 'file.txt')
-- на Linux/Mac: 'folder/file.txt'
-- на Windows:   'folder\file.txt'