p:identity (3.1)

Copies the source to the result without modifications.

Summary
Description
Examples
Additional details
Reference information

Summary

<p:declare-step type="p:identity">
  <input port="source" primary="true" content-types="any" sequence="true"/>
  <output port="result" primary="true" content-types="any" sequence="true"/>
</p:declare-step>

The p:identity step makes a verbatim copy of what appears on its source port to its result port.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`any`	`true`	The source document(s)
`output`	`result`	`true`	`any`	`true`	The resulting document(s). These will be exactly the same as what appeared on the `source` port.

Description

The p:identity step does… nothing. It makes a verbatim copy of all documents appearing on its source port to its result port. Although it doesn’t do anything, it is actually extremely useful and virtually indispensable. The examples below show some use cases.

Examples

Create a fixed document

There are many situations where you need to create a fixed document in your pipeline. For instance:

On an error catch you want some <error …> element as result:

<p:catch>
  <p:identity>
    <p:with-input>
      <error … />
    </p:with-input>
  </p:identity>
</p:catch>

Some pipelines write their main results to disk and the actual output of the pipeline doesn’t matter. In these cases it is often useful to produce some kind of report document with relevant information (for instance, when it happened, where the results are, etc.):
```
<p:identity>
  <p:with-input>
    <report timestamp="{current-dateTime()}" href-result="{$href-result-location}" … />
  </p:with-input>
</p:identity>
```

Create an explicit anchor points in your pipeline

Because the p:identity step does’t do anything, it can be used to create “anchor points” in your pipeline. Assume you have a complicated pipeline where some version of the document flowing through must be used somewhere else. The p:identity step can be used to mark such a location explicitly. In the following example an anchor point called raw-version is created and, later on, referred to:

<p:declare-step xmlns:p="http://www.w3.org/ns/xproc" version="3.0">
  
  <!-- Some complicated computations… -->
  
  <p:identity name="raw-version"/>
  
  <!-- Some more complicated computations… -->
  
  <!-- And then a step refers back to the raw version: -->
  <p:insert match="/*" position="first-child">
    <p:port port="insertion" pipe="@raw-version"/>
  </p:insert>
  
  <!-- And some more computations… -->
  
</p:declare-step>

You could also achieve this by using the name="raw-version" attribute on the last step of the first batch of computations. However, by using an explicit p:identity step it stands out in the code. Also, when the computations change (and they will), you don’t have to remember to keep the name="raw-version" attribute on the last one always.

Produce a processing message

XProc has a message attribute (or p:message on steps not in the XProc namespace) that results in a message when the pipeline runs. Where this message appears depends on how the pipeline is run. Sometimes you want to explicitly produce messages when some point in your pipeline is reached. Since p:identity does’t do anything, it is ideal for this:

<p:identity message="We started processing!"/>
<p:identity message="- Input document {$href-input}"/>
<p:identity message="- Processing type {$processing-type}"/>

Additional details

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

Reference information

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

The p:identity step is part of categories:

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