Fileutils

Dave's Ant/XProc thread of a few days ago makes it clear that some
pipelines are going to want to interact with the local filesystem.

This seems like the ideal place for exproc; these steps aren't part of
the XProc 1.0 standard, but there's no reason we implementors can't
agree on their semantics and what they're called.

Before I try to write these up as extensions, let's see if we can all
agree on the semantics that we think would be most useful. Here's what
I've implemented so far, with a few notes.

    <p:library xmlns:p="http://www.w3.org/ns/xproc"
               xmlns:cxf="http://xmlcalabash.com/ns/extensions/fileutils"
               xmlns:ml="http://xmlcalabash.com/ns/extensions/marklogic"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    
These are in my own extension namespace, I'll move them to an exproc
namespace when there's consensus.

    <p:documentation xmlns="http://www.w3.org/1999/xhtml">
    <div>
    <h1>XML Calabash Fileutils Library</h1>
    <h2>Version 1.0</h2>
    <p>The steps defined in this library are implemented in
    <a href="http://xmlcalabash.com/">XML Calabash</a>.
    </p>
    </div>
    </p:documentation>
    
For better or worse, I've given every step a single non-primary output
port. None of them has an input port.

All of the steps may fail due to security constraints. In XML
Calabash, they all fail if you run the pipeline in "safe" mode.

    <p:declare-step type="cxf:exists">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>
    
Returns <c:result>true</c:result> if the specified file exists,
<c:result>false</c:result> otherwise.

Q: Should "file" be made absolute wrt to the current base URI, or left
unchanged (effectively making it relative to the implementations
notion of current working directory)?

    <p:declare-step type="cxf:is-readable">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns true if the file is readable.
    
    <p:declare-step type="cxf:is-writable">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns true if the file is writable.
    
    <p:declare-step type="cxf:is-directory">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>
    
Returns true if the file is a directory.

    <p:declare-step type="cxf:is-file">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns true if the file is a file (is not a directory).
    
    <p:declare-step type="cxf:is-hidden">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns true if the file is hidden (what constitutes "hidden" is
implementation-defined).
    
    <p:declare-step type="cxf:last-modified">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns a <c:result> containing an xs:dateTime of the files last
modified date. The xs:dateTime MUST be expressed in the UTC timezone.
The step fails if the specified file does not exist.
    
    <p:declare-step type="cxf:size">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns a <c:result> containing the size in bytes of the specified
file. The step fails if the specified file does not exist.
    
    <p:declare-step type="cxf:delete">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Returns a <c:result> containing the absolute filename of the deleted
file. The step fails if the file does not exist or if it cannot be
deleted.
    
    <p:declare-step type="cxf:mkdir">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
    </p:declare-step>

Creates a directory with the name spacified in the "file" option. If
the name includes more than one directory component, all of the
intermediate components are created. The path separator is
implementation-defined. Returns a <c:result> containing the absolute
filename of the directory created. The step fails if the directory
cannot be created.
    
    <p:declare-step type="cxf:copy">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
      <p:option name="target" required="true"/>
    </p:declare-step>

Returns a <c:result> containing the absolute filename of the target
file. The step fails if the file does not exist or if it cannot be
copied to the specified target.
    
    <p:declare-step type="cxf:rename">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
      <p:option name="target" required="true"/>
    </p:declare-step>

Returns a <c:result> containing the absolute filename of the target
file. The step fails if the file does not exist, if the target *does*
exist, or if the file cannot be renamed.
    
    <p:declare-step type="cxf:move">
      <p:output port="result" primary="false"/>
      <p:option name="file" required="true"/>
      <p:option name="target" required="true"/>
    </p:declare-step>

Returns a <c:result> containing the absolute filename of the target
file. The step fails if the file does not exist, if the file is a
directory, if the target file cannot be created, or if the file cannot
be deleted.
    
    </p:library>

Comments?

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com> | Every vice you destroy has a
http://nwalsh.com/            | corresponding virtue, which perishes
                              | along with it.--Anatole France