View Old View New View Both View Only Previous Next

XProc 3.1: file steps

Community Group Report

Latest editor’s draft:
https://spec.xproc.org/master/head/file/
Editors:
Norman Walsh
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Participate:
GitHub xproc/3.0-steps
Report an issue
Changes:
Diff against current “status quo” draft
Commits for this specification

This document is also available in these non-normative formats: XML and HTML with automatic change markup courtesy of DeltaXML.


Abstract

This specification describes the file related steps for XProc 3.1: An XML Pipeline Language.

Status of this Document

This specification was published by the XProc Next Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

If you wish to make comments regarding this document, please send them to xproc-dev@w3.org. (subscribe, archives).

Note

This draft is a “last call” draft. This version is stable and will not be updated.

1. Introduction

This specification describes the file related XProc steps. A machine-readable description of these steps may be found in steps.xpl.

Familarity with the general nature of [XProc 3.1] steps is assumed.

Some filesystems and some operating systems support “special” files. These may be interfaces to underlying block or character devices, or represent file system features such as linking two filenames so that they point to the same data. On many filesystems on Unix(-derived) operating systems, the files /dev/null, /dev/urandom, and /dev/zero are special, as are hard and soft symbolic links. Windows and Mac filesystems also support special files and other linking mechanisms.

How the file steps behave with respect to special files is implementation-defined. It may be an error to attempt to access them, or they may be ignored by some or all steps.

2. Step library

2.1. p:directory-list

The p:directory-list step produces a list of the contents of a specified directory.

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
pathxs:anyURI ✔ 
detailedxs:booleanfalse() 
exclude-filterxs:string*() 
include-filterxs:string*() 
max-depthxs:string?'1' 
override-content-typesarray(array(xs:string))?() 
Errors
Error codeDescription
err:XC0012It is a dynamic error if the contents of the directory path are not available to the step due to access restrictions in the environment in which the pipeline is run.
err:XC0017It is a dynamic error if the absolute path does not identify a directory.
err:XC0090It is a dynamic error if an implementation does not support directory listing for a specified scheme.
err:XC0147It is a dynamic error if a specified value is not a valid XPath regular expression.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support directory paths whose scheme is file. It is implementation-defined what other schemes are supported by p:directory-list, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
DefinedAny file or directory determined to be special by the p:directory-list step may be output using a c:other element but the criteria for marking a file as special are implementation-defined.
DefinedThe precise meaning of the detailed properties are implementation-defined and may vary according to the URI scheme of the path.
DefinedAny other attributes on c:file, c:directory, or c:other are implementation-defined
Declaration

<p:declare-steptype="p:directory-list">
     <p:outputport="result"content-types="application/xml"/>
     <p:optionname="path"required="true"as="xs:anyURI"/>        
     <p:optionname="detailed"as="xs:boolean"select="false()"/>  
     <p:optionname="max-depth"as="xs:string?"select="'1'"/>     
     <p:optionname="include-filter"as="xs:string*"/>             
     <p:optionname="exclude-filter"as="xs:string*"/>             
     <p:optionname="override-content-types"as="array(array(xs:string))?"/>
</p:declare-step>

Conformant processors must support directory paths whose scheme is file. It is implementation-defined what other schemes are supported by p:directory-list, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0090) if an implementation does not support directory listing for a specified scheme.

If path is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:directory-list in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0017) if the absolute path does not identify a directory. It is a dynamic error (err:XC0012) if the contents of the directory path are not available to the step due to access restrictions in the environment in which the pipeline is run.

If the detailed option is true, the pipeline author is requesting additional information about the matching entries, see the section called “Directory list details”.

The max-depth option may contain either the string “unbounded” or a string that may be cast to a non-negative integer. An integer value of 0 means that only information about the directory that is given in the path option is returned. A max-depth of 1, which is the default, will effect that also information about the top-level directory’s immediate children will be included. For larger values of max-depth, also the content of directories will be considered recursively up to the maximum depth, and it will be included as children of the corresponding c:directory elements.

If present, the value of the include-filter or exclude-filter option must be a sequence of strings, each one representing a regular expressions as specified in [XPath and XQuery Functions and Operators 3.1], section 7.61 “Regular Expression Syntax”. It is a dynamic error (err:XC0147) if a specified value is not a valid XPath regular expression.

