unparsed-text

(Auszug aus "XSLT 2.0 & XPath 2.0" von Frank Bongers, Kapitel 5.)

A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

   

Kategorie: Assoziation und Auffindung von Ressourcen zur Laufzeit

Herkunft: XSLT 2.0

Rückgabewert: Ein String xs:string, der dem Textinhalt der externen Res­source entspricht, die durch den übergebenen URI-String bezeichnet wird.

Aufruf/Argumente:

unparsed-text($URI-string?, $encoding-angabe?)

$URI-string:
Optional. Ein String xs:string, der lexikalisch die Form eines URI-Strings xs:anyURI besitzen muss, jedoch keinen Fragment-Identifier beinhalten darf. Handelt es sich um einen relativen URI, so wird er gemäß Basis-URI des statischen Kontextes aufgelöst. Der aufgelöste URI muss auf eine als Text lesbare Ressource zeigen. Wird als erstes Argument die leere Sequenz übergeben, so gibt die Funktion die leere Sequenz zurück.

$encoding-angabe:
Optional. Das zweite Argument benennt das Encoding der externen Ressource, um ihre Umwandlung in einen String zu ermöglichen. Das Encoding beschreibt nach RFC 2278 die Binärkodierung der Zeichendaten (Beispiel: UTF-8, ISO-8859-1). Wird das gewünschte Encoding nicht erkannt oder durch den Prozessor nicht unterstützt, so wird auf UTF-8 als Standard-Encoding zurückgegriffen. Anwendungen sind nicht verpflichtet, außer UTF-8 und UTF-16 weitere Encodings zu unterstützen.

Verwendungszweck:

Die Funktion unparsed-text() liest eine externe Ressource anhand eines ihr übergebenen URI-Strings ein und gibt deren Inhalt, ohne ihn zu parsen, als String zurück. Im Gegensatz zur document()-Funktion verlangt die unparsed-text()-Funktion also nicht, dass es sich bei dem externen Dokument um wohlgeformtes XML handelt.

Der als erstes Argument übergebene String wird als URI-String interpretiert und muss daher ein lexikalisch korrekter absoluter oder relativer URI sein. Ist das Argument eine leere Sequenz, so gibt die Funktion ebenfalls eine leere Sequenz zurück.

In anderen Fällen (siehe unten) kann die Funktion jedoch eine Fehlermeldung erzeugen, die zum Abbruch der Verarbeitung führt (non-recoverable dynamic error) – um diesem vorzubeugen, kann im Vorfeld die Testfunktion unparsed-text-available() eingesetzt werden, die im folgenden beschrieben wird.

Die Auflösung eines übergebenen relativen URI erfolgt analog zur Funktion fn:doc(), d.h. es wird der Basis-URI des statischen Kontexts des Funktions­aufrufs gegenüber dem Basis-URI des Stylesheets aufgelöst.

Stammt der URI-String jedoch aus einem Quelldokument, so ist es eher beab­sichtigt, den Basis-URI des Quellkontextes zur Auflösung zu verwenden: Da die Übergabe des gewünschten Basis-URI an unparsed-text() jedoch nicht direkt möglich ist, kann auf den URI-String im Vorfeld die XPath-Funktion fn:resolve-uri() angewendet werden. Diese darf als zweites Argument einen Basis-URI erhalten, den man damit zum gewünschten, auf das Quelldokument bezogenen, absoluten URI auflöst:

unparsed-text(fn:resolve-uri($URI-string, $Basis-URI))

Abbruch bei URI-Fehler
Die Verarbeitung wird abgebrochen, sobald die Funktion als URI-Argument einen String erhält, der einen Fragment-Identifier enthält, oder aber ein URI-Argument erhält, das nicht auf eine Textressource zielt (ERR XTDE1170).

Ermittlung des Encodings der Ressource:

Bei der Umsetzung des Inhalts des Textdokuments in einen String wird das Encoding der Ressource einbezogen. Hierbei wird in erster Linie eine dort vorhandene Encoding-Information verwendet, andernfalls eine media-type-Angabe. Liegt keines von beidem vor, so wird ein optional in Form eines zweites Argument $encoding-angabe zur Verfügung gestellter Encoding-Bezeichner her­angezogen. Wurde kein zweites Argument übergeben, nimmt der Prozessor automatisch UTF-8 als Encoding an.

Abbruch bei Encodingfehlern
Wurde das zweite Argument weggelassen und er Prozessor kann weder UTF-8 auf die Ressource anwenden, noch das Encoding aus der Ressource erschließen, so wird die Verarbeitung abgebrochen (ERR XTDE1200).

Einschränkungen in Bezug auf verwendbare Zeichen:

Die Ressource darf nur solche Zeichen enthalten, die auch als XML-Zeichen erlaubt sind. Weiterhin dürfen keine Zeichenoktette enthalten sein, die anhand der angegebenen Enco­dierung nicht in gültige XML-Zeichen umsetzbar sind.

