unparsed-text-available

(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 boolescher Wert xs:boolean, der true oder false ist, je nachdem, ob die Funktion unparsed-text() mit den gleichen Argumenten aufgerufen, einen Textstring (nicht-leere Textressource) zurückgeben würde.

Aufruf/Argumente:

unparsed-text-available($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 false 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. Wird als zweites Argument die leere Sequenz übergeben, so wird das Argument ignoriert.

Verwendungszweck:

Die Funktion unparsed-text-available() wird in XSLT 2.0 zusätzlich zu unparsed-text() zur Verfügung gestellt um Abbrüche zu vermeiden, die durch Aufruf von unparsed-text() mit fehlerhaften Argumenten oder unbrauchbaren externen Ressourcen entstehen. Dass auch das Encoding der externen Ressource geprüft wird, erfordert deren tatsächliches Einlesen und Verarbeiten (z.B. um falsche Zeichen-Oktette festzustellen). Die Funktion nimmt die gleichen Argumente wie unparsed-text() entgegen, gibt jedoch einen booleschen Wert zurück.

Dieser ist stets true, wenn der Aufruf der Partnerfunktion mit gleichen Argumenten keinen Fehler ergäbe und eine nicht-leere Textressource zurückliefert.

Führt der Aufruf zu einem potentiellen Fehler, so wird false zurückgegeben. Der Rückgabewert ist jedoch ebenfalls false, wenn das erste Argument (der URI der Ressource) die leere Sequenz ist – denn in diesem Fall könnte keine nicht-leere Textressource zurückgeliefert werden.

Anmerkung: Der Aufruf von unparsed-text() würde »nur« eine leere Sequenz liefern (sicher auch nicht immer brauchbar) und keinen Fehler ergeben; die Festlegung von true als Rückgabewert wäre vertretbar gewesen. Dies Inkongruenz wurde in Kauf genommen, um das Verhalten von unparsed-text-available() an die XPath-Funktion fn:doc-available() anzupassen.

Die Funktion ist stabil im Sinne der Spezifikation, ergibt also zur Laufzeit für gleiche Argumente stets einen gleichbleibenden Rückgabewert.

Beispiel:

Eine Prüfung auf Verfügbarkeit einer Ressource für unparsed-text() kann im Rahmen des gleichen XPath-Ausdrucks durch eine if-Expression erfolgen. Hier wirde das Beispiel aus unparsed-text() entsprechend erweitert:

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

Dies führt jedoch dazu, dass das Template in jedem Fall einen Container <ergebnis> ... </ergebnis> ausgibt, auch wenn keine Ressource erreichbar ist (immerhin wird für diesen Fall ein Fehler vermieden). Um die Ausgabe eines leeren LR-Containers zu vermeiden, kann das Beispiel alternativ auch folgendermaßen erweitert werden:

Dies führt jedoch dazu, dass das Template in jedem Fall einen Container <ergebnis> ... </ergebnis> ausgibt, auch wenn keine Ressource erreichbar ist (immerhin wird für diesen Fall ein Fehler vermieden). Um die Ausgabe eines leeren LR-Containers zu vermeiden, kann das Beispiel alternativ auch folgendermaßen erweitert werden:

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

Auch hier wird zunächst geprüft, ob unparsed-text() erfolgreich angewendet werden kann. Nur in diesem Fall gibt das Template ein Ergebnis aus. Würde als erstes Argument eine leere Sequenz übergeben, so verhindert die unparsed-text-available()-Funktion durch den Rückgabewert false ebenfalls das Instantiieren des Anweisungsblocks und damit auch die Ausgabe eines leeren Containers <ergebnis></ergebnis>.

Funktionsdefinition:

XSLT 1.0:

Funktion nicht verfügbar

XSLT 2.0:

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

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

   

<< 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