Pipeline Elemente

Eine XProc Pipeline besteht nicht nur aus Steps und Ports. Wie bereits schon mehrfach in dieser Ausarbeitung vorgekommen, existieren weitere Elemente, die zur Funktionalität einer Pipeline entscheidend beitragen. Im folgenden Kapitel werden diese zusammengefasst und wenn nicht schon an anderer Stelle geschehen, erläutert.

p:input

Durch <p:input> werden Ports an einen Output gebunden. Es können immer nur Outputs an einen Input Port gebunden werden. Mehr zu diesem Element in Ports.

p:iteration-source

<p:Iteration-Source> ist ein Element, welchen im Step <p:for-each> zum Einsatz kommt. Es bietet einen alternativen Input für die Schleife. Mehr in Compound Steps.

p:viewport-source

Das Element <p:viewport-source> kommt im Step <p:viewport> zum Einsatz. Durch diesen Compound Step lassen sich bestimmte Teile eines Dokuments durch einen entsprechenden XSLT Ausdruck selektieren, um diese dann in einer Subpipeline verarbeiten zu können. Dies kann unter anderem durch <p:viewport-source> als alternatives Selektierungswerkzeug innerhalb von <p:viewport> erfolgen. Mehr dazu in Compound Steps.

p:output

Durch <p:output> wird ein Output Port eines Steps oder einer Pipeline definiert. Mehr zu diesem Element in Ports.

p:log

Viele Steps unterstützen das Element <p:log>. Es handelt sich dabei um eine Log-File Implementierung. So wird der Output eines definierten Ports in eine Datei geschrieben.

<p:log
 port = NCName
 href? = anyURI />
 

Am Attribut “port“ wird eingetragen, welcher Port ausgelesen werden soll. Im Attribut “href“ wird der Name der gewünschten Zieldatei (z.b. Logfile.txt), die das Log beinhalten soll, festgelegt.

Beispiel

Das folgende Beispiel demonstriert die Einbindung eines <p:log> Elements in einen Step.

<p:validate-with-schematron assert-valid="true" name="schematron">
   <p:log port="report" href="schematron_reports.log"></p:log>
   <p:input port="parameters"
   <p:empty/>
   </p:input>
   <p:input port="schema">
   <p:document href="schematron.sch"/>
   </p:input>
</p:validate-with-schematron>
 

Im Beispiel wird ein Log für den Port “report“ angelegt. Dieser Port gibt spezielle Validierungsinformationen des Steps <p:validate-with-schematron> aus. Alle Ausgaben auf diesen Port werden in eine Datei mit Namen “schematron_reports.log“ geschrieben.

p:serialization

Durch das Element können Serialisierungs Aktionen auf den Output von Pipelines die durch <p:pipeline> oder <p:declare-step> erzeugt wurden, durchgeführt werden.

p:variable, p:options

In XProc können Variablen und Optionen definiert werden. Je nach Beschaffenheit der Pipeline und der verwendeten Steps nehmen sie Einfluss auf das jeweilige Verhalten. Mehr zu diesen Themen hier (Variablen) und hier (Optionen).

p:declare-step

Durch <p:declare-step> können entweder Atomic Steps oder ganze Pipelines beschrieben werden.

<p:declare-step
 name? = NCName
 type? = QName
 psvi-required? = boolean
 xpath-version? = string
 exclude-inline-prefixes? = prefix list
 version? = string>
  (p:input |
   p:output |
   p:option |
   p:log |
   p:serialization)*,
  ((p:declare-step |
   p:pipeline |
   p:import)*,
   subpipeline)?
</p:declare-step>
 

Sämtliche Attribute sind optional. Die Bezeichnungen “name“ und “type“ müssen, wenn gesetzt, QNames sein. Das Attribut “xpath-version“ gibt die verwendete XPath Versionsnummer an. Durch einen boolschen Wert kann bei “psvi-required“ festgelegt werden, ob “PSVI“ (Post-Schema-Validation-Infoset), innerhalb des definierten Steps oder Pipeline, verlangt werden oder nicht. PSVI Daten beinhalten XML bezogene Informationen, die beim Validieren gegen ein XML-Schema Dokument entstehen können. Ist der Wert auf “true“ so werden diese Informationen unter den Steps in einer Pipeline weitergereicht (kann je nach Implementierung relevant sein).

Das Attribut “exclude-inline-prefixes“ erwartet eine Liste. Hier können Prefixe angegeben werden, die beim Erzeugen eines Outputs durch <p:inline> ignoriert werden sollen.