Abbruch bei Oktettfehlern
Enthält das externe Dokument Zeichen-Ok­tette, die mittels des angegebenen Encodings nicht auflösbar sind (dies gilt auch in dem Fall, dass der Prozessor das genannte Encoding nicht unterstützt), wird die Verarbeitung mit einer Fehlermeldung abgebrochen (ERR XTDE1190).

Verhalten gegenüber Zeilenenden in der externen Ressource:

Die Funktion unparsed-text() normalisiert Zeilenenden nicht, verhält sich also nicht entsprechend einem XML-Parser. Dies kann je nach Systemplattform zu Problemen mit dem Encoding der Zeilenenden beim Einlesen oder Ausgeben führen. Ein Ansatz bestünde darin, mittels fn:replace() das Normalisierungsverfahren eines XML-Parsers nachzuahmen:

fn:replace(unparsed-text('beispiel.txt', 'ISO-8859-1'), '[
]+', '
')

Hierbei wird die Ressource zunächst geholt, als ISO-8859-1 interpretiert und als erstes Argument an die Ersetzungsfunktion fn:replace() weitergereicht. Diese ersetzt die durch den regulären Ausdruck im zweiten Argument bestimmte Zeichenfolge CR+LF durch ein einfaches LF. Dies ist jedoch für die Verwendung in Mac OS problematisch, da dieses System wiederum ein einfaches CR (&xD;) benötigt. Gegebenenfalls muss die Umwandlung also angepasst werden, um Portabilität des Stylesheets zu ermöglichen. (Zusätzlich kompliziert wird das Problem in Mainframe-Umgebungen, da diese auch NEL und LS als Zeilenende kennen.)

Eine weitere Möglichkeit, Zeilenumbrüche zu vereinheitlichen, kann mittels XSLT-Instruktionen vorgenommen werden (angelehnt an ein Arbeitsbeispiel in der XSLT-Spezifikation).

<xsl:for-each select="fn:tokenize(unparsed-text($in), '\r?\n')">
  <!-- je Zeile der Textressource irgendetwas machen -->
  ...
</xsl:for-each>

Hier spaltet die Tokenize-Funktion die Textressource in Segmente, die jeweils einer Textzeile entsprechen. Dies geschieht mit dem regulären Ausdruck '\r?\n', wobei \r? einem oder keinem CR-Zeichen entspricht, \n genau einem LF-Zeichen. Die so erhaltenen Segmente lassen sich nun einzeln verarbeiten, wobei auch kontrolliert Umbrüche hinzugefügt werden können.

Serialisierung des Strings:

Enthält das externe Dokument die Zeichen < oder >, so werden diese bei der Serialisierung durch die XML-Entitäten &gt; bzw. &lt; umschrieben. Mit Hilfe des Attri­buts disable-output-escaping von xsl:value-of kann dies jedoch unterbunden werden. Auf diesem Wege können externe Dokumente die Markup enthalten (z.B. in Form von HTML- oder XML-Codeabschnitten) ohne vorhergehendes Parsen in Ergebnisdokumente eingebettet werden.

Beispiel – Einfügen eines Textes mit unparsed-text():

Der externe Text beispiel.txt:

Das ist ein Beispieltext, 
der in ein Dokument eingefügt werden soll.

Das Stylesheet (Auszug):

...
<xsl:output method="xml" encoding="ISO-8859-1"/>
<xsl:template match="beispiel">
  <ergebnis>
    <xsl:value-of select="unparsed-text('beispiel.txt', 'ISO-8859-1')"/>
  </ergebnis>
</xsl:template>
...

Das Ergebnisdokument:

<?xml version="1.0" encoding="ISO-8859-1"?>
<ergebnis>
  Das ist ein Beispieltext, 
  der in ein Dokument eingefügt werden soll.
</ergebnis>

Funktionsdefinition:

XSLT 1.0:

Funktion nicht verfügbar

XSLT 2.0:

unparsed-text($href as xs:string?) as xs:string

unparsed-text($href as xs:string?,
              $encoding as xs:string) as xs:string

   

<< zurück vor >>
Tipp der data2type-Redaktion:
Zum Thema XSLT bieten wir auch folgende Schulungen zur Vertiefung und professionellen Fortbildung an:

Copyright © Galileo Press, Bonn 2008
Für Ihren privaten Gebrauch dürfen Sie die Online-Version ausdrucken.
Ansonsten unterliegt dieses Kapitel aus dem Buch "XSLT 2.0 & XPath 2.0 ― Das umfassende Handbuch" denselben Bestimmungen wie die gebundene Ausgabe: Das Werk einschließlich aller seiner Teile ist urheberrechtlich geschützt. Alle Rechte vorbehalten einschließlich der Vervielfältigung, Übersetzung, Mikroverfilmung sowie Einspeicherung und Verarbeitung in elektronischen Systemen.


Galileo Press, Rheinwerkallee 4, 53227 Bonn