A szabványos könyvtárakban olyan hasznos függvényeket találunk, amik közvetlenül a C API-n keresztül lettek implementálva. Néhányuk alapvető szolgáltatást nyújt (például type és getmetatable), mások az I/O kezelést könnyítik.

A Luaban a következő könyvtárak találhatók:


Hogy ezekhez a könyvtárakhoz hozzáférjünk, a C host programnak meg kell hívnia a luaL_openlibs függvényt, ami hozzáférést biztosít az összes könyvtárhoz. Lehetőség van őket egyenként is megnyitni: a luaopen_base függvény például a basic library-hez van. Ezek a függvények a lualib.h-ban vannak deklarálva és nem közvetlenül kell meghívni őket, hanem a lua_call használatával.

Basic Library


assert(v [, message])

Hibát dob, ha v értéke hamis (nil vagy false), különben visszaadja minden paraméterét. A message egy hiba üzenet. Ha nem adjuk meg, akkor az alapértelmezett értéket dobja, ami: "assertion failed!".

collectgarbage(opt [, arg])

Ez a függvény a garbage collector általános interfésze. Különböző szolgáltatásokat nyújt az opt paraméterének megfelelően.

dofile(filename)

Megnyitja a paraméterben kapott file-t és végrehajtja a tartalmát. Ha paraméter nélkül hívjuk meg, akkor a standard bemenetet hajtja végre.

error (message [, level])

Terminál és visszaadja hibaüzenetként a message paramétert. Általában kapunk valami információt az hiba helyére vonatkozóan az üzenet elején. A level paraméter meghatározza a hogy kapjuk meg a hiba helyét. Alapértelmezett értéke az 1 azt jelenti, hogy a hiba ott volt, ahol a függvényt meghívták. 2 esetén arra a függvényre mutat, ami meghívta az error függvényt. 0 esetén a hibaüzenet ad információt a hiba helyéről.

_G

Egy globális változó (nem egy függvény), ami a globális környezetet tartalmazza. A Lua önmagában nem használja ezt a változót.

getfenv ([f])

Visszaadja az f függvény által használt környezetet. f lehet egy Lua függvény vagy egy szám ami egy függvényt azonosít verem szinten.

getmetatable (object)

Ha az object paraméternek nincs metatáblája, nil-t ad vissza, egyébként ha az object metatáblájának van "__metatable" mezője, akkor annak az értékét, ha nincs neki, akkor magát a metatáblát adja vissza.

ipairs (t)

3 értéket ad vissza: egy iterátor függvényt, a t táblát és a 0-át

for i,v in ipairs(t) do body end

Ez végig megy a tábla párjain (1,t[1]), (2,t[2]), ···, amíg egy hiányzó egész kulcshoz nem ér.

pairs (t)

3 értékkel tér vissza: a next függvénnyel, a t táblával és a nil-lel.

for k,v in pairs(t) do body end

Ez végig megy a tábla összes kulcs-érték párján.

pcall (f, arg1, ···)

Meghívja az f függvényt védett módban a megadott paraméterekkel. Ez azt jelenti hogy a hiba nem terjed tovább. pcall elkapja a hibát és vissza ad egy státusz kódot. Az első eredmény a státusz kód (boolean), ami igaz, ha a hívás sikeres volt, és ebben az esetben a hívás eredményét is visszaadja. Bármilyen hiba esetén egy false-t kapunk és egy hiba üzenetet.

print (···)

Akárhány paramétere lehet, és az értékeiket kiírja a stdout-ra. A tostring függvényt használja, hogy a paramétereket stringé konvertálja. Ez nem a formázott kiíratáshoz készült, általában debbug-olásra használják. Formázott kiíratáshoz a string.format függvény használatos.

rawequal (v1, v2)

Megvizsgálja, hogy v1 egyenlő-e v2-vel. Egy boolean értékkel tér vissza.

rawget (table, index)

Lekérdezi a table[index] valódi értékét, mindenféle meta eljárás használata nélkül. A table paraméternek egy táblának kell lennie, az index paraméter bármi lehet.

rawset (table, index, value)

Beállítja a table[index] értéket a value paraméternek megfelelően. A table paraméternek egy táblának kell lennie, az index paraméter bármi lehet, kivéve nil, és a value bármilyen Lua érték lehet. Ez a függvény egy táblát ad vissza

select (index, ···)

Ha index egy szám, akkor visszaadja az összes index-edik paraméter utáni paramétert. Egyébként az index paraméter "#" kell legyen, és ekkor a select visszaadja az összes extra paramétert, amit kapott.

setmetatable (table, metatable)

Beállítja a tábla metatábláját. Ha a metatble nil, akkor törli a tábla metatábláját. Ha az eredeti metatáblának volt _metatable mezője, akkor hiba váltódik ki.

tonumber (e [, base])

Megpróbálja a paraméterét számmá konvertálni. Ha a paraméter egy szám, vagy egy számmá konvertálható string, akkor a függvény visszaadja ezt a számot, különben pedig nil-t. Meg lehet adni egy opcionális base paramétert is, ami a számrendszer alapját állítja. Ez a szám 2 és 36 között kell legyen. A 10 fölötti számrendszerekben a 'A' betű jelenti a 10-et, a 'B' a 11-et és így tovább (kis és nagybetű nem számít). Az alapértelmezett érték a 10.

tostring (e)

Bármilyen típusú paramétert stringgé konvertál. Ha irányítani akarjuk a konvertálást, akkor használjuk a string.format függvényt.

type (v)

Egy stringet ad vissza, ami a paraméterének a típusát jelöli. A lehetséges értékei ennek a stringnek: "nil" (a string, nem az érték nil), "number", "string", "boolean", "table", "function", "thread", és "userdata".

unpack (list [, i [, j]])

A paraméterként kapott tábla elemeit adja vissza. Ez a függvény ekvivalens a következővel:

return list[i], list[i+1], ···, list[j]

kivéve, hogy ez csak fix számú elemre írható. Alapértelmezésben i értéke 1, j értéke pedig a lista hossza, amit a length operátor határoz meg.

_VERSION

