Skip to content

RON Syntax

Arne K. (TRC-Loop) edited this page Nov 14, 2026 · 4 revisions

RON Syntax

A concise reference of the RON grammar rustyon accepts. The parser matches ron-rs 0.12.3 exactly, checked by a differential test suite. The authoritative description is the ron-rs grammar.

Every example below was parsed with rustyon.Parse; the right column shows the parsed value kind and the canonical form Marshal writes for it.

Documents

A document is optional extension attributes followed by exactly one value. Whitespace and comments may appear between any two tokens. Input must be valid UTF-8. A leading byte order mark is skipped; this is the only place where rustyon is more tolerant than ron-rs, which rejects it.

#![enable(implicit_some)]
// a comment
Config(name: "x")

A Decoder also reads streams of several values one after another.

Comments

Form Example
line comment // until the end of the line
block comment /* anywhere */
nested block comment /* outer /* inner */ still a comment */

Booleans and unit

Input Value
true, false bool
() unit
( ), ( newline ) empty tuple (not unit)

Unit is only the two characters () with nothing between them. Any whitespace or comment between the parentheses makes it an empty tuple, as in ron-rs.

Integers

Input Kind Canonical
42 integer 42
-42 integer -42
+7 integer 7
1_000_000 integer 1000000
0x2A integer 42
-0xff integer -255
0o17 integer 15
0b1010_1010 integer 170
255u8 integer 255
-128i8 integer -128
340282366920938463463374607431768211455u128 integer 340282366920938463463374607431768211455
b'a' integer (byte literal) 97
  • Bases: lowercase 0x hex, 0o octal, 0b binary. A sign may precede the prefix. The uppercase prefixes 0X, 0O and 0B are errors.
  • Underscores may appear between digits, but not right after a base prefix: 0x_1 is an error.
  • Leading zeros are allowed in decimal: 007 is 7.
  • Suffixes: i8, i16, i32, i64, i128, u8, u16, u32, u64, u128. isize and usize are not accepted (1usize is an error). A suffixed literal must fit its type, so 256u8 and -1u32 are errors.
  • Unsuffixed integers that fit into i128 or u128 (-2^127 to 2^128-1) are stored as rustyon.Int; the Go target type decides whether they fit when decoding. An unsuffixed integer beyond that range is not an error: it becomes a float, as in ron-rs (340282366920938463463374607431768211456 is 3.402823669209385e+38).

Floats

Input Kind Canonical
1.5 float 1.5
1. float 1.0
.5 float 0.5
1e3 float 1000.0
2.5e+2 float 250.0
1_000.000_1 float 1000.0001
3f32 float 3.0
1.5f64 float 1.5
inf, +inf, inff32 float inf
-inf float -inf
NaN, -NaN, NaNf64 float NaN
  • A literal is a float if it has a ., an exponent (e / E, optional sign) or an f32 / f64 suffix.
  • An integer suffix on a float is an error: 1.5u8.
  • Values out of range become infinities. With the f32 suffix, the value is parsed at float32 precision.
  • inf and NaN, with or without a sign, accept an f32 / f64 suffix (inff32, -inff32). To use one of these words as an identifier, write it as a raw identifier: r#inff32.

Strings

Input Kind Canonical
"tab\there" string "tab\there"
"\u{1F600}" string "😀"
"\x41" string "A"
"multi (newline) line" string "multi\nline"
"cont\ (newline) inued" string "continued"
r"raw \n" string "raw \\n"
r#"has "quotes""# string "has \"quotes\""

Escapes in strings and chars:

Escape Meaning
\" \' \\ the character itself
\n \r \t newline, carriage return, tab
\0 NUL
\xNN a byte; in strings and chars at most \x7F
\uNNNN a Unicode code point, exactly 4 hex digits
\u{N...} a Unicode code point, 1 to 6 hex digits; surrogates and values above 10FFFF are errors
\ at the end of a line line continuation: the newline and the leading whitespace of the next line are skipped
  • \b, \f and \/ are not valid escapes; they are an unknown escape character error, as in ron-rs.
  • Strings may contain raw newlines.
  • Raw strings r"...", r#"..."#, r##"..."## and so on contain no escapes. The number of # must match on both sides, so r##"has "# inside"## works.

