XProc 3.0: file steps
Editor's Draft
- This Version:
- https://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:
- Commits for this specification
This document is also available in these non-normative formats: XML.
Copyright © 2018 @@FIXME:
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-step
type
="
p:file-copy
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
target
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
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 thehref
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 thetarget
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-step
type
="
p:file-delete
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
recursive
"
as
="
xs:boolean
"
select
="
false()
"
/>
<p:option
name
="
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 thehref
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 therecursive
option was set tofalse
.
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-step
type
="
p:file-info
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
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: Ac:file
element with standard attributes (see below). -
If
href
option references a directory: Ac:directory
element with standard attributes (see below). -
If
href
option references any other file system object: Implementation defined (for example anc:other
orc: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.
Attribute | Type | Description |
---|---|---|
readable | xs:boolean | true if the object is readable. |
writable | xs:boolean | true if the object file is writable. |
hidden | xs:boolean | true if the object is hidden. |
last-modified | xs:dateTime | The last modification time of the object expressed in UTC. |
size | xs:integer | The 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 thehref
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-step
type
="
p:file-mkdir
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
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:
-
It is a dynamic error (
err:XXXXX
) if the directory referenced by thehref
option cannot be created.
Document properties
No document properties are preserved.
6 p:file-move
The p:file-move
step moves a file or directory.
<p:declare-step
type
="
p:file-move
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
target
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
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 thehref
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 thetarget
option is an existing file or other file system object. -
It is a dynamic error (
err:XC0050
) if the URI scheme of thetarget
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-step
type
="
p:file-create-tempfile
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
as
="
xs:anyURI?
"
/>
<p:option
name
="
suffix
"
as
="
xs:string?
"
/>
<p:option
name
="
prefix
"
as
="
xs:string?
"
/>
<p:option
name
="
delete-on-exit
"
as
="
xs:boolean
"
select
="
false()
"
/>
<p:option
name
="
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:
-
It is a dynamic error (
err:XD0011
) if the resource referenced by thehref
option does not exist, cannot be accessed or is not a directory. -
It is a dynamic error (
err:XXXXXX
) if the temporary file could not be created.
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-step
type
="
p:file-touch
"
>
<p:output
port
="
result
"
primary
="
true
"
content-types
="
application/xml
"
/>
<p:option
name
="
href
"
required
="
true
"
as
="
xs:anyURI
"
/>
<p:option
name
="
timestamp
"
as
="
xs:dateTime?
"
/>
<p:option
name
="
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 thehref
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.