Modul:TemplatePar/Doku: Unterschied zwischen den Versionen

Aus AnthroWiki
imported>Odyssee
(Die Seite wurde geleert.)
imported>Odyssee
 
(Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt)
Zeile 1: Zeile 1:
<onlyinclude>'''<code>TemplatePar</code>''' – Modul mit Hilfsfunktionen für die Vorlagenprogrammierung; namentlich die Analyse der Parameter der umgebenden Vorlageneinbindung.<noinclude>
Zusätzlich werden analog auch Lua-Module unterstützt.
* [[#assert|assert]] – Einzelne Zeichenkette prüfen</noinclude>
* [[#check|check]] – Gesamt-Einbindung der Vorlage prüfen
* [[#count|count]] – Anzahl der Parameter der Vorlage
* [[#countNotEmpty|countNotEmpty]] – Anzahl der nicht-leeren Parameter der Vorlage<noinclude>
* [[#downcase|downcase]] – Alle Parameternamen in Kleinbuchstaben</noinclude>
* [[#match|match]] – Vorlageneinbindung mit gefordertem Profil abgleichen
* [[#valid|valid]] – Einzelnen Parameterwert prüfen<noinclude>
* [[#verify|verify]] – Gesamtparameter des <code>#invoke</code> prüfen</noinclude>


Insbesondere sollen den Anwendern für Standardfälle der Parameteranalyse auf einfache Weise Standard-Fehlermeldungen dargestellt werden.
== {{Anker|Vorlage}} Funktionen für Vorlagen ==
=== Einzelfunktionen ===
Alle Funktionen wirken hinsichtlich der analysierten Parameter auf die umgebende Vorlageneinbindung; die Parameter von <code>#invoke</code> spezifizieren die Regeln für die Analyse.
==== assert ====
: Überprüfung einer beliebigen Zeichenkette nach den [[#Parameterformat|Regeln für das Parameterformat]].
:; 1
:: Zu untersuchende Zeichenkette (Pflichtparameter).
:; 2
:: Format („Nur Ziffern“, „ASCII“, begrenzter Zeichensatz, Lua-''pattern''); siehe [[#Parameterformat|unten]]. Optional, aber sinnvollerweise in der Regel anzugeben.
==== check ====
: Überprüfung auf vorgesehene und unerwartete Parameter der Vorlageneinbindung; Vollständigkeit von Pflichtangaben. Details siehe [[#Parameterprüfung|unten]].
: Eine Fehlermeldung wird mit <code>class=error</code> zurückgegeben.
: Wenn nichts zurückgegeben wird, scheint alles in Ordnung zu sein.
: ''Parameter (alle optional):''
:; all
:: Namen der Pflichtparameter; müssen auch mit Wert belegt sein.
:: Untereinander durch Gleichheitszeichen <code>=</code> getrennt.
:: Fehlende Angaben lösen eine Standard-Fehlermeldung aus; wenn individuelle Fehlermeldungen gewünscht werden, sind sie unter&nbsp;'''opt''' aufzuführen und mittels Vorlagenprogrammierung zu analysieren.
:; opt
:: Namen der optionalen Parameter.
:: Untereinander durch Gleichheitszeichen <code>=</code> getrennt.
:; low
:: Ignoriere Groß- und Kleinschreibung.
: →[[Wikipedia:Lua/Modul/TemplatePar/test#check|Beispiele und Test]].
==== count ====
: Anzahl der Parameter der umgebenden Vorlageneinbindung.
: ''Parameter:'' Keine (beim #invoke)
: Das Ergebnis ist eine Zahl ab <code>0</code>.
: →[[Wikipedia:Lua/Modul/TemplatePar/test#count|Beispiele und Test]].
==== countNotEmpty ====
: Anzahl der Parameter der umgebenden Vorlageneinbindung, die nicht leer sind (höchstens Leerzeichen oder Zeilenumbruch enthalten).
: ''Parameter:'' Keine (beim <code>#invoke</code>)
: Das Ergebnis ist eine Zahl ab <code>0</code>.
: →[[Wikipedia:Lua/Modul/TemplatePar/test#countNotEmpty|Beispiele und Test]].
==== match ====
: Umgebende Vorlageneinbindung mit gefordertem Profil abgleichen.<noinclude> Für Lua-Schnittstelle zurzeit noch nicht vorgesehen; dort individuell zusammenzustellen.</noinclude>
:; 1
:: Regel im Format &nbsp; <code>1=</code>''Parametername''<code>=</code>''Spezifikation''
:: Die ''Spezifikation'' entspricht der von [[#valid|valid]].
:; ''nnn''…
:: Wie '''1''' – beliebig viele unbenannte Parameter als Regeln; in beliebiger Reihenfolge und nicht lückenlos.
: Alle zulässigen Parameternamen müssen aufgelistet werden; optionale sind mit der Bedingung <code>*</code> anzugeben oder einer geeigneten [[#Parameterformat|''Spezifikation'']] zu unterwerfen.
: Es wird eine Fehlermeldung (<code>class=error</code>) zurückgegeben, wenn etwas nicht stimmt; sonst ''nichts''.
: Fatale Fehler führen in der folgenden Reihenfolge zum Abbruch: Unbekannter Parametername&nbsp;– fehlender Parameter&nbsp;– ungültiger Parameterwert.
: →[[Wikipedia:Lua/Modul/TemplatePar/test#match|Beispiele und Test]].
: Mittels der Funktion lässt sich durch einen einzigen Aufruf gleichzeitig für alle Parameter eine Prüfung ausführen auf
:* Pflichtparameter vorhanden?
:* keine unbekannten Parameternamen (Falschschreibung)?
:* gültige Werte für jeden Parameter?
: Für jeden Parameternamen bei der Vorlageneinbindung muss mindestens eine Regel vorhanden sein. Gibt es für einen Vorlagenparameter keine Regel, ist er unbekannt und damit unzulässig.
:* Für denselben Parameternamen kann es mehrere Regeln geben. Die Einhaltung der Regeln wird in der Reihenfolge geprüft, in der sie vereinbart werden.
:* Die Reihenfolge der Parameternamen ist ohne Bedeutung.
==== valid ====
: Überprüfung eines einzelnen Parameterwerts.
: Eine Fehlermeldung wird mit <code>class=error</code> zurückgegeben.
: Wenn nichts zurückgegeben wird, scheint alles in Ordnung zu sein.
: ''Parameter (bis auf '''''1''''' alle optional):''
:; 1
:: Name des einzelnen Parameters.
:; 2
:: Format („Nur Ziffern“, „ASCII“, begrenzter Zeichensatz, Lua-''pattern''); siehe [[#Parameterformat|unten]].
:; min
:: Mindestlänge ≥0.
:; max
:: Maximale Länge >0.
:; low
:: Ignoriere Groß- und Kleinschreibung.
: Aus der Gruppe ''2, min, max'' sollte sinnvollerweise wenigstens eine angegeben werden.
: →[[Wikipedia:Lua/Modul/TemplatePar/test#valid|Beispiele und Test]].
=== {{Anker|error handling}} Handhabung von Fehlern ===
Alle Funktionen, die auf einen Fehlerfall führen können (check, valid<noinclude> sowie downcase, verify</noinclude>), unterstützen auch die nachstehenden Parameter:
; template
: Titel der für Autoren sichtbaren Vorlage (für Fehlermeldungen).
: Kann auch ein anderes Schlüsselwort sein; vor allem für Untervorlagen vorgesehen.
: Ein Wikilink ist darin ebenfalls möglich; etwa auf eine bestimmte Doku-, Hilfe- oder Projektseite. (Hier wäre –&nbsp;anders als beim Titel&nbsp;– natürlich der Namensraum anzugeben.)
; cat
: Titel einer Wartungskategorie.
: Im Fehlerfall wird diese aktiviert.
: Mit <code>errNS</code> lässt sich die Kategorisierung auf bestimmte Namensräume beschränken.
: Falls der Titel die Zeichenkette <code>@@@</code> enthält und <code>template</code> gesetzt ist, wird dies durch <code>template</code> ersetzt.
; errNS
: Leerzeichen-getrennte Auflistung von Namensraum-Nummern, auf die <code>cat</code> beschränkt bleibt.
; format
: Fehlermeldung formatieren oder unterdrücken.
:* Standardfall, Standardmeldung mit <code>class="error"</code> formatiert:
:** Parameter <code>format</code> nicht angegeben.
:** <code>|format=*|</code>
:* Unterdrücken (dann sollte <code>cat=</code> gesetzt sein):
:** <code>|format=|</code>
:** <code>|format=0|</code>
:** <code>|format=-|</code>
:* Fester Text, eigene Formatierung:
:** <code>|format=<anfang>Fester Text</ende>|</code>
:* Freie Formatierung der Standardmeldung:
:** Enthält <code>@@@</code> als Platzhalter für die unformatierte Standardmeldung.
:** <code>|format=<anfang>Eigener Text; @@@</ende>|</code>
; preview
: Unterdrückung der Fehlermeldung im Vorschaumodus unterdrücken, also trotz <code>|format=0|</code> usw. immer Standardmeldung anzeigen:
:* <code>|preview=1|</code>
: Fester Text, eigene Formatierung im Vorschaumodus:
:* <code>|preview=<anfang>Fester Text</ende>|</code>
: Standardmeldung in eigener Formatierung im Vorschaumodus:
:* <code>|preview=<anfang>Standardmeldung: @@@</ende>|</code>
<noinclude>Lua-Module liefern <code>false</code> bei fehlerfreier Analyse, ansonsten die Fehlermeldung.</noinclude>
=== {{Anker|Parameterprüfung}} Parameterprüfung (check) ===
Anwendungsfall für [[#check|check]] am Beispiel der {{Vorlage|Information}}:
<syntaxhighlight lang="text">
{{#invoke:TemplatePar
        |check
        |all= Beschreibung= Quelle= Urheber=
        |opt= Datum= Genehmigung= Andere Versionen= Anmerkungen=
        |template=[[Vorlage:Information]]}}
</syntaxhighlight>
* Weil der Name eines Vorlagenparameters kein Gleichheitszeichen <code>=</code> enthalten kann, werden diese zur Abtrennung der Namen benutzt. Leerzeichen vor und nach dem Namen werden ignoriert. Zusätzliche Gleichheitszeichen sind unproblematisch.
* Die ersten drei Vorlagenparameter des Beispiels sind Pflichtparameter und müssen auch mit Wert angegeben werden.
* Alle bei der Vorlageneinbindung benutzten Parameter, die weder unter <code>all=</code> noch <code>opt=</code> aufgeführt sind, lösen eine Fehlermeldung aus.
* Die unbenannten Vorlagenparameter tragen ihre laufende Nummer als Namen; im Übrigen werden die Namen in der Fehlermeldung bezeichnet.
* Es gibt vier Fehlermeldungen:
*# ''#invoke:TemplatePar * Optionsparameter wiederholt''
*#* Beim Aufruf des Moduls wurde ein Name sowohl unter <code>all=</code> als auch <code>opt=</code> angegeben.
*# ''Fehler bei Vorlage * Parametername unbekannt''
*#* Bei der Vorlageneinbindung wurde ein Parameter benutzt, der weder unter <code>all=</code> noch <code>opt=</code> aufgeführt ist.
*# ''Fehler bei Vorlage * Pflichtparameter fehlt''
*#* Bei der Vorlageneinbindung fehlt ein unter <code>all=</code> aufgeführter Parameter.
*# ''Fehler bei Vorlage * Pflichtparameter ohne Wert''
*#* Bei der Vorlageneinbindung ist ein unter <code>all=</code> aufgeführter Parameter nur mit Gleichheitszeichen, aber ohne sichtbaren Wert angegeben; oder ein unbenannter Parameter ist leer.
* Die Fehlermeldungen sind hierarchisch gestaffelt. Bei einem Schreibfehler, der zu einem Problem höherer Ordnung führt, könnten die weiteren lediglich Folgefehler sein, die sich mit Korrektur des Grundproblems von selbst erledigen. Es wird daher nur die wichtigste gefundene Fehlerkategorie angezeigt.
=== {{Anker|Parameterformat}} Parameterformat (valid) ===
Für die optionale Bedingung '''2''' in [[#valid|valid]] gibt es zwei Grundtypen:
# Schlüsselwort
#* Erleichterung für Vorlagenprogrammierer; einige Ausdrücke mit Lua-Patterns nicht möglich.
#** Siehe [[#key|Tabelle]].
#* Spezielle Datentypen wie URL, DOI, ISBN, Datum sind nicht erwünscht. Hier müssten bei jedem neuen Typ alle Artikel (mehrere Hunderttausend) neu zusammengestellt werden. Hingegen gibt es darauf spezialisierte Funktionen wie in [[Wikipedia:Wikipedia:Lua/Modul/URLutil|URLutil]].
# Lua-Pattern (Ustring)
#* Eingeschlossen in Schrägstriche, um sie von einem Schlüsselwort unterscheiden zu können und ggf. führende und schließende Leerzeichen bei Werten unbenannter Vorlagenparameter zu identifizieren.
#* Die Zeichenketten <code>|</code> sowie <code>{&#123;</code> und <code>}}</code> sind in der Vorlagenprogrammierung nicht möglich. Dafür sind zu ersetzen:
#** <code>|</code> → <code>%!</code>
#** <code>{&#123;</code> → <code>%((</code>
#** <code>}}</code> → <code>%))</code>
Zur Spalte ''Implementierung'' siehe [[Wikipedia:Hilfe:Lua/Zeichenketten #Pattern]]
{{Anker|key}}
{| class="wikitable"
|+ Schlüssel für vereinfachten Zugriff
! Schlüssel
! Bedeutung
! Implementierung
|-
| <code>ASCII</code>
|[[Wikipedia:American Standard Code for Information Interchange|ASCII]]-Zeichen (Codes 32–126), nur innerhalb einer Zeile, oder leer
| <code>^[ -~]*$</code>
|-
| <code>ASCII+</code>
| wie vor; nicht leer
| <code>^[ -~]+$</code>
|-
| <code>ASCII+1</code>
| in einem Wort; sonst wie vor und nicht leer
| <code>^[!-~]+$</code>
|-
| <code>n</code>
| Nur ASCII-Ziffern 0–9, sowie vorangestelltes Vorzeichen ASCII-Minus, oder leer
| <code>^[%-]?[0-9]*$</code><br />einzelnes Minus ausschließen
|-
| <code>n>0</code>
| Nur ASCII-Ziffern 0–9, ohne Vorzeichen, nicht leer und mindestens eine Ziffer nicht Null
| <code>^[0-9]*[1-9][0-9]*$</code>
|-
| <code>N+</code>
| Wie <code>n</code>, aber führende Null nicht erlaubt und nicht leer
| <code>^[%-]?[1-9][0-9]*$</code>
|-
| <code>N>0</code>
| Wie <code>n>0</code>, aber führende Null nicht erlaubt
| <code>^[1-9][0-9]*$</code>
|-
| <code>x</code>
| Hexadezimalzahl; ASCII-Ziffern 0–9 Buchstaben a–f A–F, oder leer
| <code>^[0-9A-Fa-f]*$</code>
|-
| <code>x+</code>
| wie vor; nicht leer
| <code>^[0-9A-Fa-f]+$</code>
|-
| <code>X</code>
| Hexadezimalzahl; ASCII-Ziffern 0–9 Buchstaben A–F, oder leer
| <code>^[0-9A-F]*$</code>
|-
| <code>X+</code>
| wie vor; nicht leer
| <code>^[0-9A-F]+$</code>
|-
| <code>0,0</code>
| Beliebige Zahl; auch kleiner Null; kann Komma enthalten; oder leer
| <code>^[%-]?[0-9]*,?[0-9]*$</code><br />nicht nur Minus oder Komma
|-
| <code>0,0+</code>
| Zahl mit Komma und Nachkommastelle; auch kleiner Null
| <code>^[%-]?[0-9]+,[0-9]+$<code>
|-
| <code>0,0+?</code>
| Beliebige Zahl; auch kleiner Null; kann Komma und Nachkommastelle enthalten; nicht leer
| <code>^[%-]?[0-9]+,?[0-9]*$</code>
|-
| <code>0.0</code>
| Beliebige Zahl; auch kleiner Null; kann Dezimalpunkt enthalten; oder leer
| <code>^[%-]?[0-9]*[%.]?[0-9]*$</code><br />nicht nur Minus oder Punkt
|-
| <code>0.0+</code>
| Zahl mit Dezimalpunkt und Dezimalstelle; auch kleiner Null
| <code>^[%-]?[0-9]+%.[0-9]+$</code>
|-
| <code>0.0+?</code>
| Beliebige Zahl; auch kleiner Null; kann Dezimalpunkt und Dezimalstelle enthalten; nicht leer
| <code>^[%-]?[0-9]+[%.]?[0-9]*$</code>
|-
| <code>.0+</code>
| Beliebige Zahl; auch kleiner Null; kann Dezimalpunkt und Dezimalstelle enthalten, aber nicht notwendigerweise mit Ziffer davor; nicht leer
| <code>^[%-]?[0-9]*[%.]?[0-9]+$</code>
|-
| <code>aa</code>
| Mindestens zwei Buchstaben (nicht nur nebeneinander: ''N.N.'') oder ein CJK
| <code>%a.*%a</code><br />oder CJK
|-
| <code>ID</code>
| Identifizierer unter Einschränkungen, wie sie für viele Sprachen üblich sind: ASCII, beginnend mit Buchstaben; weiter Ziffern und Unterstreichungsstrich; oder leer.<br />Die nachfolgenden ASCII-Wörter sind ebenfalls unter dem Aspekt solcher Bezeichner zu sehen; etwa als Komponente einer URL.
| <code style="white-space: nowrap">^[A-Za-z]?[A-Za-z_0-9]*$</code>
|-
| <code>ID+</code>
| wie vor; aber nicht leer.
| <code>^[A-Za-z][A-Za-z_0-9]*$</code>
|-
| <code>ABC</code>
| Wort in ASCII-Großbuchstaben; oder leer.
| <code>^[A-Z]*$</code>
|-
| <code>ABC+</code>
| wie vor; aber nicht leer.
| <code>^[A-Z]+$</code>
|-
| <code>Abc</code>
| Wort in ASCII-Buchstaben mit nur erstem Buchstaben groß; oder leer.
| <code>^[A-Z]*[a-z]*$</code>
|-
| <code>Abc+</code>
| wie vor; aber nicht leer.
| <code>^[A-Z][a-z]+$</code>
|-
| <code>abc</code>
| Wort in ASCII-Kleinbuchstaben; oder leer.
| <code>^[a-z]*$</code>
|-
| <code>abc+</code>
| wie vor; aber nicht leer.
| <code>^[a-z]+$</code>
|-
| <code>aBc+</code>
| Wort in ASCII-Buchstaben mit [[Wikipedia:Binnenmajuskel#Verwendung in Programmiersprachen|lower camel casing]]; nicht leer.
| <code>^[a-z]+[A-Z][A-Za-z]*$</code>
|-
| <code>base64</code>
| [[Base64]]; oder leer.
| <code>^[A-Za-z0-9%+/]*$</code>
|-
| <code>base64+</code>
| wie vor; aber nicht leer.
| <code>^[A-Za-z0-9%+/]+$</code>
|-
| <code>pagename</code>
| Zulässiger Seitenname; nicht leer.
| nicht <code><nowiki>#<>[]|{}</nowiki></code> oder 127<sub>10</sub> oder 1–31<sub>10</sub>
|-
|
<code>file</code><br />
<code>file+</code><br />
<code>file:</code><br />
<code>file:+</code><br />
<code>image</code><br />
<code>image+</code><br />
<code>image:</code><br />
<code>image:+</code>
|
Zulässiger Titel oder Name einer Mediendatei bei <code>file</code> (der Namensraum darf vorangestellt sein).
* Mit <code>+</code> nicht leer.
* Mit <code>:</code> muss die Mediendatei existieren.
Als <code>image</code> muss das Dateiformat für ein Einzelbild geeignet sein.
|-
|
<code><</code>''nnnn''<br />
<code><=</code>''nnnn''<br />
<code>></code>''nnnn''<br />
<code>>=</code>''nnnn''<br />
<code>==</code>''nnnn''<br />
<code>!=</code>''nnnn''
| Bedingung: Arithmetischer Vergleich oder (auch) numerische Ungleichheit
|
|-
| <code>*</code>
| leer oder beliebig
|
|-
| <code>+</code><br />''nichts''
| nicht leer
| <code>%S</code>
|-
!colspan="3"| In Planung
|-
| <code>date</code>
| Irgendein bekanntes Format für Datum und auch Zeit.
|
|-
|colspan="3"| &nbsp;
|-
!colspan="3"| Hier eher nicht vorgesehen
|-
|colspan="3"|
* Vermutlich eher in einem ''Modul:WLink'':
** Name einer existierenden Seite
* Basis-Datentypen
** Datum, Zeit, [[ Wikipedia:Wikipedia:Lua/Modul/URLutil|URL]], ISBN
|}
=== Beispiele (Testseite) ===
Eine [[Wikipedia:Lua/Modul/TemplatePar/test|Testseite]] illustriert praktische Beispiele.</onlyinclude>
== {{Anker|Lua}} Funktionen für Lua-Module ==
Die Funktionen für Vorlagen sind geeignet erreichbar. Zur prinzipiellen Funktionalität siehe jeweils dort. Weitere Funktionen nur für Module kommen hinzu.
Einbindung über <code>require()</code>:
<syntaxhighlight lang="lua">
local lucky, TemplatePar = pcall( require, "Modul:TemplatePar" )
if type( TemplatePar ) == "table" then
    TemplatePar = TemplatePar.TemplatePar()
else
    -- Fehlerfall; TemplatePar enthält Fehlermeldung
    return "<span class='error'>" .. TemplatePar .. "</span>"
end
</syntaxhighlight>
; TemplatePar.[[#assert|assert]](analyze,append,options)
: Analysiere eine Zeichenkette wie mit [[#valid|valid]].
:; analyze
::* ''string;'' zu analysieren
:; append
::* ''string;'' Fehlermeldung anhängen; <code>&lt;br /></code> voranstellen, wenn nicht leer
::* sonst: Fehler werfen
:; options
:: ''table;'' Details; <code>options</code> und alle Komponenten optional
::* <code>key</code>
::*: ''string;'' [[#Parameterformat|Schlüsselwort]]
::* <code>pattern</code>
::*: ''string;'' [[#Parameterformat|Pattern]]
::* <code>min</code>
::*: ''number''
::* <code>max</code>
::*: ''number''
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
: ''Rückgabewert:'' <code>false</code>, wenn in Ordnung; sonst Fehlermeldung
; TemplatePar.[[#check|check]](options)
:; options
:: ''table;'' Details; <code>options</code> und alle Komponenten optional
::* <code>mandatory</code>
::*: ''table;'' sequence mit Namen der Pflichtparameter
::* <code>optional</code>
::*: ''table;'' sequence mit Namen der optionalen Parameter
::* <code>low</code>
::*: <code>true</code>: ignoriere Groß- und Kleinschreibung
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
: ''Rückgabewert:'' <code>false</code>, wenn in Ordnung; sonst Fehlermeldung
; TemplatePar.[[#count|count]]()
; TemplatePar.[[#countNotEmpty|countNotEmpty]]()
; {{Anker|downcase}} TemplatePar.downcase(options)
: Alle Vorlagenparameter in Kleinschreibung
: Liefert ''table'' mit den <code>.args</code> (''number'' bei unbenannten, ''string'' bei benannten Vorlagenparametern).
: Fehlermeldung, wenn der gleiche Name in unterschiedlichen Schreibungen auftritt.
:; options
:: ''table;'' Details; <code>options</code> und alle Komponenten optional
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
; TemplatePar.[[#valid|valid]](seek, options)
:; seek
:: ''Zeichenkette;'' Name des Vorlagen-Parameters.
:; options
:: ''table;'' Details; <code>options</code> und alle Komponenten optional
::* <code>key</code>
::*: ''string;'' [[#Parameterformat|Schlüsselwort]]
::* <code>pattern</code>
::*: ''string;'' [[#Parameterformat|Pattern]]
::* <code>min</code>
::*: ''number''
::* <code>max</code>
::*: ''number''
::* <code>low</code>
::*: <code>true</code>: ignoriere Groß- und Kleinschreibung
::* <code>template</code>
::* <code>cat</code>
::* <code>errNS</code>
::* <code>format</code>
::* <code>preview</code>
:: <code>key</code> und  <code>pattern</code> können nicht gleichzeitig angegeben werden.
: ''Rückgabewert:'' <code>false</code>, wenn in Ordnung; sonst Fehlermeldung
; TemplatePar.verify(options)  {{Anker|verify}}
: Wie <code>TemplatePar.[[#check|check()]]</code>, jedoch Parameter des <code>#invoke</code>
; TemplatePar()
: Liefert ''table'' mit dem Zugriff auf die Funktionen.
== Verwendung ==
Allgemeines Hilfsmittel; nicht eingegrenzt.
== Abhängigkeiten ==
Keine.
== Internationalisierung ==
Fehlermeldungen sind zurzeit in deutscher und englischer Sprache verfügbar, die sich automatisch nach der Projektsprache richten. Weitere Sprachen können hinzugefügt werden.
Die nicht-englischen Mitteilungen sollen als Systemnachrichten in MediaWiki: ausgelagert werden, um bei weiteren Sprachen und Umformulierungen nicht alle einbindenden Seiten neu aufbauen zu müssen. Sie werden bereits unterstützt und haben Vorrang vor den im Modul deklarierten Texten.
{| class="wikitable"
|+ Systemnachrichten
{{{{#rel2abs:../I18N}}#}}
|}
[[Kategorie:Wikipedia:Lua/Modul/Dokumentation|TemplatePar]]
{{Wikipedia}}

Aktuelle Version vom 29. Juli 2015, 17:40 Uhr

TemplatePar – Modul mit Hilfsfunktionen für die Vorlagenprogrammierung; namentlich die Analyse der Parameter der umgebenden Vorlageneinbindung. Zusätzlich werden analog auch Lua-Module unterstützt.

  • assert – Einzelne Zeichenkette prüfen
  • check – Gesamt-Einbindung der Vorlage prüfen
  • count – Anzahl der Parameter der Vorlage
  • countNotEmpty – Anzahl der nicht-leeren Parameter der Vorlage
  • downcase – Alle Parameternamen in Kleinbuchstaben
  • match – Vorlageneinbindung mit gefordertem Profil abgleichen
  • valid – Einzelnen Parameterwert prüfen
  • verify – Gesamtparameter des #invoke prüfen

Insbesondere sollen den Anwendern für Standardfälle der Parameteranalyse auf einfache Weise Standard-Fehlermeldungen dargestellt werden.

Funktionen für Vorlagen

Einzelfunktionen

Alle Funktionen wirken hinsichtlich der analysierten Parameter auf die umgebende Vorlageneinbindung; die Parameter von #invoke spezifizieren die Regeln für die Analyse.

assert

Überprüfung einer beliebigen Zeichenkette nach den Regeln für das Parameterformat.
1
Zu untersuchende Zeichenkette (Pflichtparameter).
2
Format („Nur Ziffern“, „ASCII“, begrenzter Zeichensatz, Lua-pattern); siehe unten. Optional, aber sinnvollerweise in der Regel anzugeben.

check

Überprüfung auf vorgesehene und unerwartete Parameter der Vorlageneinbindung; Vollständigkeit von Pflichtangaben. Details siehe unten.
Eine Fehlermeldung wird mit class=error zurückgegeben.
Wenn nichts zurückgegeben wird, scheint alles in Ordnung zu sein.
Parameter (alle optional):
all
Namen der Pflichtparameter; müssen auch mit Wert belegt sein.
Untereinander durch Gleichheitszeichen = getrennt.
Fehlende Angaben lösen eine Standard-Fehlermeldung aus; wenn individuelle Fehlermeldungen gewünscht werden, sind sie unter opt aufzuführen und mittels Vorlagenprogrammierung zu analysieren.
opt
Namen der optionalen Parameter.
Untereinander durch Gleichheitszeichen = getrennt.
low
Ignoriere Groß- und Kleinschreibung.
Beispiele und Test.

count

Anzahl der Parameter der umgebenden Vorlageneinbindung.
Parameter: Keine (beim #invoke)
Das Ergebnis ist eine Zahl ab 0.
Beispiele und Test.

countNotEmpty

Anzahl der Parameter der umgebenden Vorlageneinbindung, die nicht leer sind (höchstens Leerzeichen oder Zeilenumbruch enthalten).
Parameter: Keine (beim #invoke)
Das Ergebnis ist eine Zahl ab 0.
Beispiele und Test.

match

Umgebende Vorlageneinbindung mit gefordertem Profil abgleichen. Für Lua-Schnittstelle zurzeit noch nicht vorgesehen; dort individuell zusammenzustellen.
1
Regel im Format   1=Parametername=Spezifikation
Die Spezifikation entspricht der von valid.
nnn
Wie 1 – beliebig viele unbenannte Parameter als Regeln; in beliebiger Reihenfolge und nicht lückenlos.
Alle zulässigen Parameternamen müssen aufgelistet werden; optionale sind mit der Bedingung * anzugeben oder einer geeigneten Spezifikation zu unterwerfen.
Es wird eine Fehlermeldung (class=error) zurückgegeben, wenn etwas nicht stimmt; sonst nichts.
Fatale Fehler führen in der folgenden Reihenfolge zum Abbruch: Unbekannter Parametername – fehlender Parameter – ungültiger Parameterwert.
Beispiele und Test.
Mittels der Funktion lässt sich durch einen einzigen Aufruf gleichzeitig für alle Parameter eine Prüfung ausführen auf
  • Pflichtparameter vorhanden?
  • keine unbekannten Parameternamen (Falschschreibung)?
  • gültige Werte für jeden Parameter?
Für jeden Parameternamen bei der Vorlageneinbindung muss mindestens eine Regel vorhanden sein. Gibt es für einen Vorlagenparameter keine Regel, ist er unbekannt und damit unzulässig.
  • Für denselben Parameternamen kann es mehrere Regeln geben. Die Einhaltung der Regeln wird in der Reihenfolge geprüft, in der sie vereinbart werden.
  • Die Reihenfolge der Parameternamen ist ohne Bedeutung.

valid

Überprüfung eines einzelnen Parameterwerts.
Eine Fehlermeldung wird mit class=error zurückgegeben.
Wenn nichts zurückgegeben wird, scheint alles in Ordnung zu sein.
Parameter (bis auf 1 alle optional):
1
Name des einzelnen Parameters.
2
Format („Nur Ziffern“, „ASCII“, begrenzter Zeichensatz, Lua-pattern); siehe unten.
min
Mindestlänge ≥0.
max
Maximale Länge >0.
low
Ignoriere Groß- und Kleinschreibung.
Aus der Gruppe 2, min, max sollte sinnvollerweise wenigstens eine angegeben werden.
Beispiele und Test.

Handhabung von Fehlern

Alle Funktionen, die auf einen Fehlerfall führen können (check, valid sowie downcase, verify), unterstützen auch die nachstehenden Parameter:

template
Titel der für Autoren sichtbaren Vorlage (für Fehlermeldungen).
Kann auch ein anderes Schlüsselwort sein; vor allem für Untervorlagen vorgesehen.
Ein Wikilink ist darin ebenfalls möglich; etwa auf eine bestimmte Doku-, Hilfe- oder Projektseite. (Hier wäre – anders als beim Titel – natürlich der Namensraum anzugeben.)
cat
Titel einer Wartungskategorie.
Im Fehlerfall wird diese aktiviert.
Mit errNS lässt sich die Kategorisierung auf bestimmte Namensräume beschränken.
Falls der Titel die Zeichenkette @@@ enthält und template gesetzt ist, wird dies durch template ersetzt.
errNS
Leerzeichen-getrennte Auflistung von Namensraum-Nummern, auf die cat beschränkt bleibt.
format
Fehlermeldung formatieren oder unterdrücken.
  • Standardfall, Standardmeldung mit class="error" formatiert:
    • Parameter format nicht angegeben.
    • |format=*|
  • Unterdrücken (dann sollte cat= gesetzt sein):
    • |format=|
    • |format=0|
    • |format=-|
  • Fester Text, eigene Formatierung:
    • |format=<anfang>Fester Text</ende>|
  • Freie Formatierung der Standardmeldung:
    • Enthält @@@ als Platzhalter für die unformatierte Standardmeldung.
    • |format=<anfang>Eigener Text; @@@</ende>|
preview
Unterdrückung der Fehlermeldung im Vorschaumodus unterdrücken, also trotz |format=0| usw. immer Standardmeldung anzeigen:
  • |preview=1|
Fester Text, eigene Formatierung im Vorschaumodus:
  • |preview=<anfang>Fester Text</ende>|
Standardmeldung in eigener Formatierung im Vorschaumodus:
  • |preview=<anfang>Standardmeldung: @@@</ende>|

Lua-Module liefern false bei fehlerfreier Analyse, ansonsten die Fehlermeldung.

Parameterprüfung (check)

Anwendungsfall für check am Beispiel der {{Information}}:

{{#invoke:TemplatePar
         |check
         |all= Beschreibung= Quelle= Urheber=
         |opt= Datum= Genehmigung= Andere Versionen= Anmerkungen=
         |template=[[Vorlage:Information]]}}
  • Weil der Name eines Vorlagenparameters kein Gleichheitszeichen = enthalten kann, werden diese zur Abtrennung der Namen benutzt. Leerzeichen vor und nach dem Namen werden ignoriert. Zusätzliche Gleichheitszeichen sind unproblematisch.
  • Die ersten drei Vorlagenparameter des Beispiels sind Pflichtparameter und müssen auch mit Wert angegeben werden.
  • Alle bei der Vorlageneinbindung benutzten Parameter, die weder unter all= noch opt= aufgeführt sind, lösen eine Fehlermeldung aus.
  • Die unbenannten Vorlagenparameter tragen ihre laufende Nummer als Namen; im Übrigen werden die Namen in der Fehlermeldung bezeichnet.
  • Es gibt vier Fehlermeldungen:
    1. #invoke:TemplatePar * Optionsparameter wiederholt
      • Beim Aufruf des Moduls wurde ein Name sowohl unter all= als auch opt= angegeben.
    2. Fehler bei Vorlage * Parametername unbekannt
      • Bei der Vorlageneinbindung wurde ein Parameter benutzt, der weder unter all= noch opt= aufgeführt ist.
    3. Fehler bei Vorlage * Pflichtparameter fehlt
      • Bei der Vorlageneinbindung fehlt ein unter all= aufgeführter Parameter.
    4. Fehler bei Vorlage * Pflichtparameter ohne Wert
      • Bei der Vorlageneinbindung ist ein unter all= aufgeführter Parameter nur mit Gleichheitszeichen, aber ohne sichtbaren Wert angegeben; oder ein unbenannter Parameter ist leer.
  • Die Fehlermeldungen sind hierarchisch gestaffelt. Bei einem Schreibfehler, der zu einem Problem höherer Ordnung führt, könnten die weiteren lediglich Folgefehler sein, die sich mit Korrektur des Grundproblems von selbst erledigen. Es wird daher nur die wichtigste gefundene Fehlerkategorie angezeigt.

Parameterformat (valid)

Für die optionale Bedingung 2 in valid gibt es zwei Grundtypen:

  1. Schlüsselwort
    • Erleichterung für Vorlagenprogrammierer; einige Ausdrücke mit Lua-Patterns nicht möglich.
    • Spezielle Datentypen wie URL, DOI, ISBN, Datum sind nicht erwünscht. Hier müssten bei jedem neuen Typ alle Artikel (mehrere Hunderttausend) neu zusammengestellt werden. Hingegen gibt es darauf spezialisierte Funktionen wie in URLutil.
  2. Lua-Pattern (Ustring)
    • Eingeschlossen in Schrägstriche, um sie von einem Schlüsselwort unterscheiden zu können und ggf. führende und schließende Leerzeichen bei Werten unbenannter Vorlagenparameter zu identifizieren.
    • Die Zeichenketten | sowie {{ und }} sind in der Vorlagenprogrammierung nicht möglich. Dafür sind zu ersetzen:
      • |%!
      • {{%((
      • }}%))

Zur Spalte Implementierung siehe Wikipedia:Hilfe:Lua/Zeichenketten #Pattern

Schlüssel für vereinfachten Zugriff
Schlüssel Bedeutung Implementierung
ASCII ASCII-Zeichen (Codes 32–126), nur innerhalb einer Zeile, oder leer ^[ -~]*$
ASCII+ wie vor; nicht leer ^[ -~]+$
ASCII+1 in einem Wort; sonst wie vor und nicht leer ^[!-~]+$
n Nur ASCII-Ziffern 0–9, sowie vorangestelltes Vorzeichen ASCII-Minus, oder leer ^[%-]?[0-9]*$
einzelnes Minus ausschließen
n>0 Nur ASCII-Ziffern 0–9, ohne Vorzeichen, nicht leer und mindestens eine Ziffer nicht Null ^[0-9]*[1-9][0-9]*$
N+ Wie n, aber führende Null nicht erlaubt und nicht leer ^[%-]?[1-9][0-9]*$
N>0 Wie n>0, aber führende Null nicht erlaubt ^[1-9][0-9]*$
x Hexadezimalzahl; ASCII-Ziffern 0–9 Buchstaben a–f A–F, oder leer ^[0-9A-Fa-f]*$
x+ wie vor; nicht leer ^[0-9A-Fa-f]+$
X Hexadezimalzahl; ASCII-Ziffern 0–9 Buchstaben A–F, oder leer ^[0-9A-F]*$
X+ wie vor; nicht leer ^[0-9A-F]+$
0,0 Beliebige Zahl; auch kleiner Null; kann Komma enthalten; oder leer ^[%-]?[0-9]*,?[0-9]*$
nicht nur Minus oder Komma
0,0+ Zahl mit Komma und Nachkommastelle; auch kleiner Null ^[%-]?[0-9]+,[0-9]+$
0,0+? Beliebige Zahl; auch kleiner Null; kann Komma und Nachkommastelle enthalten; nicht leer ^[%-]?[0-9]+,?[0-9]*$
0.0 Beliebige Zahl; auch kleiner Null; kann Dezimalpunkt enthalten; oder leer ^[%-]?[0-9]*[%.]?[0-9]*$
nicht nur Minus oder Punkt
0.0+ Zahl mit Dezimalpunkt und Dezimalstelle; auch kleiner Null ^[%-]?[0-9]+%.[0-9]+$
0.0+? Beliebige Zahl; auch kleiner Null; kann Dezimalpunkt und Dezimalstelle enthalten; nicht leer ^[%-]?[0-9]+[%.]?[0-9]*$
.0+ Beliebige Zahl; auch kleiner Null; kann Dezimalpunkt und Dezimalstelle enthalten, aber nicht notwendigerweise mit Ziffer davor; nicht leer ^[%-]?[0-9]*[%.]?[0-9]+$
aa Mindestens zwei Buchstaben (nicht nur nebeneinander: N.N.) oder ein CJK %a.*%a
oder CJK
ID Identifizierer unter Einschränkungen, wie sie für viele Sprachen üblich sind: ASCII, beginnend mit Buchstaben; weiter Ziffern und Unterstreichungsstrich; oder leer.
Die nachfolgenden ASCII-Wörter sind ebenfalls unter dem Aspekt solcher Bezeichner zu sehen; etwa als Komponente einer URL.
^[A-Za-z]?[A-Za-z_0-9]*$
ID+ wie vor; aber nicht leer. ^[A-Za-z][A-Za-z_0-9]*$
ABC Wort in ASCII-Großbuchstaben; oder leer. ^[A-Z]*$
ABC+ wie vor; aber nicht leer. ^[A-Z]+$
Abc Wort in ASCII-Buchstaben mit nur erstem Buchstaben groß; oder leer. ^[A-Z]*[a-z]*$
Abc+ wie vor; aber nicht leer. ^[A-Z][a-z]+$
abc Wort in ASCII-Kleinbuchstaben; oder leer. ^[a-z]*$
abc+ wie vor; aber nicht leer. ^[a-z]+$
aBc+ Wort in ASCII-Buchstaben mit lower camel casing; nicht leer. ^[a-z]+[A-Z][A-Za-z]*$
base64 Base64; oder leer. ^[A-Za-z0-9%+/]*$
base64+ wie vor; aber nicht leer. ^[A-Za-z0-9%+/]+$
pagename Zulässiger Seitenname; nicht leer. nicht #<>[]|{} oder 12710 oder 1–3110

file
file+
file:
file:+
image
image+
image:
image:+

Zulässiger Titel oder Name einer Mediendatei bei file (der Namensraum darf vorangestellt sein).

  • Mit + nicht leer.
  • Mit : muss die Mediendatei existieren.

Als image muss das Dateiformat für ein Einzelbild geeignet sein.

<nnnn
<=nnnn
>nnnn
>=nnnn
==nnnn
!=nnnn

Bedingung: Arithmetischer Vergleich oder (auch) numerische Ungleichheit
* leer oder beliebig
+
nichts
nicht leer %S
In Planung
date Irgendein bekanntes Format für Datum und auch Zeit.
 
Hier eher nicht vorgesehen
  • Vermutlich eher in einem Modul:WLink:
    • Name einer existierenden Seite
  • Basis-Datentypen
    • Datum, Zeit, URL, ISBN

Beispiele (Testseite)

Eine Testseite illustriert praktische Beispiele.

Funktionen für Lua-Module

Die Funktionen für Vorlagen sind geeignet erreichbar. Zur prinzipiellen Funktionalität siehe jeweils dort. Weitere Funktionen nur für Module kommen hinzu.

Einbindung über require():

local lucky, TemplatePar = pcall( require, "Modul:TemplatePar" )
if type( TemplatePar ) == "table" then
    TemplatePar = TemplatePar.TemplatePar()
else
    -- Fehlerfall; TemplatePar enthält Fehlermeldung
    return "<span class='error'>" .. TemplatePar .. "</span>"
end
TemplatePar.assert(analyze,append,options)
Analysiere eine Zeichenkette wie mit valid.
analyze
  • string; zu analysieren
append
  • string; Fehlermeldung anhängen; <br /> voranstellen, wenn nicht leer
  • sonst: Fehler werfen
options
table; Details; options und alle Komponenten optional
  • key
    string; Schlüsselwort
  • pattern
    string; Pattern
  • min
    number
  • max
    number
  • template
  • cat
  • errNS
  • format
  • preview
Rückgabewert: false, wenn in Ordnung; sonst Fehlermeldung
TemplatePar.check(options)
options
table; Details; options und alle Komponenten optional
  • mandatory
    table; sequence mit Namen der Pflichtparameter
  • optional
    table; sequence mit Namen der optionalen Parameter
  • low
    true: ignoriere Groß- und Kleinschreibung
  • template
  • cat
  • errNS
  • format
  • preview
Rückgabewert: false, wenn in Ordnung; sonst Fehlermeldung
TemplatePar.count()
TemplatePar.countNotEmpty()
TemplatePar.downcase(options)
Alle Vorlagenparameter in Kleinschreibung
Liefert table mit den .args (number bei unbenannten, string bei benannten Vorlagenparametern).
Fehlermeldung, wenn der gleiche Name in unterschiedlichen Schreibungen auftritt.
options
table; Details; options und alle Komponenten optional
  • template
  • cat
  • errNS
  • format
  • preview
TemplatePar.valid(seek, options)
seek
Zeichenkette; Name des Vorlagen-Parameters.
options
table; Details; options und alle Komponenten optional
  • key
    string; Schlüsselwort
  • pattern
    string; Pattern
  • min
    number
  • max
    number
  • low
    true: ignoriere Groß- und Kleinschreibung
  • template
  • cat
  • errNS
  • format
  • preview
key und pattern können nicht gleichzeitig angegeben werden.
Rückgabewert: false, wenn in Ordnung; sonst Fehlermeldung
TemplatePar.verify(options)
Wie TemplatePar.check(), jedoch Parameter des #invoke
TemplatePar()
Liefert table mit dem Zugriff auf die Funktionen.

Verwendung

Allgemeines Hilfsmittel; nicht eingegrenzt.

Abhängigkeiten

Keine.

Internationalisierung

Fehlermeldungen sind zurzeit in deutscher und englischer Sprache verfügbar, die sich automatisch nach der Projektsprache richten. Weitere Sprachen können hinzugefügt werden.

Die nicht-englischen Mitteilungen sollen als Systemnachrichten in MediaWiki: ausgelagert werden, um bei weiteren Sprachen und Umformulierungen nicht alle einbindenden Seiten neu aufbauen zu müssen. Sie werden bereits unterstützt und haben Vorrang vor den im Modul deklarierten Texten.

Systemnachrichten Modul:TemplatePar/I18N
Dieser Artikel basiert auf einer für AnthroWiki adaptierten Fassung des Artikels Modul:TemplatePar/Doku aus der freien Enzyklopädie de.wikipedia.org und steht unter der Lizenz Creative Commons Attribution/Share Alike. In Wikipedia ist eine Liste der Autoren verfügbar.