Ez egy globális változó, nem pedig egy függvény, ami egy stringet tartalmaz az aktuális iterpreter verziójára vonatkozóan. Ez jelen esetben "Lua 5.1".

xpcall (f, err)

Ez a függvény hasonlít a pcall függvényhez, kivéve, hogy itt definiálhatunk saját hiba kezelőt. xpcall meghívja az f függvényt protected módban. Az err paraméter a hibakezelésre van. Ha f-ben kiváltódik egy hiba, akkor az nem terjed tovább, hanem az xpcall meghívja az err függvényt az eredeti hiba objektummal, és egy (boolean) státusz kóddal tér vissza, ami true ha a hívás sikeres volt, ebben az esetben a hívás összes eredményét is megkapjuk. Bármiféle hiba esetén a visszatérési érték false és az err függvény visszatérési értéke.

Modulkezelés

A package könyvtár alapvető eszközöket tartalmaz modulok betöltéséhez Luában. A require függvényt a globális névtérbe exportálja, minden más függvény a package táblában érhető el. (A könyvtár leírása az 5.2-es Lua verzión alapul.)


require (modname)

Betölt egy modult. A függvény először belenéz a package.loaded táblába, hogy ellenőrizze, nincs-e már betöltve a modul. Ha megtalálja a táblában, akkor visszaadja a package.loaded[modname] értékét. Ellenkező esetben megpróbál találni egy loadert (betöltőfüggvényt) a modulhoz. A loader kereséséhez a package.searchers listát használja a függvény. Ha ezt a listát megváltoztatjuk, akkor a Lua más módon fog modulokat betölteni. Az alábbi leírás az alapértelmezett package.searchers működését dokumentálja.
Először a require függvény ellenőrzi a package.preload[modname] értékét. Ha van értéke, akkor függvényként értelmezi ezt az értéket és ezt használja loadernek. Ha nincs értéke, akkor a require függvény a package.path alapján keres egy Lua loadert. Ha ez sem sikerül, akkor a package.cpath alapján keres egy C loadert. Ha ezzel sem jár sikerrel, akkor az ún. all-in-one keresőt indítja el. (Lsd. a package.searchers leírását lentebb.)
Ha a require függvény talált egy loadert, akkor meghívja azt és két argumentumot ad át neki: a modname-et és egy plusz argumentumot attól függően, hogy hogyan találta meg a loadert. (Pl. ha egy fájlból jött, akkor a plusz argumentum a fájl neve.)
Ha a loader visszaad bármilyen nem-nil értéket, akkor az az érték bekerül a package.loaded[modname] alá. Ha a loader nem ad vissza nem-nil értéket és nem ad értéket a package.loaded[modname]-nek sem, akkor a require függvény true értéket rendel a package.loaded[modname]-hez.
Ha bármilyen hiba lép fel a modul betöltése vagy futtatása során, vagy ha a require nem talál betöltőt a modulhoz, akkor kivétel keletkezik.


package.config

String, ami fordítási idejű információkat tárol a modulok számára. Több sorból áll:


package.cpath

Az elérési utak, amiket a require a C loaderek (betöltőfüggvények) kereséséhez használ. A Lua ugyanúgy inicializálja ezt a változót, mint a package.path változót, azaz a LUA_CPATH_5_2 környezeti változóból, vagy a LUA_CPATH környezeti változóból vagy a luaconf.h-ban definiált alapértelmezett útvonalból.


package.loaded

A require által használt tábla; ebben tartjuk nyilván a már betöltött modulokat. Ha a require függvény meghívásakor egy modname értékre a package.loaded[modname] értéke nem false, akkor a require egyszerűen csak visszaadja az ott tárolt értéket.
Ez a változó csak egy referencia az igazi táblára; ha megváltoztatjuk az értékét, attól még a require nem fog másik táblát használni.


package.loadlib (libname, funcname)

Dinamikusan linkeli a Luát futtató programot a libname C könyvtárhoz. (A Lua egy beágyazott nyelv, nem csak standalone interpreterrel használhatjuk.)
Ha a funcname értéke '*', akkor csak linkeli a könyvtárat, amivel hozzáférhetővé teszi az általa exportált szimbólumokat más könyvtárak számára. Ellenkező esetben megkeresi a nevezett függvényt a könyvtáron belül és visszaadja mint egy C függvényt. (Tehát a funcname függvénynek illeszkednie kell a lua_CFunction típusra.)
Ez egy alacsony szintű funkció ami teljesen figyelmen kívül hagyja a csomag- és modulrendszert. Ellentétben a require függvénnyel, ez a függvény nem keres elérési utak között és nem egészíti ki kiterjesztésekkel a fájlneveket, ezért libname a C könyvtár teljes elérési útját kell, hogy tartalmazza, kiterjesztéssel együtt. A funcname értéke a C könyvtár által exportált szimbólum pontos neve kell, hogy legyen. (Ez az érték fordítónként és linkerenként változhat.)
Ez a funkcionalitás nem része a Standard C-nek, ezért csak bizonyos platformokon működik (Windows, Linux, Mac OS X, Solaris, BSDés minden Unix rendszer, ami támogatja a dlfcn szabványt).


package.path

Az elérési utak, amiket a require a Lua loaderek (betöltőfüggvények) kereséséhez használ.
Indításkor a Lua a változó értékét a LUA_PATH_5_2 környezeti változóból, vagy a LUA_PATH környezeti változóból vagy a luaconf.h-ban definiált alapértelmezett útvonalból állítja be. (Ebben a sorrendben.) A környezeti változók értékében a ';;' szöveg az alapértelmezett útvonalra cserélődik.


package.preload

Egy tábla, ami egyes modulokhoz loadereket (betöltőfüggvényeket) tárol. (Lsd. require.) Ez a változó csak egy referencia az igazi táblára; ha megváltoztatjuk az értékét, attól még a require nem fog másik táblát használni.


package.searchers