BEISPIEL

Im folgenden Beispiel wird die Verwendung von “exclude-inline-prefixes“ demonstriert.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" 
xmlns:c="http://www.w3.org/ns/xproc-step"
xmlns:a="http://beispiel.de/a" 
xmlns:b="http://beispiel.de/b" exclude-inline-prefixes="a"
  version="1.0">
  <p:output port="result"/>
  <p:identity>
    <p:input port="source">
      <p:inline>
        <doc>
          <b:beispiel/>
        </doc>
      </p:inline>
    </p:input>
  </p:identity>
</p:declare-step>
 

Im Beispiel werden zwei zusätzliche Prefixe mit den Namen “a“ und “b“ angelegt. In die “exclude-inline-prefixes“ Liste wird “a“ geschrieben. Dies hat zur Folge, dass der Prozessor das Prefix “a“ nicht im Output vom <p:inline> Step nennen wird. Der Output sieht dementsprechend folgendermaßen aus:

<doc xmlns:c="http://www.w3.org/ns/xproc-step" xmlns:b="http://beispiel.de/b">
   <b:beispiel/>
</doc>
 

Ohne den “exclude-inline-prefixes“ Zusatz sieht das Resultat folgendermaßen aus:

<doc xmlns:c="http://www.w3.org/ns/xproc-step" xmlns:a="http://beispiel.de/a"
   xmlns:b="http://beispiel.de/b">
 <b:beispiel/>
</doc>
 

Das Attribut “version“ gibt die Versionsnummer von XProc an. Weiterhin kann innerhalb eines <p:declate-Step> Elements ein oder mehrere <p:input>, <p:output>, <p:option>, <p:log> und <p:serialization> Elemente definiert werden. Es besteht auch die Möglichkeit weitere <p:declate-step> Elemente anzulegen.

Weiterhin ist die Angabe einer Pipeline durch <p:pipeline> möglich. Externe Inhalte können mit <p:import> geladen werden. Anschließend kann eine (oder mehrere) komplette Subpipeline angegeben werden. Soll ein Atomic Step durch <p:declare-step> beschrieben werden, muss die Subpipeline leer sein. In fast allen Beispielen dieser Arbeit wurden sämtliche Pipelines mit dem <p:declare-step> Element definiert.

p:library

Mit dem Element <p:library> ist es Möglich, eine Sammlung aus Steps und Pipelines zusammenzustellen. Diese Bibliothek kann dann anderen Pipelines durch die entsprechenden Importmaßnahmen (<p:import>, siehe nächsten Abschnitt) zur Verfügung gestellt werden.

<p:library
 psvi-required? = boolean
 xpath-version? = string
 exclude-inline-prefixes? = prefix list
 version? = string>
  (p:import |
   p:declare-step |
   p:pipeline)*
</p:library>
 

Zunächst können hier dieselben Angaben getätigt werden wie bei einem <p:declare-step> Element (siehe vorherigen Abschnitt). Also “psvi-required“, “xpath-version“,“exclude-inline-prefixes“ und “version“. Weiterhin kann nun mittels <p:import> externer Inhalt in die Bibliothek geladen werden. Durch <p:declare-step> und <p:pipeline> kann ein Step oder eine Pipeline definiert werden.

Beispiel

Im folgenden Beispiel wird eine triviale Bibliothek angelegt.

<p:library xmlns:p="http://www.w3.org/ns/xproc" 
xmlns:beispiel="http://beispiel.de" version="1.0">
  <p:declare-step type="beispiel:identity" name="beispiel-identity">
    <p:input port="source" sequence="true"/>
    <p:output port="result"/>
    <p:identity/>
  </p:declare-step>
</p:library>
 

Die Library im Beispiel stellt einen Step mit dem Titel “idenitity“ im Namensraum “beispiel“ bereit. Die Implementierung ist durch den XProc Step <p:identity> realisiert. In einem anderen XProc Dokument kann dieser Step, vorausgesetzt die Library wurde importiert und der Namensraum “beispiel“ ist angelegt, verwendet werden. Somit können zum Beispiel komplexe Pipelines , im Sinne der Übersichtlichkeit, ausgelagert werden.

p:import

Durch <p:import> können externe Inhalte in ein XProc Stylesheet geladen werden. Diese Inhalte können andere Pipelines oder Bibliotheken (siehe <p:library>) sein.

<p:import
  href = anyURI />
 

