p:hash (3.1) 

Summary

<p:declare-step type="p:hash">
  <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="algorithm" as="xs:QName" required="true"/>
  <option name="value" as="xs:string" required="true"/>
  <option name="match" as="xs:string" required="false" select="'/*/node()'"/>
  <option name="parameters" as="map(xs:QName,item()*)?" required="false" select="()"/>
  <option name="version" as="xs:string?" required="false" select="()"/>
</p:declare-step>

The p:hash step generates a hash code for some value and injects this into the document appearing on the source port.

Ports:

Options:

Description

A hash code in the digital world is a, relatively simple, value computed from some, possibly lengthy, input data. The same input data always results in the same hash code. Hash codes are also called hash values, (hash) digests, (digital) fingerprints, or simply hashes. Hash codes are used for various purposes, see for instance Wikipedia.

The p:hash step computes the hash code of the string value of the value option and inserts this into the document appearing on the source port. The result appears on the result port.

The algorithm used for computing the hash code must be specified using the algorithm option. There are 3 predefined values, that must be supported by all XProc processors:

You can specify the algorithm version using the version option. If you don’t specify this option and use one of the predefined algorithm option values, the default version from the table above is used.

Examples

<hash-value>
   <hash>Will be replaced by the hash value!</hash>
</hash-value>

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

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

  <p:hash algorithm="crc" value="Hi there!"/>

</p:declare-step>

<hash-value>b5c57055b5c57055b5c57055</hash-value>

<hash-values crc="" md="" sha=""/>

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

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

  <p:hash algorithm="crc" value="Hi there!" match="/*/@crc"/>
  <p:hash algorithm="md" value="Hi there!" match="/*/@md"/>
  <p:hash algorithm="sha" value="Hi there!" match="/*/@sha"/>

</p:declare-step>

<hash-values crc="b5c57055"
             md="396199333edbf40ad43e62a1c1397793"
             sha="95e2b07e12754e52c37cfd485544d4f444597bff"/>

<anything/>

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

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

  <p:hash algorithm="crc" value="Hi there!" match="/"/>

</p:declare-step>

b5c57055

Additional details

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

  The exception is when the match option matches the document-node /. In that case the resulting document will be of type text, the content-type document-property will become text/plain and a serialization document-property is removed. Any other document-property is preserved.

• If an XProc processor supports any other algorithm, its code (as supplied to the algorithm option) will be in a namespace.

• If the match option matches an attribute called xml:base, the base URI of this attribute’s parent element is amended accordingly. This is a side-effect of changing an attribute with a pre-defined meaning (and in this case probably never useful).

Errors raised

Reference information

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

The p:hash step is part of categories:

• Standard XProc steps

• Miscellaneous

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