Helper

Helper adalah sekumpulan fungsi pembantu Lua untuk bekerja dengan nyaman dalam proyek.

Fungsi pembantu ini secara signifikan memperluas kemampuan standar Lua dan menyederhanakan pengembangan.

---

• 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()

Metode yang disediakan oleh Luanti:

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

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

string:lower()

Mengubah string menjadi huruf kecil dengan dukungan untuk Cyrillic.

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

string:upper()

Mengubah string menjadi huruf besar dengan dukungan untuk Cyrillic.

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

string:is_one_of(table)

Memeriksa apakah string adalah salah satu nilai dalam array yang dilewatkan.
(Analog semantik dari table.contains, yang memeriksa apakah string terkandung dalam array yang dilewatkan.)

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

string:first_to_upper()

Mengubah huruf pertama menjadi huruf besar.

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

string :title()/:to_headline()

Mengubah huruf pertama setiap kata menjadi title case.
Nama alternatif: 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)

Memeriksa apakah string dimulai dengan prefix yang ditentukan.

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

string:ends_with(suffix)

Memeriksa apakah string diakhiri dengan suffix yang ditentukan.

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

string:contains(sub_string)

Memeriksa keberadaan substring.

local text = 'Hello, World !!!'
print(text:contains('World'))   -- true
print(text:contains('world'))   -- false (case-sensitive)

string:replace(pattern, replacement, n?)

Mengganti substring (analog dari gsub, tetapi hanya mengembalikan string tanpa jumlah penggantian).
Lihat dokumentasi untuk string.gsub dan Patterns

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

-- Ganti hanya kemunculan pertama
local result2 = text:replace('World', 'Lua', 1)
print(result2)  -- 'Hello, Lua, World!'

string:remove(pattern, n?)

Menghapus substring.
Lihat dokumentasi untuk string.gsub dan Patterns

local text = 'Hello, World!'
print(text:remove(', '))        -- 'HelloWorld!'
print(text:remove('o', 1))      -- 'Hell, Wrld!' (hapus hanya 'o' pertama)

string:reg_escape()

Melarikan karakter khusus untuk ekspresi reguler.
Lihat Patterns

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

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

string:vxr_split(delimiter?, processor?)

Membagi string dengan delimiter yang ditentukan dengan kemampuan memproses bagian-bagian.

Luanti memiliki metode string.split sendiri, tetapi tidak mendukung pemrosesan bagian.
Metode ini menambahkan kemampuan untuk memproses bagian-bagian string.

-- Tanpa pemrosesan
('hello world'):vxr_split()             -- { 'hello', 'world' }
('apple,banana,cherry'):vxr_split(',')  -- { 'apple', 'banana', 'cherry' }

-- Dengan pemrosesan
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)

Mengubah ke string atau mengembalikan nil.

print(string.or_nil('hello'))     -- 'hello'
print(string.or_nil(42))          -- '42'
print(string.or_nil(nil))         -- nil
print(tostring(nil))              -- 'nil' (perbandingan)

---

Metode yang disediakan oleh Luanti :

Luanti string.split()

Lihat juga: string.vxr_split(delimiter?, processor?)

Membagi string menjadi bagian-bagian dengan separator yang ditentukan. Mengembalikan array dari string. Argumen:

• separator? separator, default: ","
• include_empty? default: false
• max_splits? jika negatif, pembagian tidak terbatas, default: -1
• sep_is_pattern? jika separator adalah string normal atau pattern (regex), default: false

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

-- Bagi dengan spasi
local words = 'hello world lua'.split(' ')
print(words[1], words[2], words[3])  -- 'hello', 'world', 'lua'

Luanti string.trim()

Menghapus karakter spasi di awal dan akhir string.

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

Luanti string.pack()

Mengemas nilai ke dalam string biner sesuai format.
Backport dari Lua 5.4.

