Vorlage:?n-ary

[Bearbeiten] Vorlagen-Dokumentation

Diese Vorlage zeichnet sich durch ihre hohe Komplexität aus. Wenn du die Auswirkungen genau kennst, kannst du sie bearbeiten. Danach sollte die Vorlage ausführlich getestet werden.

Diese Vorlage dient dazu, ein Array mit N-Ary-Werten zu durchsuchen und alle Treffer als Array mit N-Ary-Werten zurück zu geben. Als Array wird dabei eine Aneinanderkettung von SMW:Semantic Mediawiki Attributewerten verstanden, getrennt durch ein Komma. Die N-Ary-Werte werden innerhalb der einzellnen Array-Einträge durch ein Semikolon seperiert. Anstelle von Komma und Semikolon können auch alternative Trennzeichen angegeben werden.

Des Weiteren können mit der Vorlage alle Arrayeinträge bestehend aus N-Ary-Werte neu strukturiert, erweitert und gekürzt werden. Der Begriff N-Ary wurde in SMW 1.5 gegen den Datentyp Record ausgetauscht. Im RPG-Dev-Wiki bleibt der Begriff N-Ary erhalten.

Kopiervorlage

Für die meisten Anwendungen sollte folgende Vorlage ausreichen:

{{?n-ary |Array= |Suche= |Ausgabe=}}

Vollständige Kopiervorlage:

{{?n-ary
| Name = 
| Array = 
| Suche = 
| Ausgabe = 
| Case Sensitive = nein
| Unique = 
| Offset = 0
| Limit = 
| ArraySep = 
| NArySep = 
}}

Anwendung

Durchsuchen eines Arrays

Für den Suchausdruck kann ein regulärer Ausdruck verwendet werden, indem der Parameterwert mit / beginnt, gefolgt von einem regulären Ausdruck und einem abschließenden / hinter dem eventuell weiter Argumente wie i für ignore case. Alternativ kann aber auch eine vereinfachter Suchsyntax verwendet werden, eine Art vereinfachte reguläre Ausdrücke.

Suche mit vereinfachten Suchausdrücken

Diese Möglichkeit birgt den Vorteil in sich, dass sie einfacher zu verstehen und anzuwenden ist, jedoch etwas performancelastiger ist da der angegebene Suchausdruck erst interpretiert werden muss. Im Normalfall dürfte dies jedoch keine große Rolle spielen. Entwickler die diese Vorlage für größere Vorlagen verwenden möchten sollte jedoch eher auf die Möglichkeit mit regulären Ausdrücken zurückgreifen.

Folgende Zeichenfolgen haben in den vereinfachten Suchausdrücken eine spezielle Bedeutung:

• + steht für eine Menge von 0 bis ∞ Zeichen bestehend aus jedem beliebigen Zeichen außer dem Trennzeichen der N-Ary-Werte.
• ++ steht für eine Menge von 1 bis ∞ Zeichen bestehend aus jedem beliebigen Zeichen außer dem Trennzeichen der N-Ary-Werte.
• * steht für eine Menge von 0 bis ∞ Zeichen bestehend aus jedem beliebigen Zeichen inklusive dem Trennzeichen der N-Ary-Werte.
• ** steht für eine Menge von 1 bis ∞ Zeichen bestehend aus jedem beliebigen Zeichen inklusive dem Trennzeichen der N-Ary-Werte
• # steht für jede ganze Zahl (Keine Nachkommastellen, keine Tausendertrennzeichen erlaubt).
• Mit {{!}} können alternative Suchausdrücke angegeben werden.

Angenommen das Trennzeichen für N-Ary-Werte ist wie standardmäßig definiert ein ;, so sind beispielsweise folgende Ausdrücke möglich:

• +;+;20;++ Findet alle Arrayeinträge deren erster beiden N-Ary-Werte einen beliebigen (auch leeren) Wert haben und deren dritter N-Ary-Wert 20 ist, außerdem muss ein vierte N-Ary-Wert vorhanden sein der nicht leer sein darf.
• **;# Findet alle Arrayeinträge deren letzter N-Ary-Wert gleich einer beliebigen ganzen Zahl ist, wobei vorher noch etwas außer einem leeren N-Ary-Wert existieren muss. Z.B. ein gefüllter oder auch zwei leere N-Ary-Werte.
• *;#;* Findet alle Arrayeinträge die einen N-Ary-Wert haben der einer ganzen Zahl entspricht, der jedoch nicht der erste oder letzte N-Ary-Wert sein darf.
• *;20;*{{!}}20;*{{!}}*;20 Findet alle Arrayeinträge die den N-Ary-Werte 20 irgendwo im gesamten N-Ary haben.

Damit auch nach den Zeichen mit besonderer Bedeutung gesucht werden kann müssen diese mit \ escaped werden. Dies betrifft die Zeichen ( ) + * ? | \ #. Escaped entspricht das \( \) \+ \* \? \| \\ \#. Für ein automatisches Escapen existiert die Vorlage Vorlage:?n-ary/Quote.

Suche mit regulären Ausdrücken

Diese Möglichkeit ist in der Ausführung etwas schneller als die Suche mit vereinfachten Suchausdrücken und sollte von Vorlagen-Entwicklern bevorzugt werden. Ein regulärer Ausdruck muss zu regulären Ausdrücken in Perl kompatibel sein und zwischen einem einleitenden / und einem abschließenden / stehen. Dahinter können ggf. Parameter wie in Perl folgen, beispielsweise ein i für Case Insensitive-Suche.

