Wikisanakirja:Lua-moduulit

Lua-moduulin rakenne

Moduulit luodaan nimiavaruuteen Module. Esim. moduuli nimeltä Hiekkalaatikko nimetään Module:Hiekkalaatikko.

local m = {}
  
-- Tämä funktio sanoo terve espanjaksi.
function m.sano_terve(frame)
   return '¡Buenos días!'
end

return m

Rivillä

1. luodaan moduuliolio. M on muuttujan nimi, = on sijoitusoperaattori ja {} on tyhjä arvo. Muuttuja m alustetaan siis (toistaiseksi) tyhjäksi olioksi. Tämä nimi m on moduulin sisäinen, ulkopuolella sitä ei käytetä.
2. ei ole mitään. Tyhjillä riveillä ei ole merkitystä koodin toiminnan kannalta.
3. on kommentti. Tämä kommentti kertoo ihmislukijalle mitä alla oleva funktio tekee.
4. alkaa funktion määritelmä. Avainsana fuction kertoo, että kyseessä on fuktio, sen jälkeen tulee funktion nimi, tässä tapauksessa funktio kuuluu oliolle muuttujassa m. Viimeisenä on pari sulkumerkkejä, joka sisältää funktion parametrit. Tässä tapauksessa ainoaan parametriin viitataan frame-nimellä. Ks. kohta #Funktiot.
5. palautetaan funktion arvo. Return-lauseita voi olla funktiossa useitakin, sen ei tarvitse olla viimeisenä.
6. on avainsana end, jota käytetään lohkojen sulkemiseen.
7.  
8. palautetaan moduuliolio. Tämä lause antaa luodun moduulin sitä tulkitsevalle ohjelmalle ja on siis tärkeä, jotta moduulia voidaan yleensä käyttää.

Moduulin käyttäminen

