Extension:ParserFunctions/String functions/de

Die Erweiterung StringFunctions bietet einen zusätzlichen Satz Parser-Funktionen, welche Zeichenketten bearbeiten. Die Version 2.0 behebt Probleme mit &lt;nowiki> und lässt die Notwendigkeit entfallen, auf dem Server die PHP-Erweiterung mbstring installiert zu haben.

Funktionen
Dieses Modul definiert die Funktionen: len, pos, rpos, sub, pad, replace, explode, urlencode und urldecode</tt>.

Alle diese Funktionen laufen mit der Zeitkomplexität $$\mathcal{O}(n)$$, was vor DoS-Attacken schützt.


 * 1) Zur Vorbeugung von Missbrauch unterliegen einige Parameter Begrenzungen. Siehe Abschnitt Begrenzungen unten.
 * 2) Für Funktionen, die unerwünschterweise Groß- und Kleinschreibung unterscheiden, kann das Magic Word ausdruck verwendet werden.

#len:
Die Funktion #len gibt die Länge der eingegebenen Zeichenkette aus. Beispiel:


 * → 8


 * Leerzeichen am Ende werden nicht mitgezählt. Beispiel:  → 12
 * Zeichen werden ordnungsgemäß gezählt, auch wenn sie in UTF-8 mehrere Bytes einnehmen. Beispiel:  → 8.
 * Tags wie &lt;nowiki> werden samt Inhalt nicht mitgezählt, weil sie vor dem Parser versteckt sind. Beispiel:  → 4.

#pos:
Die Funktion #pos gibt die Position eines gegebenen Suchbegriffs innerhalb der Zeichenkette aus.



Der Parameter Suchbeginn ist optional und teilt der Funktion mit, ab welcher Stelle gesucht werden soll.

Wird der Suchbegriff gefunden, so wird die Stellennummer des ersten Zeichens seines ersten Auftauchens innerhalb der Zeichenkette ausgegeben. Die erste Stelle wird dabei mit 0 nummeriert. Wird der Suchbegriff nicht gefunden, wird nichts ausgegeben. Damit ist die Funktion auch ideal für den Test, ob die Zeichenkette den Suchbegriff überhaupt enthält.

Beispiele:
 * → 9
 * → 24


 * Diese Funktion unterscheidet Groß- und Kleinschreibung.
 * Die maximale Länge des Suchbegriffes ist in $wgStringFunctionsLimitSearch festgelegt.
 * Zeichen werden ordnungsgemäß gezählt, auch wenn sie in UTF-8 mehrere Bytes einnehmen. Beispiel:  → 4.
 * Wiki-Tags wie &lt;nowiki> werden mitsamt ihrem Inhalt als eine einzige Stelle gezählt:  → 1.

#rpos:
Die Funktion #rpos durchsucht eine Zeichenkette vom Ende an nach einem Suchbegriff.

Es wird die Stelle ausgegeben, an der der Suchbegriffs das letzte Mal innerhalb der Zeichenkette auftaucht. Dabei bedeutet 0 die letzte Stelle der Zeichenkette, und pro Schritt Richtung Anfang erhöht sich die ausgegebene Zahl um 1. Wenn der Suchbegriff nicht gefunden wird, wird -1 ausgegeben.


 * Diese Funktion unterscheidet Groß- und Kleinschreibung.
 * Die maximale Länge des Suchbegriffes ist in $wgStringFunctionsLimitSearch festgelegt.
 * Zeichen werden ordnungsgemäß gezählt, auch wenn sie in UTF-8 mehrere Bytes einnehmen. Beispiel:  → 4.
 * Wiki-Tags wie &lt;nowiki> werden mitsamt ihrem Inhalt als eine einzige Stelle gezählt:  → 1.

#sub:
Die Function #sub gibt ein Teilstück einer Zeichenkette aus. Die Syntax ist:

Der Start-Parameter gibt die erste Stelle des gewünschten Teilstücks innerhalb der Zeichenkette an. Dabei bezeichnet 0 die erste Stelle der Zeichenkette. Beispiel:
 * → beereis</tt>
 * → Erdbeereis</tt>.

