p:file-copy (3.0) 

Copies a file or directory.

Summary

<p:declare-step type="p:file-copy">
  <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()"/>
  <option name="overwrite" as="xs:boolean" required="false" select="true()"/>
</p:declare-step>

The p:file-copy step copies a file or a directory to a given target.

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 copy from.

target

xs:anyURI

true

 

The URI of the target file or directory to copy 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.

If you’re copying a directory, please note that an error may mean that a partial copy has already been made.

overwrite

xs:boolean

false

true

Determines what happens if p:file-copy needs to overwrite an existing file:

  • If this option is true (default), the existing file is overwritten.

  • If this option is false, no existing file will be changed.

Description

The p:file-copy step copies a file or a directory, as specified in the href option, to the target specified in the target option. Any non-existent directory in the target option value will be created. 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).

If the target option specifies an existing directory (existing on disk), the step attempts to copy the source file or directory into that target directory, preserving the name of the source. This means that you cannot use p:file-copy to copy a directory to another location under a different name. See the Copying a directory under a different name example on how to achieve this.

Examples

Basic usage

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

Pipeline document:

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

  <p:output port="result"/>

  <p:file-copy 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>

Copying a directory under a different name

If you’re copying a directory, the p:file-copy step always copies this into the designated target directory. This means that you cannot copy a directory to another location under a different name. In order to achieve this, you subsequently must rename the copied result using p:file-move:

Pipeline document:

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

  <p:output port="result"/>

  <p:file-copy href="data/" target="build/"/>
  <p:file-move href="build/data/" target="build/data-renamed/"/>

</p:declare-step>

Result document (of the p:file-move):

<c:result xmlns:c="http://www.w3.org/ns/xproc-step">file:/…/…/build/data-renamed/</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-copy 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.

XC0144

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

XC0145

It is a dynamic error if <p:file-copy> is not available to the step due to access restrictions in the environment in which the pipeline is run.

XC0157

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-copy 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-copy step can be found here.

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

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