Ohjelmakirjastot
Yleistä
Yleistä
Sovellusohjelmilla on käytössään kaikki Lua-kielen standardi-kirjastot. Enimmäkseen ne ovat hyvin käyttökelpoisia, mutta suoritettaessa käyttöjärjestelmän shell komentoja esim. os.execute() kutsulla, tai massamuistia käytettäessä täytyy pitää mielessä, että käyttöjärjestelmä ei takaa komennolle laisinkaan suoritusaikaa, sopivassa tilanteessa jossa kaksi prosessia koettaa kirjoittaa samaaan tiedostoon, saadaan aikaa kilpailutilanne (race condition), joka aiheuttaa kyseisten prosessien totaalisen jumittumisen. Lisäksi tiedostoon kirjoittaminen ja lukeminen ovat usein prosesseja joiden nopeus voi vaihdella järjestelmän kuormitustilanteen ja muistipuskureiden täyttöasteen mukana jopa kymmenkertaisesti suorituskertojen välillä.
Lua ja erityisesti luaJIT mahdollistavat ainakin periaatteessa myös minkä vain käyttöjärjestelmästä löytyvän ominaisuuden tai jaetun kirjaston käyttämisen. Ne eivät kuitenkaan kuulu tämän dokumentin aihepiiriin.
Actiweb
SLC engineen on lisätty myös joitakin Plc ohjelmointia tukevia ohjelmakirjastoja, joita ei ole yleisesti jaossa. Nämä kirjastot on ladattu aina automaattisesti, eivätkä ne tarvitse require -kutsua.
SLC
sisältää SLC enginen tehtävien hallitsemiseen tarvittavia funktioita. Sovellusohjelmien tarvitsee käyttää näitä vain harvoin.
Tärkeä huomio!
Kutsut jotka vaikuttavat plc-prosessin suoritusparametreihin tai hakevat tietoa niistä eivät tavallisesti toimi laisinkaan mikäli niitä kutsutaan Luan coroutine säikeen sisältä, koska tällainen suoritussäie näyttää Slc-kirjaston kutsujen mielestä toiselta lua virtuaalikoneelta (prosessi toisen prosessin sisällä). Näin ollen Slc-kirjaston kutsu ei tiedä mihin plc-prosessiin kutsu kohdistuu.
Slc.enableWatchdog ()
Slc.disableWatchdog ()
Ei argumentteja
Koko järjestelmän watchdog ominaisuuden ottaminen käyttöön, tai asettaminen pois päältä. Huomaa, että monilla laitealustoilla ei ole mahdollista kytkeä watchdog ajastinta pois päältä sen käynnistämisen jälkeen. Kun watchdog ajastin on käynnistetty Slc.enableWatchdog() kutsulla, slc engine huolehtii automaattisesti ajastimen ajoittaisesta resetoinnista (kutsutaan usein vahtikoiran syöttämiseksi) niin kauan on käynnissä, eikä sovellusohjelmanm tarvitse välittää asiasta. Oikea tapa käyttää näitä funktiota on esimerkiksi kutsua toista niistä yhden kerran järjestelmän käynnistyksen yhteydessä.
Paluuarvot
true jos onnistui, nil jos kohdattiin virhe.
Esimerkki:
-- Set watchdog ON
Slc.enableWatchdog ()
Slc.setWatchdogDelay ( ms )
Slc.getWatchdogDelay ()
ms Taskin vahtikoira-ajastimen viive millisekunteina
Slc.error (strLevel, strMessage)
strLevel Virheen vakavuus: ”exception”, ”notify”, ”fault”, ”error”, ”critical”, ”fatal”
strMessage Virheen kuvausteksti
Ilmoittaa virhetilanteesta käyttäjälle, ja mikäli virhe on riittävän vakava, voi aiheuttaa myös PLC ohjelman siirtymisen virhe tilaan.
”error” taso aiheuttaa PLC ohjelman siirtymisen ”running” tilasta ”error” tilaan.
”critical” tai ”fatal” taso aiheuttaa PLC ohjelman suorituksen päättymisen, mikä yleensä aiheuttaa watchdog:n vuoksi koko laitteen uudelleen käynnistymisen.
Paluuarvot:
true mikäli onnistui, nil mikäli kohdattiin virhe (esimerkiksi virheellinen argumentti).
Esimerkki:
Slc.error(”error”, ”Houston, we had a problem”)
Slc.version ()
ei argumentteja
Lukee ja palauttaa järjestelmän ohjelmistoversion ja muita tietoja taulukkona. Taulukossa on kentät ”application” joka kertoo sovellusohjelman version (mm. monet plc kirjastot riippuvat tästä), ”kernel” joka kertoo käyttöjärjestelmän ytimen version ja ”plc” joka kertoo slc enginen binääritiedoston version.
Paluuarvot
taulukko jossa ohjelmistoversioiden tiedot.
Esimerkki:
print (”System kernel version: ” .. Slc.version().kernel)
Slc.createTask (strFile, strName, strMainCall, strSchMode, intDelay)
strFile lähdekooditiedoston koko polku
strName PLC tehtävän nimi
strMainCall tehtävän pääfunktion nimi
strSchMode Ajoitustila ”periocid” tai ”cyclic”
intDelay Ajoitusviive millisekunteina
Luo uuden PLC tehtävän annettujen parametrien perusteella. Tehtävä luodaan niin, että ensiksi tarkistetaan ovatko argumentit oikein, ja sen jälkeen käynnistetään uusi säie, ja viimeisessä vaiheessa ladataan ja käännetään annettu lähdekooditiedosto.
Paluuarvot:
true jos tehtävän luominen onnistuu, muuten nil.
Esimerkki:
Slc.createTask(”/opt/slc/prg/main.lua”, ”myTask”, ”main”, ”cyclic”, 500)
Slc.getSchedule ()
Slc.setSchedule (strMode)
strMode Haluttu ajoitustila, ”cyclic” tai ”periodic”
Funktioiden avulla voidaan lukea PLC ohjelman nykyinen ajoitustila, tai asettaa se halutuksi.
Slc.getSchedule palauttaa nykyisen tilan merkkijonona (”cyclic” tai ”periodic”).
Slc.setSchedule kutsulla se voidaan asettaa halutuksi,ja paluuarvo kertoo onnistuiko operaatio (true tai nil).
Esimerkki:
if Slc.getSchedule() ~= cyclic then
Slc.setSchedule (”cyclic”)
end
Slc.getTiming ()
Slc.setTiming (intDelay)
intDelay Haluttu ajoitusviive
Funktioilla saadaan luettua PLC ohjelman nykyinen ajoitusviive, tai asetettua se halutuksi.
Slc.getTiming lukee viiveen ja palauttaa sen millisekunteina.
Slc.setTiming taas asettaa ohjelman viiveeksi halutun millisekuntimäärän. Palauttaa onnistuessa true, muutoin nil.
Slc.getTaskInfo ()
Slc.setName (strName)
strName Haluttu uusi PLC tehtävän nimi
Funktiolla getTaskInfo saadaan luettua PLC ohjelman tietoja, ja kutsu palauttaa taulukon jossa on kentät: ”name”, ”sourcefile”, ”callcounter”, ”runtime”, ”maincall”.
Name kenttä sisältää tehtävän nimen, sourcefile taas lähdekooditiedoston polun.
Callcounter kenttä on kokonaisluku joka kasvaa yhdellä joka kerran kun tehtävän pääfunktiota kutsutaan, eli se kertoo PLC ohjelman suorituskerrat.
Runtime kertoo kuinka kauan PLC ohjelman suorittaminen kestää, yksikkönä nanosekunti (PLC ohjelmien sisäinen ajoitus tehdään nanosekunteina).
SetName -kutsulla on mahdollista vaihtaa PLC ohjelman nimeä. Kutsu palauttaa true jos onnistuu, muutoin nil.
Esimerkki:
local info = Slc.getTaskInfo()
print (”task. ”..info.name..” running time: ”..info.runtime)
Slc.echo (strTxt)
strTxt Tulostettava teksti
Tulostaa tekstiä tai ohjelman tilaan liittyvää tietoa joka voidaan näyttää esimerkiksi grafiikka sivulla (mm. taskList -komponentti).
Paluuarvot
true mikäli onnistuu, muuten nil.
Esimerkki:
Slc.echo(n..” error on this run cycle”)
Slc.runRemote (strHost, strCmd)
strHost kohde laitteen IP-osoite tai DNS nimi.
strCmd Kohde koneessa suoritettava lua koodi
Tämän funktion avulla voidaan suorittaa lua komentoja toisessa SLC laitteessa (tcp portti 30001) ja lukea suoritetun lua-koodin paluuarvo takaisin ohjelmaan.
Funktiota voidaan käyttää hyvin monipuolisesti esimerkiksi tiedonsiirtomenetelmänä.
Huomioi! Tämä protokolla ei sisällä laisinkaan tietosuojaominaisuuksia! Jos tätä tiedonsiirtoprotokollaa käytetään julkisessa verkossa, se tulee suojata esimerkiksi SSH tunnelin avulla.
Esimerkki:
-- Lukee ulkolämpötilan LJH vakista
local te00 = Slc.runRemote (”192.168.0.201”, ”return Data.get(’ioPoints/TE00.pv’)”)
-- käynnistä poistopuhallin IV konehuoneessa
if not Slc.runRemote (”192.168.0.205”, ”return Data.set(’ioPoints/PK01/PF01.pv’, 1)”) then
Slc.error (”fault”, ”Etäohjaus ei onnistu”)
end
System
Sisältää käyttöjärjestelmään ja laitteistoon liittyviä funktioita.
System.base64encode (strTxt)
System.base64decode (strTxt)
strTxt Tulostettava teksti
Koodaa ja dekoodaa tekstiä tai binääridataa base64 -muotoon. Kyseistä koodaustapaa käytetään usein binäärimuotoisen datan siirtämiseksi vain tekstimuotoa tukevan linjan ylitse – usein ascii 7-bit.
Paluuarvot
Palauttaa koodatun tai dekoodatun datan.
Esimerkki:
-- Lue binääri dataa tiedostosta ja koodaa se
local bin = file:read (”*a”)
local coded = System.base64encode(bin)
System.shell (strCmd)
strCmd Suoritettava komento
Suorittaa komennon järjestelmän shellissä (synkronisesti, eli kutsuva käyttöjärjestemän prosessi odottaa että komento on suoritettu kokonaan) ja palauttaa komennon stdout:iin tulostaman tekstin riveittäin taulukossa. Palautettu taulukko on numeraalisesti indeksoitu 1 eteenpäin, ja yksi tulosteen rivi vastaa yhtä taulukon riviä.
Palauttaa nil jos komentoa ei voitu suorittaa, ja tyhjän taulukon jos komento ei tulosta mitään std out:iin.
Komento palauttaa toisena paluuarvona suoritetun komennon paluuarvon, eli n.s. exit code:n.
Esimerkki:
-- hakemiston tiedostot
-- huom! että kaksi ensimmmäistä aina . Ja ..
-- ne pitää ohittaa
local dir, ec = System.shell (”ls /tmp/*”)
if #dir > 2 and ec == ”0” then
for i = 3, #dir do
print (dir[i])
end
end
System.log (prio, strCmd)
prio Loki merkinnän kiireellisyys. Kokonaisluku välillä 0 .. 7 jossa 0 vähiten kiireellinen (debug).
strCmd Tulostettava teksti
Kirjoittaa merkinnän järjestelmä lokiin.
Paluuarvot
true mikäli onnistuu, muuten nil.
Esimerkki:
Slc.log(0, ”This is my system log info”)
System.nanosleep (intDly)
intDly Viive nanosekunteina
Vastaa POSIX kutsua nanosleep(). Asettaa kutsuvan säikeen uneen (minimissään) annetuksi ajaksi.
Esimerkki:
-- Plc ohjelma odottaa 1 millisekunnin
Slc.nanosleep (1000000)
System.nanotimer ()
Ei argumentteja
Palauttaa järjestelmän tarkkuusajastimen nykyisen arvon. Ajastin on laskuri (uint64), joka alkaa juosta 0:sta kun käyttöjärjestelmä käynnistyy. Sen laskee nanosekuntteja, ja sen todellinen tarkkuus on usein noin 40 nanosekunnin luokkaa (ARM cortex A8).
Esimerkki:
print (”Current hires timer value: ”.. System.nanotimer () )
System.parseUrl (strUrl)
strUrl Url teksti
Parsii URL merkkijonon, ja palauttaa URL eri kentät talukossa.
Esimerkkinä:
URL: https://areena.yle.fi/tv/ohjelmat/sarjat?t=uusimmat
Parsittu taulukko:
URL_taulukko = {
protocol = ”https”,
user = ””,
pass = ””,
address=”areena.yle.fi”,
port=””,
fullpath=”/tv/ohjelmat/sarjat”,
path={”tv”, ”ohjelmat”, ”sarjat”},
paramstring=”t=uusimmat”,
params={t=”uusimmat”}
}
Toinen esimerkki:
URL:
http://name:secret@www.google.com:8080/this/is/path/file.xml?param1=1&meaning=42
Parsittu taulukko:
{
protocol = "http",
user = "name",
pass = "secret",
address = "www.google.com",
port = "8080",
fullpath = "/this/is/path/file.xml",
path = {"this", "is", "path", "file.xml" },
paramstring = "param1=1&meaning=42",
params = {
param1 = "1",
meaning = "42"
}
}
Virhetilanteessa funktio voi palauttaa arvon nil.
Esimerkki:
local parsed = System.parseUrl ( urlString )
if parsed.protocol == ”http” then
-- Handle http request
end
System.encodeUrl (strData)
System.decodeUrl (strData)
strData Tulostettava teksti
Kun käsitellään URL tekstejä, on itse lokaattorin lopussa annettavien parametrien arvot koodattava niin sanotulla prosentti koodauksella. Näillä funktioilla voidaan tehdä parametrien arvojen prosenttikoodaus, ja dekoodaus.
Paluuarvot
koodattu tai purettu teksti.
Esimerkki:
-- Palauttaa meik%C3%A4%0A
local encoded = System.encodeUrl (”meikä”)
System.serialize (data)
data Serialisoitava data (merkkijono, luku, taulukko)
Tekee lua objekteille niin sanotus sarjoituksen, eli serialisoinnin.
Täma muunnos tarkoittaa että objekti muutetaan takaisin lähdekoodi -muotoon. Tätä muunnosta tarvitaan esimerkiksi silloin kun lua taulukko halutaan siirtää tcp yhteyden ylitse toiseen laitteeseen, tai vain IPC-kanavan lävitse laitteen muistissa toiseen prosessiin, tai tallentaa tiedostoon.
Serialisoitu objekti on helppoa palauttaa takaisin ohjelmassa käsiteltäväksi, koska se voidaan ”ajaa” normaalissa lua tulkissa.
Vastaa suurinpiirtein javascriptin JSON.stringify() kutsua.
Tämä funktio on käyttökelpoinen paitsi tiedonsiirrossa ja tallentamisessa, myös ohjelmien debuggauksessa, koska miltei mikä tahansa objekti voidaan tulostaa tekstimuodossa vaikkapa konsoliin ohjelmoijan tarkasteltavaksi.
Paluuarvot
Annettu objekti tekstimuodossaan merkkijonona, tai nil mikäli kutsuttiin virheellisillä arvoilla.
System.importCSV (strCsv [, strDlm] )
strCsv Tab eroteltu data
strDlm Sarakeet erottava merkki, oletus on \t eli tabulaattori
Tämä funktio luo CSV muotoisesta – tai oletusarvoisesti TAB-erotellusta tekstistä – taulukon ja palauttaa sen.
Nimestään huolimatta oletus sarake-erottimelle on ’\t’.
Luotavan rivin nimen oletetaan löytyvän sarakkeesta, jonka nimi on ”dataname”, ”pointname”, ”rowname”, ”datapoint” tai ”keyname” – kaikki edellämainitut ovat synonyymejä.
Esimerkki:
csv = [[name description pv
data1 tunnit 7.0
data2 minuutit 15.0
data3 sekunnit 23.0
data4 paivat 1.0
]]
local d = System.importCSV (csv)
>> taulukon d sisältö:
d = {
data1 = {description = ”tunnit”, pv = 7},
data2 = {description = ”minuutit”, pv = 15},
data3 = {description = ”sekunnit”, pv = 23},
data4 = {description = ”paivat”, pv = 1}
}
System.archInfo ()
Funktio palauttaa taulukossa laitteiston käyttöjärjestelmän ja prosessoriarkkitehtuurin.
Palauttaa taulukon, jossa rivit
os Käyttöjärjestelmän nimi. Joitakin tavallisia arvoja ovat mm.
Ubuntu, Builtroot, Debian.
arch Prosessoriarkkitehtuuri. Tyypillisiä arvoja ovat
armv7l (beagle bone) ja x86_64
Esimerkki:
local d = System.archInfo (csv)
print (”Käyttöjärjestelmä: ”.. d.os)
System.getNetworkInterfaces ()
Funktio palauttaa taulukossa järjestelmän verkkosovittimet ja niiden asetukset.
System.pid ()
Funktio palauttaa kutsuvan prosessin (yleensä slc engine) process ID (eli pid) numeron. Tämä on se tekninen tunnus, jolla käyttöjärjestelmä tunnistaa prosessit, ja jonka avulla voi lähettää mm. signaaleita prosessien välillä.
System.sendSig (pid, signal)
pid (int) prosessin ID numero
signal (int) signaali joka lähetetään (kts. posix singals)
Funktion avulla voi lähettää signaalin käyttöjärjestelmäprosessien välillä. Palauttaa true onnistuessaan, ja nil mikäli kutsussa ilmeni virhe.
BitOps
Sisältää perus binäärioperaatioita, ja muistipuskureihin liittyviä funktioita. Jotkin näistä funktioista ovat päällekkäisiä luaJIT:n bit -kirjaston kanssa, eikä niiden välillä ole suurta toiminnallista eroa.
Huomaa, että monista operaatioista on olemassa eri versioista (esim. not16 ja not32) joiden erona on, että operaatioiden aikana lukuja käsitellään funktion nimessä mainitulla tarkkuudella – binääri-operaatioiden tapauksessa muunnos tehdään aina unsigned muotoon (ei etumerkkiä).
BitOps.not16 (v)
BitOps.not32 (v)
v Arvo jolle halutaan tehdä binäärinen NOT operaatio.
Suorittaa annetun luvun biteille loogisen NOT operaation, eli invertoi ne.
Esimerkki:
-- Tulos on 0xFF
local r = BitOps.not16 (0xFF00)
BitOps.and16 (v1, v2)
BitOps.and32 (v1, v2)
v1 Binäärisen JA -operaation syöteluku.
v2 Binäärisen JA -operaation syöteluku.
Suorittaa annettujen lukujen välillä AND operaation.
Esimerkki:
-- Tulos on 0xFF
local r = BitOps.and16 (0xFFFF, 0xFF)
BitOps.or16 (v1, v2)
BitOps.or32 (v1, v2)
v1 Binäärisen OR operaation syöte.
v2 Binäärisen OR operaation syöte.
Suorittaa annettujen lukujen välillä OR operaation.
Esimerkki:
-- Tulos on 0xFFFF
local r = BitOps.and16 (0xFF00, 0xFF)
BitOps.xor16 (v1, v2)
BitOps.xor32 (v1, v2)
v1 Binäärisen XOR operaation syöte.
v2 Binäärisen XOR operaation syöte.
Suorittaa annettujen lukujen välillä n.s. poissulkevan OR operaation (eng. exclusive or), jota usein merkitään XOR lyhenteellä.
Esimerkki:
-- Tulos on 0xFF
local r = BitOps.and16 (0xFFFF, 0xFF00)
BitOps.shr16 (v, n)
BitOps.shr32 (v, n)
BitOps.shl16 (v, n)
BitOps.shl32 (v, n)
v Siirto operaation kohdeluku.
n Siirrettävien bittien määrä.
Siirtää luvun v bittejä n kappaletta joko oikealle (shr) tai vasemmalle (shl). Vasemmalle siirto kasvattaa luvun arvoa, ja oikealle siirto pienentää sitä.
Esimerkki:
-- Siirtää bittejä puolikkaan tavun verran,
-- joka vastaa yhtä heksadesimaali numeroa
-- Tulos on 0xFF00
local r = BitOps.shl16 (0xFF0, 4)
BitOps.createBuffer (n)
n Luotavan puskurin koko tavuina.
Luo uuden raakadatapuskurin.
Esimerkki:
-- Luo puskurin jonka koko on 32 tavua.
local buf = BitOps.createBuffer (32)
BitOps.fillBuffer (b, v, i, n)
b Puskuri jolle operaatio tehdään (luotu createBuffer kutsulla)
v Arvo jota puskuriin kirjoitetaan (huom! Arvo muutetaan BYTE tyyppiseksi, lukualue 0x0 .. 0xFF)
i Indeksi josta täyttö aloitetaan (oltava >= 0)
n Kirjoitettavien tavujen määrä (puskurin indeksistä i lähtien).
Kutsu kirjoittaa BitOps.createBuffer -kutsulla luotuun muistipurkuriin tiettyä argumenttina annettua tavua, ja sitä voidaan käyttää esimerkiksi nollaamaan puskurin muistipaikat.
Huomaa että indeksoint seuraa lua käytäntöä, eli puskurin ensimmäinen tavu on indeksissä 1!
Esimerkki:
-- Luo puskurin ja nollaa sen kaikki tavut
local buf = BitOps.createBuffer (32)
BitOps.fillBuffer (buf, 0x0, 0, 32)
BitOps.deleteBuffer (b)
b Puskuri jolle operaatio tehdään (luotu createBuffer kutsulla)
Tuhoaa muistipuskurin ja vapauttaa sille varatun muistin.
Esimerkki:
-- Luo puskurin ja sitten tuhoaa sen
local buf = BitOps.createBuffer (2048)
if buf then
BitOps.deleteBuffer (buf)
end
BitOps.getBufferLen (b)
b Puskuri jonka koko halutaan tietää
Palauttaa argumenttina annetun muistipuskurin pituuden – eli sille varatun muistin määrän tavuina.
Esimerkki:
-- Luo puskurin ja näyttä sen koon
local buf = BitOps.createBuffer (2048)
if buf then
print (”Buffer is ” .. BitOps.getBufferLen(buf).. ” bytes long”)
end
BitOps.setBufferLen (b)
b Puskuri jonka pituus halutaan asettaa
Muuttaa jo luodun muistipuskuri kokoa. Operaatio tehdään varaamalla puskurille uusi muistialue ja kopioimalla vanha sisältö uuteen – jos uusi puskuri on pienempi kuin vanha, kopioidaan vain se osa joka uuteen puskuriin mahtuu.
Esimerkki:
-- Luo puskurin ja muutaa sen koon pienemmäksi
local buf = BitOps.createBuffer (2048)
BitOps.setBufferLen (buf, 32)
BitOps.getByte (b, i)
BitOps.setByte (b, i, v)
BitOps.getWord (b, i)
BitOps.setWord (b, i, v)
BitOps.getDWord (b, i)
BitOps.setDWord (b, i, v)
BitOps.getString (b, i)
BitOps.setString (b, i, v)
BitOps.getFloat32 (b, i)
BitOps.setFloat32 (b, i, v)
b Puskuri jolle operaatio tehdään
i Luettavan tai arvon alkukohdan indeksi (tavuja)
v Kirjoitettava arvo
Näillä funktioilla voidaan kirjoittaa ja lukea muistipuskurista yksittäisiä tavuja, sanoja, kaksoisanoja, merkkijonoja tai IEEE koodattuja liukulukuja.
Huomaa että indeksoint seuraa lua käytäntöä, eli puskurin ensimmäinen tavu on indeksissä 1!
Esimerkki:
-- Luo puskuri
local buf = BitOps.createBuffer (2048)
BitOps.setString(buf, 1, ”Handling buffer”)
local byte = BitOps.getByte(buf, 1) -- Lukee merkin ’H’ ascii koodin 0x48
BitOps.asBitArray (v, [n] )
v Luku joka halutaan muuttaa
n Vastauksen sisältämä TAVU määrä (ei pakollinen)
Muuttaa annetun luvun lua taulukoksi, joka sisältää riveillä annetun luvun bitit.
Argumentilla n voidaan määrätä montako tavua vastauksessa on (1 tavu vastaa 8 bittiä, eli 8 riviä).
Esimerkki:
-- Luo puskurin ja muutaa sen koon pienemmäksi
local arr = BitOps.asBitArray(0xF0, 1)
>> tulos:
arr = {1, 1, 1, 1, 0, 0, 0, 0}
BitOps.arrayAsDWord (t)
t Luvuksi muunnettava taulukko
Käänteinen operaatio BitOps.asBitArray () -kutsulle. Muuntaa annetun bitti taulukon takaisin luvuksi.
Esimerkki:
-- v saa arvon 0xF0
local v = BitOps.arrayAsDWord ({1, 1, 1, 1, 0, 0, 0, 0})
BitOps.fillArray (v, n, [i])
v Arvo jota taulukon soluihin kirjoitetaan
n Kuinka monta kertaa arvo kirjoitetaan taulukkoon
i Indeksi josta kirjoittaminen aloitetaan (ei pakollinen)
Luo uuden lua -taulukon ja täyttää sen annetulla luvulla.
Esimerkki:
-- luo taulukon jossa 512 riviä arvoina 1
local t = BitOps.fillArray( 1, 512 )
BitOps.convertTo (v, t)
v Arvo joka muunnetaan
t Muoto merkkijonona, johon luku halutaan muuttaa ”int8”, ”uint8”, ”int16”, ”uint16”,
”int32”, ”uint32”, ”int64”, ”uint64”, ”float32”.
Muuttaa luvun annettuun datatyyppiin. Tätä muunnosta tarvitaan melko harvoin, mutta joskus on välttämätöntä tulkita luku esimerkiksi uint16 tyypissä.
Esimerkki:
local v = 0xFFFF
local int16 = BitOps.convertTo (v, ”int16”) -- Tulos -32767
local uint16 = BitOps.convertTo (v, ”uint16”) -- Tulos 65535
local overFlow = BitOps.convertTo ( (v+1), ”uint16”) -- Tulo nolla
BitOps.binaryDWordAsFloat (dw)
BitOps.binaryFloatAsDWord (f)
dw Kaksoissana joka halutaan muuttaa float32 koodatuksi.
f Float32 luku josta halutaan saada raaka binääriesitys.
Näillä kutsuilla on mahdollista muuttaa esimerkiksi tiedostosta tai sarjaliikenneportista luettu binääriesitys takaisin liukuluvuksi, ja toisinpäin.
Esimerkki:
-- puskuriin luetussa datassa on liukuluku,
-- palautetaan se binääri esityksestä käytettävään muotoon
b = BitOps.getDWord (buf, 5)
f = BitOps.binaryDWordAsFloat (b)
XML
Sisältää XML datan käsittelyyn tarvittavia funktioita. Perustuu TinyXML2 -kirjastoon.
Xml.parseAsLuaDOM (strXml)
Xml.loadAsLuaDOM (strFile)
strXml Merkkijono joka sisältää XML dataa
strFile Tiedosto josta XML data ladataan
Parsii XML annetun datan, ja palauttaa sen lua taulukkona.
Tuloksena syntyvä lua taulukko seuraa seuraavaa DOM -mallia mukailevaa rakennetta:
-- Esimerkki XML data:
xmlData = [[
<kirjat>
<kirja muoto=”kovakantinen”>
<kirjailija>Pekka Meikäläinen</kirjailija>
<vuosi>1975</vuosi>
</kirja>
<kirja muoto=”pokkari”>
<kirjailija>Matti Meikäläinen</kirjailija>
<vuosi>1974</vuosi>
</kirja>
</kirjat> ]]
-- Funktiokutsu:
local d = Xml.parseAsLuaDOM (xmlString)
>> tulos
d = {
_name = ”kirjat”,
_attr = {},
_text = ””,
kirja = {
_name = ”kirja”,
_attr = {muoto=”pokkari”},
_text = ””,
kirjailija={
_name = ”kirjailija”,
_attr = {},
_text = ”Matti Meikäläinen”
},
vuosi={
_name = ”vuosi”,
_attr = {},
_text = ”1974”
}
[1] = {
_name = ”kirjailija”,
_attr = {},
_text = ”Matti Meikäläinen”
}
[2] = {
_name = ”vuosi”,
_attr = {},
_text = ”1974”
}
},
[1] = {
_name = ”kirja”,
_attr = {muoto=”kovakantinen”},
_text = ””,
kirjailija={
_name = ”kirjailija”,
_attr = {},
_text = ”Pekka Meikäläinen”
},
vuosi={
_name = ”vuosi”,
_attr = {},
_text = ”1975”
},
[1] = {
_name = ”kirjailija”,
_attr = {},
_text = ” Pekka Meikäläinen”
},
[2] = {
_name = ”vuosi”,
_attr = {},
_text = ”1975”
}
},
[2] = {
_name = ”kirja”,
_attr = {muoto=”pokkari”},
_text = ””,
kirjailija={
_name = ”kirjailija”,
_attr = {},
_text = ”Matti Meikäläinen”
},
vuosi={
_name = ”vuosi”,
_attr = {},
_text = ”1974”
},
[1] = {
_name = ”kirjailija”,
_attr = {},
_text = ”Matti Meikäläinen”
},
[2] = {
_name = ”vuosi”,
_attr = {},
_text = ”1974”
}
}
}
Yllä olevasta esimerkistä käy ilmi, että tuloksena yksinkertaisesta XML datasta on melko monimutkainen lua taulukko. Syitä siihen on monia; XML dokumentin perusyksikkö on n.s. node, eli solmu. XML dokumentti koostuu määritelmän mukaan yhdestä juuri elementistä – esimerkissä nimeltään kirjat – joka voi puumaisesti sisältää minkä tahansa määrän alisolmuja. Koska nämä solmut voivat olla nimeltään identtisiä, täytyy XML dokumenttia parsiessa säilyttää paitsi solmun nimi, myös niiden järjestys. Koska lua taulukoiden tapauskessa on usein näppärämpää viitata taulukon alkioihin nimellä kuin indeksillä, tässä tapauksessa molemmat.; Lapsi solmut lisätään lua-taulukkoon paitsi juoksevasti numeroiden, myös solmu nimellään, jolloin viimeinen lisätty solmu jää voimaan. Esimerkin tapauksessa ”kirjat.kirja” osoituksen takaa löytyy Matti Meikäläisen kirjoittama kirja.
Tässä mallissa säilytetään siis kaikki XML dokumenttiin sisältyvä tieto.
Xml.loadAsTable (strXml)
Xml.parseAsTable (strFile)
strXml Merkkijono joka sisältää XML dataa
strFile Tiedosto josta XML data ladataan
Lataa annetun XML datan ja palauttaa tuloksen yksinkertaisena taulukkona. Tuloksena syntyvä lua -taulukko on yksinkertaisempi kuin DOM mallia seuraava, mutta se ei esimerkiksi ymmärrä solmujen attribuutteja, tai saman nimisiä lapsisolmuja.
Esimerkki:
-- Esimerkki XML data:
xmlData = [[
<kirjat>
<kirja muoto=”kovakantinen”>
<kirjailija>Pekka Meikäläinen</kirjailija>
<vuosi>1975</vuosi>
</kirja>
<kirja muoto=”pokkari”>
<kirjailija>Matti Meikäläinen</kirjailija>
<vuosi>1974</vuosi>
</kirja>
</kirjat> ]]
-- Funktiokutsu:
local d = Xml.parseAsLuaDOM (xmlString)
>> tulos
d = {
kirjat={
kirja={
kirjailija=”Matti Meikäläinen”,
vuosi=”1974”
}
}
}
Xml.serialize (o, r)
o Lua objekti joka muutetaan XML muotoon.
r Dokumentin juurisolmun nimi
Muuttaa hyvin suoraviiveisesti lua-taulukon XML muotoon.
Huomaa, että lua-taulukon numeraaliset indeksit eivät käänny XML muotoon oikein. Funktio muuttaa ne <1>, <2>, .. jne nimisiksi solmuiksi, mutta nämä eivät ole sallittua XML:ää.
Esimerkki:
-- Esimerkki XML data:
data = {
description = ”testi data”,
pv = 90.5,
polarity = ”normal”
}
local xml = Xml.serialize (data, ”testNode”)
>> tulos
xml = [[
<testNode>
<description>testi data</description>
<pv>90.5</pv>
<polarity>normal</polarity>
</testNode>
]]
sqlite
Toteuttaa rajapinnan sqlite3 -tietokantojen käsittelyyn sovellusohjelmista.
Sqlite.connect (strDB)
strDB Tietokanta tiedosto joka halutaan avata
Avaa tietokantatiedoston käsittelyä varten
-- Avaa tietokannan
local bd = Sqlite.connect (”/opt/slc/data/myData.sql”)
Sqlite.disconnect (hDB)
hDB Avatun tietokannan kahva
Sulkee yhteyden tietokantatiedostoon
-- Avaa ja sulkee tietokannan
local bd = Sqlite.connect (”/opt/slc/data/myData.sql”)
Sqlite.disconnect (db)
Sqlite.query (hDB, strQuery)
hDB Avatun tietokannan kahva
strQuery SQL query joka halutaan suorittaa
Ajaa SQL queryn tietokannassa ja palauttaa tuloksen taulukkona (tai nil mikäli kyselyssä tapahtuu virhe).
Jos kysely ei palauta dataa, palautetaan tyhjä taulukko.
Huomaa! Kaikki SQL queryt täytyy päättää ; -merkkiin, muuten ne palauttavat virheen.
-- Suorita yksinkertainen kysely tietokantaan
local bd = Sqlite.connect (”/opt/slc/data/myData.sql”)
local r = Sqlite.query(db, ”select * from myTable;”)
Sqlite.disconnect (db)