Benutzer:Schnark/js/Template

Dieses Skript stellt einen Vorlagen-Parser zur Verfügung.

Verwendung

Nach dem Laden des Skripts stehen zwei Funktionen zur Verfügung: mw.libs.templateGetLastError und mw.libs.Template. Beispiele für die Verwendung zeigen die QUnit-Tests unter Benutzer:Schnark/js/Template.js/test.js.

templateGetLastError

Die Funktion gibt eine Fehlermeldung zurück, die den letzten aufgetretenen Fehler beschreibt. Nach dem Parsen wird der Fehler wieder zurückgesetzt, und man erhält den Leerstring.

Template

Die Funktion kann sowohl als Konstruktor (mit new) als auch als normale Funktion verwendet werden und erwartet neben zwei Pflichtparametern bis zu drei optionale Parameter:

Name der Vorlage
Wikitext
Index der Vorlage (bei mehrfachem Vorkommen, 0 ist der Standard und findet das erste Vorkommen der Vorlage, 1 das zweite, etc.)
boolesches Flag, ob mehrfache Parameter in der Vorlage ignoriert werden (bei true) oder einen Fehler erzeugen sollen (bei false, Standard).
boolesches Flag, ob in der Vorlage auch unbenannte Parameter vorkommen dürfen (bei true) oder einen Fehler erzeugen sollen (bei false, Standard).

Zurückgeliefert wird im Erfolgsfall ein Vorlagenobjekt. Tritt ein Fehler auf, so wird entweder null zurückgegeben (falls Template als Funktion aufgerufen wurde) oder ein Fehler ausgelöst (falls Template als Konstruktor verwendet wurde).

Vorlagenobjekt

Das Vorlagenobjekt hat folgende Methoden:

toString

Liefert den eventuell geänderten Wikitext zurück. Das Skript wurde so konzipiert, dass ein möglichst sauberer Roundtrip stattfindet, ruft man die Methode ohne vorherige Änderungen auf, so finden nur die folgenden Änderungen am Wikitext statt:

Der Vorlagenname wird so geschrieben, wie er der Template-Funktion übergeben wurde, der Namensraum wird in jedem Fall entfernt.
Leere, auskommentierte Parameter werden entfernt.
Bei mehrfach auftretenden Parametern (sofern erlaubt) werden alle bis auf den letzten entfernt.
Numerische Parameter werden in unbenannte Parameter umgewandelt, sofern dies möglich ist.

Alles andere, insbesondere Kommentare und Whitespace bleibt erhalten.

insert

Die Methode fügt einen neuen Parameter ein und erwartet als Parameter

den Namen des neuen Parameters,
seinen Wert und
optional den Name des Parameters, hinter dem der neue Parameter eingefügt werden soll. Andernfalls oder wenn dieser Parameter nicht vorhanden ist, wird am Ende eingefügt.
optional ein boolescher Wert, true, falls nicht hinter, sondern vor dem Parameter, bzw. ganz am Anfang statt am Ende eingefügt werden soll

Ist der Name schon vorhanden, wird false zurückgegeben und ein Fehler gesetzt, sonst true.

Bei der Einfügung wird automatisch auf richtige Einrückung geachtet.

change

Die Methode ändert den Wert eines vorhandenen Parameters und erwartet als Parameter

den Namen des Parameters und
den neuen Wert.

Ist der Parameter nicht vorhanden, wird false zurückgegeben und ein Fehler gesetzt, sonst true.

Beim Wechsel von oder zu einem leeren Wert wird automatisch auf schließende Leerzeichen geachtet.

rename

Die Methode benennt einen Parameter um und erwartet als Parameter

den alten Parameternamen und
den neuen Namen.

Ist der alte Parameter nicht vorhanden oder existiert der neue Name schon, wird false zurückgegeben und ein Fehler gesetzt, sonst true.

Es wird automatisch auf eine eventuell notwendige Anpassung der Einrückung geachtet.

remove

Die Methode entfernt einen Parameter und erwartet als Parameter

den Namen des zu entfernenden Parameters.

Ist der Parameter nicht vorhanden, wird false zurückgegeben und ein Fehler gesetzt, sonst true.

move

Die Methode verschiebt einen Parameter an eine andere Stelle und erwartet als Parameter

den Name des zu verschiebenden Parameters und
optional den Parameter, hinter den der Parameter verschoben werden soll. Andernfalls oder wenn dieser Parameter nicht vorhanden ist, wird ans Ende verschoben.

Ist der Parameter nicht vorhanden, wird false zurückgegeben und ein Fehler gesetzt, sonst true.

getIndention

Die Methode liefert ein Array, dessen Werte die erkannte Einrück-Konvention beschreiben. Seine Einträge sind:

1, falls jeder Parameter in einer eigenen Zeile steht, 0 sonst
die Anzahl der Leerzeichen zwischen dem Zeilenumbruch oder dem vorhergehenden Parameter und der Pipe
die Anzahl der Leerzeichen zwischen Pipe und Parametername
die Anzahl der Leerzeichen zwischen Parametername und Gleichheitszeichen oder das Negative der Position des Gleichheitszeichens (falls diese untereinander angeordnet sind)
die Anzahl der Leerzeichen zwischen Gleichheitszeichen und Wert
1, falls diese Leerzeichen auch bei leerem Wert vorhanden sind, 0 sonst

setIndention

Die Methode erlaubt es, die Werte zur Einrück-Konvention zu ändern und erwartet bis zu sechs Parameter, in der obigen Reihenfolge, wobei Werte mit undefined nicht geändert werden.

normalize

Die Methode passt die gesamte Vorlage der erkannten oder gesetzten Einrück-Konvention an.

trim

Die Methode entfernt innerhalb der Vorlage alle Leerzeichen am Zeilenende.

sort

Die Methode sortiert die Parameter der Vorlage und erwartet als Parameter

ein Array mit der gewünschten Reihenfolge und
optional ein boolesches Flag, ob unbekannte Parameter akzeptiert und dann ans Ende sortiert werden sollen.

Bei Sortieren wird automatisch auf Kommentare geachtet, die offenbar als Überschrift für einzelne Bereiche gedacht sind.

validate

Die Methode überprüft die gesamte Vorlage nach bestimmten Regeln, die in einem Objekt als Parameter übergeben werden. Dieses Objekt muss für alle möglichen Parameter ein Objekt angeben, das die Regeln angibt, die für diesen Parameter gelten. Dieses Objekt kann folgende Werte enthalten:

re: ein regulärer Ausdruck, dem der Wert entsprechen muss.
optional: falls auf true gesetzt, ist dieser Parameter optional
allGroup: ist ein Parameter aus dieser Gruppe vorhanden, so müssen auch alle anderen angegeben sein (offenbar nur bei optionalen Parametern sinnvoll)
oneGroup: aus dieser Gruppe darf nur ein Parameter vorhanden sein (optional sollte für alle Parameter dieser Gruppe den gleichen Wert haben)

Schlägt die Überprüfung fehlt, wird false zurückgegeben und ein Fehler gesetzt, sonst true.

getVal

Die Methode liefert den Wert des übergebenen Parameters zurück oder undefined, falls er nicht vorhanden ist.

Code

Der Javascript-Code befindet sich unter Benutzer:Schnark/js/Template.js.