p:file-move (3.1) 

Moves or renames a file or directory.

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.

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:

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.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-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.0.