Open Paalon opened 3 months ago
Not sure I agree with all of these - the semantics of print
and write
are different for example - if the API of YAML.write
are more like that of print
, then fine, but other packages CSV.jl comes to mind
use write
.
This package predates a lot of other conventions, and in general I'm in favor of unifying the API with what is now standard. Would probably want to have a patch release that adds deprecation warnings, and then a separate release where things are changed.
I propose:
parseonly
for parsing the only single document in a YAML file, if the YAML file consists of 0 or 2 or more than 2 documents (n == 0 || 2 ≤ n
), throw an error. This is the best API for users who want to use YAML as an alternative of JSON or TOML.parsefirst
for parsing the first document from 1 or more documents in a YAML file (= load
in v0.4.10), if the YAML file consists of 0 documents (n == 0
), throw an error.parse
for parsing all documents in a YAML file (=load_all
in v0.4.10)Users should be aware of that a YAML file represents 0 or more YAML documents in order that they do not cause possible misuse and errors.
This makes it clear for users that the current behavior that YAML.load("")
gives an error (https://github.com/JuliaData/YAML.jl/issues/129 and https://github.com/JuliaData/YAML.jl/issues/143) is not a bug.
This sounds ok to me. We could even make const load = parsefirst
and add a deprecation warning before removing it.
The deprecation code will be:
# YAML.jl v0.5
@deprecate load parsefirst
@deprecate load_all parse
@deprecate load_file parsefirstfile
@deprecate load_all_file parsefile
YAML spec uses the words load and dump for converting a YAML to a native data and the reverse process.
If the deprecation is completed, I think it may be good to prepare load
and dump
for aliases of reading and writing.
Julia base exports the name parse
so we need to replace existing parse
to Base.parse
to define parse
of the module YAML
.
Thinking about it again, the semantics of Base.parse
are quite specific, and I think it might be a little bit weird to add YAML.parse*
that does something different. Same for tryparse
. I know I'm reversing course here. @GunnarFarneback what do you think?
It's the most important interface, it will be good to gather broad opinions.
On the whole I think it's better to follow YAML terminology than trying to match some other markup language implementation, regardless whether that's an stdlib.
Even if YAML allows multiple documents in a file or stream, single-document files are by far the more common case and should be easy to use. The proposal to change load_file
to parsefirstfile
would go from an easily read and understood name to something that's nearly unreadable and much more annoying to write. Although I can agree that there's a certain logic to the proposed function names I value user friendliness much higher in the public API.
So well, I think the current names for the reading functions are basically fine, and better than the alternatives.
YAML.jl uses different function names but we should use same function names with TOML.jl (and JSON.jl) because most people are accustomed to its names. Also we should not use underscores for function names because Julia don't use them in conventions.
load
,load_all
→parse
,tryparse
load_file
,load_all_file
→parsefile
,tryparsefile
write
→print
I have no idea about how to treat
all
.