p:label-elements (3.1)

Labels elements by adding an attribute.

Summary
Description
Examples
- Basic usage
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:label-elements">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="true"/>
  <option name="attribute" as="xs:QName" required="false" select="'xml:id'"/>
  <option name="label" as="xs:string" required="false" select="'concat("_",$p:index)'"/>
  <option name="match" as="xs:string" required="false" select="'*'"/>
  <option name="replace" as="xs:boolean" required="false" select="true()"/>
</p:declare-step>

The p:label-elements step generates a label for each matched element and stores that label in the specified attribute.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`xml html`	`false`	The document to label.
`output`	`result`	`true`	`xml html`	`true`	The resulting document.

Options:

Name	Type	Req?	Default	Description
`attribute`	`xs:QName`	`false`	`xml:id`	The name of the attribute that contains the label
`label`	`xs:string` (XPath expression)	`false`	`concat("_",$p:index)`	An XPath expression that computes the value for the label. This expression is evaluated with a matched element as context item. A variable `$p:index` is available that holds the index (sequence number) of the match.
`match`	`xs:string` (XSLT selection pattern)	`false`	`*`	An XSLT match expression that matches the elements to label.
`replace`	`xs:boolean`	`false`	`true`	Whether to replace existing attributes. If this value is `false`, existing attributes with the same name as mentioned in the `attribute` option are left in peace. If `true` (default), they are replaced.

Description

The p:label-elements step performs the following actions:

It takes the document appearing on its source port and finds all the elements matched by the expression in the match option.
For every matched element, it evaluates the expression in the label option. This is done with the matched element as context item (so accessible using the dot . operator). An additional variable $p:index is available that holds the index (sequence number) of the match.
If the replace option is true (default), an attribute is added/replaced on the matched element. The name of this attribute is in the attribute option. Its value comes from the evaluation of the expression in the label option.
If the replace is false, an existing attribute with the same name is not replaced.
After all matches are handled, the resulting document appears on the result port.

Examples

Basic usage

The following example uses all the default values of the options of p:label-elements. This means an attribute called xml:id is added to every element. Values become an underscore followed by the index of the element. Existing xml:id attributes are replaced.

Source document:

<movies>
   <movie title="Apocalypse now"/>
   <movie title="Dune" xml:id="1234"/>
</movies>

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:label-elements/>

</p:declare-step>

Result document:

<movies xml:id="_1">
   <movie title="Apocalypse now" xml:id="_2"/>
   <movie title="Dune" xml:id="_3"/>
</movies>

To make this a little more interesting, let’s label the <movie> elements only and compute their label based on a generated identifier (using fn:generate-id()) and the movie’s name (replacing whitespace using fn:replace()). We keep existing xml:id attributes. The source document is the same as in the previous example.

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:label-elements match="movie" label="generate-id() || '_' || replace(@title, '\s', '-')" replace="false"/>

</p:declare-step>

Result document:

<movies>
   <movie title="Apocalypse now" xml:id="id274174643_Apocalypse-now"/>
   <movie title="Dune" xml:id="1234"/>
</movies>

Additional details

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

Errors raised

Error code	Description
`XC0023`	It is a dynamic error if the selection pattern matches a wrong type of node.

Reference information

This description of the p:label-elements 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:label-elements step can be found here.

The p:label-elements step is part of categories:

The p:label-elements step is also present in version: 3.0.