eXProc.org

Proposed File Utilities

This page collects proposed extension steps. Implementation welcome, but contents subject to change at any time.

These steps are in the “proposed file utilities extension namespace”, http://exproc.org/proposed/steps/file, identified by the prefix “pxf”.

pxf:copy

Copies a file.

<p:declare-step type="pxf:copy">
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="target" required="true"/>                     <!-- boolean -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The pxf:copy copies the file 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.

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

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if the file named in href does not exist or cannot be copied to the specified target.

pxf:delete

Deletes a file.

<p:declare-step type="pxf:delete">
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="recursive" select="'false'"/>                 <!-- boolean -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The pxf:delete step attempts to delete the file or directory named in href.

If the file or directory is successfully deleted, the step returns a c:result element containing the absolute URI of the deleted file.

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

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if the file named in href does not exist or cannot be deleted.
err:FU02Occurs if the step attempts to delete a directory that is not empty and the recursive option is not true.

pxf:info

Returns information about a file or directory.

<p:declare-step type="pxf:info">
     <p:output port="result" sequence="true"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The info step returns information about the file or directory named in href.

The step returns a c:directory for directories, a c:file for ordinary files, or a c:other for other kinds of filesystem objects. Implementations may also return more specific types, for example c:device, so anything other than c:directory or c:file must be interpreted as “other”. If the document doesn't exist, an empty sequence is returned.

The document element of the result, if there is one, will have the following attributes:

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 the value of a particular attribute is unknown or inapplicable for the particular kind of object, or in the case of boolean attributes, if it's false, then the attribute is not present. Additional implementation-defined attributes may be present, but they must be in a namespace.

If the

<att>href</att>
attribute specified is not a file: URI, then the result is implementation-defined.

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if the file named in href cannot be read.

pxf:mkdir

Creates a directory.

<p:declare-step type="pxf:mkdir">
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The pxf:mkdir step creates a directory with the name in href. If the name includes more than one directory component, all of the intermediate components are created. The path separator is implementation-defined.

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

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if the directory named in href cannot be created.

pxf:move

Moves (renames) a file or directory.

<p:declare-step type="pxf:move">
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="target" required="true"/>                     <!-- boolean -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The pxf:move step attempts to move (rename) the file specified in the href option to the new name specified in the target option.

If the target is a directory, the step attempts to move the file into that directory, preserving its base name.

If the move is successful, the step returns a c:result element containing the absolute URI of the new name of the file. The original file is effectively removed.

If the fail-on-error option is true, then the step will fail if a file with the name specified in the target option already exists, or if the file specified in href does not exist or cannot be moved.

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

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

pxf:tail

Returns the last few lines of a text file.

<p:declare-step type="pxf:tail">
     <p:output port="result"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="count" required="true"/>                      <!-- int -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

Returns the last count lines of the file named in href. If count is negative, the step returns all except those last lines.

The step returns a c:result element containing one c:line for each line. Lines are identified as described in XML, 2.11 End-of-Line Handling.

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if the file named in href does not exist or cannot be read.
err:FU03Occurs if the file named in href does not appear to be a text file. The exact conditions that constitute “does not appear to be” are implementation-defined.

pxf:tempfile

Creates a temporary file.

<p:declare-step type="pxf:tempfile">
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="prefix"/>                                     <!-- string -->
     <p:option name="suffix"/>                                     <!-- string -->
     <p:option name="delete-on-exit"/>                             <!-- boolean -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The pxf:tempfile step creates a temporary file. The temporary file is guaranteed not to already exist when pxf:tempfile is called.

The file is created in the directory specified by the href option. If prefix is specified, the file's name will begin with that prefix. If suffix is specified, the file's name will end with that suffix.

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

If the delete-on-exit option is true, then the temporary file will automatically be deleted when the processor terminates.

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if href does not specify a directory or if the directory does not exist.
err:FU04Occurs if it is not possible to create a file in the href directory.

pxf:touch

Update the modification time of a file.

<p:declare-step type="pxf:touch">
     <p:output port="result" primary="false"/>
     <p:option name="href" required="true"/>                       <!-- anyURI -->
     <p:option name="timestamp"/>                                  <!-- xs:dateTime -->
     <p:option name="fail-on-error" select="'true'"/>              <!-- boolean -->
</p:declare-step>

The pxf:touch step “touches” the file named in href. The file will be created if it does not exist.

If timestamp is specified, the modification time of the file will be updated to the specified time. If unspecified, the current date and time will be used.

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

If an error occurs, the step fails if fail-on-error is true; otherwise, the step returns a c:error element which may contain additional, implementation-defined information about the nature of the error.

Errors

ErrorDescription
err:FU01Occurs if the file named in href does not exist or if its timestamp cannot be changed.