Wenn der Start-Parameter negativ ist, wird vom Ende der Zeichenkette aus gezählt. Die letzte Stelle entspricht dabei -1. Beispiel:
 * → eis</tt>.

Der Parameter Länge legt die Maximallänge des auszugebenden Teilstücks fest. Beispiel:
 * → beer</tt>.

Wenn der Parameter Länge negativ ist, werden entsprechend viele Stellen vom Ende des Teilstücks abgeschnitten. Beispiel:
 * → bee</tt>.


 * Die Längenangabe 0 wird ignoriert.
 * Beispiel:  → becher</tt>
 * Wenn der Parameter Länge negativ und der Start-Parameter zu groß ist, wird nichts ausgegeben.
 * Beispiel:  →
 * Zeichen werden ordnungsgemäß gezählt, auch wenn sie in UTF-8 mehrere Bytes einnehmen. Beispiel:  → žlina</tt>.
 * Wiki-Tags wie &lt;nowiki> werden mitsamt ihrem Inhalt als eine einzige Stelle gezählt:  → Test</tt>.
 * Wenn die ursprüngliche Zeichenkette einen Doppelpunkt enthält ("etwa:so") und nun das gesamte Teilstück vor dem Doppelpunkt entfernt wird, so (miss)versteht MediaWiki dies gegebenenfalls als Einrückung.

#pad:
Die Funktion #pad verlängert eine gegebene Zeichenkette auf eine bestimmte Länge. Die Syntax lautet:

Der Parameter Länge gibt die gewünschte Endlänge der Zeichenkette an.

Der Parameter Füllmaterial, falls angegeben, wird benutzt, um die fehlenden Stellen auszufüllen. Er kann aus einem einzelnen oder aus mehreren Zeichen bestehen, und wird so lange wiederholt, bis die Lücken aufgefüllt sind. Beispiel:
 * → xXxXxXxEis</tt>.

Wenn kein Füllmaterial angegeben wird, werden Leerzeichen zum Auffüllen verwendet.

Der Richtungs-Parameter kann einen der folgenden Werte annehmen:
 * left</tt> - es wird auf der linken Seite der Zeichenkette aufgefüllt. Beispiel:  → xxEis</tt>.
 * right</tt> - es wird auf der rechten Seite der Zeichenkette aufgefüllt. Beispiel:  → Eisxx</tt>.
 * center</tt> - die eingegebene Zeichenkette wird in der ausgegebenen zentriert. Beispiel:  → xEisx</tt>.

Standardwert ist <tt>left</tt>.

Die Funktion füllt nun die gegebene Zeichenkette mit dem Füllmaterial bis auf die angegebene Länge auf. Wenn die Zeichenkette bereits länger als die gewünschte Ziellänge ist, wird sie nicht verändert.


 * Der Maximalwert für den Parameter Länge ist in $wgStringFunctionsLimitPad festgelegt.
 * Diese Funktion kann nur teilweise mit Zeichen umgehen, die in UTF-8 mehrere Bytes einnehmen. In der ursprünglichen Zeichenkette werden sie wie normale Zeichen behandelt, im Füllmaterial allerdings nicht:
 * → zzzzZmrzlina
 * → zzzzŽmržlina
 * → žžŽmržlina
 * Wiki-Tags wie &lt;nowiki> werden nicht unterstützt. Wenn solche Tags in der Zeichenkette enthalten sind, werden sie entfernt.

#replace:
Die Funktion #replace ersetzt in einer gegebenen Zeichenkette einen Suchbegriff durch einen Ersetzungsbegriff. Es werden alle Auftritte des Suchbegriffes ersetzt.

