p:file-move (3.0)

Moves or renames a file or directory.

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

Summary

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

The p:file-move step moves (or renames) a file or directory to a different location (or name).

Ports:

Port	Type	Primary?	Content types	Seq?	Description
`result`	`output`	`true`	`application/xml`	`false`	A `<c:result>` element containing the absolute URI of the target (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 source file or directory to move (or rename).
`target`	`xs:anyURI`	`true`		The URI of the target file or directory to move to.
`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.

Name

Type

Req?

Default

Description

href

xs:anyURI

true

The URI of the source file or directory to move (or rename).

target

xs:anyURI

true

The URI of the target file or directory to move to.

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.

Description

The p:file-move step attempts to move (or rename) the file or directory specified in the href option to the location specified in the target option. The result port emits a small XML document with only a <c:result> element containing the absolute URI of the target (the c prefix here is bound to the http://www.w3.org/ns/xproc-step namespace).

The inspiration for this step comes from the Unix mv command. If you’re not used to it, it may come as a surprise that moving something can also mean renaming it:

Moving file:///a/b/c.xml to file:///a/b2/c.xml moves the file to the b2 directory. See also the Basic usage example.
But moving file:///a/b/c.xml to file:///a/b/c2.xml renames the file. See also the Renaming a file example.
An example of renaming a directory can be found in the example Copying a directory under a different name in step p:file-copy.

If you’re moving into another directory, this directory must exist. A target must not exist.

Examples

Basic usage

The following example moves a file data/x1.xml to build/x1-copied.xml:

Pipeline document:

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

  <p:output port="result"/>
  
  <p:file-move href="data/x1.xml" target="build/x1-copied.xml"/>

</p:declare-step>

Result document:

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

Please note that the target build/ directory must exist, without an existing x1-copied.xml file.

Renaming a file

The following example renames an existing file build/x1.xml to build/x2.xml:

Pipeline document:

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

  <p:output port="result"/>
  
  <p:file-move href="build/x1.xml" target="build/x2.xml"/>

</p:declare-step>

Result document:

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">file:/…/…/build/x2.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 and target options 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-move 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
`XC0050`	It is a dynamic error the file or directory cannot be copied to the specified location.
`XC0115`	It is a dynamic error if the resource referenced by the `target` option is an existing file or other file system object.
`XC0148`	It is a dynamic error if an implementation does not support `<p:file-move>` for a specified scheme.
`XC0149`	It is a dynamic error if `<p:file-move>` is not available to the step due to access restrictions in the environment in which the pipeline is run.
`XC0158`	It is a dynamic error if the `href` option names a directory, but the `target` option names a file.
`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-move step is for XProc version: 3.0. This is a non-required step (an XProc 3.0 processor does not have to support this).

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

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

The p:file-move step is also present in version: 3.1.