Pipeline elements

A XProc pipeline does not only consist of steps and ports. As noted repeatedly earlier, there are further elements which contribute significantly to the functionality of a pipeline. In the following these elements are summarised and explained.

p:input

With the help of <p:input>, ports are bound on an output. Outputs can only be bound on one input port. Read more about this element in Ports.

p:iteration-source

<p:iteration-source> is an element which is used in the <p:for-each> step. It offers an alternative input for the loop. See Compound Steps.

p:viewport-source

The <p:viewport-source> element is used in the <p:viewport> step. With this Compound Step certain parts of a document can be selected by an appropriate XSLT expression in order to be able to process these later in a subpipeline. This can be realised for example by <p:viewport-source> as an alternative selection tool within <p:viewport>. See Compound Steps.

p:output

With <p:output> an output port of a step or a pipeline is defined. Read more about this element in Ports.

p:log

Many steps support the <p:log> element which is a log file implementation. In that way, the output of a defined port is written into a file.

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

At the “port“ attribute is entered which port shall be read. In the “href“ attribute the name of the desired target file (e.g. Logfile.txt) which shall contain the log is determined.

Example

The following example demonstrates the embedding of a <p:log> element in a 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>

In the example, a log for the “report“ port is generated. This port outputs special validation information of the <p:validate-with-schematron> step. All outputs on this port are written into a file with the name “schematron_reports.log“.

p:serialization

With this element serialization actions can be performed on the output of pipelines being generated by <p:pipeline> or <p:declare-step>.

p:variable, p:options

In XProc variables and options can be defined. Depending on the nature of the pipeline and the used steps, variables and options have an influence on the respective behaviour. Read more about these topics on the pages Variables and Options.

p:declare-step

With <p:declare-step> Atomic Steps or entire pipelines can be described.

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

All attributes are optional. The identifications “name“ and “type“ must be QNames, if set. The “xpath-version“ attribute indicates the used XPath version number. With the help of a Boolean value, it can be determined for “psvi-required“ whether “PSVI“ (Post-Schema-Validation-Infoset) is required within the defined step or pipeline or not. PSVI files contain XML-related information which may result from the validation against a XML Schema document. If the value is set to “true“, this information will be passed on among the steps in a pipeline (this may be relevant depending on the implementation).

The “exclude-inline-prefixes“ attribute expects a list. Here, prefixes can be indicated which shall be ignored by <p:inline> when generating an output.

Example

In the following example the use of “exclude-inline-prefixes“ is demonstrated.

<?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://example.de/a" xmlns:b="http://example.de/b" exclude-inline-prefixes="a" version="1.0">
  <p:output port="result"/>
  <p:identity>
    <p:input port="source">
      <p:inline>
        <doc>
          <b:example/>
        </doc>
      </p:inline>
    </p:input>
  </p:identity>
</p:declare-step>

In the example two further prefixes with the names “a“ and “b“ are generated. "a" is written into the “exclude-inline-prefixes“ list. As a result, the processor will not name the “a“ prefix at the output of the <p:inline> step. Accordingly, the output is as follows:

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

Without the “exclude-inline-prefixes“ supplement, the result is as follows:

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

The “version“ attribute indicates the XProc version number. In addition, one or several <p:input>, <p:output>, <p:option>, <p:log> and <p:serialization> elements can be defined within a <p:declare-step> element. It is also possible to generate further <p:declare-step> elements.

Furthermore, the indication of a pipeline by <p:pipeline> is possible. External contents can be loaded with <p:import>. Then, one (or several) complete subpipelines can be indicated. If an Atomic Step shall be described by <p:declare-step>, the subpipeline has to be empty. In almost all examples all pipelines were defined with the <p:declare-step> element.

p:library

With the <p:library> element, the user can create a collection of steps and pipelines. This library can be placed at the disposal of other pipelines with the help of the appropriate import techniques (<p:import>, see next section).

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

At first, in this example the same indications can be provided as for a <p:declare-step> element (see previous section). Which means “psvi-required“, “xpath-version“,“exclude-inline-prefixes“ and “version“. In addition, external content can be loaded into the library with the help of <p:import>. With <p:declare-step> and <p:pipeline> a step or a pipeline can be defined.

Example

In the following example a trivial library is generated.

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

The library in the example provides a step with the title “identity“ in the namespace “example“. The implementation is realised by the XProc step <p:identity>. This step can be used in another XProc document provided that the library had been imported and the namespace “example“ is generated. So, for example complex pipelines can be swapped out for more clarity.

p:import

With <p:import>, external contents can be loaded into a XProc stylesheet. These contents may be other pipelines or libraries (see <p:library>).

<p:import href = anyURI/>

The <p:import> element expects as only specification an URI which leads to the desired XProc document. If the indication is defective, which means the chosen document cannot be found, a static error will be outputted.

Example

In the following example the library is outputted.

