p:make-absolute-uris (3.1) 

Make URIs in the document absolute.

Summary

<p:declare-step type="p:make-absolute-uris">
  <input port="source" primary="true" content-types="xml html" sequence="false"/>
  <output port="result" primary="true" content-types="xml html" sequence="false"/>
  <option name="match" as="xs:string" required="true"/>
  <option name="base-uri" as="xs:anyURI?" required="false" select="()"/>
</p:declare-step>

The p:make-absolute-uris step makes element and/or attribute values in the document appearing on the source port absolute by applying a base URI.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

xml html

false

The document to resolve the URIs in.

result

output

true

xml html

false

The resulting document.

Options:

Name

Type

Req?

Default

Description

match

xs:string (XSLT selection pattern)

true

 

The XSLT match pattern for the attributes and/or elements that hold the URIs to change.

base-uri

xs:anyURI?

false

()

The base URI to use for making the matched attributes/elements absolute.

If this option is not specified, the base URI of the matched element/attribute in the source document is used. In most cases this will be the location (path on disk) where it originated from.

Description

The p:make-absolute-uris step takes the document appearing on its source port and searches for elements and/or attributes as indicated by the match option. The values of these elements/attributes are taken as URIs and, if relative, resolved against a base URI as specified in the base-uri option. If there's no base-uri option, the base URI of the element/attribute is used.

Why is this useful? URIs in documents that are edited or received from the web are often relative. They point to other documents, for instance images, that are elsewhere on disk or the web, in a location relative to the source document. For instance: images/picture.jpg. This allows for flexibility in the location of the documents. However, when processing these URIs and access the referenced documents, the code needs to know how to resolve them into absolute ones. It is practical to arrange all this URI resolving in advance, and this is what p:make-absolute-uris is for.

There is an important thing to keep in mind when supplying a value for the base-uri option:

  • When its value ends with a slash (/), it points to a location. All URIs are resolved against that location. For instance: file:///myapp/images/

  • When its value does not end with a slash, it points to a document. All URIs are resolved against the location of this document. For instance, for a base-uri value file:///myapp/images/logo.svg, the URIs are resolved against the location file:///myapp/images/

The Basic usage example shows this difference.

Examples

Basic usage

This example shows what happens to different kinds of URIs when resolved. The base-uri value here points to a location (because it ends with a /).

Source document:

<URIs>
   <URI>image.jpg</URI>
   <URI>A/B/C/</URI>
   <URI>/image.jpg</URI>
   <URI>https://xprocref.org/index.html</URI>
</URIs>

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:make-absolute-uris match="URI" base-uri="file:///X/Y/Z/"/>

</p:declare-step>

Result document:

<URIs>
   <URI>file:/…/…/image.jpg</URI>
   <URI>file:/…/…/file:/X/Y/Z/A/B/C/</URI>
   <URI>file:/…/…/image.jpg</URI>
   <URI>https://xprocref.org/index.html</URI>
</URIs>

Just to show you the difference, this is what happens when you omit the final / from the base-uri option. Its value, file:///X/Y/Z, now points to a document called Z. The URIs are resolved against the location of this document.

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:make-absolute-uris match="URI" base-uri="file:///X/Y/Z"/>
  
</p:declare-step>

Result document:

<URIs>
   <URI>file:/…/…/image.jpg</URI>
   <URI>file:/…/…/file:/X/Y/A/B/C/</URI>
   <URI>file:/…/…/image.jpg</URI>
   <URI>https://xprocref.org/index.html</URI>
</URIs>

Additional details

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

  • The match option must match attributes or elements. If anything else is matched, error XC0023 is raised.

  • A relative value for the base-uri option is resolved against the base URI of the element on which this option is specified. In most cases this will be the static base URI of your pipeline (the path where the XProc source containing the p:make-absolute-uris is stored). This is very probably not what you want.

  • If no base-uri option is specified and an element/attribute matched has no base URI also, the result is implementation-defined and therefore dependent on the XProc processor used.

Errors raised

Error code

Description

XC0023

It is a dynamic error if the selection pattern matches a wrong type of node.

XD0064

It is a dynamic error if the base URI is not both absolute and valid according to RFC 3986 .

Reference information

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

The p:make-absolute-uris step is part of categories:

The p:make-absolute-uris step is also present in version: 3.0.