Hilfe:Lua/Modul für eine bestimmte Vorlage

Diese Hilfeseite gibt für Lua-Programmierer einen Startpunkt, wie sich ein Modul schreiben lässt, das genau eine Vorlage unterstützen soll.

Das Gegenstück wären Bibliotheksmodule, die von beliebig vielen unterschiedlichen Vorlagen aufgerufen werden können.

Grundprinzip

• Das Modul erhält den Namen

  Modul:Vorlage:Vorlagen-Titel

  • Damit ist die Zuordnung leicht nachzuvollziehen.
• Die Arbeit der Vorlage wird ausschließlich durch das Modul vorgenommen.
  • Die Vorlage enthält in der Regel nur eine einzige Zeile:

    {{#invoke:Vorlage:Vorlagen-Titel|f}}<noinclude>{{Dokumentation}}</noinclude>

• Die Funktion f (oder nach Belieben anders genannt) ist die einzige für Vorlagen verfügbare Schnittstelle.
• Parameter der Vorlageneinbindung müssen nicht weitergereicht werden; sie können besser und vollständiger innerhalb des Moduls ermittelt werden.
• Innerhalb eines Wiki-Projektes sind keine anderen Parameter erforderlich; Sonderfälle wären Mehrere Vorlagen oder Internationalisierung.

Muster

--[=[ 2013-05-19
Unterstützung für {{Vorlagen-Titel}}
f() test()
]=]


--
--


local function x( u )
    local r
    --
    return  r
end -- x()


local function main( a )
    local r
    --
    r = x( u )
    --
    return  r or ""
end -- main()



-- Export
local p = {}

function p.test( a )
    local lucky, r = pcall( main, a )
    return r
end

function p.f( frame )
    local lucky, r = pcall( main, frame:getParent().args )
    return r
end

return p

Vorlagen-Schnittstelle

Die Funktion f übernimmt mittels getParent() die Parameter der Vorlageneinbindung.

Sie ruft die Haupt-Funktion in geschützter Ausführung auf.

Rückgabewert ist die von main() zurückgegebene Zeichenkette oder die von pcall() zugewiesene Zeichenkette der Fehlermeldung.

Test-Schnittstelle

• Für automatisierte Tests können von einem entsprechenden Lua-Modul aus eine größere Serie von Parameter-Sätzen vorgegeben und mit den erwarteten Ergebnissen verglichen werden.
• Die Parameter-Sätze werden in gleicher Weise formatiert, wie sie bei der Vorlageneinbindung benutzt würden.
• Die Haupt-Funktion wird genau analog aufgerufen.

Haupt-Funktion

• Die Funktion main() (oder nach Belieben anders genannt) ist die eigentliche Arbeitsfunktion.
• Sie erhält alle Parameterzuweisungen als a, egal ob diese aus #invoke oder der Simulation stammen.
• Der Rückgabewert ist die für Vorlagen passende Zeichenkette; und dies identisch für die Vorlageneinbindung und die Simulation, damit die Ergebnisse vergleichbar sind.
• frame wird nicht übergeben. Sollte das Objekt einmal benötigt werden, kann es mittels mw.getCurrentFrame() ermittelt werden. Es wäre das der Vorlageneinbindung oder aber das zwangsläufig irgendwo vorhandene #invoke der Simulation.
• Die lokale Funktion main() muss als letzte aller lokalen Funktionen vereinbart sein.

Geschützte Ausführung

Der Aufruf der Haupt-Funktion wird jeweils in pcall() geschützt.

• Kommt es nun zu einem Laufzeitfehler, oder wird durch das eigene Modul mittels assert() oder error() ein Fehler ausgelöst, dann ist r die Fehlermeldung.
• Damit wird das notorisch unspezifische „Skriptfehler“ vermieden.

Mehrere Vorlagen

Wenn es eine eng umgrenzte Gruppe von Vorlagen gibt (etwa Vorlage:Str*), bei denen sich der Aufwand für Einzelmodule nicht lohnen würde, können sie in einem gemeinsamen Modul untergebracht werden.

Beispiel anhand der Vorlage:Str len:

{{#invoke:Vorlage:Str|f|f=len}}

mit einem einzigen Modul:Vorlage:Str für alle.

Die Funktion f ist dann wie folgt zu modifizieren:

function p.f( frame )
    local a = frame:getParent().args
    a.f = frame.args.f
    local lucky, r = pcall( main, a )
    return r
end

Während alle anderen Parameter der umgebenden Vorlage entstammen, wird f den Argumenten des #invoke entnommen.

Die Funktion test muss sich den Vorlagen-Namen in ihrer Simulation entsprechend vorgeben.