The logo is a pig framed between two angle brackets.

XProc 3.0 Tutorial

XProc’s XPath Extension Functions

The XProc spec defines additional functions that extend the XPath function library. You rarely need them and feel free to skip this part, but in some cases they come in handy.

Reading the System Properties

p:system-property($property as xs:string) as xs:string

Sometimes it is important to know the characteristics of the system your pipeline is running on. For example, if you offer support for messages in multiple languages, you might want to know the locale setting of the system. Therefore, you can use the function p:system-property(xs:string) while xs:string represents a set of predefined values.


<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:input port="source">
    <p:inline>
      <system/>
    </p:inline>
  </p:input>
  
  <p:output port="result"/>
  
  <p:add-attribute attribute-name="xpath-version"
    attribute-value="{p:system-property('p:locale')}"/>
  
</p:declare-step>

Output

<?xml version="1.0" encoding="UTF-8"?>
<system locale="de-DE"/>

Available function arguments are p:episode, p:locale, p:product-name, p:product-version, p:vendor, p:vendor-uri, p:version, p:xpath-version and p:psvi-supported. If you need the full description, just have a look into the XProc 3.0 spec.

Check Whether a Step is Available

p:step-available($step-type as xs:string) as xs:boolean

Apart from the XProc default step library, you can specify custom steps and the XProc processor might bring its own extension steps. For this reasons, in some scenarios it might be nessecary to check whether a step is available:

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:output port="result"/>
  
  <p:if test="p:step-available('p:file-info')">
    <p:file-info href="myfile.txt"/>
  </p:if>
  
</p:declare-step>

Output

<?xml version="1.0" encoding="UTF-8"?>
<c:file xmlns:c="http://www.w3.org/ns/xproc-step"
  xml:base="file:/home/xporc/myfile.txt"
  name="myfile.txt" content-type="text/plain" readable="true" writable="true" 
  hidden="false" last-modified="2024-03-29T20:18:10.48Z" size="5"/>

Functions for Iterations

p:iteration-position() as xs:integer
p:iteration-size() as xs:integer

There are two steps that process a sequence of documents in XProc: p:for-each and p:viewport. Within these steps, you can use the functions p:iteration-position() and p:iteration-size() that return the index of the current document and the number of all documents in that sequence.

Test if the XProc or XPath Version Is Supported

p:version-available($version as xs:string) as xs:boolean
p:xpath-version-available($version as xs:string) as xs:boolean

If you want to know whether the XProc processor supports XProc 3.0, you can verify this with p:version-available('3.0'). The same applies to the XPath version with p:xpath-version-available('3.1'). Both functions return either true or false.

Retrieve Document Properties

p:document-properties($doc as item()) as map(xs:QName,item()*)
p:document-property($doc as item(), $key as item()) as item()*

XProc stores the document properties of each document that flows through the pipeline. To get these properties, you can use p:document-properties(/) which returns a map.

Output

{"content-type":"application\/xml",
 "base-uri":"file:\/\/\/C:\/home\/xporc\/myfile.xml"}

If you want to get a specific document property like the base URI, you can utilize p:document-property(/, 'base-uri') to achieve that.

Get URIs From File System Paths

p:urify($filepath as xs:string, $basedir as xs:string?) as xs:string
p:urify($filepath as xs:string) as xs:string

With XProc you work usually with URIs as well as file system paths. These file system paths differ between Windows and Unix-like operating systems. Therefore, it might be useful to transform the file system paths into URIs and this is where p:urify() comes into place.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <p:input port="source">
    <p:inline>
      <image src="c:/home/xporc/image.png"/>
    </p:inline>
  </p:input>
  
  <p:output port="result"/>
  
  <p:add-attribute match="/image" attribute-name="uri" 
                   attribute-value="{p:urify(/image/@src)}"/>
  
</p:declare-step>

Output

<?xml version="1.0" encoding="UTF-8"?>
<image uri="file:///c:/home/xporc/image.png" src="c:/home/xporc/image.png"/>

Check for a Function Library

p:function-library-importable($library-type as xs:string) 
  as xs:boolean

According to the XProc spec, developers of XProc processors might add the feature to import individual XSLT function libraries which are identified by a individual type such as my:function-lib. The ability to import functions is provided by declaring p:import-functions href="my-function-lib.xsl" in the prolog. This feature is optional in the spec. However, you can test whether a specific library can be imported with p:function-library-importable('my:function-lib').

Read more…