p:file-touch (3.1) 

Changes the modification timestamp of a file.

Summary

<p:declare-step type="p:file-touch">
  <output port="result" primary="true" content-types="application/xml" sequence="false"/>
  <option name="href" as="xs:anyURI" required="true"/>
  <option name="fail-on-error" as="xs:boolean" required="false" select="true()"/>
  <option name="timestamp" as="xs:dateTime?" required="false" select="()"/>
</p:declare-step>

The p:file-touch step changes the modification timestamp of the file specified in the href option.

Ports:

Port

Type

Primary?

Content types

Seq?

Description

result

output

true

application/xml

false

A <c:result> element containing the absolute URI of the modified file (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

Options:

Name

Type

Req?

Default

Description

href

xs:anyURI

true

 

The URI of the file to change the modification timestamp of.

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.

timestamp

xs:dateTime?

false

()

If set, the file’s modification timestamp is to this value. If absent or empty, the current system date/time is used.

Description

The p:file-touch step changes the modification timestamp of the file specified in the href option. The result port emits a small XML document with only a <c:result> element, containing the absolute URI of the changed file (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

If the file specified by the href option doesn’t exist, an empty file will be created at the given location.

Examples

Basic usage

The following example changes the modification date of data/x.xml the current system date and time:

Pipeline document:

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

  <p:output port="result"/>

  <p:file-touch href="data/x.xml"/>

</p:declare-step>

Result document:

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

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-touch 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

XC0136

It is a dynamic error if an implementation does not support <p:file-touch> for a specified scheme.

XC0137

It is a dynamic error if <p:file-touch> 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-touch 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-touch step can be found here.

The p:file-touch step is part of categories:

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