-- Masukkan bilangan bulat
local packed = string.pack('i4', 42)
print(#packed)  -- 4 (ukuran dalam byte)

-- Masukkan beberapa nilai
local data = string.pack('i4f8', 100, 3.14)
print(#data)  -- 12 (4 + 8 byte)

Luanti string.unpack()

Membongkar string biner menjadi nilai sesuai format.
Backport dari 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 (posisi setelah pembongkaran)

-- Bongkar dari posisi yang ditentukan
local value = string.unpack('i4', packed, 5)
print(value)            -- 3.14 (sebagai float)

Luanti string.packsize()

Mengembalikan ukuran string yang akan dibuat oleh string.pack.
Backport dari Lua 5.4.

local size = string.packsize('i4f8')
print(size)  -- 12 (4 + 8 byte)

-- Untuk format kompleks
local complex_size = string.packsize('i4c10f8')
print(complex_size)  -- 22 (4 + 10 + 8 byte)

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()

Metode, yang disediakan oleh Luanti :

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

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

table.keys(table)

Mengembalikan array dari kunci tabel.

local data = { name = 'Alek', age = 25, city = 'Vladivostok' }

local keys = table.keys(data)
-- `keys` berisi `{ 'name', 'age', 'city' }` (urutan mungkin berbeda)

table.values(table)

Mengembalikan array dari nilai tabel.

local data = { name = 'Alek', age = 25, city = 'Vladivostok' }

local values = table.values(data)
-- `values` berisi { 'Alek', 25, 'Vladivostok' }

table.has_key(table, key)

Memeriksa apakah kunci ada dalam tabel.

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)

Memeriksa apakah nilai ada dalam tabel.

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

Anda juga bisa menggunakan string:is_one_of():

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

Nama alternatif: 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)

Mengembalikan tabel dengan kunci dari tabel yang ditentukan yang memiliki nilai yang ditentukan.

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 (tidak ada kunci seperti itu)

table.has_any_key(table, find_keys)

Memeriksa apakah kunci tabel mengandung setidaknya satu nilai dari array yang ditentukan.

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

print(table.has_any_key(data, find_keys))   -- true (kunci 'name' ada di find_keys)

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

table.equals(table1, table2)

Membandingkan dua tabel secara rekursif untuk kesamaan penuh.

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)

Memeriksa apakah tabel kosong.

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

table.is_position(table)

Memeriksa apakah tabel merepresentasikan koordinat.

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)

Memeriksa bahwa semua elemen tabel sama dengan nilai yang ditentukan. Default memeriksa untuk 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)

Menghitung jumlah elemen dalam tabel.

NOTE

Untuk tabel dengan kunci integer, gunakan #table.
Karena operator # tidak bekerja pada tabel dengan kunci non-integer, gunakan table.count untuk mereka.

local data = { a = 1, b = 2, c = 3 }
print(table.count(data))  -- 3
print(#data)              -- 0, karena operator `#` tidak bekerja dengan kunci non-integer.

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

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

Menghasilkan urutan angka.

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)

Mengembalikan tabel baru yang berisi data hanya dengan kunci yang ditentukan.

local data = { name = 'Alek', age = 25, city = 'Vladivostok', country = 'Russia' }
local filtered = table.only(data, { 'name', 'age' })
-- `filtered` berisi `{ name = 'Alek', age = 25 }`
print(filtered.name, filtered.age)    -- 'Alek', 25
print(filtered.city)                  -- nil

table.except(table, keys)

Mengembalikan tabel baru yang berisi data tanpa kunci yang ditentukan.
(menyalin tabel, mengecualikan kunci yang ditentukan)

local data = { name = 'Alek', age = 25, city = 'Vladivostok', country = 'Russia' }
local filtered = table.except(data, { 'age', 'country' })
-- `filtered` berisi `{ name = 'Alek', city = 'Vladivostok' }`
print(filtered.name, filtered.city)      -- 'Alek', 'Vladivostok'
print(filtered.age,  filtered.country)   -- nil, nil

table.merge(table1, table2, overwrite?)

Menggabungkan tabel secara rekursif.

Default, tabel pertama tidak ditimpa, tabel baru dibuat.

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",
-- }

Timpa tabel pertama:

table.merge(defaults, user_config, true)

TIP

Lebih baik gunakan table.overwrite() untuk keterbacaan yang lebih baik.

table.join(table1, table2, recursively?)