A require által használt tábla, amivel a modulok betöltésének módja és sorrendje állítható be. Minden bejegyzés a táblában egy keresőfüggvény. Amikor a require keres egy modult, akkor ezen tábla elemeit hívja meg növekvő sorrendben, egyetlen argumentumként átadva a betöltendő modul nevét. A keresőfüggvény egy másik függvényt (egy loadert) ad vissza és egy extra értéket, ami paraméterként lesz átadva a loadernek. Az extra érték lehet egy szöveg is egy hibaüzenettel, ha a keresőfüggvény nem találta a kért modul betöltőjét, de lehet nil is az értéke.
A package.searchers alapértelmezésben 4 keresőfüggvényt tartalmaz: Az első keresőfüggvényen kívül (ami a package.preload táblát vizsgálja) mindegyik keresőfüggvény azt a fájlnevet adja vissza extra értékként, ahol a modult megtalálta. Az első keresőfüggvény nil értéket ad vissza.


package.searchpath (name, path [, sep [, rep]])

A megadott nevű modult keresi a megadott keresési útvonalon.
A keresési útvonal egy string, ami pontosvesszővel elválasztott sablonokat tartalmaz. A függvény minden sablonban kicseréli a kérdőjeleket a name másolatára, amiben előtte a sep (alapértelmezésben '.') összes előfordulását kicserélte rep-re (alapértelmezésben a rendszer könyvtárelválasztó karaktere). Az így kapott értéket mint fájlnevet értelmezi és megpróbálja megnyitni.
Például, ha az elérési utak a következők:
"./?.lua;./?.lc;/usr/local/?/init.lua"

akkor a foo.a nevű modul betöltésekor a rendszer a ./foo/a.lua, ./foo/a.lc és /usr/local/foo/a/init.lua fájlokat próbálja megnyitni, ebben a sorrendben.
A függvény az első olyan fájl nevét adja vissza, ami megnyitható olvasásra, vagy nil-t és egy hibaüzenetet, ha nem tudott fájlt megnyitni. (A hibaüzenet tartalmazza az összes fájl nevét, amit megpróbált megnyitni.)

Coroutine manipuláció

A coroutine műveletek a basic library egy alkönyvtárát képezik.

coroutine.create (f)

Létrehoz egy coroutine-t, melynek a visszatérési értéke egy olyan objektum, aminek a típus thread. f-nek egy Lua függvénynek kell lennie.

coroutine.resume (co [, val1, ···])

Elkezdi vagy folytatja a co coroutine futtatását.

coroutine.running ()

Visszaadja az éppen futó coroutine-t. A main thread esetén pedig nil-t.

coroutine.status (co)

Visszaadja a co coroutine státuszát egy stringben. Ez lehet "running", ha a coroutine éppen fut, "suspended", ha fel van függesztve, "normal", ha aktív, de nem fut, és "dead", ha a body függvény lefutott, vagy egy hiba miatt leállt.

coroutine.wrap (f)

Egy új coroutine-t hoz létre f törzsével. f-nek egy Lua függvénynek kell lennie.

coroutine.yield (···)

Felfüggeszti az őt hívó coroutine futását. Ez a coroutine nem lehet C függvény, metaeljárás vagy iterátor.

String kezelés

Luában a stringek 1-től indexeltek, a negatív indexek a string végétől visszafele számítanak. Így az utolsó karakter indexe (többek közt) -1. A string könyvtárban található eljárások a string táblából érhetők el. A legfontosabb műveletek:

string.byte (s [, i])

Visszaadja az s i-edik karakterének belső numerikus kódját, vagy nilt, ha az index nem megfelelő. Ha nincs megadva i, az első karakterre vonatkozik.


string.char (i1, i2, ...)

A kapott 0 vagy több integert stringgé alakítja a numerikus kódjuk szerint. Ezek a kódok nem feltétlenül azonosak az egyes platformokon!


string.find(s, pattern [, init [, plain]])

Megkeresi a minta első előfordulását az init indextől kezdődően. Az init értéke alapértelmezésben 1, és lehet negatív is. Ha plain értéke igaz, a minta nem reguláris kifejezés, ekkor sima részstring-keresést végez. Visszatérési értéke nil, ha nincs találat, egyébként az illeszkedő részstring elejének és végének indexe, valamint ha reguláris kifejezést kerestünk, plusz értékként az illeszkedő részstring (FIXME).


string.len (s)

A kapott string hosszát adja vissza. Az üres string hossza 0.


string.lower (s)

A használt kódlapnak megfelelően kisbetűssé alakítva adja vissza a stringet.


string.rep (s, n)

Az s-et n-szer összefűzve adódó stringgel tér vissza.


string.sub (s, i [, j])

Az s i-től j-ig tartó szeletét adja vissza. Mindkét index lehet negatív. Ha j nincs megadva, értéke -1 (vagyis a string utolsó karakterének indexe).


string.upper (s)

A használt kódlapnak megfelelően nagybetűssé alakítva adja vissza a stringet.


string.format (formatstring, e1, e2, ...)

Ez a C nyelv printf-jéhez hasonlóan működő függvény visszaad egy olyan stringet, ami a formatstringben lecseréli a megfelelő opciókat a megadott paraméterek megfelelően formázott alakjára. Az egyetlen eltérés, hogy a *, l, L, n, p és h opciók nem használhatók, de újként megjelenik a q, ami egy stringet alakít biztonságosan visszaolvasható formára:

string.format('%q', 'a string with "quotes" and \n new line')

Az eredmény:

"a string with \"quotes\" and \ new line"

A c, d, E, e, f, g, G, i, o, u, X és x opciók paraméterként egy számot várnak, az q és s pedig egy stringet. A %s-sel formázott stringek nem tartalmazhatnak 0 kódú karaktereket.


string.gfind (s, pat)

Egy bejárófüggvényt ad vissza, ami minden hívásakor a pat következő s-beli illeszkedését adja vissza. Például a következő ciklus a string szavait egyenként, külön sorban sorolja fel:

s = "Aki javítani akar az emberiség sorsán, \ annak vállalnia kell némi kockázatot." for w in string.gfind(s, "%a+") do print(w) end

Az alábbi példa egy stringben felsorolt "kulcs=érték" párokból táblát készít:

t = {} s = "from=world, to=Lua" for k, v in string.gfind(s, "(%w+)=(%w+)") do t[k] = v end



string.gsub (s, pat, repl [, n])

Az s egy olyan másolatát adja vissza, amelyben a pat minden előfordulása a repl-re van cserélve (ha n-t megadjuk, akkor legfeljebb n cserét hajt végre). Második visszatérési értéke a stringben történt cserék száma.

Ha a repl string, akkor ez határozza meg, mire cserélődjön az előfordulás. Ha van benne %n alakú részstring (n = 1..9), akkor az az n-edik lefogott részstring értékét jelenti (lásd később).

Ha a repl függvény, akkor meg fog hívódni minden csere alkalmával, és sorra megkapja a lefogott részstringeket paraméterként. Ha a minta nem tartalmaz lefogásokat, az egyedüli paraméter az egész találat lesz. Az előfordulás az ezen függvény által visszaadott értékre cserélődik, vagy ha ez nem string, akkor az üres stringre.

Néhány példa:

x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" x = string.gsub("hello world", "(%w+)", "%1 %1", 1) --> x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from"

A mintában az alábbi karakterosztályok szerepelhetnek:

Továbbá a kisbetűvel jelölt osztálynevek nagybetűs alakja azok komplementerére illeszkedik.

Ezek az osztályok önmagukban egy előfordulásra illeszkednek. A karakterosztály nevét követő *, + és ? karakterek rendre nem negatív, pozitív illetve 0 és 1 közötti előfordulást jelentenek. A - karakter a *-hoz hasonló, de a legrövidebb részstringre illeszkedik. A minta elején álló ^ és minta végén álló $ karakterek a string elejére illetve végére illeszkednek, más helyen viszont nincs különleges jelentésük.

A mintákban lehetnek alminták (lefogás). Mikor a minta illeszkedik, az illeszkedés jelölt része elraktározódik (lefogódik). A számozásuk a kezdő zárójelüknek megfelelően történik. Például a "(a*(.)%w(%s*))" mintának a "a*(.)%w(%s*)"-ra illeszkedő része lesz az első lefogott részstring. A .-ra illeszkedő karakter a második, és így tovább.

Speciális esetként az üres lefogás az aktuális stringpozíciót jelenti (és értéke egy szám). Például ha a "()aa()" mintát keressük a "flaaap" stringben, a két lefogás értéke 3 és 5.

A lefogott részekre később hivatkozhatunk, lásd a gsub függvény leírásában.

A bitlib Library

Ez a könyvtár bitenkénti műveletek elvégzésére szolgáló függvényeket tartalmaz. Minden függvény a bit32 táblában található.

A függvények alapértelmezésben numerikus argumentumokat fogadnak a (-251,+251) intervallumból. Az argumentumok normalizálásra kerülnek, modulo 232 után egészre kerekítéssel. (A kerekítés iránya nem specifikált.)
Így mind a normalizált argumentumok, mind a visszaadott eredmények a [0,232 - 1] intervallumba esnek.
Vegyük észre, hogy a bit32.bnot(0) értéke 0xFFFFFFFF lesz, ami különbözik a -1-től.


bit32.arshift (x, disp)

Visszaadja az x számot disp bittel jobbra eltolva. disp bármilyen egész szám lehet, negatív érték esetén balra tolja el a biteket.
Ez a függvény az ún. aritmetikai eltolást valósítja meg: a bal oldali belépő bitek az eddigi legnagyobb helyiértékű bitek másolatai lesznek, a jobb oldali belépő bitek (negatív eltolás esetén) pedig minden esetben nullák lesznek.
Ez azt jelenti, hogy ha disp abszolútértéke nagyobb, mint 31, akkor az eredmény biztosan 0 vagy 0xFFFFFFFF lesz, mivel minden eredeti bit eltűnik x-ből.


bit32.band (i1, i2, ...)

Bitenkénti ÉS műveletet végez az operandusain és visszaadja az eredményt.


bit32.bnot (x)

Bitenkénti negációt végez x-en. Bármely x-re igaz az alábbi összefüggés: assert(bit32.bnot(x) == (-1 - x) % 2^32)


bit32.bor (i1, i2, ...)

Bitenkénti VAGY műveletet végez az operandusain és visszaadja az eredményt.


bit32.btest (i1, i2, ...)

Logikai igaz értéket ad vissza, ha az operandusainak logikai ÉS eredménye nemnulla. (Minden más esetben logikai hamis értéket ad vissza.)


bit32.bxor (i1, i2, ...)

Bitenkénti kizáró VAGY műveletet végez az operandusain és visszaadja az eredményt.


bit32.extract (n, field [, width])

Visszaadja azt az előjel nélküli számot, amit n-ből képezhetünk, a field helyiértéktől a field + width - 1 helyiértékig kiemelve a biteket. A bitek számozása 0-tól (legkisebb helyiértékű) 31-ig (legnagyobb helyiértékű) történik. Minden hivatkozott bitnek ebbe a helyiérték-intervallumba kell beleesnie.
A width alapértelmezett értéke 1.


bit32.replace (n, v, field [, width])

A függvény kicseréli n másolatában a field és a field + width - 1 helyiértékek közötti biteket v értékével, majd visszaadja a kapott számot. A bitek helyiérték-intervallumáról bővebb információk a bit32.extract függvény leírásában olvashatók.


bit32.lrotate (x, disp)

Visszaadja az x-et disp bittel balra elforgatva. A disp értéke bármilyen egész szám lehet. Bármely elforgatásra igaz az alábbi összefüggés: assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))
A negatív disp értékek jobbra forgatnak.


bit32.lshift (x, disp)

Visszaadja az x-et disp bittel balra eltolva. A disp értéke bármilyen egész szám lehet. A negatív disp értékek jobbra tolnak el. Bármelyik irányba tolunk el, az oldalt belépő bitek értéke 0 lesz.
Ez azt jelenti, hogy ha disp abszolútértéke nagyobb, mint 31, akkor az eredmény biztosan 0 lesz.
Pozitív disp értékekre fennáll az alábbi összefüggés: assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)


