Yardımcılar

Yardımcılar, projede rahat çalışmak için bir dizi Lua yardımcı fonksiyonudur.

Bu yardımcı fonksiyonlar, Lua'nın standart yeteneklerini önemli ölçüde genişletir ve geliştirmeyi basitleştirir.

---

• 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 tarafından sağlanan yöntemler:

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

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

string:lower()

String'i Kiril desteği ile küçük harfe çevirir.

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

string:upper()

String'i Kiril desteği ile büyük harfe çevirir.

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

string:is_one_of(table)

String'in geçirilen dizideki değerlerden biri olup olmadığını kontrol eder.
(table.contains fonksiyonunun semantik analoğu, string'in geçirilen dizide içerilip içerilmediğini kontrol eder.)

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

string:first_to_upper()

İlk harfi büyük harfe çevirir.

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

string :title()/:to_headline()

Her kelimenin ilk harfini title case'e çevirir.
Alternatif isim: 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)

String'in belirtilen önekle başlayıp başlamadığını kontrol eder.

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

string:ends_with(suffix)

String'in belirtilen sonekle bitip bitmediğini kontrol eder.

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

string:contains(sub_string)

Alt string varlığını kontrol eder.

local text = 'Hello, World !!!'
print(text:contains('World'))   -- true
print(text:contains('world'))   -- false (büyük/küçük harf duyarlı)

string:replace(pattern, replacement, n?)

Alt string'i değiştirir (gsub'un analoğu, ancak sadece değiştirme sayısı olmadan string döndürür).
string.gsub ve Patterns için belgelere bakın

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

-- Sadece ilk geçişi değiştir
local result2 = text:replace('World', 'Lua', 1)
print(result2)  -- 'Hello, Lua, World!'

string:remove(pattern, n?)

Alt string'i kaldırır.
string.gsub ve Patterns için belgelere bakın

local text = 'Hello, World!'
print(text:remove(', '))        -- 'HelloWorld!'
print(text:remove('o', 1))      -- 'Hell, Wrld!' (sadece ilk 'o'yu kaldır)

string:reg_escape()

Düzenli ifadeler için özel karakterleri kaçış yapar.
Patterns bakın

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

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

string:vxr_split(delimiter?, processor?)

String'i belirtilen delimiter ile böler ve parçaları işleme yeteneği vardır.

Luanti'nin kendi string.split yöntemi vardır, ancak parça işlemini desteklemez.
Bu yöntem, string parçalarını işleme yeteneği ekler.

-- İşleme olmadan
('hello world'):vxr_split()             -- { 'hello', 'world' }
('apple,banana,cherry'):vxr_split(',')  -- { 'apple', 'banana', 'cherry' }

-- İşleme ile
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)

String'e dönüştürür veya nil döndürür.

print(string.or_nil('hello'))     -- 'hello'
print(string.or_nil(42))          -- '42'
print(string.or_nil(nil))         -- nil
print(tostring(nil))              -- 'nil' (karşılaştırma)

---

Luanti tarafından sağlanan yöntemler :

Luanti string.split()

Ayrıca bakın: string.vxr_split(delimiter?, processor?)

String'i belirtilen ayırıcıya göre parçalara böler. String dizisi döndürür. Argümanlar:

• separator? ayırıcı, varsayılan: ","
• include_empty? varsayılan: false
• max_splits? negatif ise, sınırsız bölmeler, varsayılan: -1
• sep_is_pattern? ayırıcının normal string mi yoksa pattern (regex) mi olduğu, varsayılan: false

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

-- Boşluklara göre böl
local words = 'hello world lua'.split(' ')
print(words[1], words[2], words[3])  -- 'hello', 'world', 'lua'

Luanti string.trim()

String'in başındaki ve sonundaki boşluk karakterlerini kaldırır.

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

Luanti string.pack()

Değerleri formata göre ikili string'e paketler.
Lua 5.4'ten backport.