Menambahkan kunci yang hilang dari table2 ke table1.
Nilai yang merupakan tabel disalin menggunakan 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 }

Jika recursively adalah true, fungsi akan diterapkan secara rekursif hanya untuk nilai yang merupakan tabel di kedua table1 dan 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)

Menimpa sepenuhnya table1 dengan nilai dari table2.

Variasi semantik untuk table.merge(table1, table2, true).

table.merge_values(table1, table2)

Menggabungkan nilai dari dua tabel menjadi satu, menghapus duplikat.
Urutan dipertahankan - pertama nilai dari table1, kemudian dari table2 yang tidak ada di 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?)

Menerapkan fungsi ke setiap elemen tabel.
callback: fun(value: any, key: any): any - menerima nilai dan kunci, mengembalikan nilai baru.

Default mengembalikan tabel baru.

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 }

Jika overwrite adalah true, maka fungsi memodifikasi tabel asli.

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)

Iterasi pada tabel dengan menerapkan fungsi (tidak memodifikasi tabel).
callback: fun(value: any, key: any): void - menerima nilai dan kunci; tidak mengembalikan apa-apa.

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

Nama alternatif: table.each()

local data = { a = 10, b = 20, c = 30 }
table.each(data, function(value, key)
    data[key] = value * 2
    -- Tidak ada yang mencegah akses ke upvalue `data`. Sekarang `data` telah ditimpa.
end)
print(dump(data))  -- { a = 20, b = 40, c = 60 }

table.multiply_each_value(table, multiplier_table)

Mengalikan setiap nilai tabel dengan nilai yang sesuai dari multiplier_table per kunci.

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 }
-- Kunci tanpa pengali tetap tidak berubah

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

Menambahkan nilai dengan kunci yang sama dari dua tabel.

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 }

-- Dengan nilai kosong untuk kunci yang hilang
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?)

Mengurangi nilai table2 dari table1 untuk kunci yang sama.

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?)

Mengalikan nilai dengan kunci yang sama dari dua tabel.

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?)

Membagi nilai table1 dengan nilai table2 untuk kunci yang sama.

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)

Membatasi nilai ke interval yang ditentukan.
Nama alternatif: 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)

Memeriksa bahwa nilai berada secara ketat dalam interval (min < value < max).

print(math.is_within(5, 1, 10))   -- true
print(math.is_within(1, 1, 10))   -- false (batas tidak termasuk)
print(math.is_within(10, 1, 10))  -- false

math.is_among(value, min, max)

Memeriksa bahwa nilai berada dalam interval, termasuk batas (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)

Memeriksa bahwa nilai berada dalam interval semi-terbuka (min, max] (min < value <= max).

print(math.is_in_range(5, 1, 10))   -- true
print(math.is_in_range(1, 1, 10))   -- false (sama dengan minimum)
print(math.is_in_range(10, 1, 10))  -- true (sama dengan maksimum)

math.is_near(value, near, gap?)

Memeriksa bahwa nilai dekat dengan yang ditentukan (|value - near| <= gap).

print(math.is_near(10, 12))        -- false (gap = 1 default)
print(math.is_near(11, 12))        -- true
print(math.is_near(10, 12, 3))     -- true (gap = 3)

math.quadratic_equation_roots(a, b, c)

Menyelesaikan persamaan kuadrat dari bentuk y = a*x^2 + b*x + c.

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

-- Tidak ada akar real
local r1, r2 = math.quadratic_equation_roots(1, 0, 1)
print(r1, r2)  -- nil, nil

math.point_on_circle(radius, angle)

Menghitung titik pada lingkaran.

local x, z = math.point_on_circle(5, math.pi/4)
print(x, z)  -- koordinat titik pada lingkaran dengan jari-jari 5 pada sudut 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?)

Mengembalikan nama file saat ini atau file fungsi pemanggil tergantung pada kedalaman stack.

• depth? - kedalaman stack panggilan (default 0)
• full? - tampilkan path lengkap (default false)

-- Dapatkan path relatif file
print(__FILE__())  -- 'mods/Voxrame/helpers/src/lua_ext/debug.lua'