<?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:example="http://example.de">
  <p:input port="source">
    <p:inline>
      <doc>Small example</doc>
    </p:inline>
  </p:input>
  <p:output port="result"/>
  <p:import href="library.xpl"/>
  <example:identity/>
</p:declare-step>

In this example, the same namespace ("example") as used in the library has to be determined. At the input port “source“ a short text is created by <p:inline>. This text shall be re-outputted at the output port by the <example:identity> step. The result is as follows:

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

p:pipe

With the help of the <p:pipe> element, readable ports of other steps are connected with the current port (as input).

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

Example

In this example the use of <p:pipe> is demonstrated.

<?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="Example">
  <p:input port="source">
    <p:inline>
      <doc>Hello World!</doc>
    </p:inline>
  </p:input>
  <p:input port="alternative">
    <p:inline>
      <doc>Alternative Output</doc>
    </p:inline>
  </p:input>
  <p:output port="result"/>
  <p:identity>
    <p:input port="source">
      <p:pipe port="alternative" step="Example"/>
    </p:input>
  </p:identity>
</p:declare-step>

In the <p:identity> step, the appropriate “source“ input port is connected with the "alternative" input port by <p:pipe>. As a consequence, the output of the pipeline is as follows:

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

The “source“ input port of “Example“ (the name of the pipeline) is not outputted, because <p:identity> was not connected with it.

p:inline

With <p:inline>, documents can be directly generated in a XProc document.

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

With “exclude-inline-prefixes“, prefixes can be indicated which shall be ignored when generating an output by <p:inline>. A document generated by <p:inline> must only contain one element (with an unlimited number of nestings). As in a XML document, maximally one root element may be contained. Otherwise a static error would be outputted.

Example

In the following example a trivial document is generated with a <p:inline> element and outputted by the <p:identity> step.

<?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>A small example</doc>
  </p:inline>
 </p:input>
 <p:output port="result"/>
 <p:identity/>
</p:declare-step>

Here, a document is generated which only consists of one element called <doc> and the content text “A small example“. The <p:identity> step outputs exactly this content at the end of the pipeline.

p:document

The <p:document> element imports a XML document and therefore makes it available for the pipeline.

<p:document href = anyURI/>

If the document (to be indicated in the “href“ attribute) cannot be found at the desired position, a dynamic error will be outputted. Normally, documents are defined via <p:document> as input data on input ports.

Example

In the following code excerpt, a document is loaded by <p:document>.

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

Considering that the “FilmCollection.xml“ document can be found in the same directrory as the XProc document, the content is read and assigned to the “source“ input port.

p:data

The <p:data> element reads in any source of an indicated URI and outputs its content enclosed with an appropriate wrapper.

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

The target object to be read in is indicated under “href“. If it cannot find the file, a dynamic error will be outputted. The XProc processor will try to encode the object in order to be able to output it. It is therefore possible, for example, to read in text documents which have no XML structure. But also other data types are possible as long as they can be encoded accordingly.

By indicating a string, the “content-type“ attribute can get the information what type of data the document to be read in is. Otherwise, the processor will try to automatically find out the type, which is not always successful. With the three attributes “wrapper“, “wrapper-prefix“ and “wrapper-namespace“, the wrapper can be defined which will enclose the document to be outputted. If no separate wrapper is determined, <c:data> is used per default.

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

The <c:data> wrapper can indicate the underlying “content-type“ (file type), “charset“ (character set) and the “encoding“. Then, the real content follows.

Example

In the following example a text file (“example.txt“) is read in with <p:data> and outputted in a self-generated wrapper.

<?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="example.txt" wrapper="example" wrapper-namespace="http://www.exa.de" wrapper-prefix="b" content-type="text/plain"/>
  </p:input>
  <p:output port="result"/>
  <p:identity/>
</p:declare-step>

With the help of <p:data>, a text file with the content “This is a small example.“ is read in. By indicating a “content-type“, namely “text/plain“, the user can ensure that the processor recognizes the document as text file and outputs it correctly. “example“ with the prefix “b“ and the namespace “http://www.exa.de“ is used as wrapper. The resut is as follows:

<b:example xmlns:b="http://www.exa.de" c:content-type="text/plain">This is a small example.</b:example>

p:empty

With the help of the <p:empty> element, ports can be connected with an empty document.

<p:empty/>

Some ports require an input, since otherwise an error would occur. However, this is not always desired. In such situations these ports can be calmed by indicating the <p:empty> element, since they get assigned an empty document as input, which has no influence on the original flow of the pipeline.

p:documentation

With <p:documentation>, the author of the pipeline can write contents which may be relevant for other developers. For example an exact explanation of the present pipeline. All <p:documentation> elements are ignored by processors.

p:pipeinfo

A <p:pipeinfo> element contains further information which may be relevant for a step. For example information which may be useful for the processor. In contrast to <p:documentation>, the content of <p:pipeinfo> is not ignored by the processor, because it may contain important information.

<< back

next >>