-- Tamsayıları paketle
local packed = string.pack('i4', 42)
print(#packed)  -- 4 (byte olarak boyut)

-- Birden fazla değeri paketle
local data = string.pack('i4f8', 100, 3.14)
print(#data)  -- 12 (4 + 8 byte)

Luanti string.unpack()

İkili string'i formata göre değerlere açar.
Lua 5.4'ten backport.

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 (açmadan sonraki pozisyon)

-- Belirtilen pozisyondan aç
local value = string.unpack('i4', packed, 5)
print(value)            -- 3.14 (float olarak)

Luanti string.packsize()

string.pack tarafından oluşturulacak string'in boyutunu döndürür.
Lua 5.4'ten backport.

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

-- Karmaşık formatlar için
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()

Yöntemler, Luanti tarafından sağlanan :

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

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

table.keys(table)

Tablonun anahtarlarından oluşan bir dizi döndürür.

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

local keys = table.keys(data)
-- `keys` `{ 'name', 'age', 'city' }` içerir (sıralama değişebilir)

table.values(table)

Tablonun değerlerinden oluşan bir dizi döndürür.

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

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

table.has_key(table, key)

Bir anahtarın tabloda olup olmadığını kontrol eder.

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)

Bir değerin tabloda olup olmadığını kontrol eder.

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

Ayrıca string:is_one_of() kullanabilirsiniz:

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

Alternatif isim: 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)

Belirtilen değere sahip belirtilen tablonun anahtarlarından oluşan bir tablo döndürür.

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 (böyle bir anahtar yok)

table.has_any_key(table, find_keys)

Tablo anahtarlarının belirtilen diziden en az bir değer içerip içermediğini kontrol eder.

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

print(table.has_any_key(data, find_keys))   -- true ('name' anahtarı find_keys'te var)

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

table.equals(table1, table2)

Tam eşitlik için iki tabloyu rekursif olarak karşılaştırır.

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)

Tablonun boş olup olmadığını kontrol eder.

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

table.is_position(table)

Tablonun koordinatları temsil edip etmediğini kontrol eder.

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)

Tablodaki tüm elemanların belirtilen değere eşit olduğunu kontrol eder. Varsayılan olarak true için kontrol eder.

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)

Tablodaki eleman sayısını sayar.

NOTE

Tamsayı anahtarlı tablolar için #table kullanın.
# operatörü tamsayı olmayan anahtarlı tablolarda çalışmadığından, onlar için table.count kullanın.

local data = { a = 1, b = 2, c = 3 }
print(table.count(data))  -- 3
print(#data)              -- 0, çünkü `#` operatörü tamsayı olmayan anahtarlarla çalışmaz.

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

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

Sayı dizisi oluşturur.

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)

Belirtilen anahtarlarla sadece veri içeren yeni bir tablo döndürür.

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

table.except(table, keys)

Belirtilen anahtarlar olmadan veri içeren yeni bir tablo döndürür.
(tabloyu kopyalar, belirtilen anahtarları hariç tutar)

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

table.merge(table1, table2, overwrite?)

Tabloları rekursif olarak birleştirir.

Varsayılan olarak, ilk tablo üzerine yazılmaz, yeni tablo oluşturulur.

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

İlk tabloyu üzerine yaz:

table.merge(defaults, user_config, true)

TIP

Daha iyi okunabilirlik için table.overwrite() kullanın.

table.join(table1, table2, recursively?)

table2'den eksik anahtarları table1'e ekler.
Tablo olan değerler table.copy() kullanılarak kopyalanır.

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 }

Eğer recursively true ise, fonksiyon sadece hem table1 hem de table2'de olan değerler için rekursif olarak uygulanır.

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'i table2'den gelen değerlerle tamamen üzerine yazar.

table.merge(table1, table2, true) için semantik varyant.

table.merge_values(table1, table2)

İki tablonun değerlerini bir tabloda birleştirir, duplikatları kaldırır.
Sıra korunur - önce table1'den değerler, sonra table1'de olmayan table2'den değerler.

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

