p:compare (3.1) 

Compares documents for equality.

Summary

<p:declare-step type="p:compare">
  <input port="source" primary="true" content-types="any" sequence="false"/>
  <output port="result" primary="true" content-types="application/xml" sequence="false"/>
  <input port="alternate" primary="false" content-types="any" sequence="false"/>
  <output port="differences" primary="false" content-types="any" sequence="true"/>
  <option name="fail-if-not-equal" as="xs:boolean" required="false" select="false()"/>
  <option name="method" as="xs:QName?" required="false" select="()"/>
  <option name="parameters" as="map(xs:QName, item()*)?" required="false" select="()"/>
</p:declare-step>

The p:compare step compares the documents appearing on its source and alternate for equality. It returns a simple XML document containing the boolean result of the comparison.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

any

false

Source document to compare.

result

output

true

application/xml

false

An XML document consisting of a single <c:result> element (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace) containing true when the documents compare as equal or false when differences were found.

Example: <c:result xmlns:c="http://www.w3.org/ns/xproc-step">true</c:result>

alternate

input

false

any

false

Source document to compare.

differences

output

false

any

true

If the fail-if-not-equal option is false and differences were found, this port may submit a summary of the differences. The existence and format of this summary document is implementation-defined and therefore depends on the XProc processor used.

Options:

Name

Type

Req?

Default

Description

fail-if-not-equal

xs:boolean

false

false

If this option is true and the documents do not compare as equal, the step raises error XC0019.

method

xs:QName?

false

()

Specifies the comparison method used. If the value of this option is the empty sequence (default) or deep-equal, p:compare must do the same as the XPath deep-equal() function.

Support for any other comparison method is implementation-defined and therefore depends on the XProc processor used.

parameters

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

false

()

Parameters controlling the comparison. Keys, values and their meaning depend on the value of the method option and the XProc processor used.

Description

The p:compare step takes the documents appearing on its source and alternate ports and tests whether these are equal. Now testing XML documents for equality is not as easy as it sounds: what to do with whitespace, comments, order of attributes, etc. The default behavior of p:compare is the same as that of the XPath deep-equal() function. Whether other comparison methods are supported is implementation-defined and therefore dependent on the XProc processor used.

If the fail-if-not-equal option is false (default), the step emits a simple XML document on its result port, saying true (equal) or false (not equal). If the fail-if-not-equal option is true and the documents are not equal, error XC0019 is raised.

Examples

Comparing two documents

The following document is compared against what we supply on the alternate port. In this example the comparison checks out and p:compare returns true.

<texts>
   <text>Hi there!</text>
</texts>

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:compare>
    <p:with-input port="alternate">
      <texts>
        <text>Hi there!</text>
      </texts>
    </p:with-input>
  </p:compare>

</p:declare-step>

Result document:

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">true</c:result>

Additional details

  • No document-properties from the documents on the source and/or alternate ports survive. The resulting document has a content-type document-property set to application/xml and no base-uri document-property.

Errors raised

Error code

Description

XC0019

It is a dynamic error if the documents are not equal according to the specified comparison method, and the value of the fail-if-not-equal option is true.

XC0076

It is a dynamic error if the comparison method specified in <p:compare> is not supported by the implementation.

XC0077

It is a dynamic error if the media types of the documents supplied are incompatible with the comparison method.

Reference information

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

The p:compare step is part of categories:

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