https://github.com/peterhellberg/zon
ZON encoding/decoding for Go ⚡
https://github.com/peterhellberg/zon
encoding zon
Last synced: 3 months ago
JSON representation
ZON encoding/decoding for Go ⚡
- Host: GitHub
- URL: https://github.com/peterhellberg/zon
- Owner: peterhellberg
- License: mit
- Created: 2025-09-30T15:12:50.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-10-01T10:26:00.000Z (8 months ago)
- Last Synced: 2025-10-01T10:35:18.543Z (8 months ago)
- Topics: encoding, zon
- Language: Go
- Homepage:
- Size: 85.9 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ZON encoding/decoding for Go ⚡
[](https://github.com/peterhellberg/zon/actions/workflows/test.yml)
[](https://goreportcard.com/report/github.com/peterhellberg/zon)
[](https://pkg.go.dev/github.com/peterhellberg/zon)
[](https://github.com/peterhellberg/zon#license-mit)
`zon` is a Go library for marshaling and unmarshaling [ZON](https://ziglang.org/) data,
similar in usage to `encoding/json`.
> [!IMPORTANT]
> This library is not yet battle-tested; consider it more of an experiment :)
## Features
- Marshal Go primitives and structs into ZON format
- Unmarshal ZON data into Go values
- Support for `Encoder` and `Decoder`
- Handles booleans, numbers, strings, slices, maps, and structs
## Installation
go get -u github.com/peterhellberg/zon
## Usage
### Marshal / Unmarshal
[embedmd]:# (examples/zon-marshal-unmarshal/zon-marshal-unmarshal.go)
```go
package main
import (
"fmt"
"github.com/peterhellberg/zon"
)
type Example struct {
Name string `zon:"name"`
Age int `zon:"age"`
List []int `zon:"list"`
Omit []int `zon:"omit,omitempty"`
}
func main() {
v := Example{Name: "Peter", Age: 42}
if err := run(v); err != nil {
panic(err)
}
}
func run(v Example) error {
data, err := zon.Marshal(v, zon.Indent(""))
if err != nil {
return err
}
fmt.Println(string(data))
// Output: .{ .name = "Peter", .age = 42, .list = .{ }, }
var v2 map[string]any
if err := zon.Unmarshal(data, &v2); err != nil {
return err
}
fmt.Printf("%+v\n", v2)
// Output: map[age:42 list:[] name:Peter]
return nil
}
```
### Encoder / Decoder
[embedmd]:# (examples/zon-encoder-decoder/zon-encoder-decoder.go)
```go
package main
import (
"bytes"
"fmt"
"github.com/peterhellberg/zon"
)
type Example struct {
Name string `zon:"name"`
}
func main() {
v := Example{Name: "Peter"}
if err := run(v); err != nil {
panic(err)
}
}
func run(v Example) error {
var buf bytes.Buffer
if err := zon.NewEncoder(&buf, zon.Indent("")).Encode(v); err != nil {
return err
}
fmt.Println(buf.String())
// Output: .{ .name = "Peter", }
var v2 Example
if err := zon.NewDecoder(&buf).Decode(&v2); err != nil {
return err
}
fmt.Printf("%+v\n", v2)
// Output: {Name:Peter}
return nil
}
```
> [!TIP]
> As a slight convenience, there are `zon.Encode` and `zon.Decode` functions;
[embedmd]:# (examples/zon-encoder-decoder-convenience/zon-encoder-decoder-convenience.go /func run/ $)
```go
func run(v Example) error {
var buf bytes.Buffer
if err := zon.Encode(&buf, v, zon.Indent("")); err != nil {
return err
}
fmt.Println(buf.String())
// Output: .{ .name = "Peter", }
var v2 Example
if err := zon.Decode(&buf, &v2); err != nil {
return err
}
fmt.Printf("%+v\n", v2)
// Output: {Name:Peter}
return nil
}
```
## CLI
This library also comes with a small CLI called `zon`
which can be used to convert between **ZON** and **JSON**.
```console
$ go install https://github.com/peterhellberg/zon/cmd/zon@latest
```
> [!TIP]
> You can set the indentation per level by using the `-i` flag. (default `" "`)
### JSON to ZON
```console
$ echo '{"langs":["Zig", "Go"],"none":null}' | zon | zq -q 'langs'
```
```zig
.{
"Zig",
"Go",
}
```
> [!NOTE]
> `zq` in the example above is
### ZON to JSON
```console
$ cat testdata/build.zig.zon | zon -j | jq
```
```json
{
"dependencies": [],
"fingerprint": "0x99e5365e8f803dab",
"minimum_zig_version": "0.16.0-dev.205+4c0127566",
"name": ".testdata",
"paths": [
"build.zig",
"build.zig.zon",
"src"
],
"version": "0.0.0"
}
```
> [!NOTE]
> `jq` in the example above is
```console
$ cat testdata/comments.zon | tee /dev/stderr | zon -j | jq
```
```zig
// Comment before object
.{
.name = .comment,
.fingerprint = 0xcd164bbdb7002101,
.field = "with a string", // Trailing comment
// Comment between fields
.another = .{
.value = .{ "first", 2, false },
},
}
```
```json
{
"another": {
"value": [
"first",
2,
false
]
},
"field": "with a string",
"fingerprint": "0xcd164bbdb7002101",
"name": ".comment"
}
```
## License (MIT)
[embedmd]:# (LICENSE text)
```text
Copyright © 2025 Peter Hellberg - https://c7.se/
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```