Fonksiyonu tablodaki her elemana uygular.
callback: fun(value: any, key: any): any - değer ve anahtarı kabul eder, yeni değer döndürür.

Varsayılan olarak yeni bir tablo döndürür.

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 }

Eğer overwrite true ise, fonksiyon orijinal tabloyu değiştirir.

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)

Tablo üzerinde fonksiyonu uygulayarak iterasyon yapar (tabloyu değiştirmez).
callback: fun(value: any, key: any): void - değer ve anahtarı kabul eder; hiçbir şey döndürmez.

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

Alternatif isim: table.each()

local data = { a = 10, b = 20, c = 30 }
table.each(data, function(value, key)
    data[key] = value * 2
    -- `data` upvalue'ına erişimi engelleyen bir şey yok. Şimdi `data` üzerine yazıldı.
end)
print(dump(data))  -- { a = 20, b = 40, c = 60 }

table.multiply_each_value(table, multiplier_table)

Tablodaki her değeri, anahtara göre multiplier_table'dan karşılık gelen değerle çarpar.

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 }
-- Çarpanı olmayan anahtarlar değişmeden kalır

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

İki tablodan aynı anahtara sahip değerleri ekler.

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 }

-- Eksik anahtarlar için boş değerle
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?)

Aynı anahtarlar için table2 değerlerini table1'den çıkarır.

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

İki tablodan aynı anahtara sahip değerleri çarpar.

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

Aynı anahtarlar için table1 değerlerini table2 değerlerine böler.

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)

Değeri belirtilen aralığa sınırlar.
Alternatif isim: 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)

Değerin aralıkta olduğunu kontrol eder (min < value < max).

print(math.is_within(5, 1, 10))   -- true
print(math.is_within(1, 1, 10))   -- false (sınırlar dahil değil)
print(math.is_within(10, 1, 10))  -- false

math.is_among(value, min, max)

Değerin aralıkta olduğunu kontrol eder, sınırları dahil (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)

Değerin yarı-açık aralıkta olduğunu kontrol eder (min, max] (min < value <= max).

print(math.is_in_range(5, 1, 10))   -- true
print(math.is_in_range(1, 1, 10))   -- false (minimuma eşit)
print(math.is_in_range(10, 1, 10))  -- true (maksimuma eşit)

math.is_near(value, near, gap?)

Değerin belirtilen değere yakın olduğunu kontrol eder (|value - near| <= gap).

print(math.is_near(10, 12))        -- false (gap = 1 varsayılan)
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 formundaki ikinci dereceden denklemi çözer.

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

-- Gerçek kök yok
local r1, r2 = math.quadratic_equation_roots(1, 0, 1)
print(r1, r2)  -- nil, nil

math.point_on_circle(radius, angle)

Daire üzerinde bir nokta hesaplar.

local x, z = math.point_on_circle(5, math.pi/4)
print(x, z)  -- 5 yarıçaplı dairede 45° açıda bir noktanın koordinatları

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

Mevcut dosyanın veya çağrı fonksiyonun dosyasının adını yığın derinliğine göre döndürür.

• depth? - çağrı yığınının derinliği (varsayılan 0)
• full? - tam yolu göster (varsayılan false)

-- Dosyanın göreli yolunu al
print(__FILE__())  -- 'mods/Voxrame/helpers/src/lua_ext/debug.lua'

-- Dosyanın tam yolunu al
print(__FILE__(0, true))  -- '/home/alek13/projects/my-game/mods/Voxrame/helpers/src/lua_ext/debug.lua'

-- Çağrı yığınının 2 seviye üstündeki dosyayı al
print(__FILE__(2))  -- çağrı fonksiyonunu çağıran fonksiyonun dosyası

__LINE__(depth?)

Mevcut satır numarasını veya çağrı fonksiyonun satır numarasını yığın derinliğine göre döndürür.

print(__LINE__())  -- 57

