p:uuid (3.1) 

Injects UUIDs into a document.

Summary

<p:declare-step type="p:uuid">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="text xml html" sequence="false"/>
  <option name="match" as="xs:string" required="false" select="'/*'"/>
  <option name="parameters" as="map(xs:QName, item()*)?" required="false" select="()"/>
  <option name="version" as="xs:integer?" required="false" select="()"/>
</p:declare-step>

The p:uuid step takes the document appearing on its source port and replaces nodes matching the match option with a UUID.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to inject the UUIDs in.

result

output

true

text xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

match

xs:string (XSLT selection pattern)

false

/*

The XSLT match pattern for the nodes to replace with the UUID.

parameters

map(xs:QName, item()*)?

false

()

Parameters used to control the UUID generation. The XProc specification does not define any parameters for this option. A specific XProc processor might define its own.

version

xs:integer?

false

()

The UUID version to use for computing its value. Its default value is implementation-defined and therefore dependent on the XProc processor used.

Version 4 UUIDs are always supported. Whether any other versions are supported is also implementation-defined.

Description

UUID stands for Universally Unique Identifier. It is also known as GUID, which stands for Globally Unique Identifier. A UUID is a 128-bit value that is, for all practical purposes, worldwide unique. It is usually written as a 32-character hexadecimal value in a pattern using hyphens, for example f81d4fae-7dec-11d0-a765-00a0c91e6bf6. The Wikipedia page about UUIDs is here.

The p:uuid step does the following:

  • It computes a single UUID, using the version and parameters options. This UUID is used for all replacements (so all replacements get the same value).

  • It takes the document appearing on its source port and holds the XSLT selection pattern in the match option against this.

  • For all matched nodes:

    • If the matched node is an attribute, the value of the attribute is replaced with the UUID.

    • If the document-node is matched, the full document will be replaced by UUID (and the result will therefore be a text document).

    • In all other cases, the full node is replaced by the UUID.

Examples

Basic usage

The following example replaces the text inside the <uuid> elements with a generated UUID:

Source document:

<thing>
   <uuid>UUID</uuid>
   <uuid>UUID</uuid>
</thing>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:uuid match="/thing/uuid/text()"/>

</p:declare-step>

Result document:

<thing>
   <uuid>0f0afa4f-6c7d-4801-81e8-0a143b7c7d59</uuid>
   <uuid>0f0afa4f-6c7d-4801-81e8-0a143b7c7d59</uuid>
</thing>

Please notice that the UUIDs are identical, the same value is used for every replacement.

 

If the match option matches an attribute, the value of the attribute is replaced:

Source document:

<thing uuid=""/>

Pipeline document:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">

  <p:input port="source"/>
  <p:output port="result"/>

  <p:uuid match="/thing/@uuid"/>

</p:declare-step>

Result document:

<thing uuid="5bb6f60c-722a-4219-a836-7214bf2bc541"/>

Additional details

  • p:uuid preserves all document-properties of the document(s) appearing on its source port.

    There is one exception: if the resulting document contains only text, the content-type document-property is changed to text/plain and the serialization document-property is removed.

  • If an attribute called xml:base is added or changed, the base URI of the element is updated accordingly. See also category Base URI related.

Errors raised

Error code

Description

XC0060

It is a dynamic error if the processor does not support the specified version of the UUID algorithm.

Reference information

This description of the p:uuid step is for XProc version: 3.1. This is a required step (an XProc 3.1 processor must support this).

The formal specification for the p:uuid step can be found here.

The p:uuid step is part of categories:

The p:uuid step is also present in version: 3.0.