API

This page describes the XSLT functions provided by the project.

Parser functions

There are two parsing functions available:

• nk:xpath-model to parse plain XPath expressions.
• nk:xpath-model-value-template to parse (attribute or text) value templates.
• nk:xpath-type-model to parse sequence type declarations (like document-node(element(foo)))

nk:xpath-model

Function signature:

nk:xpath-model($xpath as xs:string) as element()
nk:xpath-model($xpath as xs:string, $config as map(xs:string, item()*)) as element()
nk:xpath-model($xpath as xs:string, $config as map(xs:string, item()*), $fail-on-error as xs:boolean) as element()

Parameter	Default	Type	Description
$xpath	-	xs:string	Plain XPath expression as input.
$config	map {'validation-mode': 'lax', 'namespaces': map {}, 'ignore-undeclared-namespaces' : true()}	map(xs:string, item()*)	Configuration map. See parser configuration.
$fail-on-error	false()	xs:boolean	If true, the function throws an error if the parsing result is not valid against the model schema. Otherwise it returns an <ERROR> element.

Return value: returns an <expr> element representing the input expression $xpath in the XPath model. In cases of parsing or validation errors an <ERROR> element is returned, if $fail-on-error is false.

nk:xpath-model-value-template

Function signature:

nk:xpath-model-value-template($value-template as xs:string) as element()
nk:xpath-model-value-template($value-template as xs:string, $config as map(xs:string, item()*)) as element()
nk:xpath-model-value-template($value-template as xs:string, $config as map(xs:string, item()*), $fail-on-error as xs:boolean) as element()

Parameter	Default	Type	Description
$value-template	-	xs:string	A value template as input. XPath expressions are marked by {xpath}
$config	map {'validation-mode': 'lax', 'namespaces': map {}, 'ignore-undeclared-namespaces' : true()}	map(xs:string, item()*)	Configuration map. See parser configuration.
$fail-on-error	false()	xs:boolean	If true, the function throws an error if the parsing result is not valid against the model schema. Otherwise it returns an <ERROR> element.

Return value: returns an <value-template> element representing the input value template $value-template in the XPath model. In cases of parsing or validation errors an <ERROR> element is returned, if $fail-on-error is false.

nk:xpath-type-model

Function signature:

nk:xpath-type-model($type as xs:string) as element(itemType)?
nk:xpath-type-model($type as xs:string, $config as map(xs:string, item()*)) as element(itemType)?

Parameter	Default	Type	Description
$type	-	xs:string	Plain sequence type declaration as input.
$config	map {'validation-mode': 'lax', 'namespaces': map {}, 'ignore-undeclared-namespaces' : true()}	map(xs:string, item()*)	Configuration map. See parser configuration.

Return value: returns an <itemType> element representing the input sequence type declaration in the XPath model.

Parser Configuration

The parser configuration is provided by the second function parameter $config as map with several possible entries:

Key	Default	Type	Description
validation-mode	lax	xs:string	In validation mode lax the returned model is not validated by the model schema. In mode strict the validation is performed.
namespaces	map {}	map(xs:string, xs:string)	A prefix/namespace-uri map to specify a prefix binding for used prefixes in the XPath expression.
ignore-undeclared-namespaces	true()	xs:boolean	If true namespace nodes with dummy namespaces are created for prefixes which was used in the XPath expression but not declared in $config?namespaces. Otherwise an error with the code nk:xp-model-undelcared-prefix is thrown.

Serializer functions

There are four serializer functions available:

• nk:xpath-serializer to serialize plain XPath expressions.
• nk:xpath-serializer-hl to serialize plain XPath expressions with a highlighting function.
• nk:value-template-serializer to serialize (attribute or text) value templates.
• nk:value-template-serializer-hl to serialize (attribute or text) value templates with a highlighting function.

nk:xpath-serializer

Function signature:

nk:xpath-serializer($expr as element(expr)) as xs:string
nk:xpath-serializer($expr as element(expr), $config as map(*)) as xs:string

Parameter	Default	Type	Description
$expr	-	element(expr)	A model representation of an XPath expression.
$config	map{}	map(*)	Configuration map. See serializer configuration.

Return value: serializes the input expression in the XPath model ($expr) to a string value. With the $config the serialization can be influenced.

nk:xpath-serializer-hl

Function signature:

nk:xpath-serializer-hl($expr as element(expr)) as node()*
nk:xpath-serializer-hl($expr as element(expr), $config as map(*)) as node()*

Parameter	Default	Type	Description
$expr	-	element(expr)	A model representation of an XPath expression.
$config	map{}	map(*)	Configuration map. See serializer configuration.

Return value: serializes the input expression in the XPath model ($expr). With the $config the serialization can be influenced. The returned value is a node sequence produced by the highlighter function specified in the $config.

nk:value-template-serializer

Function signature:

nk:value-template-serializer($expr as element(value-template)) as xs:string
nk:value-template-serializer($expr as element(value-template), $config as map(*)) as xs:string

Parameter	Default	Type	Description
$expr	-	element(value-template)	A model representation of a valute template expression.
$config	map{}	map(*)	Configuration map. See serializer configuration.

Return value: serializes the input value template in the XPath model ($expr) to a string value. With the $config the serialization can be influenced.

nk:value-template-serializer-hl

Function signature:

nk:value-template-serializer-hl($expr as element(value-template)) as node()*
nk:value-template-serializer-hl($expr as element(value-template), $config as map(*)) as node()*

Parameter	Default	Type	Description
$expr	-	element(value-template)	A model representation of a value template expression.
$config	map{}	map(*)	Configuration map. See serializer configuration.

Return value: serializes the input value template in the XPath model ($expr). With the $config the serialization can be influenced. The returned value is a node sequence produced by the highlighter function specified in the $config.

Serializer Configuration

Key	Default	Type	Description
literal-string-quote	auto	xs:string	Specifies which quote sign should be used to serialize literal string values. double → use always ", single → use always ', auto → dependent of the value, prefer '.
target-prefixes	()	map(xs:string, xs:string)?	Specifies with a namespace-uri/prefix map the prefixes which should be used serializing the QNames of the model.
namespaces	map {}	map(xs:string, xs:string)?	Specifies with a prefix/namespace-uri map the prefixes which should be used for serialization of the QNames of the model. Used only if target-prefixes is not present. The prefix #default is ommitted for element node tests or types. In case of two prefixes for the same namespace it takes the first (in alphabetical order).
highlighter	nk:default-highlighter#3	function()	See highlighting serialization.
spacing-strategy	#default	xs:string	Currently there are two spacing strategies available: #default → spacing as best guess, always → adds spaces between any operators.

Serialization with syntax highlighting

To serialize expressions with a syntax highlighting the functions nk:xpath-serializer-hl or nk:value-template-serializer-hl should be used. In this cases each model node is serialized at first and then provided to the highlighter function ($config?highlighter). The highlighter function should have the signature:

function($model-node as node(), $serialized as item()*, $config as map(*)) as node()*

Parameter	Type	Description
model-node	element()	The current model node which should be serialized.
$serialized	item()*	The serialization of the the given $model-node (inclusive the highlighting result of the children).
$config	map(*)	Configuration which was provided to the serializer function.

Return value: the result sequence of nodes which should represent and markup the serialized $model-node.

Sample with the default highlighter

The default highlighter create span elements for each serialized model node with custom classes.

"foo[@bar = 'baz']" 
=> nk:xpath-model() 
=> nk:xpath-serializer-hl()

Serialized result with syntax highlighting:

<span class="expr xpath-hl">
    <span class="locationStep xpath-hl">
        <span class="nodeTest xpath-hl">foo</span>
        <span class="predicate xpath-hl">[<span class="operation xpath-hl">
          <span class="arg xpath-hl">
             <span class="locationStep xpath-hl">
                <span class="axis xpath-hl">@</span>
                <span class="nodeTest xpath-hl">bar</span>
             </span>
          </span>
          <span class="eq xpath-hl"> = </span>
          <span class="arg xpath-hl">
             <span class="string xpath-hl">'baz'</span>
          </span>
       </span>]</span>
    </span>
</span>

XPath evaluation functions

Function signature:

xpe:xpath-evaluate($context as item()?, $xpath as xs:string, $execution-context as map(*)) as item()*
xpe:xpath-evaluate($context as item()?, $xpath as xs:string) as item()*

Parameter	Default	Type	Description
$context	-	item()?	Context of the evaluated expression.
$xpath	-	xs:string	XPath expression to be evaluated in the context of $context.
$execution-context	map{}	map(*)	The execution context provides static and dynamic context informations for the XPath evaluation. See XPath Evaluation.

Return value: returns the return value of the evaluated expression $xpath in the given context $context. Read more about the evaluation in XPath Evaluation.

Tool functions

The project provides a collection of functions for miscellanous tasks working with the XPath Model. They are stored in the src/main/resources/xsl/xpath-model-tools.xsl.

nk:get-path-in-expression

Function signature:

nk:get-path-in-expression($nodeTest as element(nodeTest), $exprContext as map(*)) as array(map(xs:string, xs:string))*

Parameter	Default	Type	Description
$nodeTest	-	element(nodeTest)	A nodeTest element from an XPath Model instance.
$exprContext	-	map(*)	A context object. See context objects.

Return value: returns a sequence of Path Objects for the given $nodeTest.

nk:get-return-from-expr

Function signature:

nk:get-return-from-expr($expr-content as element()) as element()*

Parameter	Default	Type	Description
$expr-content	-	element()	Any element of the XPath Model repressenting an expression or sub expression.