bit32.rrotate (x, disp)

Visszaadja az x-et disp bittel jobbra elforgatva. A disp értéke bármilyen egész szám lehet. Bármely elforgatásra igaz az alábbi összefüggés: assert(bit32.rrotate(x, disp) == bit32.rrotate(x, disp % 32))
A negatív disp értékek balra forgatnak.


bit32.rshift (x, disp)

Visszaadja az x-et disp bittel jobbra eltolva. A disp értéke bármilyen egész szám lehet. A negatív disp értékek balra tolnak el. Bármelyik irányba tolunk el, az oldalt belépő bitek értéke 0 lesz.
Ez azt jelenti, hogy ha disp abszolútértéke nagyobb, mint 31, akkor az eredmény biztosan 0 lesz.
Pozitív disp értékekre fennáll az alábbi összefüggés: assert(bit32.rshift(b, disp) == math.floor(b % 2^32 / 2^disp))
Ez a függvény az ún. logikai eltolást valósítja meg.

Be- és kimenet kezelése

A Lua nyelvben a fájlok elérésére kétféle megoldás létezik: ezek az implicit és explicit fájlleírók használata.

A két mód között az a különbség, hogy míg az implicit fájlleírókat az io osztálybeli függvények segítségével kezelhetjük, addig az explicit fájlleírót az io.open függvénytől megkapva azt lényegében objektumszerűen használhatjuk, a fájlműveleteket a leíró metódusain keresztül érhetjük el.

Ugyancsak az io tábla tartalmazza az előre definiált io.stdin, io.stdout és io.stderr leírókat.

Ahol nem jelezzük, a függvények nilt adnak vissza, sikertelen művelet esetén, és niltől eltérő értéket, ha a művelet sikerrel zárult.


io.close ([file])

Egyenértékű a file:close metódushívással. Paraméter nélkül az alapértelmezett fájlt zárja le.


io.flush ()

Egyenértékű az alapértelmezett fájlon végzett file:flush hívással.


io.input ([file])

String paraméterrel hívva megnyitja a megadott fájlt megnyitja szöveges módban, és beállítja alapértelmezett input fájlnak.


io.lines ([filename])

Megnyitja a megadott fájlt olvasásra, és visszaad egy iterátorfüggvényt, amely minden hívásakor egy újabb sort ad a fájlból. Így a

for line in io.lines(filename) do ... end

konstrukcióval végigolvashatjuk a fájl sorait. Ha vége a fájlnak, az iterátorfüggvény nil-lel tér vissza (így áll le a fenti ciklus is), és a fájl lezáródik.

Az io.lines() egyenértékű az io.input():lines() hívással, tehát az alapértelmezett input fájlon dolgozik.


io.open (filename [, mode])

Megnyit egy fájlt, a megadott elérési móddal. Fájl handle-t ad vissza, vagy (hiba esetén) nilt.

A mode string lehetséges értékei:

A mode string végén állhat egy b betű, amely egyes rendszereken a bináris módhoz szükséges. Az itt megadott string egyébként egy az egyben átadódik az fopen standard C függvénynek.


io.output ([file])

Hasonlóan működik, mint az io.input, de az alapértelmezett kimeneti fájlra vonatkozik.


io.read (format1, ...)

Egyenértékű az io.input():read paranccsal.


io.tmpfile ()

Ideiglenes fájlt nyit update módban, és visszaadja a file handle-jét. A program lefutása után a fájl automatikusan törlődik.


io.type (obj)

Ellenőrzi, hogy a paraméterként kapott obj file handle-e. Ha igen, visszatérési értéke a "file" string megnyitott, és a "closed file" string már lezárt file handle esetén, egyébként nil.


io.write (value1, ...)

Egyenértékű az io.output():write paranccsal.


file:close ()

Lezárja a file fájlt.


file:flush ()

Minden a file-ban történt módosítás kiírása.


file:lines ()

Visszaad egy bejárófüggvényt, amely minden hívásakor a fájl éppen következő sorával tér vissza. Így az alábbi szerkezet segítségével végigolvasható a fájl.

for line in file:lines() do ... end

Továbbá

file:lines

annyiban különbözik az io.lines-tól, hogy már megnyitott fájllal dolgozik, és azt a ciklus végén sem zárja le.


file:read (format1, ...)

A megadott formátumoknak megfelelően olvas a fájlból. A megfelelő típusú eredményekkel tér vissza, vagy nillel, ha a művelet sikertelen volt (beleértve, hogy nem felelt meg az adat a megadott formátumnak). Paraméterek nélkül meghívva alapértelmezésként egész sort olvas. A megengedett formátumazonosítók:
file:seek ([whence] [, offset])

Beállítja és lekérdezi a fájlmutató pozícióját. A megadott értéket a fájl elejétől számítja, értéke az offset plusz a szövegesen megadott alappozíció:

Ha a művelet sikeres volt, visszaadja az új pozíciót, a fájl elejétől, bájtban számítva. Ha hiba történt, nilt ad, és egy szöveges hibaleírást.

Az alapértelmezett értékek rendre "cur" és 0. Így paraméter nélkül hívva a file:seek-et mindössze az aktuális pozíciót kérdezi le, míg a file:seek("set") a fájl elejére lép (és nullát ad), továbbá file:seek("end") a fájl végére lép, és visszaadja a fájl méretét.


file:write (value1, ...)

Minden argumentumot kiír a file handle-re. A paraméterek számok vagy stringek kell legyenek, egyéb értékeket konvertálni kell a tostring vagy string.format eljárással.

Matematikai könyvtár

Ez gyakorlatilag egy felület a C-beli math könyvtárhoz. Minden függvény a math táblából érhető el, többnyire az eredetivel megegyező néven. Emellett ez tartalmazza a hatványozást végző bináris ^ operátort megvalósító globális __pow függvényt. A könyvtár által biztosított függvények:

math.abs math.acos math.asin math.atan math.atan2 math.ceil math.cos math.deg math.exp math.floor math.log math.log10 math.max math.min math.mod math.pow math.rad math.sin math.sqrt math.tan math.frexp math.ldexp math.random math.randomseed

