Documentation on ZON files

[Arnau478]

Now that ZON files (Zig Object Notation) are a thing, they should be documented in langref
ZON files described on #14523

[tisonkun]

Do we have a standing example now? I don't find a build.zig.zon in this repository even.

[Arnau478]

Not sure, but it should be there by 0.12.0, so... Anyway, the syntax is very simple, just anonymous nested structs, like so:

.{
    .foo = .{
        .a = "hello",
    }
}

(then, they can be imported just like JSON in node.js)

Whenever the build system starts using ZON files we will see them on the repo I guess

EDIT: Zig compiler doesn't need a build.zig.zon, as it does not have any dependency. Also, it will never be a dependency, so not even the version field would be used.

[Earnestly]

A major flaw with json is its inability to store non-UTF8 strings which inadvertently makes them unreliable for storing unix filenames (here a filename is defined as any sequence of bytes except NUL and /, including invalid UTF-8).

Will or does zon address this issue?

Some prior art on this would be Rust's raw string literal notation and qsn which is a format based on those ideas. It is documented quite nicely here, along with good general coverage of this topic: http://www.oilshell.org/release/latest/doc/qsn.html

[mlugg]

ZON strings are no different from Zig string literals in this context, so the answer is: yes, ZON strings store any sequence of bytes, agnostic to their interpretation. The literal in file must itself be UTF-8 encoded, because Zig sources - and by extension ZON - are always UTF-8 encoded, but you can represent any byte sequence which is not valid UTF-8 by using simple escape sequences (the main relevant one here being \xNN).

[Earnestly]

This is what I hope for, essentially exposing zig's string literals directly, but if zon is to be like json and independent of language then perhaps these aspects should be made explicit when documenting the format?

Then tools like fq can pick up the format making it useful for a wider array of purposes.

[Arnau478]

Now that i'm thinking about this, it would be wise to wait for #14531, and document everything at once. More importantly, some aspects of ZON files might change.

[andrewrk]

as of f7bc55c there is documentation here: https://github.com/ziglang/zig/blob/master/doc/build.zig.zon.md

[Earnestly]

Closing this may be premature as that commit doesn't document ZON format, but instead documents the build.zig.zon file and its possible fields.

[Arnau478]

I totally agree with @Earnestly, having documentation for build.zig.zon is good, but the .zon format itself should also be documented (maybe in langref?).

[mlugg]

I definitely agree we should have documentation on the ZON format itself, not just the schema of build.zig.zon - reopening for this.