XSLT-SB 0.2.50: Bessere Dokumentation und neue Funktionen


XSLT-SB im Google-Code-Wiki

XSLT-SB im Google-Code-Wiki

Heute habe ich Release 0.2.50 der XSLT-SB veröffentlicht. Neben einigen neuen Funktionen bringt das Release vor allem eine stark verbesserte Dokumentation im Goolge-Code-Wiki. Zu jeder Funktion und zu jedem Template gibt es jetzt eine Einzelseite mit Beschreibung, Implementierung und Verweisen auf benutzte XSLT-SB-Funktionen und -Templates. Damit ist ein sehr einfacher Zugang zum Code – auch außerhalb der kompletten Stylesheets – möglich. Hier je ein Beispiel für eine Funktion und für ein Template.

Die neuen Funktionen – xsb:sort(), xsb:replace(), xsb:integer-to-hex(), xsb:hex-to-integer(), xsb:twos-complement(), xsb:reverse-twos-complement(), xsb:fill-left(), xsb:fill-right(), xsb:escape-for-regex(), xsb:escape-for-replacement(), xsb:count-matches(), xsb:index-of-first-match() und xsb:decode-from-url() haben sich im Laufe einiger Projekte bei mir angesammelt und sind nun in die XSLT-SB gewandert; einige möchte ich im Folgenden näher beschreiben.

xsb:sort()

Diese Funktion sortiert atomic values, also Zahlen, Strings usw. Das Fehlen dieser Funktion in den XPath-Funktionen ist ein Rätsel, deshalb liefert der XSLT-Standard wohl das Gerüst der Implementierung – als Wrapper für xsl:perform-sort – gleich mit. Ich habe das Beispiel um die Möglichkeit ergänzt, die Reihenfolge (aufsteigend/absteigend, englisch ascending/descending) in Funktionsaufruf zu übergeben. Das sieht dann so aus:

<xsl:function name="xsb:sort" as="xs:anyAtomicType*" intern:solved="EmptySequenceAllowed">
	<xsl:param name="input-sequence" as="xs:anyAtomicType*"/>
	<xsl:param name="order" as="xs:string"/>
	<xsl:perform-sort select="$input-sequence">
		<xsl:sort select="." order="{$order}"/>
	</xsl:perform-sort>
</xsl:function>

Sortiert werden können nur Werte, die mit dem lt-Operator verglichen werden können, also nur Sequenzen aus Strings, Zahlen, Daten; nicht aber gemischte Sequenzen aus diesen Typen. Gemischte Sequenzen können aber auf string gecastet werden, etwa mit for $i in $sequence return string($i).

Zur bequemeren Benutzung gibt es auch eine Version mit nur einem Argument, dann ist die Reihenfolge auf aufsteigend resp. ascending festgelegt.

xsb:index-of-first-match()

Diese Funktion ermittelt die Position des ersten Auftretens eines RegEx-Patterns in einem String. Mit fn:tokenize() wird der erste Teilstring vor dem Pattern ermittelt und zu dessen Länge 1 addiert:

<xsl:function name="xsb:index-of-first-match" as="xs:integer">
	<xsl:param name="input" as="xs:string?"/>
	<xsl:param name="pattern" as="xs:string?"/>
	<xsl:param name="flags" as="xs:string?"/>
	<xsl:choose>
		<xsl:when test="normalize-space($pattern) and matches($input, $pattern, $flags)">
			<xsl:sequence select="string-length(tokenize($input, $pattern, $flags)[1]) + 1"/>
		</xsl:when>
		<xsl:otherwise>0</xsl:otherwise>
	</xsl:choose>
</xsl:function>

Auch hier gibt es wieder die »bequeme« Version ohne flags.

xsb:replace()

xsb:replace() erweitert fn:replace() um die Möglichkeit, Listen (genauer Sequenzen) als Argumente für Such-Pattern und Ersetzungszeichenfolgen zu übergeben. Das ist praktisch, wenn in einem String paarweise verschiedene Fundstellen durch korrespondierende Texte ersetzt werden sollen, also z.B. alle »Jan.« durch »Januar«, »Feb.« durch »Februar«, »Apr.« durch »April« usw. Ohne benutzerdefinierte Funktionen müssen mehrere fn:replace() geschachtelt werden, es entstehen dann Ungetüme wie:

