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