Moduuli:ParametrisoituTeksti/ohje

Tämä on ohjesivu moduulille Moduuli:ParametrisoituTeksti

Tässä ohjeessa kuvataan toiminnallisuutta jonka kehitys on vielä kesken. Sivu on tarkoitettu lähinnä kehityksen apuvälineeksi, ei yleiseen käyttöön.

Kirjaston avulla voi tehdä helposti tekstejä, joissa ehdollisia kohtia. Kirjaston avulla voi varmistaa, että lopputulos on järkevä rippumatta siitä mikä yhdistelmä parametreja on annettu.

Moduulin funktiot

muotoile

muotoile(rakenne)

Pääfunktio, joka prosessoi annetun elementtirakenteen ja palauttaa sen tuottaman tekstin. Tämä on lyhyt tapa tehdä peräkkäin uusi_muotoilija, prosessoi ja tostring(muotoilija)

uusi_muotoilija

uusi_muotoilija()

Luo uuden muotoiluolion. Tätä ei tarvitse kutsua suoraan, jos käytetään muotoile-funktiota.

Rakenne-elementit

Tekstin rakenne kuvataan alla luetelluilla elementeillä. Kun elementti evaluoidaan, se voi tuottaa pätkän tekstiä tai tyhjän arvon, mikä vaikuttaa sen sisältävien elementtien tuottamaan tulokseen.

Jotta koodista saa selkeämmän rakenne-elementit kannattaa tuoda moduulin nimiavaruuteen:

local pt = require("Moduuli:ParametrisoituTeksti")
local ryhma, muuttuja, luettelo, tai = pt.ryhma, pt.muuttuja, pt.luettelo, pt.tai

muuttuja

muuttuja(m)

Yksinkertaisin elementti, jolla merkitään ehdolliset kohdat eli ne kohdat, joilla joko on arvo tai ei ole arvoa.

Parametrit:

Lua-muuttuja, joka sisältää merkkijonon tai arvon nil. Tyhjä merkkijono ja nil luetaan tyhjiksi.

local m1 = "eka"
local m2 = ""
local m3 = nil

ryhma("(", muuttuja(m1), ")") -- Tulos: "(eka)"
ryhma("(", muuttuja(m2), ")") -- Tulos: ""
ryhma("(", muuttuja(m3), ")") -- Tulos: ""

ryhma

ryhma(prefiksi, elementti1, [erotin1, elementti2, [erotin2, elementti3...]], suffiksi)

Tärkein elementti, jolla merkitään ehdollista tekstiä.

Parametrit:

Vaihtuva määrä parametreja.
- Ensimmäinen parametri on aina prefiksi ja viimeinen suffiksi. Prefiksi ja suffiksi tulostetaan, jos yksikin elementti on ei-tyhjä.
- Elementit: tässä luetelluilla rakenne-elementeillä merkittyjä alirakenteita.
- Erottimet: Merkkijonoja, jotka lisätään tulostukseen, jos niiden molemmilla puolilla olevilla muuttujilla on arvo. Erotinta voi edeltää numeroarvo, joka kertoo erottimen presedenssin toisiin erottiimiin nähden (oletusarvo on 0).

Esimerkkejä:

local m1 = "na"
local t1 = nil

ryhma("''", muuttuja(m1), "''-taivutus")  -- tulos: "''na''-taivutus"
ryhma("''", muuttuja(t1), "''-taivutus")  -- tulos: ""

local m1 = "eka"
local m2 = "toka"
local m3 = "kolkki"
local t1 = nil

ryhma("(", muuttuja(m1), ", ", muuttuja(m2), "; ", muuttuja(m3), ")")  -- tulos: "(eka, toka; kolkki)"
ryhma("(", muuttuja(m1), ", ", muuttuja(m2), "; ", muuttuja(t1), ")")  -- tulos: "(eka, toka)"
ryhma("(", muuttuja(t1), ", ", muuttuja(m2), "; ", muuttuja(m3), ")")  -- tulos: "(toka; kolkki)"
ryhma("(", muuttuja(t1), ", ", muuttuja(m2), "; ", muuttuja(t1), ")")  -- tulos: "(toka)"
ryhma("(", muuttuja(t1), ", ", muuttuja(t1), "; ", muuttuja(t1), ")")  -- tulos: ""

-- Tässä tulokseen tulee puolipiste (;), koska sen sille on annettu suurempi presedenssi (1) kuin pilkulle (0).
ryhma("(", muuttuja(m1), ", ", muuttuja(t1), 1, "; ", muuttuja(m3), ")")  -- tulos: "(eka; kolkki)"

