eio
eio copied to clipboard
Confusing API for open_out: ~append Vs ~create
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'sopen_out
) -
`Create_or_append perm
-
`Create_or_smash_expert_mode perm
-
`Append_or_fail
-
`Erase_or_fail
-
`Smash_or_fail