Re: [expath] EXPath File Module, June 06 2012

Michael,

thanks for your comprehensive feedback, very appreciated. The updated
specification contains numerous edits reflecting your suggestions:

    http://files.basex.org/modules/expath/file/file-120611.html


> file:append: the third argument is referred to variously as $params and
> $parameters. More substantially, what is this method supposed to do about
> XML declarations and DOCTYPE declarations? Are they simply generated if
> requested, ignoring the fact that the resulting file might not be well
> formed?

Yes, because there are too many use cases (we believe) in which we do
not know what a user intends to do. Next, we never know which contents
have already been written to the addressed file. file:write($arg,
$params) is equivalent to file:write-text(fn:serialize($arg,
$params)), except for the encoding, which is not supposed to be
ignored by this function (I have added a comment in the spec. to point
out this difference).


> file:delete - presumably if $recursive is omitted or set to false, deletion
> will fail if the file is a non-empty directory? But I would expect an
> explicit error code for this.

True; I have added FILE0004 for this case (path points a non-empty directory).


> file:list with $recursive=true() - does this list all the files/directories
> in the directory tree, or only the leaf nodes (the non-directories)?

Directories will be returned, too, no matter which values have been
chosen for the $recursive and $pattern arguments.


> file:write-text - presumably writes the strings as supplied with no
> separator. A function that writes the strings separated by newline
> characters might be more user-friendly.

An interesting idea. Pros and contras I see here:
+ newlines are most likely the characters that would be needed here
– potentially confusing if we don’t call the function
file:write-text-lines(), or add another one with this label (but the
number of functions could grow exponentially if we continue this)
– potentially restrictive if you need different separators (you could
still resort to file:write(), though).


> file:path-to-native - the concept of a "native path" is not explained. I can
> make guesses as to what is intended, but in the absence of any examples or
> explanations I fear my guess might be completely wrong.

I remember that the wording stems from quite an old version of the
spec. In Java terminology, "file:path-to-native" returns the
canonical, system-dependent representation of a path. I have edited
the specification to hopefully make this more comprehensible. As I’m
not that happy with the term "native", we could as well rename it to
"canonical"; what do you think?


> file:path-to-uri and file:resolve-path make explicit reference to the
> "current working directory", but all other functions say that the
> interpretation of relative paths is system-dependent (which presumably
> allows use of the static base URI for resolution, rather than the current
> working directory).

I have added a comment in 1.2 to point out that all functions are
supposed to consider the current working directory as base directory.


> I'm having a bit of difficulty working out what to do with
> $file:dir-separator and $file:path-separator.

Yes, I agree that the functional representation of variables is
probably more compliant with the existing W3 specifications and XQuery
processors (which should be the chief purpose of all modules). It
would be interesting to have the opinions on that from the eXist guys
and other implementors. Regarding BaseX and Zorba (afaik), constant
variables have already been implemented in our processors.


> file:copy() - the semantics are not at all clear when the source is a
> directory.

Another thank you for the elaborated alternative, which I've adopted
in the updated spec. All of your assumptions were correct, and I added
another FILE0004 error for existing subdirectories. However, I decided
to keep all errors listed after the description itself, as it has been
done for the other functions. Your feedback is welcome.


> What does file:create-dir() do if the directory already exists?

It will do nothing (added in the spec.)

To summarize, the major two questions to be decided might be:
- do we want to use a fixed separator for file:write-text() ?
- do we want to switch from variables to a function representation?

Christian

Received on Monday, 11 June 2012 17:48:07 UTC