The regular expressions will be matched against an item’s file system path relative to the top-level path that was given in the path option. If the item is a directory, a trailing slash will be appended. The matching is done unanchored: it is a match if the regular expression matches part of the relative item’s file system path. Informally: matching behaves like applying the XPath matches#2 function, like in matches($path, $regular-expression).

Examples: A file file.txt in the directory specified by path will remain file.txt, a relative path dir1/file.txt will remain dir1/file.txt, while a relative path dir1/dir2 will become dir1/dir2/ if dir2 is a directory.

Regular expressions that match a/a/b/file.txt are, for example, ^(\w+/){2,3}.+\.txt$, a/a/b/, or /file\.[^/]+$.

If any include-filter pattern matches the slash-augmented relative path, the entry is included in the output. Matching a directory doesn’t automatically include the contents of the directory or its descendants; to be included, each individual entry must match an include filter. For example, the filter regex ^dir/ will match a directory and its content, but ^dir/$ won’t.

Although matching a directory doesn’t automatically include its entries, matching an entry does automatically include all of its ancestors (back to the initial directory). This assures that the hierarchy of the XML elements matches the hierarchy of the filesystem. When ancestors are included this way, none of their other entires are included unless they match an include filter.

For a file a/a/b/file.txt below the initial directory /home/jane, this output will be produced, omitting content that might be present in the intermediate directories:

<c:directory xml:base="file:///home/jane/" name="jane"> <c:directory xml:base="a/" name="a"> <c:directory xml:base="a/" name="a"> <c:directory xml:base="b/" name="b"> <c:file xml:base="file.txt" name="file.txt"/> </c:directory> </c:directory> </c:directory> </c:directory>

If the exclude-filter pattern matches the slash-augmented relative path, the entry (and all of its content in case of a directory) is excluded in the output.

If both options are provided, the include filter is processed first, then the exclude filter. As a result, an item is included if it matches (at least) one of the include-filter values and none of the exclude-filter values.

If no include-filter is given, that is, if include-filter is an empty sequence, any item will be included in the result (unless it is excluded by exclude-filter).

Note

There is no way to specify a list of values using attribute value templates. If the option shortcut syntax is used to provide the include-filter or exclude-filter option, it will consist of a single regular expression. To specify a list of regular expressions, you must use the p:with-option syntax.

The override-content-types option can be used to partially override the content-type determination mechanism. This works just like with the override-content-types option of p:archive-manifest and p:unarchive (see Overriding content types in XProc 3.1: Standard Step Library), except that the regular expression matching is done against the paths as used for the matching of the include-filter and exclude-filter options.

The result document produced for the specified directory path has a c:directory document element whose base URI, attached as an xml:base attribute, is the absolute directory path (expressed as a URI that ends in a slash) and whose name attribute (without a trailing slash) is the last segment of the directory path. The same base URI is attached as the resulting document’s base-uri property and, accordingly, as its document node’s base URI.

<c:directory
  name = string
  size? = integer
  readable? = boolean
  writable? = boolean
  last-modified? = dateTime
  hidden? = boolean>
    (c:file |
     c:directory |
     c:other)*
</c:directory>

Its contents are determined as follows, based on the entries in the directory identified by the directory path. For each entry in the directory and subject to the rules that are imposed by the max-depth, include-filter, and exclude-filter options, a c:file, a c:directory, or a c:other element is produced, as follows:

  • A c:directory is produced for each subdirectory not determined to be special. Depending on the values of the three options, it may contain child elements for the directory’s content.

  • A c:file is produced for each file not determined to be special.

    <c:file
      name = string
      size? = integer
      readable? = boolean
      writable? = boolean
      last-modified? = dateTime
      hidden? = boolean
      content-type? = ContentType />

  • Any file or directory determined to be special by the p:directory-list step may be output using a c:other element but the criteria for marking a file as special are implementation-defined.

    <c:other
      name = string
      size? = integer
      readable? = boolean
      writable? = boolean
      last-modified? = dateTime
      hidden? = boolean />

Each of the elements c:file, c:directory, and c:other has a name attribute, whose value is a relative IRI reference, giving the (local) file or directory name.

Each of these element also contains the corresponding resource’s URI in an xml:base attribute, which may be a relative URI for any but the top-level c:directory element. In the case of c:directory, it must end in a trailing slash. This way, users will always be able to compute the absolute URI for any of these elements by applying fn:base-uri() to it.

Directory list details

If detailed is false, then only the name and xml:base attributes are expected on c:file, c:directory, or c:other elements.

