Custom XPath Functions

Custom XPath Function

With xtriples-micro, we are not limited to the standard XPath functions, but can write and use our custom function library.

Writing a Function Library

xtriples-micro evaluates the XPath expressions in an XTriples configuration dynamically with <xsl:evaluate>. For making a custom function known to the processor when evaluating dynamic XPath expressions, it has to be declared visible; cf. the XSLT 3.0 Specs:

Function signatures: [...] All user-defined functions present in the containing package provided their visibility is not hidden or private;

E.g., the utils:diwan-code#1 function from the following xsl stylesheet is declared visible (visibility="public") und thus can be used in an XTriples configuration.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:map="http://www.w3.org/2005/xpath-functions/map"
    xmlns:utils="https://edition-ibn-nubatah.arabistik.uni-muenster.de/textapi/utils/"
    xpath-default-namespace="http://www.tei-c.org/ns/1.0" exclude-result-prefixes="#all"
    version="3.0">

    <!-- make a work identifier for diwan from a given listWit element -->
    <xsl:function name="utils:diwan-code" as="xs:string" visibility="public">
        <xsl:param name="listWit" as="element(listWit)"/>
        <xsl:choose>
            <xsl:when test="$listWit/@xml:id">
                <xsl:value-of
                    select="$listWit/@xml:id => replace('[a-z]', '') || $listWit/ancestor::TEI/@xml:id => lower-case()"
                />
            </xsl:when>
            <xsl:otherwise>
                <xsl:value-of select="$listWit/ancestor::TEI/@xml:id"/>
            </xsl:otherwise>
        </xsl:choose>
    </xsl:function>

	<!-- other custom functions -->

</xsl:stylesheet>

Loading a Function Library

Of cource, the function library has to be loaded into the XSLT processor. This can be achieved by not using xtriples-micro stylesheet directly, but indirectly via a stylesheet that loads it and the new function library:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:xs="http://www.w3.org/2001/XMLSchema" exclude-result-prefixes="#all" version="3.0"
    default-mode="eval-xtriples">

    <xsl:import href="../target/dependencies/xtriples/xsl/extract-collection.xsl"/>

    <xsl:import href="my-function-library.xsl"/>

</xsl:stylesheet>

This is the most straight forward solution. But please note, that there is also a static stylesheet parameter called libraries, that you can try to use for loading additional libraries, see https://github.com/SCDH/xtriples-micro/blob/main/xsl/extract-collection.xsl#L16.

Using a Function Library

Using the function in an XTriples configurtation just requires binding the utils namespace prefix to the https://edition-ibn-nubatah.arabistik.uni-muenster.de/textapi/utils/ namespace name in the <vocabularies> section:

<vocabulary prefix="utils" uri="https://edition-ibn-nubatah.arabistik.uni-muenster.de/textapi/utils/"/>

utils:diwan-code(...) can then be used in the XPath expressions.