ndw / sinclude

Saxon XInclude processor

Saxon XInclude Processor

This is an XInclude processor. It operates on the Saxon data model; it is not a streaming processor.

At the Java level, it works like this:

XdmNode document = … // You got a document from somewhere, right?
XInclude xinclude = new XInclude();
XdmNode expanded = xinclude.expandXIncludes(document);

It supports the xmlns, element, text, xpath, and search fragment identifier schemes.

I tried to build it in an extensible, pluggable way so that new schemes could be added with relative ease, but that may be a bit aspirational.

Extension function

You can use this XInclude implementation from XSLT as an extension function. Pass the command line option -init:com.nwalsh.xslt.Register to Saxon to register the extension function. (If you’re running Saxon in some other context, arrange to have the function registered).

In your stylesheet, declare the extension namespace:

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

                xmlns:ext="http://nwalsh.com/xslt"

                xmlns:xs="http://www.w3.org/2001/XMLSchema"
                exclude-result-prefixes="ext xs"
                version="3.0">

Then you can call the extension function:

<xsl:sequence select="ext:xinclude($node, $options)"/>

You can use function-available() to code more defensively. The options map is a map from QName keys to values. Only two keys are recognized: fixup-xml-base and fixup-xml-lang, both in no namespace. The default value for each is “true”. You can omit the second argument entirely if you’re happy with those defaults.

Command line example

You can use the xinclude.xsl file included in the distribution to expand the XIncludes in a document.

The trickiest part, as usual with Java applications, is arranging for the correct classpath. You need to include the Saxon jar file, the SInclude jar file, and any other jars that are necessary for dependencies (for example, the XML Resolver jar files for Saxon 11+).

If you have downloaded Saxon HE 11.5 and unzipped it into the directory saxon, the following classpath will work:

export CLASSPATH=saxon/saxon-he-11.5.jar\
:saxon/lib/xmlresolver-4.6.4.jar\
:build/libs/sinclude-4.2.1.jar

On Windows, the syntax is different. And you may find it more convienent to run from a shell script. The actual transformation is:

java -cp $CLASSPATH net.sf.saxon.Transform \
     -init:com.nwalsh.xslt.Register \
     -xsl:src/test/resources/xinclude.xsl \
     -s:input-document.xml -o:output-docuent.xml 

The -init: option will make sure that Saxon can find and use the extension function.

XPointer schemes

The standard xmlns() and element() schemes are supported for XML parsing. An xpath() scheme is also supported. It evaluates an XPath expression against the document.

For text documents, RFC 5147 fragment identifiers are supported. My own “search” scheme is also supported. The GitHub scheme: L​/start/-L​/end/ (for example L5-L10 for lines 5-10) is also supported.