If detailed is true, then the pipeline author is expecting additional details about each entry. The following attributes should be provided by the implementation:

content-type

The content-type attribute contains the content type of the respective file. The value “application/octet-stream” will be used if the processor is not able to identify another content type.

readable

true” if the entry is readable.

writable

true” if the entry is writable.

hidden

true” if the entry is hidden.

last-modified

The last modification time of the entry, expressed as a lexical xs:dateTime in UTC.

size

The size of the entry in bytes.

The precise meaning of the detailed properties are implementation-defined and may vary according to the URI scheme of the path. If the value of an attribute is “false” or if it has no meaningful value, the attribute may be omitted.

Any other attributes on c:file, c:directory, or c:other are implementation-defined, but they must be in a namespace.

Document properties

Besides the content-type property, the resulting document has a base-uri. Its value is identical to the top-level element’s xml:base attribute, that is, to the directory’s URI.

2.2. p:file-copy

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

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
hrefxs:anyURI ✔ 
targetxs:anyURI ✔ 
fail-on-errorxs:booleantrue() 
overwritexs:booleantrue() 
Errors
Error codeDescription
err:XC0050It is a dynamic error the file or directory cannot be copied to the specified location.
err:XC0144It is a dynamic error if an implementation does not support p:file-copy for a specified scheme.
err:XC0145It 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.
err:XC0157It is a dynamic error if the href option names a directory, but the target option names a file.
err:XD0011It is a dynamic error if the resource referenced by the href option does not exist, cannot be accessed or is not a file or directory.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href and target options of p:file-copy. It is implementation-defined what other schemes are supported by p:file-copy, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-copy">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"required="true"as="xs:anyURI"/>        
     <p:optionname="target"required="true"as="xs:anyURI"/>      
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
     <p:optionname="overwrite"as="xs:boolean"select="true()"/>  
</p:declare-step>

The p:file-copy step copies the file or directory named in href to the new position specified in target. Any non existent directory contained in target will be created before copying starts. If the target is a directory, the step attempts to copy the file or directory into that directory, preserving its base name. It is a dynamic error (err:XC0157) if the href option names a directory, but the target option names a file.

If the overwrite evaluates to false, no existing file will be changed.

Conformant processors must support URIs whose scheme is file for the href and target options of p:file-copy. It is implementation-defined what other schemes are supported by p:file-copy, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0144) if an implementation does not support p:file-copy for a specified scheme.

If href or target are relative, they are made absolute against the base URI of the element on which they are specified (p:with-option or p:file-copy in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0145) if p:file-copy is not available to the step due to access restrictions in the environment in which the pipeline is run.

If no error occurs, the step returns a c:result element containing the absolute URI of the target.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error. In the case of a recursive copy, processing stops at the first error.

If an error occurs and fail-on-error is true, one of the following errors is raised:

  • It is a dynamic error (err:XD0011) if the resource referenced by the href option does not exist, cannot be accessed or is not a file or directory.

  • It is a dynamic error (err:XC0050) the file or directory cannot be copied to the specified location.

Copying directories

If href identifies a directory and target also identifies a directory, or does not exist, then the p:file-copy step attempts to copy the entire directory tree identified by href: the directory and all of its descendants.

In this case:

  • If fail-on-error is false and an error occurs, no further copying is attempted after the first error is detected.

  • If overwrite is true, err:XC0157 does not apply to descendants. A directory under href may replace a file with the corresponding name under target.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

2.3. p:file-delete

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

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
hrefxs:anyURI ✔ 
fail-on-errorxs:booleantrue() 
recursivexs:booleanfalse() 
Errors
Error codeDescription
err:XC0113It is a dynamic error if an attempt is made to delete a non-empty directory and the recursive option was set to false.
err:XC0142It is a dynamic error if an implementation does not support p:file-delete for a specified scheme.
err:XC0143It 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.
err:XD0011It is a dynamic error if the resource referenced by the href option cannot be accessed or is not a file or directory.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href option of p:file-delete. It is implementation-defined what other schemes are supported by p:file-delete, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-delete">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"required="true"as="xs:anyURI"/>        
     <p:optionname="recursive"as="xs:boolean"select="false()"/> 
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
</p:declare-step>

The p:file-delete step attempts to delete an existing file or directory named in href. If the named file or directory does not exist, the step just returns a c:result element as described below.

