saxon:pedigree

Given a map or array that was obtained by downward selection within a tree of maps and arrays (such as might be obtained by parsing JSON), and that was marked for tracking of such selections using the saxon:with-pedigree() function, the saxon:pedigree() function returns a map containing information about the containing map or array in this tree, and the key or index used to select it within its immediately containing map or array.

pedigree($in as function(*)) ➔ tuple(container: function(*), key: anyAtomicType?, index: xs:integer?)?

Arguments

 

$in

function(*)

The input map or array

Result

tuple(container: function(*), key: anyAtomicType?, index: xs:integer?)?

Namespace

http://saxon.sf.net/

Saxon availability

Requires Saxon-PE or Saxon-EE. Implemented since Saxon 9.9.

Notes on the Saxon implementation

Available since Saxon 9.9.

Details

If the supplied value is a map or array that has pedigree information by virtue of the fact that it was obtained by downward selection from a map or array that retains pedigree information, the pedigree() function returns information about the containing map or array from which it was selected.

The result of the function is a map. There is always an entry with the key "container", whose value is the containing map or array (or an empty sequence, if we are at the root of the tree). If the container is a map, there will also be an entry with key "key" whose value is the key of this map/array within the containing map. If the container is an array, there will also be an entry with key "index" whose value is the 1-based index of this map/array within the containing array.

If the supplied argument has no pedigree information, the result is an empty sequence.

For example, given the input:

let $M := map{ "roman": map{ "min":1, "max":10, "codes":map{"i":1, "ii":2, "iii":3, "iv":4, "v":5, "vi":6, "vii":7, "viii":8, "ix":9, "x":10} }, "alpha": map{ "min":1, "max":26, "codes":map{"a":1, "b":2, "c":3, "d":4, "e":5, "f":6, "g":7, "h":8, "i":9, "j":10} } } let $augmentedMap := $M => saxon:with-pedigree() let $romanCodes := $augmentedMap?roman?codes return ....

Then ($romanCodes => saxon:pedigree())?container?max returns 10.

The function is particularly useful when using xsl:apply-templates to process JSON structures recursively. For example, it becomes possible to write a template rule such as:

<xsl:template match=".[saxon:pedigree(.)?key='roman']">

Which matches a map (or array) whose key value in its parent map is "roman".

See also the saxon:deep-update extension instruction, which makes use of pedigree information internally.

See also:

saxon:with-pedigree()