replace(
	replace(
		replace($input,
			'Apr\.', 'April'),
		Feb\.', 'Februar'),
	'Jan\.', 'Januar')

Viel übersichtlicher ist es dann doch so:

xsb:replace($input,
	('Jan\.', 'Feb.\', 'Apr\.'),
	('Januar', 'Februar', 'April') )

Neben der Übersichtlichkeit ist ein zweiter wesentlicher Vorteil, dass mit xsb:replace() die Länge der Sequenzen resp. die Anzahl der Ersetzungspaare nicht schon beim Schreiben des Stylesheets bekannt sein müssen. Dazu folgt weiter unter ein Beispiel. Aber erst noch ein paar Worte zur Implementierung, die so aussieht:

<xsl:function name="xsb:replace" as="xs:string">
	<xsl:param name="input" as="xs:string?"/>
	<xsl:param name="pattern" as="xs:string*"/>
	<xsl:param name="replacement" as="xs:string*"/>
	<xsl:param name="flags" as="xs:string?"/>
	<xsl:choose>
		<xsl:when test="exists($pattern[1])">
			<xsl:sequence select="
				xsb:replace(
					if (boolean($pattern[1]) )
						then replace($input, $pattern[1], string($replacement[1]), $flags)
						else $input,
					$pattern[position() gt 1],
					$replacement[position() gt 1],
					$flags
				)"/>
		</xsl:when>
		<xsl:otherwise>
			<xsl:sequence select="concat('', $input)"/>
		</xsl:otherwise>
	</xsl:choose>
</xsl:function>

Es handelt sich um eine rekursive Funktionsdefinition. Die Implementierung ist nicht ganz geradlinig, weil Leerstrings und Leersquenzen sinnvoll behandelt werden müssen. Der Reihe nach:

  • exists($pattern[1]) testet, ob ein weiteres pattern-Argument vorhanden ist. Wichtig ist, dass fn:exists() (im Unterschied zu fn:boolean()) den Leerstring zu true() evaluiert. Ist kein weiteres pattern-Argument vorhanden, sind die Ersetzungen abgeschlossen, und das Ergebnis der Funktion wird im xsl:otherwise-Zweig zurückgegeben. (Das Ergänzen eines Leerstrings dort stellt sicher, dass keine Leersequenz, sondern mindestens ein Leerstring ausgegeben wird.)
  • Wenn ein weiteres pattern-Argument (das auch ein Leerstring sein kann) vorhanden ist, wird xsb:replace() rekursiv aufgerufen
    • Für das zu übergebende input-Argument wird mit boolean($pattern[1]) geprüft, ob das aktuelle Such-Pattern Zeichen enthält, und nur in diesem Fall wird ein fn:replace() mit den aktuellen pattern und replacement aufgerufen. Im Fall eines Leerstrings wird input unverändert weitergereicht. Diese Akrobatik ist notwendig, weil der Leerstring kein gültiger Suchstring in fn:replace() ist, ich mir aber an dieser Stelle etwas Fehlertoleranz gewünscht habe.
    • Die in den pattern– und replacement-Sequenzen auf den jeweils ersten Wert folgenden Werte werden als neue pattern und replacement übergeben. Wenn keine weiteren Argumente vorhanden sind, wird halt eine Leersequenz weitergereicht, was im Fall von pattern im nächsten Durchlauf zum Abbruch der Rekursion und zur Ausgabe der Ergebnisses führt.
    • flags wird unverändert durchgereicht.

Leerstrings in der pattern-Sequenz werden als »nichts suchen« interpretiert und samt dem zugehörigen replacement übersprungen.

Sind mehr pattern-Werte als replacement-Werte vorhanden, werden die Fundstellen der »überzähligen« pattern-Werte gelöscht: xsb:replace('Affe Bär Elefant', ('Affe', 'Elefant') , ('monkey') ) ergibt »monkey Bär «. Dieses Verhalten entspricht dem des guten alten fn:translate().

xsb:replace kann man wunderbar zum Suchen-und-Ersetzen an Hand einer Ersetzungstabelle verwenden. Im folgenden Beispiel wird die Ersetzungstabelle als externes Dokument verwaltet, dass ggfs. unabhängig vom Stylesheet bearbeitet werden kann.

Ersetzungstabelle (search-and-replace_list.xml):

<root>
	<pair>
		<pattern>Affe</pattern>
		<replacement>monkey</replacement>
	</pair>
	<pair>
		<pattern>Wolf</pattern>
		<replacement>wolf</replacement>
	</pair>
</root>

Stylesheet:

<xsl:stylesheet
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:xs="http://www.w3.org/2001/XMLSchema"
	xmlns:xsb="http://www.expedimentum.org/XSLT/SB"
	exclude-result-prefixes="xs xsb"
	version="2.0">
	<xsl:import href="strings.xsl"/>
	<xsl:param name="search-and-replace-list">search-and-replace_list.xml</xsl:param>
	<xsl:template match="p">
		<xsl:copy>
			<xsl:value-of select="xsb:replace(
				.,
				doc($search-and-replace-list)//pair/string(pattern),
				doc($search-and-replace-list)//pair/string(replacement)
			)"/>
		</xsl:copy>
	</xsl:template>
	<xsl:template match="@*|node()">
		<xsl:copy>
			<xsl:apply-templates select="@*, node()"/>
		</xsl:copy>
	</xsl:template>
</xsl:stylesheet>

Beispieldokument:

<root>
	<p>Affe</p>
	<p>Wolf</p>
	<p>Zebra</p>
</root>

Transformationsergebnis:

<root>
	<p>monkey</p>
	<p>wolf</p>
	<p>Zebra</p>
</root>

Achtung! Leersequenzen innerhalb der pattern-Sequenz (bzw. fehlende pattern-Elemente in der Ersetzungstabelle) führen dazu, dass die folgenden Werte innerhalb der pattern-Sequenz nach links rücken: xsb:replace('Affe Wolf Zebra', ('Affe', (), 'Zebra'), ('monkey', 'wolf', 'zebra') ) ergibt – ebenso wie xsb:replace('Affe Wolf Zebra', ('Affe', 'Zebra'), ('monkey', 'wolf', 'zebra') ) – »monkey Wolf wolf«. Das gilt analog auch für die replacement-Sequenz bzw. replacement-Elemente der Ersetzungstabelle. Diesem Problem kann man mit einem rigiden Schema samt Validierung oder durch geschickte Konstruktion der pattern– und replacement-Sequenzen begegnen: im obigen Stylesheet wurde nicht das naheliegende doc($search-and-replace-list)//pattern verwendet, sondern statt dessen doc($search-and-replace-list)//pair/string(pattern), womit bei fehlendem pattern-Element mit fn:string() ein Leerstring erzeugt wird.

Exkurs: Im Gegensatz zu fn:string() evaluiert xs:string() die Leersequenz zu einer Leersequenz. Ich bin mir sicher, dass es für diesen Unterschied eine sachliche Begründung gibt, aber solche Inkonsistenzen machen das Programmieren nicht nur für Einsteiger unnötig kompliziert.

Durch die Verwendung von fn:replace() werden die Suchstrings als reguläre Ausdrücke interpretiert. Entsprechend wird im Beispiel oben der Punkt mit dem Backslash escapet. Wenn das händische Escapen nicht sinnvoll oder möglich ist, hilft die Funktion xsb:escape-for-regex(). Analog dazu gibt es auch im Ersetzungstext Steuerzeichen, die mit xsb:escape-for-replacement() escapet werden können.

Auch von xsb:replace() gibt es die »bequeme« Version ohne flags.

xsb:escape-for-regex() und xsb:escape-for-replacement()

Die Funktion xsb:escape-for-regex() escapet in Strings Steuerzeichen für reguläre Ausdrücke mit einem Backslash (\). Damit können Strings, die Steuerzeichen enthalten, als Suchmuster in regulären Ausdrücken verwendet werden. Im Beispiel oben musste beispielsweise der Punkt (steht in regulären Ausdrücken für ein beliebiges Zeichen) in Jan. escapet werden (Jan\.), damit nicht auch »Jana« ersetzt wird. Die Implementierung ist sehr simpel:

<xsl:function name="xsb:escape-for-regex" as="xs:string">
	<xsl:param name="input" as="xs:string?"/>
	<xsl:sequence select="concat('', replace($input, '[\\*.+?\^\$()\[\]{}|]', '\\$0') )"/>
</xsl:function>

Im pattern von fn:replace() werden die »verbotenen« Zeichen gesucht. Bemerkenswert ist vielleicht das replacement: der doppelte Backslash ist ein escapeter einfacher Backslash, und $0 steht für den gesamten gematchten Teilstring. Es wird also ein Backslash ausgegeben und anschließend die Fundstelle wiederholt.

Da es also auch im Ersetzungstext von fn:replace() Steuerzeichen – »\« und »$« – geben kann, macht eine Funktione zu Escapen eben dieses Ersetzungstextes das Leben einfacher: xsb:escape-for-replacement().

Ein Beispiel für die Nutzung der beiden Funktionen ergibt sich im Zusammenhang mit der oben beschriebenen Ersetzungstabelle. Wenn man davon ausgehen kann, dass in search-and-replace_list.xml keine regulären Ausdrücke notiert werden, kann das Stylesheet zur Absicherung modifiziert werden:

<xsl:template match="p">
	<xsl:copy>
		<xsl:value-of select="xsb:replace(
			.,
			doc($search-and-replace-list)//pair/xsb:escape-for-regex(string(pattern)),
			doc($search-and-replace-list)//pair/xsb:escape-for-replacement(string(replacement))
		)"/>
	</xsl:copy>
</xsl:template>

Quelldokument, Ersetzungstabelle und Stylesheet habe ich wie üblich in der Beispielsammlung abgelegt.

Weblinks:

  1. Bisher keine Kommentare.
(wird nicht veröffentlicht)

Time limit is exhausted. Please reload CAPTCHA.