Conformant processors must support URIs whose scheme is file for the href option of p:file-delete. It is implementation-defined what other schemes are supported by p:file-delete, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0142) if an implementation does not support p:file-delete for a specified scheme.

If href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-delete in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0143) if p:file-delete is not available to the step due to access restrictions in the environment in which the pipeline is run.

If href specifies a directory, it can only be deleted if the recursive option is true or if the specified directory is empty.

The step returns a c:result element containing the absolute URI of the file or directory.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, one of the following errors is raised:

  • It is a dynamic error (err:XD0011) if the resource referenced by the href option cannot be accessed or is not a file or directory.

  • It is a dynamic error (err:XC0113) if an attempt is made to delete a non-empty directory and the recursive option was set to false.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

2.4. p:file-info

The p:file-info step returns information about a file, directory or other file system object.

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
hrefxs:anyURI ✔ 
fail-on-errorxs:booleantrue() 
override-content-typesarray(array(xs:string))?() 
Errors
Error codeDescription
err:XC0134It is a dynamic error if an implementation does not support p:file-info for a specified scheme.
err:XC0135It is a dynamic error if p:file-info is not available to the step due to access restrictions in the environment in which the pipeline is run.
err:XD0011It is a dynamic error if the resource referenced by the href option does not exist, cannot be accessed or is not a file, directory or other file system object.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href option of p:file-info. It is implementation-defined what other schemes are supported by p:file-info, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-info">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"required="true"as="xs:anyURI"/>        
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
     <p:optionname="override-content-types"as="array(array(xs:string))?"/>
</p:declare-step>

The p:file-info step returns information about the file, directory or other file system object named in the href option.

Conformant processors must support URIs whose scheme is file for the href option of p:file-info. It is implementation-defined what other schemes are supported by p:file-info, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0134) if an implementation does not support p:file-info for a specified scheme.

If href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-info in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0135) if p:file-info is not available to the step due to access restrictions in the environment in which the pipeline is run.

If the href option is a file: URI, the step returns:

  • If href option references a file: A c:file element with standard attributes (see below).

  • If href option references a directory: A c:directory element with standard attributes (see below).

  • If href option references any other file system object: Implementation defined (for example an c:other or c:device element). It is advised to use the standard attributes (see below) if applicable.

The override-content-types option can be used to partially override the content-type determination mechanism for files. This works just like with the override-content-types option of p:archive-manifest and p:unarchive (see Overriding content types in XProc 3.1: Standard Step Library), except that the regular expression matching is done against the absolute URI of the file.

Each of the elements c:file, c:directory, and c:other has a name attribute, whose value is a relative IRI reference, giving the (local) file or directory name.

The following attributes are standard on a returned c:file or c:directory element. All attributes are optional and must be absent if not applicable. Additional implementation-defined attributes may be present, but they must be in a namespace.

AttributeTypeDescription
readablexs:booleantrue if the object is readable.
writablexs:booleantrue if the object file is writable.
hiddenxs:booleantrue if the object is hidden.
last-modifiedxs:dateTimeThe last modification time of the object expressed in UTC.
sizexs:integerThe size of the object in bytes.
content-typexs:stringThe content type, if the object is a file.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, one of the following errors is raised:

  • It is a dynamic error (err:XD0011) if the resource referenced by the href option does not exist, cannot be accessed or is not a file, directory or other file system object.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

2.5. p:file-mkdir

The p:file-mkdir step creates a directory.

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
hrefxs:anyURI ✔ 
fail-on-errorxs:booleantrue() 
Errors
Error codeDescription
err:XC0114It is a dynamic error if the directory referenced by the href option cannot be created.
err:XC0140It is a dynamic error if an implementation does not support p:file-mkdir for a specified scheme.
err:XC0141It is a dynamic error if p:file-mkdir not available to the step due to access restrictions in the environment in which the pipeline is run.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href option of p:file-mkdir. It is implementation-defined what other schemes are supported by p:file-mkdir, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-mkdir">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"required="true"as="xs:anyURI"/>        
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
</p:declare-step>

The p:file-mkdir create the directory named in the href option. If this includes more than one directory component, all of the intermediate components are created. If the directory already exists the step just returns the c:result element as described below. The path separator is implementation-defined.

Conformant processors must support URIs whose scheme is file for the href option of p:file-mkdir. It is implementation-defined what other schemes are supported by p:file-mkdir, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0140) if an implementation does not support p:file-mkdir for a specified scheme.

