Confusing API for open_out: ~append Vs ~create

[smondet]

Maybe it is not too late to think of a more human-friendly API?

Eio.Path.with_open_out ~append:false ~create:(`If_missing 0o666) (* … *)

If the file already exists, this is going overwrite from the beginning and leave the leftovers if the second write is shorter.

It is indeed documented in tests/fs.md:129 but the API seems too confusing, right?
The function call does not really say that.

When ?append is false (the default), I feel like 99% of users will want `Or_truncate 0o666.

The word comes from POSIX's O_TRUNC which (cf. open(2)) actually means “truncated to length 0.” The file is not really truncated, it's “erased” or “overwritten” maybe?

One idea would be to merge ?append and ?create into a single ?how:

• `Create_or_erase perm: seems like the best default? (it's OCaml's open_out)
• `Create_or_append perm
• `Create_or_smash_expert_mode perm
• `Append_or_fail
• `Erase_or_fail
• `Smash_or_fail

[talex5]

I feel like 99% of users will want `` Or_truncate 0o666.

I'd say that's the least likely one. Typically you want:

• Exclusive when you want to write a file atomically (and so you are creating a temporary file for the new version, which you will then rename over the original), or
• If_missing for random-access files.

Smash seems like a bad name for the one that preserves things. It's what you want for e.g. databases, disk images, archives.

It might be good to have a save_atomic type operation the handles the rename stuff for you. And it would be great to replace the octal modes with something safer (it's too easy to forget the 0o).

Erase is quite nice. On the other hand, there is some value in copying the POSIX terminology. It may not be great, but at least most people know it.

[smondet]

I feel like 99% of users will want `` Or_truncate 0o666.

I'd say that's the least likely one.

~append:false ~create:(`Or_truncate 0o644) is the stdlib's open_out:

(** Open the named file for writing, and return a new output channel
   on that file, positioned at the beginning of the file. The
   file is truncated to zero length if it already exists. It
   is created if it does not already exists.*)

Smash seems like a bad name for the one that preserves things. It's what you
want for e.g. databases, disk images, archives.

Writing that kind of software, that's 1% of use-cases of file I/O right?

“Preserve” might be a better word indeed :)

“Open for seeking” might work also?

⁂

save_atomic sounds very good (but I don't know if it can even be implemented with rename on exotic OSes).