rustyon is a Go implementation of Rusty Object Notation (RON), the human-readable serialization format used in the Rust ecosystem. It is an independent implementation and is not affiliated with the ron-rs project.
// Read and write files like this from Go.
#![enable(implicit_some)]
GameConfig(
window_size: (800, 600),
window_title: "Rusty Game",
difficulty: Hard,
spawn: Circle(radius: 2.5),
key_bindings: {"up": Up, "down": Down},
)Marshal/Unmarshalwith anencoding/jsonstyle API, struct tags,omitemptyandomitzero,EncoderandDecoderfor streams.- Rust enums on Go interfaces. Register variants once and
Circle(radius: 1.0)decodes into yourCircletype. - Dynamic
Valuetree for documents with an unknown shape, including 128-bit integers. - Formatter that keeps comments, like
gofmtfor.ronfiles. - Full ron-rs grammar: raw strings, byte strings, nested block comments, number suffixes,
#![enable(...)]extensions. rustyonCLI to format, validate, query and convert RON to and from JSON, YAML and TOML.- Zero dependencies in the library, fuzz tested, Go 1.24+. The CLI is a separate module, so its YAML and TOML libraries never reach your build.
go get github.com/peltonapp/rustyon-goThe package name is rustyon:
import "github.com/peltonapp/rustyon-go"type Config struct {
WindowTitle string // matches window_title
WindowSize [2]int // matches (800, 600)
MaxFPS *int // Option<u32>: None or Some(60)
Tags []string `ron:"labels,omitempty"`
}
var c Config
err := rustyon.Unmarshal(data, &c)
out, err := rustyon.MarshalIndent(c, "", " ")Go field names become snake_case by default, so Go structs line up with Rust structs without tags. Pointers map to Option: nil is None, anything else is Some(v). The wiki has the full type mapping.
snake_case stays the default. Pick another strategy for a whole encoder or decoder, or per struct with a serde style rename_all option on the blank field. Explicit ron:"name" tags always win.
out, err := rustyon.MarshalWith(cfg, rustyon.EncodeOptions{FieldNaming: rustyon.CamelCase})
err = rustyon.UnmarshalWith(data, &cfg, rustyon.DecodeOptions{FieldNaming: rustyon.CamelCase})
type Window struct {
_ struct{} `ron:",rename_all=PascalCase"` // also: camelCase, SCREAMING_SNAKE_CASE, kebab-case, identity, ...
Title string // Title
}Like serde's flatten: embedded structs and struct fields tagged ron:",flatten" are written inline, and a map[string]T field tagged ron:",flatten" collects every field no other field matches.
type Item struct {
Common `ron:",flatten"` // id and name appear directly in Item
Extra map[string]any `ron:",flatten"` // all other fields
}MarshalIndent covers the common case. MarshalWithConfig (or Encoder.SetPrettyConfig) mirrors ron-rs's PrettyConfig: compact arrays, structs and maps, separate tuple members, a depth limit, \u{..} escapes for non-ASCII text, custom line break, indent, prefix and separator after the colon, and // [0] index comments for lists. The output always parses back to the same value.
out, err := rustyon.MarshalWithConfig(v, rustyon.PrettyConfig{CompactArrays: true, DepthLimit: 2})rustyon.Raw (like json.RawMessage) keeps one RON value as text, so a part of a document can be decoded later or passed through. UnmarshalAs[T] and DecodeAs[T] return the value instead of filling a pointer.
type Envelope struct {
Kind string
Payload rustyon.Raw // captured as written, comments included
}
cfg, err := rustyon.UnmarshalAs[Config](data)Go has no sum types, so a Rust enum becomes an interface and each variant a type that implements it:
type Shape interface{ isShape() }
type Circle struct{ Radius float64 } // Circle(radius: 1.0)
type Rect struct { // Rect(2.0, 3.0)
_ struct{} `ron:",tuple"`
W, H float64
}
type Empty struct{} // Empty
func (Circle) isShape() {}
func (Rect) isShape() {}
func (Empty) isShape() {}
func init() {
rustyon.RegisterEnum[Shape](
rustyon.Variant[Circle]("Circle"),
rustyon.Variant[Rect]("Rect"),
rustyon.Variant[Empty]("Empty"),
)
}
var shapes []Shape
err := rustyon.Unmarshal([]byte(`[Circle(radius: 1.5), Rect(2.0, 3.0), Empty]`), &shapes)Enums without data, like enum Difficulty { Easy, Hard }, map onto Go constants with rustyon.RegisterUnitEnum.
Enums that use serde's other representations register with RegisterEnumWith and match what ron-rs reads and writes (checked against the ron-rs oracle):
// #[serde(tag = "type")] (type: "Circle", radius: 1.0)
rustyon.RegisterEnumWith[Shape](rustyon.EnumOptions{Tag: "type"}, variants...)
// #[serde(tag = "t", content = "c")] (t: Circle, c: (radius: 1.0))
rustyon.RegisterEnumWith[Shape](rustyon.EnumOptions{Tag: "t", Content: "c"}, variants...)
// #[serde(untagged)] (radius: 1.0), first variant that fits wins
rustyon.RegisterEnumWith[Shape](rustyon.EnumOptions{Untagged: true}, variants...)v, err := rustyon.Parse([]byte(`Point(x: 1, y: -2)`))
s := v.(rustyon.Struct)
y, _ := s.Get("y") // rustyon.Intpretty, err := rustyon.Format(src) // comments stay where they werego install github.com/peltonapp/rustyon-go/cmd/rustyon@latest
rustyon fmt -w config.ron # format in place, keeps comments
rustyon validate *.ron # check syntax
rustyon to-json save.ron # RON to JSON
rustyon from-json data.json # JSON to RON
rustyon to-yaml save.ron # RON to YAML
rustyon from-yaml cfg.yaml # YAML to RON
rustyon to-toml save.ron # RON to TOML
rustyon from-toml cfg.toml # TOML to RON
rustyon get 'items[0].name' save.ron # print one valueBinaries for Linux, macOS, Windows and FreeBSD are attached to the releases tagged cmd/rustyon/v*. The CLI is its own Go module (github.com/peltonapp/rustyon-go/cmd/rustyon) with its own version tags, so the library stays free of dependencies.
Syntax errors point at the problem:
$ rustyon validate game.ron
game.ron:3:16: expected ',' or ')'
3 | size: (800 600),
| ^
Conversions. to-* and from-* read a file or standard input and write to standard output. from-json, from-yaml and from-toml take -structs to write mappings whose keys are identifiers as structs (key: value) instead of maps ({"key": value}), and -indent to change or disable pretty printing. Like JSON, YAML and TOML cannot hold everything RON can, so struct and variant names are dropped. YAML keeps the field order. TOML has no null and needs a table at the top level: None fields are left out, None inside an array is an error, and keys are written sorted. Dates and times in TOML become strings.
get. rustyon get <path> [file] prints the RON value at a path and exits with status 1 if it does not exist. A path is built from three steps:
| Step | Selects |
|---|---|
.name |
struct field, or map entry with a string or identifier key (leading dot is optional) |
[N] |
list or tuple element, -1 is the last; map entry with integer key N |
["key"] |
map entry with a string key (Go escapes), or struct field |
Examples: items[0].name, .config.port, players["alice"], tags[-1]. Some(x) is looked through, and . selects the whole document. Use -indent "" for compact output.
Everything is linear in the input size. Typed Unmarshal decodes straight from the text without building an intermediate tree and runs on par with encoding/json; parsing into a dynamic tree is about twice as fast as encoding/json decoding into any; typed Marshal is about 2.3x slower than encoding/json. Format keeps comments and is several times slower than json.Indent. A 13 KB file encodes in about 0.13 ms, decodes in about 0.09 ms and formats in about 0.18 ms on an Apple M2. Charts, Big O tables and methodology are on the Performance wiki page.
- Wiki: guides, type mapping, enums, formatter rules, performance
- API reference on pkg.go.dev
- RON itself: ron-rs/ron and the Rust crate docs on docs.rs/ron
Contributions are welcome. Please read CONTRIBUTING.md; all commits need a DCO sign-off (git commit -s).
BSD-3-Clause. The RON format was created by the ron-rs authors.