Return value: returns the XPath Model elements which are specifies the return value of the input expression. For example in the expression foo[@bar], the node test foo would specify the return value of the expression, the node test @bar doesn't.

The following elements of the XPath Model can be returned by this function:

• string
• integer
• decimal
• double
• varRef
• empty
• self
• root
• function-call
• function
• lookup
• map
• array
• function-impl
• nodeTest
• operation (not all operation types)

nk:parent-or-self-el

Function signature:

nk:parent-or-self-el($node as node()) as element()?

Parameter	Default	Type	Description
$node	-	node()	The source node.

Return value: if $node is not an element the function returns the parent element of $node. Otherwise the $node is returned. Note: this is just a small helper function.

nk:QName

Function signature:

nk:QName($node as node()) as xs:QName

Parameter	Default	Type	Description
$node	-	node()	The source node.

Return value: A qualified name, created by the value and in the namespace context of $node.

nk:sch-context

Function signature:

nk:sch-context($node as node(), $expr as element(expr)?) as map(xs:string, item()*)

Parameter	Default	Type	Description
$node	-	node()	A node in an Schematron schema which has an XPath expression as value.
$expr	-	element(expr)?)	The expression repressented in the XPath Model.

Return value: The Schematron context object for the XPath expression in $node.

nk:serialize-steps

Function signature:

nk:serialize-steps($steps as array(map(xs:string, xs:string))) as xs:string
nk:serialize-steps($steps as array(map(xs:string, xs:string)), $namespaces as map(xs:string, xs:string)) as xs:string

Parameter	Default	Type	Description
$steps	-	array(map(xs:string, xs:string))	A Path Object.
$namespaces	map{'':''}	map(xs:string, xs:string)	A prefix→namespace URI mapping for QName serialization.

Return value: Returns the Path Object serialized to a string.

Important: this is just for visualisation of the Path Objects. For better understanding it follows the XPath syntax but it is not ensured, that the return value is a valid XPath expression!

nk:varQName

Function signature:

nk:varQName($node as node()) as xs:QName

Parameter	Default	Type	Description
$node	-	node()	The source node.

Return value: The same as the function nk:QName would return, just that unprefixed names are always in the null namespace. Note: this is just a small helper function for XSLT variable names.

nk:xsl-context

Function signature:

nk:xsl-context($node as node(), $expr as element(expr)?) as map(xs:string, item()*)

Parameter	Default	Type	Description
$node	-	node()	A node in an XSLT stylesheet which has an XPath expression as value.
$expr	-	element(expr)?)	The expression repressented in the XPath Model.

Return value: The XSLT context object for the XPath expression in $node.

Tool Function Concepts

Some tool functions are based on complex concepts which have to be described more detailed.

Context Objects

To analyze an XPath Model instance the context of the original expression (base expression) is required. For instance: if the expression contains variable references, only with the context you can make the lookup to its declaration.

To provide the context, the tool functions knows context objects. The creation of the context object is depending on the host language of the original expression. Currently this project supports two host languages: XSLT and Schematron. To create a context object you can use the following functions:

• nk:sch-context
• nk:xsl-context

The Context Object is an XDM map with the following fields:

Key	Type	Value Description
parent	function() as map(*)?	A function which creates a context object for the expression which specifies the context of the base expression.
variable-context	function($variableName as xs:QName) as map(*)?	A function which makes a look up for the declaration of the variable $variableName and creates a context object for its expression (if it was declared with a single expression).
expr	element(expr)?	Base expression of the context as XPath model instance
node	node()	XDM node which has the original expression as value (usually an attribute, in rare cases text nodes or elements)

The context object is expected as parameter of the function:

• nk:get-path-in-expression

Path Objects

To analyze XPath node tests in the XPath Model it is useful to detect the context path of it's evaluation. The context path of the node test @baz in the expression /foo[@id][parent::bar[1]/count(@baz) = 1] is /child::foo/parent::bar/@baz. To have a common and simple way to express such context paths through a tree the Path Object were introduced.

A Path Object is modeled as XDM arrays (array(map(xs:string, xs:string))). Each array member represents a step with a Step Object.

The Path Object is returned by the following function:

• nk:get-path-in-expression

The Path Object is expected as parameter of the function:

• nk:serialize-steps

Step Object

A step object is modeled as XDM map (map(xs:string, xs:string)) and created by an XPath Model <nodeTest> element. The map has always the following fields:

Key	Reference to XPath Model	Value Description
axis	nodeTest/parent::locationStep/@axis	The XPath axis used to select the nodes.
local-name	nodeTest/@name	A local name or *. Wildcards or generic node test have always *
namespace	nodeTest/@name	A namespace URI or *. The null namespace is represented as an empty string.
kind	nodeTest/@kind	Possible values: element, attribute, text, processing-instruction, comment, document-node and node.