Chars

Input Kind Canonical
'a' char 'a'
'\'' char '\''
'\u{263A}' char '☺'

A char literal holds exactly one Unicode code point.

Byte strings and byte literals

Input Kind Canonical
b"bytes" byte string b"bytes"
b"\x00\xff" byte string b"\x00\xff"
br"raw\x" byte string b"raw\\x"
br#"a"b"# byte string b"a\"b"
b'a' integer 97

Byte strings (b"..." and br"...") accept any character, including non-ASCII ones, which are stored as their UTF-8 bytes, plus \xNN escapes for any byte (\x00 to \xFF) and \u{...} escapes, which are also stored as UTF-8: b"é" is b"\xc3\xa9" and b"\u{1F600}" is b"\xf0\x9f\x98\x80". Byte literals (b'a') hold exactly one byte: b'é' and b'\u{41}' are errors, b'\x80' is 128.

Identifiers

Identifiers follow the Unicode XID rules, like Rust: they start with a character with the XID_Start property or _, and continue with XID_Continue characters. Größe and 日本 are identifiers, a·b is one too (the middle dot is XID_Continue), but · alone is not. rustyon uses its own Unicode tables, newer than the ones in Go's unicode package, so that it agrees with ron-rs on recent characters.

The words true, false, inf, NaN, None and Some have special meaning. A raw identifier r#name turns any of them back into a plain identifier and also allows ., + and - in the name:

Input Kind Canonical
Red identifier Red
r#true identifier r#true
r#foo-bar.baz identifier r#foo-bar.baz

Option

Input Value
None empty option
Some(1) option holding 1
Some(1,) a trailing comma is allowed
Some(None) nested option

With the implicit_some extension, Some(x) may be written as x, and Some x (without parentheses) is valid too, as in ron-rs. Without the extension, Some 1 is an error (expected '(' after Some). See Type Mapping.

Collections

Kind Syntax Examples
list [a, b, ...] [], [1, 2, 3,]
map {key: value, ...} {}, {"a": 1, 2: [true]}
tuple (a, b, ...) (1, "x"), (1,)
struct (field: value, ...) (x: 1, y: 2)
  • Trailing commas are allowed everywhere.
  • Map keys can be any value.
  • () is unit; ( ) (anything between the parentheses) is an empty tuple. Name() and Name( ) are both a named empty tuple.
  • A parenthesized group whose first element is identifier: is a struct; otherwise it is a tuple.

Ranges

As ron::Value does, the parser accepts Rust range syntax and turns it into a map with start and end string keys, or into unit:

Input Value
1..2, 1..=2 {"start": 1, "end": 2}
1.. {"start": 1}
..2, ..=2 {"end": 2}
.. unit
1.5..2.5 {"start": 1.5, "end": 2.5}

Named structs, tuple structs and enums

