p:compare (3.0)

Compares documents for equality.

Summary
Description
Examples
- Comparing two documents
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:compare">
  <input port="source" primary="true" content-types="any" sequence="false"/>
  <input port="alternate" primary="false" content-types="any" sequence="false"/>
  <output port="differences" primary="false" content-types="any" sequence="true"/>
  <output port="result" primary="false" content-types="application/xml" sequence="false"/>
  <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.
`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.
`result`	`output`	`false`	`application/xml`	`false`	An XML document consisting of a single `<c:result>` element containing `true` when the documents compare as equal or `false` when differences were found (the `c` prefix here is bound to the `http://www.w3.org/ns/xproc-step` namespace). Example: `<c:result xmlns:c="http://www.w3.org/ns/xproc-step">true</c:result>` Notice that for XProc 3.0 this port is not primary (as would be expected). This was an oversight and amended in `p:compare` in version 3.1.

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 dependent 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.

Name

Type

Req?

Default

Description

fail-if-not-equal

xs:boolean

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 dependent 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" pipe="result@comparing"/>

  <p:compare name="comparing">
    <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>

Notice that for XProc 3.0 we have to bind the step’s result port explicitly to the result port of p:compare (using the pipe="result@comparing" attribute on <p:output>). This is because in XProc 3.0, the result port of p:compare is not primary. This was an oversight and amended in p:compare in version 3.1.

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.0. This is a required step (an XProc 3.0 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.1.