Mit den alternativen Suchausdrücken sollte bereits fast alles möglich sein, sehr komplexe Ausdrücke lassen sich jedoch manchmal nur als regulärer Ausdruck realisieren. Zudem ist die Ausführungsgeschwindigkeit von regulären Ausdrücken ein klein wenig kürzer da der alternative Ausdruck erst interpretiert werden muss. Vorlagen-Entwickler sollten also gerade bei komplexeren Ausdrücken auf reguläre Ausdrücke ausweichen.

Umstrukturieren von N-Ary-Werten

Zusätzlich zu der Suche ist es zusätzlich möglich die gefundenen Arrayeinträge zu bearbeiten. Das heist die einzelnen Arrayeinträge bestehend aus N-Ary-Werten können umstrukturiert, erweitert und/oder gekürzt werden. Möchte man dies mit der Vorlage erreichen, so gilt für den oben beschriebenen Suchausdruck eine weitere Regel.

• Mit Hilfe der runden Klammern ( und ) ist es möglich innerhalb des Suchausdrucks Gruppierungen zu definieren.

Gruppierungen haben keine Auswirkung auf die Suche, speichern jedoch den umklammerten Wert als Zwischenergebnis, auf das im nächsten Schritt wieder zugegriffen werden kann. Dazu wird der Parameter Ausgabe benötigt. In diesem Parameter kann die neue Struktur der gefundenen Arrayeinträge definiert werden. Die Struktur wird durch die Neuanordnung und/oder Erweiterung der in den runden Klammern gefundenen Wert beeinflusst. Die erste Klammer-Gruppierung hat den Index 1, die Zweite 2, die Dritte 3 und so weiter. Auf die Gruppierungen kann im Parameter Ausgabe durch $Gruppen-Index zugegriffen werden. Beispielsweise Ausgabe=$1;$2.

Angenommen das Trennzeichen für N-Ary-Werte ist wie standardmäßig definiert ein ;, so sind beispielsweise folgende Kombinationen möglich:

• |Suche=(*);+ und |Ausgabe=$1 kürzt die N-Ary-Werte um den letzten N-Ary-Wert.
• |Suche=(+);(+);(+);(+) und |Ausgabe=$2;$1;$4;$3 vertauscht den ersten mit dem zweiten N-Ary-Wert und den Dritten mit dem Vierten.
• |Suche=(+);* und |Ausgabe=[[$1]] erzeugt ein einfaches Array ohne N-Ary-Werte in dem alle Arraywerte als Links formatiert sind.
• |Suche=(+);(*);(+) und |Ausgabe=$1 und $3;$2 erzeugt aus dem ersten und letzten N-Ary-Wert einen einzelnen Wert verknüpft durch ein und im Wert. Alle anderen N-Ary-Werte werden wie gehabt übernommen.

Auf die $-Ergebnisse können zum Teil auch Vorlagen angewandt werden, jedoch nur solche, die etwas um das Ergebnis herum bauen und keinen String erwarten der verarbeitet werden soll, da die Ersetzung der Marker erst am Ende stattfindet. Parserfunktionen wie #len können also nicht auf die Ergebnisse angewandt werden.

Erweitertes

Gierigkeit von Ausdrücken bei alternativen Ausdrücken

Dieser Abschnitt ist für die erweiterte Anwendung gedacht. Wie man bei komplizierteren Ausdrücken schnell merken wird, können diese teilweise mehrdeutig sein. Der Suchausdruck *;+(#)+;* zum Beispiel, der prüft ob einer der mittleren N-Ary-Werte eine Zahl enthält die optional von Text umgeben ist. Zurückgegeben werden soll die Zahl. Das Problem hierbei jedoch ist, dass + (so wie auch *) ebenfalls Zahlen als Treffer versteht und diese dem # wegnehmen könnte, was als gierig verstanden wird. Aus diesem Grund sind *, **, + und ++ standardmäßig ungierig, lassen also dem gierigen # den vorrang. Möchte man dieses Verhalten invertieren, so kann hinter den einzelnen Teilausdrücken wie * ein ? anhängen. Beispiel: *;(+);* Gibt den zweiten N-Ary-Wert zurück. *?;(+);* Gibt den vorletzten N-Ary-Wert zurück weil erstes * mit ? auf gierig umgeschalten wurde und so viele Zeichen erfasst, wie es ihm möglich ist ohne dass der Ausdruck fehlschlägt.

Anwendung mit der Vorlage Vorlage:SMW-AskToArray

Die Anwendung dieser Vorlage macht vor allem Sinn zusammen mit der Vorlage Vorlage:SMW-AskToArray, die es ermöglicht ein SMW-Ask-Query zu definieren das ein oder mehrere Attribute von beliebig vielen Seiten zurückgibt, wobei die vom Query zurückgegebenen Attribute schließlich in ein Array gespeichert und zurückgegeben werden.

Das dadurch erhaltene Array lässt sich über diese Vorlage einfach anpassen, somit wird möglich, was SMW nicht möglich ist, der Umgang mit Many-Valued Properties und N-Ary-Werten in Query-artigen Abfragen.

Parameter

Fett markierte Parameter sind Pflichtangaben, die unbedingt einen Wert enthalten müssen, um die Vorlage sinnvoll verwenden zu können. An einige Parameter können mehrere Werte übergeben werden, in der Regel getrennt durch ein Komma. Diese Werte werden im Nachfolgenden durch eine Unterstreichung hervorgehoben.

Diese Dokumentation wird von einer Unterseite eingebunden. Anwendungsbeispiele und Funktionalitätsprüfungen können auf der Testseite gemacht werden. Verwendung der Vorlage in Artikeln.