-- Çağrı fonksiyonunun satır numarasını al
print(__LINE__(1))  -- çağrı dosyasındaki satır numarası

__FILE_LINE__(depth?, full?)

"Dosya:satır" formatında dosya ve satır döndürür.

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

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

__DIR__(depth?)

Mevcut dosyanın veya çağrı fonksiyonun dosyasının dizinini yığın derinliğine göre döndürür.

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

__FUNC__(depth?)

Mevcut fonksiyonun adını döndürür.

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

print_dump(depth, with_trace, ...)

Geçirilen tüm parametrelerin ... içeriğini yazdırır.
Çıktıdan önce, dosya adı ve satır @ <file>:<line> ekler.

Eğer with_trace true ise, ek olarak yığın izi yazdırır.

NOTE

Eğer terminaliniz linkleri destekliyorsa, her @ <file>:<line> IDE açılışına bağlanacaktır, yapılandırma için readme.md bakın.

TIP

• Daha kısa sözdizimi için pd() ve pdt() kullanın. Aşağıdaki örnekler bakın.

pd(...)

print_dump için kısaltma. with_trace == false ile print_dump çağırır.

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 için kısaltma. with_trace == true ile print_dump çağırır.

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

Çağrı yığınını, en içteki çerçeveden en dıştakine doğru bir dizi olarak döndürür.

Her çerçeve bir tablodur:

Alan	Tür	Açıklama
file	string	fonksiyonun kaynak dosyası (C ile yazılmış fonksiyonlar için =[C])
line	integer	dosyadaki geçerli satır (C ile yazılmış fonksiyonlar için -1)
name	string?	biliniyorsa fonksiyonun adı
what	string	Lua, C, main veya tail

depth, kaç seviyenin atlanacağıdır; varsayılan 0 — ilk çerçeve get_stack_frames()'i çağıran fonksiyondur.

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

output (debug etkinken):

@ 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 mutlak bir yoldur. Onu kısaltmayı (veya başka şekilde biçimlendirmeyi) kendiniz yapabilir, ya da bunu debug.render_backtrace()'a bırakabilirsiniz.

debug.render_backtrace(frames, plain?)

debug.get_stack_frames()'den (veya :catch()'dan) gelen çerçeveleri, her çerçeve için bir satır olacak şekilde çok satırlı bir dizeye dönüştürür.

Varsayılan olarak dize terminal için stilize edilmiştir (renkler + linkler). Stil ve link olmadan almak için plain = true geçin, böylece bir loga yazmak güvenli olur:

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

    -- terminale:
    print(debug.render_backtrace(frames))

    -- bir log dosyasına (örn. üretimde):
    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

bir loga (plain = true ile):

   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

Eğer terminaliniz linkleri destekliyorsa, her @ <file>:<line> IDE açılışına bağlanacaktır, yapılandırma için readme.md bakın.

debug.print_backtrace(frames)

Çerçeveleri terminale yazdırır (stilize edilmiş, linklerle). Hata ayıklama sırasında hızlı bir bakış için.

Voxrame.terminal.print(debug.render_backtrace(frames)) için kısaltma.

TIP

Üretimde kullanmayın, bunun yerine debug.render_backtrace(frames, true) ile bir loga yazın.

debug.measure(name, callback, print_result?)

Fonksiyonun yürütme süresini ölçer.

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

-- Sonuç çıktısı ile ölç
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


-- Çıktı olmadan ölç
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)

Önceki ölçümlerin istatistiklerini name yazdırır, debug.measure(name, ....) çağrılarından elde edilir.

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

Exception

• exception.try()
• :catch()

Diğer dillerde alışık olduğunuz gibi kullanışlı bir 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()'i hemen korumalı modda çağırır ve :catch() metoduna sahip bir nesne döndürür.

WARNING

Hatalar yeniden fırlatılmaz. :catch() olmadan bir hata sessizce yutulur.

