p:file-create-tempfile (3.1)

Creates a temporary file.

Summary
Description
Examples
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:file-create-tempfile">
  <output port="result" primary="true" content-types="application/xml" sequence="false"/>
  <option name="delete-on-exit" as="xs:boolean" required="false" select="false()"/>
  <option name="fail-on-error" as="xs:boolean" required="false" select="true()"/>
  <option name="href" as="xs:anyURI?" required="false" select="()"/>
  <option name="prefix" as="xs:string?" required="false" select="()"/>
  <option name="suffix" as="xs:string?" required="false" select="()"/>
</p:declare-step>

The p:file-create-tempfile step creates a temporary file.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`result`	`output`	`true`	`application/xml`	`false`	A `<c:result>` element containing the absolute URI of the created temporary file (the `c` prefix here is bound to the `http://www.w3.org/ns/xproc-step` namespace).

Options:

Name	Type	Req?	Default	Description
`delete-on-exit`	`xs:boolean`	`false`	`false`	If set to `true`, an attempt will be made to automatically delete the temporary file when the processor terminates the pipeline. No error will be raised if this is unsuccessful.
`fail-on-error`	`xs:boolean`	`false`	`true`	Determines what happens if an error occurs during the operation: If this option is `true` (default), an appropriate XProc error is raised. If this option is `false`, the step returns a `<c:error>` document (see here for more information) on its `result` port.
`href`	`xs:anyURI?`	`false`	`()`	The URI of the (existing) directory where the temporary file is created. If not specified, location of the temporary file is implementation-defined and therefore depends on the XProc processor used. Usually this will be the operating system’s default location for temporary files.
`prefix`	`xs:string?`	`false`	`()`	The prefix string for the name of the temporary file to create. Specifying a prefix is useful if your want the temporary files created by your pipeline to be distinguishable from other temporary files in the same directory.
`suffix`	`xs:string?`	`false`	`()`	The suffix string for the name of the temporary file to create. Setting the `suffix` option must be used if you want your temporary file to have a specific extension, like `.xml`. See also the Specifying the temporary file’s extension example.

Description

XProc is designed to process documents without having to continuously store and load these documents to/from disk. But sometimes you do need documents to be stored on disk, for instance when some additional process demands this. You can of course solve this by using p:store with a fixed (or generated) filename. However, if the filename is not important, or there is no obvious location for these files, or if you do’t want these documents to survive pipeline processing, p:file-create-tempfile comes to the rescue.

The p:file-create-tempfile step creates a temporary file:

It is guaranteed that this file didn’t exist beforehand.
The directory where the will be created can be specified using the href option (if you don’t, some logical, system dependent, location for temporary files will be used).
The main part of the filename will be generated by the step. However, you can specify a filename suffix (in the suffix option) and prefix (in the prefix option). This is especially useful if you want your temporary file to have a specific extension. See also the Specifying the temporary file’s extension example.
If you want the resulting temporary file to get deleted after the pipeline finishes, set the delete-on-exit option to true. There is however no guarantee that this deletion succeeds (and you will not get notified if it does’t).

The result port emits a small XML document with only a <c:result> element, containing the absolute URI of the temporary file (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

Examples

Basic usage

The following example creates a temporary file in the (existing) build/ subdirectory (and deletes this again when the pipeline has come to an end):

Pipeline document:

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

  <p:output port="result"/>
  
  <p:file-create-tempfile href="build/" delete-on-exit="true"/>

</p:declare-step>

Result document:

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

Specifying the temporary file’s extension

The following example creates a temporary file with a specific .xml extension in the (existing) build/ subdirectory. In this case we don’t specify that the file must get deleted after the pipeline finishes. Because of the explicit .xml extension, it will be easy to open and inspect the file using your XML editor, if needed.

Pipeline document:

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

  <p:output port="result"/>
  
  <p:file-create-tempfile href="build/" suffix=".xml"/>

</p:declare-step>

Result document:

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

Using a temporary file

Of course, just creating a temporary file is not very useful. You’ll want to write some data to it. The following example shows you how to do this: the document appearing on the source port is written to the temporary file. This is not very useful in itself but it shows how you can “catch” the created temporary file URI and use this in a subsequent step.

Pipeline document:

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

  <p:input port="source"/>
  <p:output port="result"/>
  
  <p:file-create-tempfile href="build/" suffix=".xml"/>

  <p:store href="{string(.)}">
    <p:with-input pipe="source@example-pipeline"/>
  </p:store>

</p:declare-step>

You might also consider catching the created temporary file URI in a variable and use it from there. For this, add the next line directly after the p:file-create-tempfile invocation:

<p:variable name="href-tempfile-uri" select="string(.)"/>

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).
Relative values for the href option are 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:file-create-tempfile is stored).
Working on “normal” files and/or directories (on disk, URI scheme file://) is always supported. Whether any other types are supported is implementation-defined, and therefore depends on the XProc processor used. For this, also the interpretation/definition of what is a “directory” and “file” may vary.

Errors raised

Error code	Description
`XC0116`	It is a dynamic error if the temporary file could not be created.
`XC0138`	It is a dynamic error if an implementation does not support `<p:file-create-tempfile>` for a specified scheme.
`XC0139`	It is a dynamic error if `<p:file-create-tempfile>` cannot be completed due to access restrictions in the environment in which the pipeline is run.
`XD0011`	It is a dynamic error if the resource referenced by the `href` option does not exist, cannot be accessed or is not a file.
`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:file-create-tempfile step is for XProc version: 3.1. This is a non-required step (an XProc 3.1 processor does not have to support this).

The formal specification for the p:file-create-tempfile step can be found here.

The p:file-create-tempfile step is part of categories:

The p:file-create-tempfile step is also present in version: 3.0.