p:file-delete (3.1)

Deletes a file or directory.

Summary
Description
Examples
- Basic usage
Additional details
Errors raised
Reference information

Summary

<p:declare-step type="p:file-delete">
  <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="recursive" as="xs:boolean" required="false" select="false()"/>
</p:declare-step>

The p:file-delete step deletes a file or directory.

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`result`	`output`	`true`	`application/xml`	`false`	A `<c:result>` element containing the absolute URI of the file or directory to delete (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 or directory to delete.
`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. If you’re deleting a directory with the `recursive` option set to `true`, please note that an error may mean that a partial delete has already been made.
`recursive`	`xs:boolean`	`false`	`false`	When deleting a directory, setting this option to `true` means that the contents of the directory (any contained files and/or sub-directories) will also be deleted. When this option is set to `false` (default), deleting a directory is possible only when the directory is empty.

Name

Type

Req?

Default

Description

href

xs:anyURI

true

The URI of the file or directory to delete.

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.

If you’re deleting a directory with the recursive option set to true, please note that an error may mean that a partial delete has already been made.

recursive

xs:boolean

false

When deleting a directory, setting this option to true means that the contents of the directory (any contained files and/or sub-directories) will also be deleted.

When this option is set to false (default), deleting a directory is possible only when the directory is empty.

Description

The p:file-delete step deletes a file or directory 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 deleted file or directory (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

Be aware that whether or not the file or directory exists, the step will always return a <c:result> element. It makes no distinction between “deleted” and “didn’t exist in the first place”. Some XProc processors add additional attributes to the <c:result> element (in a separate, processor dependent, namespace) to tell you what really happened.

If you're deleting a directory, you’ll probably want the recursive option set to true. This ensures that all containing files an/or subdirectories will also be deleted (recursively). Deleting a directory with recursive set to false (default) will succeed only when the directory is empty.

Examples

Basic usage

The following example deletes an (existing) file data/x.xml:

Pipeline document:

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

  <p:output port="result"/>
  
  <p:file-delete 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-delete 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
`XC0113`	It is a dynamic error if an attempt is made to delete a non-empty directory and the `recursive` option was set to `false`.
`XC0142`	It is a dynamic error if an implementation does not support `<p:file-delete>` for a specified scheme.
`XC0143`	It is a dynamic error if `<p:file-delete>` is not available to the step 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-delete 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-delete step can be found here.

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

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