-- Dapatkan path lengkap file
print(__FILE__(0, true))  -- '/home/alek13/projects/my-game/mods/Voxrame/helpers/src/lua_ext/debug.lua'

-- Dapatkan file 2 level di atas stack panggilan
print(__FILE__(2))  -- file dari fungsi yang memanggil fungsi pemanggil

__LINE__(depth?)

Mengembalikan nomor baris saat ini atau nomor baris fungsi pemanggil tergantung pada kedalaman stack.

print(__LINE__())  -- 57

-- Dapatkan nomor baris fungsi pemanggil
print(__LINE__(1))  -- nomor baris di file pemanggil

__FILE_LINE__(depth?, full?)

Mengembalikan file dan baris dalam format "path/relatif/ke/file:baris".

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

-- Dengan path lengkap
print(__FILE_LINE__(0, true))  -- '/home/alek13/projects/my-game/mods/Voxrame/helpers/src/lua_ext/debug.lua:65'

__DIR__(depth?)

Mengembalikan direktori dari file saat ini atau file fungsi pemanggil tergantung pada kedalaman stack.

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

__FUNC__(depth?)

Mengembalikan nama fungsi saat ini.

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

print_dump(depth, with_trace, ...)

Mencetak konten dari semua parameter yang dilewatkan ....
Sebelum output, menambahkan nama file dan baris @ <file>:<line>.

Jika with_trace adalah true, tambahan mencetak stack trace.

NOTE

Jika terminal Anda mendukung link, setiap @ <file>:<line> akan dihubungkan ke pembukaan IDE, lihat readme.md untuk konfigurasi.

TIP

Gunakan pd() dan pdt() untuk sintaks yang lebih ringkas. Lihat contoh di bawah.

pd(...)

Singkatan untuk print_dump. Memanggil print_dump dengan 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(...)

Singkatan untuk print_dump traced. Memanggil print_dump dengan 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?)

Mengembalikan call stack sebagai array frame, dari yang paling dalam hingga paling luar.

Setiap frame adalah tabel:

Field	Tipe	Deskripsi
file	string	file sumber dari fungsi (=[C] untuk fungsi yang ditulis dalam C)
line	integer	baris saat ini dalam file (-1 untuk fungsi yang ditulis dalam C)
name	string?	nama fungsi, jika diketahui
what	string	Lua, C, main atau tail

depth adalah berapa banyak level yang dilewati; default 0 — frame pertama adalah fungsi yang memanggil get_stack_frames().

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

output (dengan debug diaktifkan):

@ 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 adalah path absolut. Memperpendeknya (atau memformatnya secara berbeda) bisa Anda lakukan sendiri, atau serahkan kepada debug.render_backtrace().

debug.render_backtrace(frames, plain?)

Mengubah frame dari debug.get_stack_frames() (atau dari :catch()) menjadi string multi-baris, satu baris per frame.

Secara default string diberi gaya untuk terminal (warna + link). Berikan plain = true untuk mendapatkannya tanpa gaya dan link, sehingga aman ditulis ke log:

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

    -- untuk terminal:
    print(debug.render_backtrace(frames))

    -- untuk file log (misalnya di production):
    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

ke log (dengan 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

Jika terminal Anda mendukung link, setiap @ <file>:<line> akan dihubungkan ke pembukaan IDE, lihat readme.md untuk konfigurasi.

debug.print_backtrace(frames)

Mencetak frame ke terminal (bergaya, dengan link). Untuk melihat cepat saat debugging.

Singkatan untuk Voxrame.terminal.print(debug.render_backtrace(frames)).

TIP

Jangan gunakan di production, tulis ke log dengan debug.render_backtrace(frames, true) sebagai gantinya.

debug.measure(name, callback, print_result?)

Mengukur waktu eksekusi fungsi.

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

-- Ukur dengan output hasil
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


-- Ukur tanpa output
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)

Mencetak statistik pengukuran sebelumnya name yang diperoleh dari panggilan ke 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 yang nyaman, seperti yang biasa Anda gunakan di bahasa lain.

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)

Memanggil callback() segera dalam mode terproteksi dan mengembalikan objek dengan metode :catch().

WARNING

Error tidak dilempar ulang. Tanpa :catch(), error akan ditelan secara diam-diam.