An identifier directly followed by ( names a struct or tuple:

Input Meaning
Point(x: 1, y: 2) named struct, or struct enum variant
Point(1, 2) tuple struct, or tuple enum variant
Meters(5.0) newtype struct, or newtype variant
Empty() named tuple with no values
Red unit struct, or unit enum variant

RON uses the same syntax for structs and enum variants; which one it is depends on the type being deserialized. See Enums for how rustyon maps variants onto Go types. Field names can be raw identifiers: (r#type: 1), and a keyword used as a field name works too: (Some: 1).

Extensions

Attributes at the start of a document enable extensions:

#![enable(implicit_some)]
#![enable(unwrap_newtypes, unwrap_variant_newtypes,)]
(...)
Extension Allows
implicit_some x instead of Some(x)
unwrap_newtypes 5.0 instead of Meters(5.0)
unwrap_variant_newtypes Shape(x: 1) instead of Shape((x: 1))
explicit_struct_names requires struct names to be written

Other attributes ron-rs knows are accepted and ignored: #![type = "my::Type"] and #![schema = "path/to/schema.ron"] (a string value is required). They can be mixed with #![enable(...)] lines. Unknown extension names are a syntax error, and so is an empty list: #![enable()] fails with expected identifier. The Formatter accepts them too and keeps them as written. rustyon records the extensions in Document.Extensions; its decoder always accepts the implicit and unwrapped forms. When explicit_struct_names is enabled, decoding a struct, tuple or () without a name into a Go struct is an error.

Limits

Nesting depth when parsing is limited by the same budget ron-rs uses, 128 units, to protect against stack exhaustion on hostile input:

  • every list, map, tuple and struct costs one unit, and so does every element inside it. In practice that allows 64 nested collections: [[...]] with 64 levels parses, 65 levels fails.
  • every Some( costs one unit, so 128 nested Some(...) parse and 129 fail.

Going over the budget is a syntax error, exceeded the maximum nesting depth, reported at the position where the limit was hit. The encoder has its own limit of 1000 levels, see Errors.

Compatibility with ron-rs

rustyon accepts and rejects exactly the same documents as ron-rs 0.12.3 and parses them into the same values. This is checked by a differential test suite that runs every document through ron-rs itself:

  • compat/ronrs is a small Rust crate, the oracle. It pins ron = "=0.12.3" and, for each document it receives, answers either OK with a canonical form of the resulting ron::Value or ERR with ron-rs's error message.
  • compat_test.go sends each document to the oracle, parses it with rustyon.Parse too, and fails on any difference: accepted by one and rejected by the other, or a different canonical value (integers, float bit patterns, string and byte contents, map order and duplicate keys). Error messages and positions are not compared, only accept versus reject.
  • testdata/compat/*.txt is the corpus (numbers, strings, structure, separated by %%%% lines), extended by awkward inputs such as invalid UTF-8, NUL bytes, Unicode whitespace and identifier edge cases. FuzzCompat mutates these seeds and compares the results again. compat_typed_test.go checks typed decoding and encoding against a serde fixture the oracle serializes.
  • The CI job "ron-rs compatibility" builds the oracle and runs the suite plus a 60 second fuzz run on every change.

To run it locally you need a Rust toolchain (cargo):

make compat

This builds the oracle with cargo build --release --locked, runs the Compat tests against it, then fuzzes FuzzCompat for FUZZTIME (default 30s, for example make compat FUZZTIME=2m). Without the RONRS_ORACLE environment variable (the path of the oracle binary) the compatibility tests are skipped, so a plain go test does not need Rust.

The one deliberate difference is the leading byte order mark, which rustyon tolerates and ron-rs rejects; the suite strips it before asking the oracle. If you find a document where rustyon and ron-rs disagree, please open an issue with the input.

Common syntax errors

Input Error
256u8 syntax error at 1:4: integer out of bounds
1.5u8 syntax error at 1:4: unexpected trailing characters
1usize syntax error at 1:2: unexpected trailing characters
"\xff" syntax error at 1:6: not a valid byte-escaped Unicode character
"\b" syntax error at 1:4: unknown escape character
'ab' syntax error at 1:3: expected closing ' of char literal
"abc syntax error at 1:2: unterminated string
/* open syntax error at 1:8: unclosed block comment
#![enable(bogus)] 1 syntax error at 1:16: unknown extension "bogus"
#![enable()] 1 syntax error at 1:11: expected identifier
1 2 syntax error at 1:3: unexpected trailing characters
Some 1 syntax error at 1:6: expected '(' after Some
[1, 2 syntax error at 1:6: expected ',' or ']'
[1,,2] syntax error at 1:4: unexpected character ','

All messages start with rustyon: . See Errors.

Clone this wiki locally