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.

[Durobot]

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

In the meantime, since there's no documentation on ZON, could someone please tell if ZON supports arrays?

If yes, what is the syntax?

Is it .my_arr = .{ 1, 2, 3 },, or .my_arr = { 1, 2, 3 }, - both of these pass std.zig.Ast.parse()?

Or is it something different?

[Arnau478]

In the meantime, since there's no documentation on ZON, could someone please tell if ZON supports arrays?

You should think of a .zon file as a struct initialization. So yes, it does. And it does in the exact same way zig does. And to answer your question, just use a tuple (an anonymous struct literal with no field names):

.foo = .{
    something,
    hello_there,
},

Is it .my_arr = .{ 1, 2, 3 },, or .my_arr = { 1, 2, 3 }, - both of these pass std.zig.Ast.parse()?

The first one would work perfectly. The second one is not even valid in normal zig code.

But yeah, the first one should pass, as (someone correct me if I missed something) Ast.parse() only uses the mode parameter to call Parser.parseZon() instead of Parser.parseRoot(), and Parser.parseZon() basically calls the expression parsing routines. Acording to the grammar, this should cascade down to PrimaryTypeExpr.

[Durobot]

You should think of a .zon file as a struct initialization. So yes, it does. And it does in the exact same way zig does.

Thank you.

I have since written a small library (if it could be called that) to help extract field values from the ZON AST generated with Ast.parse(): https://github.com/Durobot/zon_get_fields

I don't want to hijack the comments for this issue.. but you wouldn't happen to know why negative numbers (field values) are represented by two tokens in AST - the minus sign ("-") and the number itself?

[Arnau478]

I don't want to hijack the comments for this issue.. but you wouldn't happen to know why negative numbers (field values) are represented by two tokens in AST - the minus sign ("-") and the number itself?

Well, most compilers do that. And it kind of makes sense, as const foo = -bar; is valid. Plus, the compiler will figure it out the same way you do const foo = 1+2;. Anyway, this is a bit out of scope, as you said. So, if you have any further questions, contact me at @arnau478:matrix.org (matrix) or @arnau478 (discord)