luettelo

luettelo(taulukko, erotin, viimeisen_erotin)

Erottimella erotellun luettelon tekemiseen.

Parametrit:

taulukko lueteltavista elementeistä
erotin, jolla arvot erotellaan
toisiksi viimeisen ja viimeisen arvon välinen erotin, jos eri kuin erotin

local m1 = { "eka", "toka", "kolkki" }

luettelo(m1, ", ", " tai ") -- Tulos: "eka, toka tai kolkki"

local m1 = { "A", "B", nil, "D" }
local m2 = { "1", nil, "3", "4" }

luettelo(ryhma("", m1, " ", ryhma("(", m2, ")"), ""), ", ", " tai ") -- Tulos: "A (1), B, (3) tai D (4)"

Luetteloita voi olla myös sisäkkäin. Tällöin muuttujien pitää olla vastaavan syvyisiä puita.

yksittäisessä luettelossa taulukko on muotoa { "1", "2", "3" },
kun luettelo on toisen sisällä, taulukko on muotoa { { "1a", "1b" }, { "2a" }, { "3a", "3b" } },
jne.

tai

tai(elementti1, [elementti2, [elementti3...]]])

Lausekkeen tulos on ensimmäisen ei tyhjän rakenne-elementin arvo.

Parametrit:

Mielivaltainen määrä muita rakenne-elementtejä.

local m1 = nil
local m2 = "toka"
local m3 = "kolkki"

tai(muuttuja(m1), muuttuja(m2)) -- Tulos: "toka" 
tai(muuttuja(m2), muuttuja(m3)) -- Tulos: "toka"

funktio

funktio(fun, param1, [param2, [param3...]]])

Tällä elementillä voi tehdä monimutkaisempia ehtoja, joita ei muilla elementeillä voi tehdä.

Parametrit:

fun: funktio muotoa f(ctx, [param1, [param2, [param3...]]]), jossa ctx on viittaus muotoilija-olioon.
muut parametrit: funktiolle mahdollisesti annettavat parametrit

Funktiossa pääse käsiksi parametrien arvoihin muotoilijaolion metodeilla hae_arvo ja hae_arvo_tai_nil.

Tekstiä lisätään tulostukseen lisäämällä muotoilijaolion out-kenttään.

Funktion pitää palauttaa true, jos tekstiä lisättiin, muuten false.

Huomaa, että se ovatko funktion parametrit elementtejä riippuu funktiosta.

Esim.

local function _sukuteksti(ctx, suku)
   local lyh = ctx:hae_arvo_tai_nil(suku)
   
   local txt = mw.getCurrentFrame():expandTemplate{ ['title'] = 'suku-teksti', ['args'] = { lyh } }
   if txt then
      table.insert(ctx.out, txt)
      return true
   end
   
   return false
end

-----
local m1 = "f"

funktio(_sukuteksti, m1) -- Palauttaa mallinekutsun {{sukuteksti|f}} arvon.

Sanarivimallineissa usein esiintyviä toimintoja on koottuu moduuuliin LibSanarivi.

Huomaa, että alirakenteita voi myös nimetä käyttäen Luan funktioita apuna. Tässä ei kuitenkaan ole kyse funktioelementistä.

function p.tailuettelo(...)
   return luettelo({...}, ", ", " tai ")
end

Muotoilu-olion metodit

hae_arvo

hae_arvo(m)

Palauttaa annetun parametrin arvon. Tätä käytetään funktio-elementissä. Arvoa ei pidä lukea suoraan ilman tätä metodia, koska metodi palauttaa oikean arvon myös silloin kun funktio on luettelon sisällä.

hae_arvo_tai_nil

hae_arvo_tai_nil(m)

Sama kuin hae_arvo, mutta palauttaa nil myös, kun arvo on tyhjä merkkijono. Tämä on yleensä se, mitä halutaan.

prosessoi

prosessoi(rakenne)

Lisää annetun elementtirakenteen tuottaman tekstin tulostukseen. Palauttaa true, jos tekstiä tulostettiin, muuten false.

Tätä voi kutsua funktio-elementissä, kun sille annetaan parametrina elementtirakenne.

Esimerkki tai-elementin toteutuksesta:

local function _tai(ctx, ...)
   local params = {...}
   local ret
   
   for i = 1, #params do
      ret = ctx:prosessoi(params[i])
      if ret then
          return true
      end
   end
   return false
end

-- Käyttö:
funktio(_tai, luettelo(mon1, mon2, mon3, ", ", " ja "), muuttuja("ei monikkoa")) -- TODO tarkista