If href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-mkdir in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0141) if p:file-mkdir not available to the step due to access restrictions in the environment in which the pipeline is run.

The step returns a c:result element containing the absolute URI of the directory.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, the following error is raised:

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

2.6. p:file-move

The p:file-move step moves a file or directory.

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
hrefxs:anyURI ✔ 
targetxs:anyURI ✔ 
fail-on-errorxs:booleantrue() 
Errors
Error codeDescription
err:XC0050It is a dynamic error if the directory cannot be moved to the specified location.
err:XC0115It is a dynamic error if the resource referenced by the target option is an existing file or other file system object.
err:XC0148It is a dynamic error if an implementation does not support p:file-move for a specified scheme.
err:XC0149It 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.
err:XC0158It is a dynamic error if the href option names a directory, but the target option names a file.
err:XD0011It is a dynamic error if the resource referenced by the href option does not exist, cannot be accessed or is not a file or directory.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href and target options of p:file-move. It is implementation-defined what other schemes are supported by p:file-move, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-move">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"required="true"as="xs:anyURI"/>        
     <p:optionname="target"required="true"as="xs:anyURI"/>      
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
</p:declare-step>

The p:file-move step moves the file or directory named in href to the new location specified in target. If the target option specifies an existing directory, the step attempts to move the file or directory into that directory, preserving its base name. It is a dynamic error (err:XC0158) if the href option names a directory, but the target option names a file.

Conformant processors must support URIs whose scheme is file for the href and target options of p:file-move. It is implementation-defined what other schemes are supported by p:file-move, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0148) if an implementation does not support p:file-move for a specified scheme.

If href or target are relative, they are made absolute against the base URI of the element on which they are specified (p:with-option or p:file-move in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0149) if p:file-move is not available to the step due to access restrictions in the environment in which the pipeline is run.

If the href option specifies a device or other special kind of object, the results are implementation-defined.

If the move is successful, the step returns a c:result element containing the absolute URI of the target.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, one of the following errors is raised:

  • It is a dynamic error (err:XD0011) if the resource referenced by the href option does not exist, cannot be accessed or is not a file or directory.

  • It is a dynamic error (err:XC0115) if the resource referenced by the target option is an existing file or other file system object.

  • It is a dynamic error (err:XC0050) if the directory cannot be moved to the specified location.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

2.7. p:file-create-tempfile

The p:file-create-tempfile step creates a temporary file.

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault value
delete-on-exitxs:booleanfalse()
fail-on-errorxs:booleantrue()
hrefxs:anyURI?()
prefixxs:string?()
suffixxs:string?()
Errors
Error codeDescription
err:XC0116It is a dynamic error if the temporary file could not be created.
err:XC0138It is a dynamic error if an implementation does not support p:file-create-tempfile for a specified scheme.
err:XC0139It is a dynamic error if p:file-create-tempfile cannot be completed due to access restrictions in the environment in which the pipeline is run.
err:XD0011It is a dynamic error if the resource referenced by the href option does not exist, cannot be accessed or is not a directory.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href option of p:file-create-tempfile. It is implementation-defined what other schemes are supported by p:file-create-tempfile, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-create-tempfile">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"as="xs:anyURI?"/>                       
     <p:optionname="suffix"as="xs:string?"/>                     
     <p:optionname="prefix"as="xs:string?"/>                     
     <p:optionname="delete-on-exit"as="xs:boolean"select="false()"/>
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
</p:declare-step>

The p:file-create-tempfile creates a temporary file. The temporary file is guaranteed not to already exist when the step is called.

If the href option is specified it must be the URI of an existing directory. The temporary file is created here. If there is no href option specified the location of the temporary file is implementation defined, usually the operating system's default location for temporary files.

Conformant processors must support URIs whose scheme is file for the href option of p:file-create-tempfile. It is implementation-defined what other schemes are supported by p:file-create-tempfile, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0138) if an implementation does not support p:file-create-tempfile for a specified scheme.

If href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-create-tempfile in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0139) if p:file-create-tempfile cannot be completed due to access restrictions in the environment in which the pipeline is run.

If the prefix option is specified, the filename will begin with that prefix. If the suffix option is specified, the filename will end with that suffix.

If the delete-on-exit option is true, an attempt will be made to automatically delete the temporary file when the processor terminates the pipeline. No error will be raised if this is unsuccessful.

