How to develop own steps

There are different approaches in order to develop own steps in XProc. With the help of <p:declare-step>, pipelines can be developed. Pipelines themselves are treated as steps in XProc.

A pipeline as step

The following pipeline reads in a folder and outputs at the end the file names contained therein. For the input value the name of the folder is required.

<?xml version="1.0" encoding="UTF-8"?>
<p:declare-step type="exa:filenames" xmlns:p="http://www.w3.org/ns/xproc" xmlns:c="http://www.w3.org/ns/xproc-step" xmlns:exa="http://www.example.de" version="1.0">
  <p:input port="Path"/>
  <p:output port="result" sequence="true"/>
  <p:directory-list include-filter=".*xml">
    <p:with-option name="path" select="/path"/>
  </p:directory-list>
  <p:filter select="//c:file"/>
</p:declare-step>

The <p:directory-list> step uses the return value of the “/path“ XPath expression as folder name. This means that the step expects the indication of the folder in the following format:

<path>Folder name</path>

This indication has to be made at the “Path“ input port. Finally, the output of <p:direcory-list> is restricted to the indication of the file names by <p:filter>.

In order to be able to use the pipeline as a step, it needs a name and an own namespace (Individual steps must not be in the XProc namespace).
This is defined in the “type“ attribute by <p:declare-step>. The name of the step is “filenames“ with the namespace prefix “exa“. The namespace is indicated by xmlns:exa="http://www.example.de". In the following figure, the pipeline is used within another pipeline as 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" xmlns:exa="http://www.example.de" version="1.0">
  <p:output port="result" sequence="true"/>
  <p:import href="filenames.xpl"/>
  <exa:filenames>
    <p:input port="Path">
      <p:inline>
        <path>input</path>
      </p:inline>
    </p:input>
  </exa:filenames>
  <p:identity/>
</p:declare-step>

For the application of an own step, first of all the “example“ namespace has to be indicated. Then, the file which contains the step (“filenames.xml“) is loaded via <p:import>.

Now, the step can be operated by prepending its namespace prefix “exa". Its “Path“ input port gets an appropriate folder name ("input") by indicating a <path> element in a <p:inline> element. The output (which means the file name) is passed on to <p:identity> and outputted.

How to program own steps

If you want to implement a step which cannot be realised with the help of XProc, you have the option to program it on your own. Since the Calabash source code (written in Java) is openly available on the Internet, own extensions are possible.

Calabash already provides a range of own step developments. These are located in the so-called “Calabash extension namespace“. These steps can only be used with the Calabash processor because they are not supported by other implementations.

It is impossible to know in advance whether own developments will be part of an official processor release and it also depends on the quality and usefulness of each step. A further possibility would be to send a proposal directly to the W3C.

<< back next >>