Als einzige Angabe erwartet das Element <p:import> eine URI, die zum gewünschten XProc-Dokument führt. Ist die Angabe fehlerhaft, also kann das gewählte Dokument nicht gefunden werden, wird ein statischer Fehler ausgegeben.

Beispiel

Im folgenden Beispiel wird die Bibliothek aus

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" 
xmlns:c="http://www.w3.org/ns/xproc-step"
  version="1.0" xmlns:beispiel="http://beispiel.de">
  <p:input port="source">
    <p:inline>
      <doc>Kleines Beispiel</doc>
    </p:inline>
  </p:input>
  <p:output port="result"/>
  <p:import href="library.xpl"/>
  <beispiel:identity/>
</p:declare-step>
 

Im vorliegenden Beispiel muss derselbe Namensraum (Beispiel), wie er in der Library vorkommt, festgelegt werden. Am Input-Port “source“ wird durch <p:inline> ein kurzer Text verfasst. Dieser soll durch den Step “beispiel:identity“ am Output-Port wieder ausgegeben werden. Das Resultat sieht also folgendermaßen aus:

<doc xmlns:c="http://www.w3.org/ns/xproc-step" 
xmlns:beispiel="http://beispiel.de">Kleines Beispiel</doc>
 

p:pipe

Durch das Element <p:pipe> werden lesbare Ports von anderen Steps mit dem aktuellen Port verbunden (Als Input).

<p:pipe
  step = NCName
  port = NCName />
 

Beispiel

Im Beispiel wird der Einsatz von <p:pipe> demonstiert.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" 
xmlns:c="http://www.w3.org/ns/xproc-step"
  version="1.0" name="Beispiel">
  <p:input port="source">
    <p:inline>
      <doc>Hello world!</doc>
    </p:inline>
  </p:input>
  <p:input port="alternativ">
    <p:inline>
      <doc>Alternativer Output</doc>
    </p:inline>
  </p:input>
  <p:output port="result"/>
  <p:identity>
    <p:input port="source">
      <p:pipe port="alternativ" step="Beispiel"/>
    </p:input>
  </p:identity>
</p:declare-step>
 

Im <p:identity> Step wird der zugehörige Input-Port “source“ durch <p:pipe> mit dem Input-Port “alternativ“ verbunden. Dies hat zur Folge das die Ausgabe der Pipeline folgendermaßen aussieht:

<doc xmlns:c="http://www.w3.org/ns/xproc-step">
Alternativer Output
</doc>
 

Der Input Port “source“ von “Beispiel“ (der Name der Pipeline) wird nicht ausgegeben, da <p:identity> nicht damit verbunden wurde.

p:inline

Durch <p:inline> können Dokumente direkt in einem XProc-Dokument erstellt werden.

<p:inline
  exclude-inline-prefixes? = prefix list>
   anyElement
</p:inline>
 

Durch die Angabe von “exclude-inline-prefixes“ können Prefixe angegeben werden, die beim Erzeugen eines Outputs durch <p:inline> ignoriert werden sollen. Ein durch <p:inline> erzeugtes Dokument darf nur ein Element beinhalten (mit beliebig vielen Verschachtelungen). Wie bei einem XML-Dokument, darf maximal ein Wurzelelement enthalten sein. Andernfalls würde ein statischer Fehler ausgegeben werden.

Beispiel

Im folgenden Beispiel wird ein triviales Dokument mit einem <p:inline> Element erstellt und durch den <p:identity> Step ausgegeben.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc"
 xmlns:c="http://www.w3.org/ns/xproc-step" version="1.0">
 <p:input port="source">
  <p:inline>
   <doc>Ein kleines Beispiel</doc>
  </p:inline>
 </p:input>
 <p:output port="result"/>
 <p:identity/>
</p:declare-step>
 

Es wird ein Dokument erzeugt, was lediglich aus einem Element namens <doc> und dem Inhaltstext “Ein kleines Beispiel“ besteht. Der <p:identity> Step gibt genau diesen Inhalt am Ende der Pipeline aus.

p:document

Das <p:document> Element liest ein XML Dokument ein und stellt es somit der Pipeline zur Verfügung.

<p:document
  href = anyURI />
 

Wird das Dokument (anzugeben im Attribut “href“) nicht an der gewünschten Stelle gefunden, wird ein dynamischer Fehler ausgegeben. Üblicherweise werden Dokumente via <p:document> als Eingangsdaten an Input-Ports definiert.

Beispiel