Wenn kein Ersetzungsbegriff angegeben wird, wird der Suchbegriff aus der Zeichenkette entfernt.


 * Diese Funktion unterscheidet Groß- und Kleinschreibung. Zur Umgehung kann nur  benutzt werden, wodurch aber auch das Resultat durchgängig kleingeschrieben ist.
 * Die maximale Länge des Suchbegriffes ist in $wgStringFunctionsLimitSearch festgelegt.
 * Die maximal erlaubte Länge des Parameters ersetzen durch wird durch die globale Variable $wgStringFunctionsLimitReplace festgelegt.
 * Auch wenn bei ersetzen durch ein Leerzeichen angegeben wird, wird der Suchbegriff lediglich entfernt. Dies ist ein Nebeneffekt des MediaWiki-Parsers. Um ein Leerzeichen als Ersetzungsparameter zu benutzen, muss es in nowiki-Tags gesetzt werden.
 * Beispiel:  → <tt>Meine kleine feine Seite</tt>.
 * Bitte beachten: Dies ist die einzig akzeptable Verwendung von nowiki im Parameter ersetzen durch, da sonst nowiki benutzt werden könnte, um $wgStringFunctionsLimitReplace zu umgehen und eine große Anzahl Leerzeichen einzuschleusen. Daher wird der Inhalt von nowiki-Tags immer durch ein einzelnes Leerzeichen ersetzt.
 * Auch diese Funktion kann problemlos mit UTF-8-Multibyte-Zeichen umgehen. Beispiel:  → <tt>Žmrzlina</tt>.

#explode:
Die Funktion #explode teilt eine gegebene Zeichenkette in Abschnitte und gibt einen dieser Abschnitte aus. Die Syntax ist:

Als zweiter Parameter (Trennmarke) ist das Zeichen oder die Zeichenkette anzugeben, an dem die Teilung erfolgen soll. Diese Trennmarke ist dann nicht Teil eines Abschnittes. Wenn zwei solche Trennmarken in der Ausgangszeichenkette direkt hintereinander auftauchen, so ensteht ein leerer Abschnitt zwischen ihnen. Wenn dieser Parameter nicht angegeben wird, wird ein einfaches Leerzeichen als Trennmarke genutzt.

Der dritte Parameter legt fest, welcher der Abschnitte ausgegeben werden soll. Abschnitte werden von 0 an durchnummeriert. Wenn dieser Parameter nicht angegeben wird, wird der erste Abschnitt (Nr. 0) ausgegeben. Wenn ein negativer Wert eingegeben wird, so werden die Abschnitte von hinten gezählt. In diesem Fall entspricht -1 dem letzten Abschnitt. Wenn der Abschnitt mit der eingegebenen Nummer nicht existiert, wird nichts ausgegeben. Beispiele:
 * → <tt>du</tt>
 * → <tt>Fotos</tt>
 * → <tt>geteilt</tt>


 * Diese Funktion unterscheidet Groß- und Kleinschreibung.
 * Die maximale Länge der Trennmarke ist in $wgStringFunctionsLimitSearch festgelegt.
 * Zeichen werden auch korrekt gezählt, wenn sie ihn UTF-8 mehrere Bytes einnehmen. Beispiel:  ergibt <tt>lina</tt>.

#urlencode: und #urldecode:
Diese zwei Funktionen arbeiten zusammen: #urlencode konvertiert eine Zeichenkette in eine URL-kompatiblen Syntax, während #urldecode eine solche Zeichenkette zurückkonvertierten kann. Die Syntax ist einfach:


 * Diese Funktionen arbeiten, indem sie direkt die PHP-Funktionen urlencode und urldecode weitergeben.
 * Für Anker innerhalb einer Seite sollte anstelle von  genutzt werden. Die Ergebnisse von  sind kompatibel mit Links innerhalb von Seiten wie , während  -generierte Werte dies nicht unbedingt sind.

Begrenzungen
Dieses Modul definiert drei globale Einstellungen:
 * <tt>$wgStringFunctionsLimitSearch</tt>
 * <tt>$wgStringFunctionsLimitReplace</tt>
 * <tt>$wgStringFunctionsLimitPad</tt>

Sie dienen dazu, die Funktionen mit der Zeitkomplexität $$\mathcal{O}(n)$$ laufen zu lassen, was vor DDoS-Attacken schützt.