és a math.pi változó. Minden trigonometrikus függvény radiánban dolgozik (a régi Lua verziók fokban számoltak!). A két mértékegység között a math.deg és math.rad függvényekkel számíthatunk át.

A math.min és math.max függvények a legalább 1 paraméterük közül a legkisebbet illetve a legnagyobbat adják vissza.

A math.random és math.randomseed függvények az ANSI C által definiált egyszerű véletlenszám-generátorhoz biztosítanak felületet. Paraméter nélkül hívva a math.random a [0,1) intervallumból ad vissza egy álvéletlenszámot. Egy n paraméterrel az [1,n], két argumentummal pedig az első és a második paraméter közötti intervallum egy elemét adja. A math.randomseed függvény az álvéletlenszám-generálás "magját" adja meg. Azonos magból indítva a generátort azonos "véletlen" számsorozatot kapunk.

Debug Interfész

Lua-nak nincs beépített debugger eszköze. Helyette, egy különleges interfészt kínál függvények és hook-ok segítségével. Ez az interfész lehetővé teszi a különböző típusú debugger-ek, profile-erek és egyék eszközök megalkotását, amelyeknek az interpreter belső információira van szükségük.

lua_Debug

typedef struct lua_Debug { int event; const char *name; /* (n) */ const char *namewhat; /* (n) */ const char *what; /* (S) */ const char *source; /* (S) */ int currentline; /* (l) */ int linedefined; /* (S) */ int lastlinedefined; /* (S) */ unsigned char nups; /* (u) number of upvalues */ unsigned char nparams; /* (u) number of parameters */ char isvararg; /* (u) */ char istailcall; /* (t) */ char short_src[LUA_IDSIZE]; /* (S) */ /* private part */ other fields } lua_Debug;

Egy struktúra, amely egy függvény vagy egy aktivációs rekord különböző információ darabjainak a tárolására használatos. lua_getstack csak a privát részét tölti ki ennek a struktúrának. A lua_Debug többi részének kitöltéséhez a lua_getinfo-t kell meghívni (jelentésük ld. lentebb).

lua_Debug tagjainak a jelentése:

lua_gethook

lua_Hook lua_gethook(lua_State *L);

Visszaadja az aktuális hook függvényt.

lua_gethookcount

int lua_gethookcount(lua_State *L);

Visszaadja az aktuális hook számot.

lua_gethookmask

int lua_gethookmask(lua_State *L);

Visszaadja az aktuális hook maszkot.

lua_getinfo

int lua_getinfo(lua_State *L, const char *what, lua_Debug *ar);

Egy adott függvényről vagy függvényhívásról ad információt. Ahhoz, hogy egy függvény hívásról szerezzünk információt, az ar paraméternek egy valós aktivációs rekordnak kell lennie, amely egy korábbi hívás által lett kitöltve a lua_getstack-nek vagy egy hook-nak lett argumentumként megadva. Ahhoz, hogy egy olyan függvényről szerezzünk információt, a veremre kell rátolni és what string-et '>'-el kell kezdeni. (Ebben az esetben a lua_getinfo kiszedi a verem tetején lévő függvényt.) Például, ahhoz, hogy megtudjuk melyik sorban lett definiálva egy f függvény, a következő kódot írhatjuk:


lua_Debug ar; lua_getglobal(L, "f"); /* get global 'f' */ lua_getinfo(L, ">S", &ar); printf("%d\n", ar.linedefined);

Minden karakter a what string-ben választ néhány tagot az ar struktúrából, hogy kitöltésre kerüljön vagy egy értéket, hogy beszúrásra kerüljön a verembe: 'n': a name és namewhat tagokat tölti ki; 's': a source, short_src, linedefined, lastlinedefined, és what tagokat tölti ki; 'l': a currentline tagot tölti ki; 't': az istailcall tagot tölti ki; 'u': a nups, nparams és isvararg tagokat tölti ki; 'f': beszúrja a verembe azt a függvényt ami a megadott szinten fut; 'L': beszúr a verembe egy táblát, amelynek az indexei a sorok számai, amelyek érvényesek a függvénynél. (Egy érvényes sor egy sor és a hozzá tartozó kód, amely egy sor, ahova a break point-ot tehetjük. Nem valid sorok az üres sorok vagy a kommentek.)

Ez a függvény 0-val tér vissza hiba esetén (például hibás opció esetén a what-ban).

lua_getlocal

const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);

Információt ad vissza egy adott aktivációs rekord vagy függvény lokális változójáról. Az első esetben az ar paraméternek egy valid aktivációs rekordnak kell lennie amely egy korábbi hívás által lett kitöltve a lua_getstack miatt vagy egy hook-nak lett átadva argumentumként. Az n index választja ki, hogy melyik lokális változó legyen vizsgálva; változó indexekről és nevekről több információ itt található: http://www.lua.org/manual/5.2/manual.html#pdf-debug.getlocal A lua_getlocal beteszi a verembe a változó értékét és visszaadja a nevét. A második esetben, ar-nek NULL-nak kell lennie és a vizsgált függvénynek a verem tetején kell lennie. Ebben az esetben csak a Lua függvények paraméterei láthatóak (mivel nincs információ arról, hogy mely változók aktívak) és egy érték sincs a verembe szúrva. NULL-t ad vissza (és nem szúr be semmit) ha az index nagyobb mint a lokális változók száma.

lua_getstack

int lua_getstack (lua_State *L, int level, lua_Debug *ar);

Információt ad vissza az interpreter futási idejű verméről.

Ez a függvény a lua_Debug struktúra részeit tölti ki egy adott szinten végrehajtódó függvény aktivációs rekordjának azonosításával. 0-ás szint a jelenleg futó függvény, míg n+1-edik szint az a függvény amely az n-edig szintet hívta (kivéve a farok hívásokat, amelyek nem a vermen számolandók). Amikor nincs hiba, lua_getstack 1-et ad vissza; ha nagyobb szinttel lett hívva mint a verem mélysége akkor 0-át ad vissza.

lua_getupvalue

const char *lua_getupvalue (lua_State *L, int funcindex, int n);