Yığın izi yalnızca bir hata oluştuğunda toplanır (hatanın oluştuğu anda, yığın açılmadan önce), bu yüzden başarılı bir çağrı neredeyse hiçbir şeye mal olmaz.

:catch(handler)

Daha önce try()'a geçirilen callback başarısız olduysa handler(error, traceback)'i çağırır. Aksi halde hiçbir şey yapmaz.

• error — error() tarafından fırlatılan şey. Genellikle bir string'dir, ancak error() herhangi bir değeri fırlatabilir.
• traceback — hatanın oluştuğu andaki çağrı yığını, debug.get_stack_frames()'den gelen bir çerçeve dizisi, en içteki önce.

traceback'i işleme/kullanma örnekleri:

try(function()
    error('Something went wrong')
end):catch(function(error, traceback)
    -- geliştirmede: terminale
    debug.print_backtrace(traceback)

    -- üretimde: loga
    core.log('error', tostring(error) .. '\n' .. debug.render_backtrace(traceback, true))
end)

debug.print_backtrace(traceback) (debug etkinken):

   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, sondaki dahili olanlar (xpcall, try) dahil tüm çerçeveleri içerir.

TIP

:catch() aynı nesneyi döndürür, bu yüzden birden fazla :catch()'i zincirleyebilirsiniz.

Global

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

errorf(message, ...)

Lua'daki error() ile benzer, ancak message belirtilen parametrelerle şablon string olabilir, string.format() ile benzer.

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

output (debug etkin olduğunda):

++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
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'da Hata Yönetimi

WARNING

Yığın izi ekstra satırlar içerecektir, çünkü Luanti belirtilen level'i core.error_handler() geçmez.

errorlf(message, level, ...)

errorf() gibi format stringi ve parametre geçebilir, ayrıca izleme seviyesi belirtebilirsiniz.

errorlf('Verilerde hata', 3, 'değer: %d', 42)
-- 3 seviye üstünde izleme ile hata

Luanti'da hata yönetimi bakın

assertf(condition, message, ...)

Lua'daki assert() ile benzer, ancak message olarak belirtilen parametrelerle format string belirtebilirsiniz, string.format() ile benzer.

condition koşulu sağlanmazsa errorf() çağırır.

-- Player varsa yürütmeye devam et, yoksa hata
local player = nil
assertf(player, 'Oyuncu `%s` bulunamadı', player)

IO

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

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

io.file_exists(name)

Dosyanın var olup olmadığını kontrol eder.

if io.file_exists('config.txt') then
    print('Yapılandırma dosyası bulundu')
else
    print('Yapılandırma dosyası eksik')
end

io.dirname(path)

Yolun dizinini döndürür.

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

İçeriği dosyaya yazar.

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

if success then
    print('Veri başarıyla yazıldı')
else
    print('Yazma hatası:', error_code, error_message)
end

-- Dosyanın sonuna ekle
io.write_to_file('log.txt', 'Yeni giriş\n', 'a')

io.read_from_file(filepath, mode?)

Dosyadan tüm içeriği okur.
Başarılı olursa dosya içeriği string ile veya hata durumunda false, error_code, error_message döndürür.

local content = io.read_from_file('config.json')
if content then
    print('Dosya içeriği:', content)
else
    print('Dosya okuma hatası')
end

Hata yönetimi

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

veya:

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

İkili modda okuma

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

io.get_file_error()

io.read_from_file() veya io.write_to_file() fonksiyonlarından son hata kodunu ve mesajını döndürür.

local success = io.read_from_file('nonexistent.txt')
if not success then
    local error_code, error_message = io.get_file_error()
    print('Hata:', error_code, error_message)
end
-- Output: Hata: 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('Yazma hatası:', error_code, error_message)
end
-- Output: Yazma hatası: 13       /readonly/file.txt: Permission denied

OS

os.DIRECTORY_SEPARATOR

Mevcut işletim sistemi için dizin ayırıcı.

local DS = os.DIRECTORY_SEPARATOR

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