Stack trace hanya dikumpulkan saat terjadi error (pada saat error terjadi, sebelum stack di-unwind), jadi pemanggilan yang berhasil hampir tidak memakan biaya apa pun.

:catch(handler)

Memanggil handler(error, traceback) jika callback yang sebelumnya diberikan ke try() gagal. Jika tidak, tidak melakukan apa-apa.

• error — apa yang dilempar oleh error(). Biasanya berupa string, tapi error() bisa melempar nilai apa pun.
• traceback — call stack pada saat error terjadi, array frame dari debug.get_stack_frames(), yang paling dalam terlebih dahulu.

Contoh penanganan/penggunaan traceback:

try(function()
    error('Something went wrong')
end):catch(function(error, traceback)
    -- saat development: ke terminal
    debug.print_backtrace(traceback)

    -- saat production: ke log
    core.log('error', tostring(error) .. '\n' .. debug.render_backtrace(traceback, true))
end)

debug.print_backtrace(traceback) (dengan debug diaktifkan):

   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 berisi semua frame, termasuk yang internal (xpcall, try) di bagian akhir.

TIP

:catch() mengembalikan objek yang sama, jadi Anda bisa merangkai beberapa :catch().

Global

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

errorf(message, ...)

Mirip dengan error() dalam Lua, tetapi message bisa berupa template string dengan parameter yang ditentukan, mirip dengan string.format().

local player_name = nil
errorf('Player `%s` not found', player_name)
-- Error: Player `nil` not found

output (ketika debug diaktifkan):

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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

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

Penanganan kesalahan di Luanti

WARNING

Stack trace akan berisi baris tambahan, karena Luanti tidak meneruskan level yang ditentukan ke core.error_handler().

errorlf(message, level, ...)

Seperti dalam errorf() Anda bisa meneruskan string format dan parameter, dan juga menentukan level trace.

errorlf('Kesalahan dalam data', 3, 'nilai: %d', 42)
-- Error dengan trace 3 level di atas

lihat penanganan kesalahan di Luanti

assertf(condition, message, ...)

Mirip dengan assert() dalam Lua, tetapi sebagai message Anda bisa menentukan string format dengan parameter, mirip dengan string.format().

Memanggil errorf() jika kondisi condition tidak terpenuhi.

-- Lanjutkan eksekusi jika player ada, jika tidak error
local player = nil
assertf(player, 'Pemain `%s` tidak ditemukan', player)

IO

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

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

io.file_exists(name)

Memeriksa apakah file ada.

if io.file_exists('config.txt') then
    print('File konfigurasi ditemukan')
else
    print('File konfigurasi tidak ada')
end

io.dirname(path)

Mengembalikan direktori dari 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?)

Menulis konten ke file.

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

if success then
    print('Data berhasil ditulis')
else
    print('Error penulisan:', error_code, error_message)
end

-- Tambahkan ke akhir file
io.write_to_file('log.txt', 'Entri baru\n', 'a')

io.read_from_file(filepath, mode?)

Membaca seluruh konten dari file.
Mengembalikan string dengan konten file jika berhasil atau false, error_code, error_message jika error.

local content = io.read_from_file('config.json')
if content then
    print('Konten file:', content)
else
    print('Error membaca file')
end

Penanganan error

local success, error_code, error_message = io.read_from_file('nonexistent.txt')
if not success then
    print('Error:', error_code, error_message)
end
-- Error: 2       nonexistent.txt: No such file or directory

atau:

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

Membaca dalam mode biner

local binary_content = io.read_from_file('image.png', 'rb')
if binary_content then
    print('Ukuran file:', #binary_content, 'byte')
end

io.get_file_error()

Mengembalikan kode dan pesan error terakhir dari fungsi io.read_from_file() atau 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:', error_code, error_message)
end
-- Output: Error: 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 penulisan:', error_code, error_message)
end
-- Output: Error penulisan: 13       /readonly/file.txt: Permission denied

OS

os.DIRECTORY_SEPARATOR

Pemisah direktori untuk sistem operasi saat ini.

local DS = os.DIRECTORY_SEPARATOR

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