If the temporary file creation is successful, the step returns a c:result element containing the absolute URI of this file.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, one of the following errors is raised:

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

2.8. p:file-touch

The p:file-touch step updates the modification timestamp of a file.

Summary

Output portPrimarySequenceContent types
result✔  application/xml 
Option nameTypeDefault valueRequired
hrefxs:anyURI ✔ 
fail-on-errorxs:booleantrue() 
timestampxs:dateTime?() 
Errors
Error codeDescription
err:XC0136It is a dynamic error if an implementation does not support p:file-touch for a specified scheme.
err:XC0137It is a dynamic error if p:file-touch cannot be completed due to access restrictions in the environment in which the pipeline is run.
err:XD0011It is a dynamic error if the resource referenced by the href option does not exist and cannot be created or exists and cannot be accessed.
err:XD0064It is a dynamic error if the base URI is not both absolute and valid according to .
Implementation details
ImplementationDescription
DefinedConformant processors must support URIs whose scheme is file for the href option of p:file-touch. It is implementation-defined what other schemes are supported by p:file-touch, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.
Declaration

<p:declare-steptype="p:file-touch">
     <p:outputport="result"primary="true"content-types="application/xml"/>
     <p:optionname="href"required="true"as="xs:anyURI"/>        
     <p:optionname="timestamp"as="xs:dateTime?"/>                
     <p:optionname="fail-on-error"as="xs:boolean"select="true()"/>
</p:declare-step>

The p:file-touch step updates the modification timestamp of the file specified in the href option. If the file specified by href does not exist, an empty file will be created at the given location.

Conformant processors must support URIs whose scheme is file for the href option of p:file-touch. It is implementation-defined what other schemes are supported by p:file-touch, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes.It is a dynamic error (err:XC0136) if an implementation does not support p:file-touch for a specified scheme.

If href is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-touch in the case of a syntactic shortcut value). It is a dynamic error (err:XD0064) if the base URI is not both absolute and valid according to [RFC 3986]. It is a dynamic error (err:XC0137) if p:file-touch cannot be completed due to access restrictions in the environment in which the pipeline is run.

If the timestamp option is set, the file's timestamp is set to this value. Otherwise the file's timestamp is set to the current system's date and time.

If the operation is successful, the step returns a c:result element containing the absolute URI of the file.

If an error occurs and fail-on-error is false, the step returns a c:error element which may contain additional, implementation-defined, information about the nature of the error.

If an error occurs and fail-on-error is true, the following error is raised:

  • It is a dynamic error (err:XD0011) if the resource referenced by the href option does not exist and cannot be created or exists and cannot be accessed.

Document properties

The resulting document has no properties apart from content-type. In particular, it has no base-uri.

3. Step Errors

These steps can raise dynamic errors.

[Definition: A dynamic error is one which occurs while a pipeline is being evaluated.] Examples of dynamic errors include references to URIs that cannot be resolved, steps which fail, and pipelines that exhaust the capacity of an implementation (such as memory or disk space). For a more complete discussion of dynamic errors, see Dynamic Errors in XProc 3.0: An XML Pipeline Language.

If a step fails due to a dynamic error, failure propagates upwards until either a p:try is encountered or the entire pipeline fails. In other words, outside of a p:try, step failure causes the entire pipeline to fail.

The following specific errors can be raised by these steps:

err:XC0012

It is a dynamic error if the contents of the directory path are not available to the step due to access restrictions in the environment in which the pipeline is run.

See: p:directory-list

err:XC0017

It is a dynamic error if the absolute path does not identify a directory.

See: p:directory-list

err:XC0050

It is a dynamic error the file or directory cannot be copied to the specified location.

See: p:file-copy, p:file-move

err:XC0090

It is a dynamic error if an implementation does not support directory listing for a specified scheme.

See: p:directory-list

err: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.

See: p:file-delete

err:XC0114

It is a dynamic error if the directory referenced by the href option cannot be created.

See: p:file-mkdir

err:XC0115

It is a dynamic error if the resource referenced by the target option is an existing file or other file system object.

See: p:file-move

err:XC0116

It is a dynamic error if the temporary file could not be created.

See: p:file-create-tempfile

err:XC0134

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

See: p:file-info

err:XC0135

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

See: p:file-info

err:XC0136

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

See: p:file-touch

err: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.

See: p:file-touch

err:XC0138

It is a dynamic error if an implementation does not support p:file-create-tempfile for a specified scheme.

See: p:file-create-tempfile

err:XC0139

It is a dynamic error if p:file-create-tempfile cannot be completed due to access restrictions in the environment in which the pipeline is run.

See: p:file-create-tempfile

err:XC0140

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

See: p:file-mkdir

err:XC0141

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

See: p:file-mkdir

err:XC0142

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

See: p:file-delete

err: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.

See: p:file-delete

err:XC0144

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

See: p:file-copy

err: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.

See: p:file-copy

err:XC0147

It is a dynamic error if a specified value is not a valid XPath regular expression.

See: p:directory-list

err:XC0148

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

See: p:file-move

err: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.

See: p:file-move

err:XC0157

It is a dynamic error if the href option names a directory, but the target option names a file.

See: p:file-copy

err:XC0158

It is a dynamic error if the href option names a directory, but the target option names a file.

See: p:file-move

A. Conformance

Conformant processors must implement all of the features described in this specification except those that are explicitly identified as optional.

Some aspects of processor behavior are not completely specified; those features are either implementation-dependent or implementation-defined.

[Definition: An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.]

[Definition: An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.]

A.1. Implementation-defined features

The following features are implementation-defined:

  1. How the file steps behave with respect to special files is implementation-defined. See Section 1, “Introduction”.
  2. Conformant processors must support directory paths whose scheme is file. It is implementation-defined what other schemes are supported by p:directory-list, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.1, “p:directory-list”.
  3. Any file or directory determined to be special by the p:directory-list step may be output using a c:other element but the criteria for marking a file as special are implementation-defined. See Section 2.1, “p:directory-list”.
  4. The precise meaning of the detailed properties are implementation-defined and may vary according to the URI scheme of the path. See Section 2.1, “p:directory-list”.
  5. Any other attributes on c:file, c:directory, or c:other are implementation-defined See Section 2.1, “p:directory-list”.
  6. Conformant processors must support URIs whose scheme is file for the href and target options of p:file-copy. It is implementation-defined what other schemes are supported by p:file-copy, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.2, “p:file-copy”.
  7. Conformant processors must support URIs whose scheme is file for the href option of p:file-delete. It is implementation-defined what other schemes are supported by p:file-delete, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.3, “p:file-delete”.
  8. Conformant processors must support URIs whose scheme is file for the href option of p:file-info. It is implementation-defined what other schemes are supported by p:file-info, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.4, “p:file-info”.
  9. Conformant processors must support URIs whose scheme is file for the href option of p:file-mkdir. It is implementation-defined what other schemes are supported by p:file-mkdir, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.5, “p:file-mkdir”.
  10. Conformant processors must support URIs whose scheme is file for the href and target options of p:file-move. It is implementation-defined what other schemes are supported by p:file-move, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.6, “p:file-move”.
  11. Conformant processors must support URIs whose scheme is file for the href option of p:file-create-tempfile. It is implementation-defined what other schemes are supported by p:file-create-tempfile, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.7, “p:file-create-tempfile”.
  12. Conformant processors must support URIs whose scheme is file for the href option of p:file-touch. It is implementation-defined what other schemes are supported by p:file-touch, and what the interpretation of ‘directory’, ‘file’ and ‘contents’ is for those schemes. See Section 2.8, “p:file-touch”.

B. References

[XProc 3.1] XProc 3.1: An XML Pipeline Language. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.

[XPath and XQuery Functions and Operators 3.1] XPath and XQuery Functions and Operators 3.1. Michael Kay, editor. W3C Recommendation. 21 March 2017

[RFC 3986] RFC 3986: Uniform Resource Identifier (URI): General Syntax. T. Berners-Lee, R. Fielding, and L. Masinter, editors. Internet Engineering Task Force. January, 2005.

C. Glossary

dynamic error

A dynamic error is one which occurs while a pipeline is being evaluated.

implementation-defined

An implementation-defined feature is one where the implementation has discretion in how it is performed. Conformant implementations must document how implementation-defined features are performed.

implementation-dependent

An implementation-dependent feature is one where the implementation has discretion in how it is performed. Implementations are not required to document or explain how implementation-dependent features are performed.

D. Change log

This appendix catalogs recent non-editorial changes.

  1. Improved the description of include filter processing in p:directory-list.

E. Ancillary files

This specification includes by reference a number of ancillary files.

steps.xpl

An XProc step library for the declared steps.