Moduulia kutsutaan rakenteella: {{#invoke:moduuli:funktio|parametri1|parametri2|...}}. Moduulin nimavaruus, Module, jätetään pois. Esimerkiksi:

{{#invoke:Hiekkalaatikko|sano_terve}}

Tämä siis korvautuu edellä määritellyn sano_terve-funktion paluuarvolla:

¡Buenos días!

Jos moduuli ottaa parametreja, ne lisätään perään kuten mallineillakin:

{{#invoke:Hiekkalaatikko|sano_terve_xlle|Veikko}}

Myös nimettömiä ja nimettömiä parametreja voi käyttää kuten mallineillakin:

{{#invoke:Hiekkalaatikko|sano_terve_xlle|Veikko|kieli=es}}

Kutsun voi luonnollisesti laittaa normaalin mallineen sisään.

Ulkoisten parametrien käsittely

Ulkoisilla parametrillä tarkoitetaan tässä #invoke-kutsun perään lisättyjä parametreja, erotuksena sisäisille funktioparametreille.

-- Funktio sanoo 'Buenos días' 1.:ssä parametrissa annetulle nimelle.
function m.sano_terve_xlle(frame)
   return '¡Buenos días, ' .. frame.args[1] .. '!'
end

Kun #invoke-komento ajetaan, tietoja sen ajoympäristöstä välitetään funktiolle oliossa sen ensimmäisessä parametrissa. Tässä siihen on viitattu frame-nimellä, mutta nimi voi olla mikä tahansa sillä se on vain funktion sisäisessä käytössä. Tästä eteenpäin sitä kutsutaan frame-olioksi. Tämä olio sisältää taulukon args, joka sisältää parametrit. Numeroituihin parametreihin viitataan taulukkoindekseillä frame.args[1], [2], jne. Numerointi alkaa 1:stä. Nimettyihin parametreihin voi viitata joko frame.args['nimi'] tai frame.args.nimi. Frame-olio sisältää myös muita tietoja, ks. #Frame.

Toisin kuin muilla taulukoilla, pituusoperaattori # ei toimi frame.args-taulukolla.[1]

Huomaa, että frame.args-parametrit ovat #invoke-kutsussa annetut parametrit. Jos kutsu on mallineen sisällä saadaan mallineen ympäristö frame.getParent()-kutsulla ja sille annetut parametrit siis frame.getParent().args-taulukosta.

Funktiot

Moduulin funktioista voi erottaa kolme eri tyyppiä:

• paikalliset funktiot
• julkiset funktiot
• #invoke-komennolla kutsuttavat funktiot

#invoke-komennolla kutsuttavat funktiot

Funktiot, joita #invoke-komennolla voi kutsua, ovat julkisia funktioita, jotka ottavat vastaan frame-olion. Erona julkisiin funktiohin on parametrienvälitystapa, josta enemmän yllä.

Paikalliset funktiot

Paikalliset funktiot ovat moduulin sisäisiä funktioita, niitä ei siis voi käyttää muista moduuleista käsin eikä #invoke-komennolla. Paikallinen funktio määritellään local function -avainsanoilla:

-- Muuttaa celsiuksina annetun asteen fahrenheiteiksi.
local function muuta_celsius_fahrenheitiksi(c)
   return 9/5 * c + 32
end

Huomaa, että funktion nimi ei myöskään sisällä olion nimeä (em. m). Paikallista funktioita ei voi määritellä metodiksi.[2] Funktio ottaa parametrin, joita se kutsuu nimellä c. Tätä funktiota voi kutsua toisesta funktiosta seuraavasti:

-- Muuttaa annetun °C:ina annetun lämpötilan °F:iksi.
function m.tulosta_fahrenheitina(frame)
   return muuta_celsius_fahrenheitiksi(frame.args[1]) .. ' °F'
end

Julkiset funktiot

Julkiset funktiot ovat funktoita, joita voidaan käyttää muista moduuleista käsin. Funktio määritellään avainsanalla function ja sen täytyy kuulua moduuliin. Esim.:

-- Muuttaa sanan kuin sanan genetiivimuotoon.
function m.muuta_genetiiviksi(sana)
    if sana == 'kissa' then 
        return 'kissan'
    else
        return '' -- TODO
    end
end

Julkisen funktion pitää olla moduuliolion jäsen. Kun funktio on olion jäsen sitä kututsutaan olion metodiksi. Edellä olevassa koodissa metodiksi määritteleminen tehdään siten, että määritelmässä nimen edessä on moduulin nimi, m. Saman lopputuloksen saa aikaan myös esim. seuraavasti:

-- Muuttaa sanan kuin sanan genetiivimuotoon.
local function f(sana)
    -- runko
end
m.muuta_genetiiviksi = f

Tai sijoittamalla funktioviitteen suoraan moduulin jäseneen:

m.muuta_genetiiviksi = function(sana)
    -- runko
end

Toisen moduulin metodien käyttäminen

Kun halutaan käyttää toisen moduulin metodeita, on sen moduuliolio ensin haettava. Tämä tapahtuu request-komennolla. Request ottaa parametriksi merkkijonon, joka sisältää moduulin nimen nimiavaruuksineen, ja palauttaa moduuliavastaavan olion, joka tallennetaan muuttujaan. Moduuliolion julkisia metodeita voi sitten kutsua muodossa muuttuja.funktio(parametrit). Esim. seuraava moduuli käyttää Module:kielikoodit-moduulin genetiivissa-metodia.

local kielet = request("Module:kielikoodit")
local m = {}

-- Palauttaa luokkalinkin annetun kielet polyyppieläimet-luokkaan
-- Parametrit:
--    arg[1]  kielen kielikoodi
function m.luokkanimi(frame)
  return '[[Luokka:' .. mw.getLanguage("fi"):ucfirst(kielet.genetiivissa(frame.args[1])) .. ' polyyppieläimet]]'
end

return m

Katso myös Luokka:Lua-kirjastot.

Tekstin käsittely

Luan string-luokan kaikkia metodeja ei voi käyttää, koska ne eivät osaa käsitellä unicode-merkkijonoja. Unicode-merkkjonojen käsittelyyn on mw.ustring-moduuli. Tämä moduuli on automaattisesti käytössä, joten request-lausetta ei tarvita. Moduulin metodit löytyvät sivulta Ustring library (englanniksi).

Kielikohtaista tekstinkäsittelyä (esim. lajittelu, iso/pienikirjan) varten on mw.language-moduuli. Language library.

Aiheesta muualla

• Lua-laajennoksen dokumentaatio. Extension:Scribunto/Lua reference manual (englanniksi)
• Lua 5.1:n dokumentaatio. Lua 5.1 Reference Manual (englanniksi)