Egy lezárás upvalue-járól ad vissza információt. (A Lua függvények esetében, az upvalue-k az external lokális változók amiket a függvény használ és amik következésképpen a lezártjában vannak.) lua_getupvalue visszaadja az n-edik upvalue indexét, beszúrja az upvalue értékét a verembe és visszaadja a nevét. funcindex a veremben lévő lezártra mutat.(Az upvalue-knak nincs adott sorrendjük, mert az egész függvényen át aktívak. Így tetszőleges sorrendben vannak számozva.) NULL-lal tér vissza (és nem szúr be semmit) ha az index nagyott mint az upvalue-k száma. C függvények esetében, ez a függvény az "" üres string-et használja névként az összes upvalue esetében.

lua_Hook

typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);

Típus a hook függvények hibakereséséhez. Minden alkalommal amikor egy hook meghívódik, az ar argumentumának az event tagja beállítódik arra az event-re amely a hook-ot triggerelte. Lua a következő konstansok valamelyikével azonosítja az event-eket: LUA_HOOKCALL, LUA_HOOKRET, LUA_HOOKTAILCALL, LUA_HOOKLINE, és LUA_HOOKCOUNT. Továbbá a sor event-ek esetén a currentline tag is beállítódik. Bármely más ar-ben lévő tag értékének megszerzéséhez a hook-nak lua_getinfo parancsot kell hívnia. Hívás eseményeknél az event lehet LUA_HOOKCALL, a normál érték, vagy LUA_HOOKTAILCALL egy farok hívás esetén; ebben az esetben nem lesz megfelelő visszatérési esemény. Amíg a Lua egy hook-ot futtat addig megakadályoz minden további hívást a hook-októl. Ezáltal, ha egy hook visszahív Lua-ban, hogy végrehajtson egy függvényt vagy egy blokkot, akkor ez minden hívás hook-olása nélkül fog végrehajtódni. A hook függvényeknek nem lehetnek folytatásaik, azaz, nem hívhatnak lua_yieldk, lua_pcallk vagy lua_callk függvényeket egy nem null k-val. (linkek a függvények leírásáról: http://www.lua.org/manual/5.2/manual.html#lua_yieldk, http://www.lua.org/manual/5.2/manual.html#lua_pcallk, http://www.lua.org/manual/5.2/manual.html#lua_callk)

lua_sethook

int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);

Beállítja a hibakereső hook függvényt. Az f argumentum a hook függvény. mask jelöli, hogy melyik eseményeken lesz a hook meghívva: bitenként vagyolt értéke a LUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE, és LUA_MASKCOUNT konstansok valamelyikének. A count argumentumnak csak akkor van jelentősége ha a mask tartalmazza a LUA_MASKCOUNT maszkot. Minden eseményre, amelyre a hook meg van hívva a következőképpen van magyarázva: A hívás hook: akkor hívódik amikor az interpreter meghív egy függvényt. Akkor hívódik a hook amikor Lua belép az új függvénybe, mielőtt a függvény megkapja az argumentumait. A visszatérési hook: akkor hívódik amikor az interpreter visszatér egy függvényből. Akkor hívódik a hook mielőtt Lua kilép a függvényből. Nincs hagyományos módja a függvény által visszaadott értékek hozzáféréséhez. A sor hook: akkor hívódik amikor az interpreter éppen egy új sor kódját készül végrehajtani, vagy amikor visszaugrik a kódhoz (ugyanahhoz a sorhoz). (Ez az esemény csak addig történik amíg a Lua végrehajt egy függvényt.) A számolás hook: akkor hívódik amikor az interpreter végrehajtja az összes count parancsot. (Ez az esemény csak addig történik amíg a Lua végrehajt egy függvényt.) A hook-ot a mask zero-ra állításával lehet kikapcsolni.

lua_setlocal

const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);

Beállítja egy megadott aktivációs rekord lokális változójának az értékét. Az ar és n paraméterek ugyanazok mint lua_getlocal-ban. lua_setlocal beállítja a verem tetején lévő értéket a változóra és visszaadja a nevét. Valamint kiszedi a verem tetején lévő értéket. NULL-al tér vissza (és nem szed ki semmit) amikor az index nagyobb mint az aktív lokális változók száma.

lua_setupvalue

const char *lua_setupvalue (lua_State *L, int funcindex, int n);

Beállítja egy lezárt upvalue-jának az értékét. Beállítja a verem tetejét az upvalue értékére és visszaadja a nevét. Továbbá ki is szedi az értéket a veremből. funcindex és n paraméterek ugyanazok mint a lua_getupvalue esetén. NULL-al tér vissza (és nem szed ki semmit) amikor az index nagyobb mint az upvalue-k száma.

lua_upvalueid

void *lua_upvalueid (lua_State *L, int funcindex, int n);

Visszadja a funcindex indexen lévő lezárt n-edik számú upvalue-jának egyedi azonosítóját. A funcindex és n paraméterek ugyanazok mint a lua_getupvalue esetén. (de n nem lehet nagyobb mint az upvalue-k száma). Ezek az egyedi azonosítók lehetővé teszik egy program számára, hogy megállapítsa, hogy a különböző lezártak megosztanak e upvalue-kat. Lua lezártak amelyek megosztanak egy upvalue-t, azonos id-t adnak vissza az upvalue indexek esetén.

lua_upvaluejoin

void lua_upvaluejoin (lua_State *L, int funcindex1, int n1, int funcindex2, int n2);

A funcindex1-en lévő Lua lezárt n1 indexű upvalue-ját referálja a funcindex2-őn lévő Lua lezárt n2 indexű upvalue-jához.

A Debug Library

Ezt a könyvtárt a Lua programok debuggolására hozták létre. Az itt található függvények kizárólagosan debuggolásra és az ilyesfajta műveletekre (profiling) jöttek létre. Tartózkodjunk minden másfajta alkalmazástól, nagyon lassúak lehetnek.

Minden a könyvtárhoz tartozó függvényt a debug tábla tartalmaz. Minden szálakhoz kapcsolódó függvénynek van egy első paramétere, ami a szálat jelképezi. Az alapértelmezett mindig az aktuális thread.

