p:encode (3.1) 

Encodes a document.

Summary

<p:declare-step type="p:encode">
  <input port="source" primary="true" content-types="any" sequence="false"/>
  <output port="result" primary="true" content-types="application/xml" sequence="true"/>
  <option name="encoding" as="xs:string" required="false" select="()"/>
  <option name="serialization" as="map(xs:QName,item()*)?" required="false" select="()"/>
</p:declare-step>

The p:encode step encodes the document appearing on its source port, for example with base64 encoding. The encoded version is wrapped in a <c:data> element and appears on the result port.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

source

input

true

any

false

The source document to encode:

  • If this is a binary document, its content is encoded directly.

  • Any other kind of document is serialized first (as if written to disk, see also the serialization option). The serialized version is encoded.

result

output

true

application/xml

true

A <c:data> element (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace), containing the encoded version of the source document. See here for a more detailed description of the <c:data> element.

Options:

Name

Type

Req?

Default

Description

encoding

xs:string

false

()

The encoding the step must produce. The only standard value currently supported is base64 (default).

Whether any other encodings are supported and what their names (value for this option) are is implementation-defined and therefore dependent on the XProc processor used.

serialization

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

false

()

This option can supply a map with serialization properties for serializing the document on the source port, before encoding takes place.

If the source document has a serialization document-property, the two sets of serialization properties are merged (properties in the document-property have precedence).

Example: serialization="map{'indent': false()}". See also the Effect of serialization example.

Description

The p:encode can be used to encode a document. The only standard encoding currently supported is base64. The encoded version of the source document is wrapped in a <c:data> element and appears on the result port. A more detailed description of the <c:data> element can be found here.

There is no p:decode step. Decoding (of <c:data> elements) is performed by the p:cast-content-type step.

Examples

Basic usage

Assume we have a simple input text document that looks like this:

Hi there!

Feeding this to p:encode results in the following:

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

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

  <p:encode/>

</p:declare-step>

Result document:

<c:data xmlns:c="http://www.w3.org/ns/xproc-step"
        content-type="text/plain"
        encoding="base64"
        charset="UTF-8">SGkgdGhlcmUh</c:data>

Effect of serialization

When encoding an XML document, this is serialized first (as if written to disk). The result of the serialization therefore has an effect on the outcome, as shown in the two examples below.

Source document:

<text>
   <para>Hello XProc fans!</para>
</text>

Encoding with indenting:

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

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

  <p:encode serialization="map{'indent': true()}"/>

</p:declare-step>

Result document:

<c:data xmlns:c="http://www.w3.org/ns/xproc-step"
        content-type="application/xml"
        encoding="base64"
        charset="UTF-8">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHRleHQ+CiAgIDxwYXJhPkhlbGxvIFhQcm9jIGZhbnMhPC9wYXJhPgo8L3RleHQ+</c:data>

Encoding without indenting (using the same input document as in the example above):

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

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

  <p:encode serialization="map{'indent': false()}"/>

</p:declare-step>

Result document:

<c:data xmlns:c="http://www.w3.org/ns/xproc-step"
        content-type="application/xml"
        encoding="base64"
        charset="UTF-8">PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48dGV4dD4KICA8cGFyYT5IZWxsbyBYUHJvYyBmYW5zITwvcGFyYT4KPC90ZXh0Pg==</c:data>

Additional details

  • The document appearing on the result port only has a content-type property. It has no other document-properties (also no base-uri).

Reference information

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

The p:encode step is part of categories: