View Old View New View Both

XProc 3.0: file steps

Editor's Draft

This Version:
https://xproc.github.io/3.0-ndw.github.io/steps/master/head/file/
Latest Version:
http://spec.xproc.org/master/head/file/
Editors:
Norman Walsh
Achim Berndzen
Gerrit Imsieke
Erik Siegel
Repository:
This specification on GitHub
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, automatic change markup from the previous draft courtesy of DeltaXML.


Abstract

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

Status of this Document

This document is an editor's draft that has no official standing.

This section describes the status of this document at the time of its publication. Other documents may supersede this document.

This document is derived from XProc: An XML Pipeline Language published by the W3C.


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.0] steps is assumed; for background details, see [XProc 3.0 Steps].

2 p:file-copy

The p:file-copy step copies a file.

<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:declare-step>

The p:file-copy step copies the file or directory named in href to the new name specified in target. If the target is a directory, the step attempts to move the file into that directory, preserving its base name.

It is a dynamic error (err:XD0064) if the href or target option value is not a valid xs:anyURI. If the href or target is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-copy in the case of a syntactic shortcut value).

If the copy 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:XC0050) if the URI scheme of the target option is not supported or the file or directory cannot be copied to the specified location.

Document properties

No document properties are preserved.

3 p:file-delete

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

<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 the file or directory named in href.

It is a dynamic error (err:XD0064) if the href option value is not a valid xs:anyURI. If the href option 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).

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

If the delete is successful, the step returns a c:result element containing the absolute URI of the deleted 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 does not exist, cannot be accessed or is not a file or directory.

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

Document properties

No document properties are preserved.

4 p:file-info

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

<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:declare-step>

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

It is a dynamic error (err:XD0064) if the href option value is not a valid xs:anyURI. If the href option 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).

If the href option is not a file: URI, the result is implementation defined.

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

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

No document properties are preserved.

5 p:file-mkdir

The p:file-mkdir step creates a directory.

<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. The path separator is implementation-defined.

It is a dynamic error (err:XD0064) if the href option value is not a valid xs:anyURI. If the href option 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).

If the create is successful, the step returns a c:result element containing the absolute URI of the directory created.

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

No document properties are preserved.

6 p:file-move

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

<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:XD0064) if the href or target option value is not a valid xs:anyURI. If the href or target is relative, it is made absolute against the base URI of the element on which it is specified (p:with-option or p:file-move in the case of a syntactic shortcut value).

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:XXXXXX) 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 URI scheme of the target option is not supported or the file or directory cannot be moved to the specified location.

Document properties

No document properties are preserved.

7 p:file-create-tempfile

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

Editorial Note

TBD: This is an almost direct port from EXProc. Details might still change.

Check the error codes. ANd is the name ok? p:file-create-tempfile sounds better to me?

I added the option to leave out the href option and have the tempfile created in the system's temp directory. Ok?

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

It is a dynamic error (err:XD0064) if the href option value is not a valid xs:anyURI. If the 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).

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

No document properties are preserved.

8 p:file-touch

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

<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 fiel specified in the href option.

It is a dynamic error (err:XD0064) if the href option value is not a valid xs:anyURI. If the href option 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).

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 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 and cannot be created or exists and cannot be accessed.

Document properties

No document properties are preserved.

9 Step Errors

This step 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 errors can be raised by this step:

err:XC0050

It is a dynamic error if the URI scheme of the target option is not supported or the file or directory cannot be copied to the specified location.

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

    A.2 Implementation-dependent features

    The following features are implementation-dependent:

      B References

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

      [XProc 3.0 Steps] XProc 3.0 Steps: An Introduction. Norman Walsh, Achim Berndzen, Gerrit Imsieke and Erik Siegel, editors.

      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 Ancillary files

      This specification includes by reference a number of ancillary files.

      steps.xpl

      An XProc step library for the declared steps.