p:store (3.0)

Stores a document.

Summary
Description
Examples
- Basic usage
- Using p:store for writing intermediate results
Additional details
Errors raised
Reference information

Summary

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

The p:store step stores the document appearing on its source port to a URI. This document is passed unchanged to the result port. It outputs the absolute URI of the location of the stored document on the result-uri port.

Ports:

Type	Port	Primary?	Content types	Seq?	Description
`input`	`source`	`true`	`any`	`false`	The document to store.
`output`	`result`	`true`	`any`	`false`	The resulting document. This will be exactly the same as the document on the `source` port.
`output`	`result-uri`	`false`	`application/xml`	`false`	An XML document consisting of just a single `<c:result>` element containing the absolute URI the document is stored to (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">file:///some/path/document.xml</c:result>`

Type

Port

Primary?

Content types

Seq?

Description

input

source

true

any

false

The document to store.

output

result

true

any

false

The resulting document. This will be exactly the same as the document on the source port.

output

result-uri

false

application/xml

false

An XML document consisting of just a single <c:result> element containing the absolute URI the document is stored to (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">file:///some/path/document.xml</c:result>

Options:

Name	Type	Req?	Default	Description
`href`	`xs:anyURI`	`true`		The URI to store the document to. In most cases, `p:store` will be used to store a document to disk. An absolute URI for this must start with `file://`. For instance, on Windows, `file:///C:/some/path/document.xml` (although Windows uses backslashes (`\`) to separate path components, slashes (`/`) work fine and are more universal). Using a single slash after `file:` also works: `file:/C:/some/path/document.xml`. An attempt will be made to create all non-existing folders in the path. If this value is relative, it 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:store` step is stored).
`serialization`	`map(xs:QName,item()*)?`	`false`	`()`	This option can supply a map with serialization properties for storing the document. 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': true()}"`

Name

Type

Req?

Default

Description

href

xs:anyURI

true

The URI to store the document to.

In most cases, p:store will be used to store a document to disk. An absolute URI for this must start with file://. For instance, on Windows, file:///C:/some/path/document.xml (although Windows uses backslashes (\) to separate path components, slashes (/) work fine and are more universal). Using a single slash after file: also works: file:/C:/some/path/document.xml. An attempt will be made to create all non-existing folders in the path.

If this value is relative, it 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:store step is stored).

serialization

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

false

()

This option can supply a map with serialization properties for storing the document.

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': true()}"

Description

The p:store step stores the document appearing on its source port to a URI. This document is passed unchanged to the result port. So within the pipeline the step acts as a p:identity step.

It outputs the absolute URI of the location of the stored document on the result-uri port.

Examples

Basic usage

Whatever input document is passed to the following pipeline, it is stored to disk in a document tmp/x.xml, relative to where the pipeline is stored. The final p:identity step is just used to show you the document appearing on the result-uri port.

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:store href="tmp/x.xml"/>
  
  <p:identity>
    <p:with-input pipe="result-uri"/>
  </p:identity>

</p:declare-step>

Result document:

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">file:/…/…/x.xml</c:result>

Doing something with what appears on the result-uri port is of course completely optional. If you don’t attach anything to this port, the <c:result> document will simply disappear into oblivion.

Using p:store for writing intermediate results

When developing a pipeline, you often want to take a look at what exactly is flowing through it at a certain stage. Inserting a (temporary) p:store step is the most easy way to quickly write some intermediate result to a temporary file on disk for inspection. Since p:store acts like a p:identity step. nothing happens to the flow in your pipeline.

…
<p:store href="file:///my/debug/files/location/stepx.xml"/>
…

Sometimes you want to keep these temporary storage steps after development. You never know what bugs will pop up and you might need them again! XProc has static options that you can use for this:

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

  <p:option static="true" name="write-debug-documents" select="true()"/>
  
  …

  <p:store use-when="{$write-debug-documents}" href="file:///my/debug/files/location/stepx.xml"/>

  …

</p:declare-step>

For the production version you set the write-debug-documents static option to false(). This makes the p:store disappear from the processed code, as if it was never there…

Additional details

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

Errors raised

Error code	Description
`XC0050`	It is a dynamic error if the URI scheme is not supported or the step cannot store to the specified location.

Reference information

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

The p:store step is part of categories:

The p:store step is also present in version: 3.1.