$wgStringFunctionsLimitSearch
Diese Variable wird bei #pos, #rpos, #replace und #explode benutzt. All diese Funktionen suchen nach einem Suchbegriff in einem Text, was mit O(n*m) laufen könnte und die Software damit anfälliger für DDoS-Attacken machen würde. Durch Festlegung dieser Variable auf einen bestimmten, kleinen Wert wird die Senkung auf O(n) erreicht.

Diese Einstellung beschränkt die Höchstlänge des Suchbegriffs.

Der Standardwert sind 30 Multibyte-Zeichen.

$wgStringFunctionsLimitReplace
Diese Variable wird bei #replace benutzt. Diese Funktion ersetzt alle Vorkommen eines Suchbegriffs durch einen anderen, was genutzt werden könnte, um in kurzer Zeit sehr große Datenmengen zu generieren, und die Software damit anfällig für DDoS-Attacken machen würde.

Diese Einstellung beschränkt die Höchstlänge des Ersetzungsbegriffs.

Der Standardwert sind 30 Multibyte-Zeichen.

$wgStringFunctionsLimitPad
Diese Variable wird bei #pad benutzt. Diese Funktion erzeugt eine Zeichenkette mit einer gewünschten Länge, was genutzt werden könnte, um in kurzer Zeit sehr große Datenmengen anzufordern, und die Software damit anfällig für DDoS-Attacken machen würde.

Diese Einstellung beschränkt die Höchstlänge der fertigen Zeichenkette.

Der Standardwert sind 100 Multibyte-Zeichen.

Installation
Diese Erweiterung erfordert MediaWiki 1.7+ und PHP 5.

Für die Installation in MediaWiki sind folgende Schritte vorzunehmen:
 * 1) Kopiere den Quelltext von SVN</tt><BR>...oder, falls du Kommandozeilen-Zugriff hast, kopiere ihn direkt per: <BR>svn co http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/StringFunctions/</tt>
 * 2) Füge der <tt>LocalSettings.php</tt> im Stammverzeichnis deiner MediaWiki-Installation folgendes hinzu:

Versionsgeschichte
StringFunctions 2.0 wurde mit MediaWiki 1.7 und höher erfolgreich getestet.

Versionsgeschichte:
 * Nov 30, 2008 -- v2.0.3 -- Angepasst an Parser-Veränderungen bei MediaWiki 1.14
 * Oct 27, 2008 -- v2.0.2 -- Beschreibung der Erweiterung internationalisiert.
 * Aug 27, 2008 -- v2.0.1 -- Verwendung von regexp bei #len hinzugefügt.
 * May 11, 2008 -- v2.0 -- StringFunctions werden nun bei SVN gepflegt.
 * Dec 10, 2007 -- v2.0 -- Funktionen neu geschrieben, um von mbstring unabhängig zu sein und um mit &lt;nowiki> u.ä. korrekt umgehen zu können.
 * Aug 28, 2007 -- v1.10 -- Negative Stellen zu #explode hinzugefügt.
 * Jan 30, 2007 -- v1.9 -- Obergrenzen für #pos, #pad, #replace, #explode hinzugefügt.
 * Oct 30, 2006 -- v1.8 -- Angepasst an MediaWiki 1.8.
 * Oct 26, 2006 -- v1.6 -- Leerzeichen bei #rpos und #replace repariert.
 * Oct 1, 2006 -- v1.5 -- #rpos, #pad, #replace, #explode hinzugefügt.
 * May 18, 2006 -- v1.2 -- #toURL und #fromURL umbenannt, um sie auf die MediaWiki-Funktion &#123;&#123;urlencode:}} abzustimmen.
 * May 18, 2006 -- v1.1 -- #pos hinzugefügt.
 * May 15, 2006 -- v1.0 -- Erste stabile Version.

Siehe auch

 * DynamicFunctions (en)
 * StringFunctionsEscaped (en) - dort können auch Escape-Zeichen verwendet werden (z. B. \n, \t, …)
 * ReplaceSet (en) - ein guter Ersatz für verschachelte #replace-Befehle
 * ParserFunctions
 * Hilfe zu ParserFunctions
 * RegexParserFunctions (en)
 * VariablesExtension (en)