Im folgenden Codeauszug wird ein Dokument durch <p:document> geladen.

<p:input port="source">
  <p:document href="filmsammlung.xml"/>
</p:input>
 

Davon ausgehend, dass das Dokument “filmsammlung.xml“ im selben Verzeichnis liegt wie das XProc Dokument, wird der Inhalt gelesen und dem Input-Port “source“ zugewiesen.

p:data

Das Element <p:data> liest eine beliebige Quelle von einer angegeben Uri ein und gibt deren Inhalt umschlossen mit einem entsprechenden Wrapper aus.

<p:data
  href = anyURI
  wrapper? = QName
  wrapper-prefix? = string
  wrapper-namespace? = string
  content-type? = string />
 

Das einzulesende Zielobjekt wird unter “href“ angegeben. Kann dieser die Datei nicht finden, wird ein dynamischer Fehler ausgegeben. Der XProc Prozessor wird versuchen das Objekt zu encodieren um es ausgeben zu können. Somit können zum Beispiel Textdokumente, die keinen XML Aufbau haben, eingelesen werden. Aber auch andere Datentypen sind möglich, solange sie entsprechend encodiert werden können.

Dem Attribut “content-type“ kann durch Angabe eines strings mitgeteilt werden, um welchen Datentyp es sich beim einzulesenden Dokument handelt. Ansonsten versucht der Prozessor den Typ automatisch herauszufinden, was nicht immer erfolgreich ist. Durch die drei Attribute “wrapper“, “wrapper-prefix“ und “wrapper-namespace“ kann ein Wrapper, der das auszugebende Dokument, umschliessen wird, definiert werden. Wird kein eigener Wrapper festgelegt, ist per Default <c:data> vorgesehen.

<c:data
  content-type? = string
  charset? = string
  encoding? = string>
   string
</c:data>
 

Der <c:data> Wrapper kann den zugrundeliegenden “content-type“ (Dateityp), “charset“ (Zeichensatz) und das “encoding“ anzeigen. Darauf folgt dann der eigentliche Inhalt.

Beispiel

Im folgenden Beispiel wird eine Textdatei (“beispiel.txt“) mit <p:data> eingelesen und in einem selbst erstellten Wrapper ausgegeben.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" 
xmlns:c="http://www.w3.org/ns/xproc-step"
  version="1.0">
  <p:input port="source">
    <p:data href="beispiel.txt" wrapper="beispiel" 
  wrapper-namespace="http://www.bsp.de" 
  wrapper-prefix="b" content-type="text/plain"/>
  </p:input>
  <p:output port="result"/>
  <p:identity/>
</p:declare-step>
 

Durch <p:data> wird eine Textdatei mit dem Inhalt “das ist ein kleines beispiel“ eingelesen. Durch die Angabe eines “content-type“, nämlich “text/plain“, wird sichergestellt das der Prozessor das Dokument als Textdatei erkennt und korrekt ausliest. Als Wrapper kommt “beispiel“ mit dem Prefix “b“ und dem Namensraum “http://www.bsp.de“ zum Einsatz. Das Resultat sieht folgendermaßen aus:

<b:beispiel xmlns:b="http://www.bsp.de" c:content-type="text/plain">
das ist ein kleines beispiel
</b:beispiel>
 

p:empty

Mit Hilfe des Elements <p:empty> können Ports mit einem leeren Dokument verbunden werden.

<p:empty />
 

Manche Ports benötigen zwingend einen Input, da sonst ein Fehler entstehen würde. Dies ist jedoch nicht immer gewünscht. In diesen Situationen können diese Ports mit Angabe des <p:empty> Elements ruhig gestellt werden, da sie als Input eine leeres Dokument zugewiesen bekommen, was auf den eigentlichen Verlauf der Pipeline keinen Einfluss nimmt.

p:documentation

Mittels <p:documentation> kann der Autor der Pipeline Inhalte schreiben, die für andere Entwickler relevant sein können. Beispielsweise eine genaue Erklärung der vorliegenden Pipeline. Sämtliche <p:documentation> Elemente werden von Prozessoren ignoriert.

p:Pipeinfo

Ein <p:pipeinfo> Element beinhaltet zusätzliche Informationen, die für einen Step relevant sein können. Beispielsweise auch Informationen die dem Prozessor dienlich sein könnten. Im Gegensatz zu <p:documentation> wird der Inhalt von <p:pipeinfo> vom Prozessor also nicht ignoriert, da er eventuell relevante Informationen beinhalten könnte.