debug.debug ()

Létrehoz egy interaktív kapcsolatot a felhasználóval. Egyszerű debug parancsokkal működik. A felhasználó nyomon követheti a globális és lokális változókat, megváltoztathatja az értéküket.


debug.getfenv (o)

Visszatérési értéke az o objektum környezete.


debug.gethook ([thread])

Visszaadja az aktuális "hook" beállításokat.


debug.getinfo ([thread,] function [, what])

Visszaad egy információkkal teli táblát a function-re vonatkozóan. Ezt a függvényt meg lehet adni direkt módon, vagy adhatunk helyette egy számot. és így tovább...

A what paraméterrel mondhatjuk meg, hogy mely információkra van szükségünk. Alapértelmezésben az összes információ bekerül a táblába. Például:

debug.getinfo(1,"n").name

Visszaad egy táblát a függvény nevével, ha talál ilyet.

debug.getinfo(print)

Ez pedig visszaadja az összes információt a print függvényről.


debug.getmetatable (object)

Visszaadja az object paraméter metatáblájával, ha nincs neki, akkor nillel


debug.getregistry ()

Visszaadja a regiszter táblát.


debug.setmetatable (object, table)

Beállítja az object metatábláját a table paraméterben adott táblára, ami lehet nil is.

Operating System Library

Az Operating System könyvtár azon könyvtári funkciókat, melyek fájl manipulációra, az aktuális dátumot és időt lekérdező függvényeket, és minden egyéb operációs rendszerhez kapcsolódó műveletet tartalmazza. A műveleteket az os táblázat tartalmazza. Ez a könyvtár felelős a LUA hordozhatóságáért is. Mivel a Lua ANSI C-ben íródott, a rendszer csak azon funkciókkal rendelkezik amenyeket az ANSI szabvány megkövetel. Sok OS létesítmény, mint például a könyvtár manipulációk, vagy socketek nem része az alap Operating System könyvtárnak, hanem más könyvtárakban vannak megvalósítva akkor is, ha logikailag ebben a könyvtárban lenne helyük. Ilyen a posix könyvtár is, mely támogatja a POSIX.1 standardjait a LUA - ban,továbbá megemlíthetjük még a luasocket könyvtárat, mely a hálózati kommunikációért felelős. Fájl manipuláció téren, a könyvtárban implementálva vannak olyan függvények, mint a os.rename, amellyel átnevezhetünk fileket, vagy mint az os.remove.

Két függvény van implementálva, amivel lekérdezhető az összes dátummal, idővel kapcsolatos információ. Ezek:


os.time([table])

Az os.time függvény paraméter nélküli meghívásakor a függvény visszatérési értéke egy szám ami az aktuális időt adja vissza másodpercekben. Amikor paraméteresen hívjuk meg, akkor megadja másodpercekben az álltalunk paraméterben megadott dátumot.
A paraméterek lehetnek:
A listában szereplő első 3 paraméter kötelező, ha paraméteresen hívjuk meg a függvényt, a többi opcionális. Az hour paraméter érték alapértelmezetten 12, a min 00, és a sec 00.
Linux rendszerben kipróbált példák:
os.time{year=1970, month=1, day=1, hour=0} = 0 os.time{year=1970, month=1, day=1, hour=0, sec=1} = 1 os.time{year=1970, month=1, day=1} = 43200

os.date([format [, time]])

Az os.date függvény a nevének ellenére az os.time függvény ellentetje, azaz a függvény egy számból dátumot és időt állít elő. Két paraméterrel lehet meghívni. Az első paraméterben adjuk meg a dátum formátumát, hogy milyen értéket szeretnénk kapni. A második egy szám, ami lényegében a másodpercekben megadott idő. Ha táblázatban szeretnénk megkapni az eredményt, akkor "*t" az első paraméter :
os.date("*t", 906000434) = {year = 1998, month = 9, day = 16, yday = 259, wday = 4, hour = 23, min = 47, sec = 24, isdst = false}

Abban az esetben ha nem táblázatban szeretnénk megkapni az eredményünket, hanem specifikusan egy adott értékre vagyunk kiváncsiak, akkor az első paraméter ’%’ + karakter kell, hogy legyen. Például:
os.date("Ma %A van %B" hónapban.) = Ma Saturday van June hónapban. os.date("%x", 906000490) = 09/16/1998

A következőkben láthatjuk, hogy az os.date függvény első paramétere mi lehet: Ha a függvényt paraméter nélkül hivjuk meg akkor az alapértelmezett paraméterértéket veszi ami a %c, és ennek megfelelően írja ki az eredményt. A %x, %X, és %c paraméterrel való meghívás során figyelembe veszi a rendszer beállításait és ennek megfelelő alakja lesz a visszatérési értéknek. Ezzel vigyázni kell, ezért ajánlott saját sztring alakot megadni amit, például igy tehetünk meg : "%m/%d/%Y".

os.clock()

Van még egy függvény ami nem más mint az os.clock, ami megadja a CPU idejét, azaz azt az időt, ami a végrehajtáshoz szükséges. Nézzünk egy példát a használatára!
local x = os.clock() local s = 0 for j=1,500000 do k = k + j end string.format("Eltelt idő = %.2f\n", os.clock() - x)

os.exit([code])

A C-beli exit függvény meghivása.

os.tmpname()

Generál egy tetszőleges file nevet, amit temporális file névként is használhatunk. Vigyázni kell vele, mert ez nem hoz létre semmilyen file-t, csak nevet generál.

os.getenv(varname)

A környezet változóinak értékét adja vissza, ha van olyan, ha nincs akkor nil értékkel tér vissza.
pl. os.getenv("HOME")= /home/lua os.getenv("USERNAME")= Ferko

os.difftime(t2,t1)

Két időpont közötti eltelt időt adja meg.

os.execute([command])

Parancssor megvalósítása a LUA-ban (ugyanaz mint C-ben a rendszerhívások). Például az os.execute("mkdir " .. dirname) paranccsal mappa létrehozása lehetséges