Re: open-output-file: overwrite or append

[Per Bothner <per at bothner dot com>]

On 09/07/2014 03:25 PM, Ito Kazumitsu wrote:
> The Kawa document says about open-output-file and open-binary-output-file,
> "If a file with the given name already exists, the effect is unspecified".

I agree that should be changed.

The implementation uses 'new FileOutputStream(FILE)'.

The JavaDoc for the above is rather misleading.  It doesn't mention
truncation.  It just says if the append option if specified and true,
"then bytes will be written to the end of the file rather than the beginning".
I.e. if 1 byte is written, then only one byte is changed, but the remaining
bytes are unchanged.  Which of course is an operation with very limited use!

Now it turns out 'new FileOutputStream(FILE)' does trunctate, as one would
expect, in spite of the poor documentation ...

> I woud like a way of specifying overwriting or appending for opening an
> output file.

You can append to a file using either:
 (&>>{FNAME} NEW-VALUE)
or the equivalent:
 (path-data-appender "FNAME" NEW-VALUE)

See: http://per.bothner.com/blog/2014/text-and-binary-data

This appends  the value of NEW-VALUE (a string, byte-array, etc) in
a single operation, which may not be what you want.

I think we should generalize open-[binary-]output-file to take
"file options":

  (open-output-file PATH OPTION ...)

but leads to the question: What kind of expression is an OPTION?
My proposal is we allow OPTION to be at least one of the following:

(1) a java.nio.file OpenOption value - e.g.:
  (open-output-file "foo" StandardOpenOption:APPEND)

(2) a R6RS-style file-options object, as implemented by a number of Schemes.
  (open-output-file "foo" (file-options append))

We might as a short-hand allow symbols, but I'm not sure about that.

Right now I'm busy focusing on finishing R7RS-compatibulity, but you
can create a Savannah bug to help us remember to get around to it later.

Patches in general welcome, but it's a little tricky because of the
interaction with gnu.kawa.io.Path; that java.nio.file OpenOption handling
only applies to java.nio.file.Path values (i.e. not general URIs); and
that we want to support minimal functionality (i.e append) on Java 5/6.
So it's not something I can do in an hour.

> Without this option, when we want the target file to be overwritten
> if it exists, which I assume is the usual case, we have to make sure
> that the file does not exit.

Truncation does seem to be happening by default - at least on GNU/Linux.
(I haven't tested Windows of MacOS.)

> I think, in many programming languages, when opening an output file,
> overwriting is the default and appending is an option.
>
> It may be a better practice to avoid overwriting to an existing file
> by always writing to a temporary file. Does Kawa recommend this practice?
> It is safer but less convevient.

It's like when writing Makefile rules: You want to minimize the risk
of an partially-written incomplete file.  But you have to decide how
important that is - I don't think it's for Kawa to do automatically,
though we could add a convenience function.

For files less thana megabyte maybe just create the whole file in
memory and write it out as a single unit, like with path-data-stter
or path-data-appender.
--
	--Per Bothner
per@bothner.com   http://per.bothner.com/