Repository navigation
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.
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.
| Form | Example |
|---|---|
| line comment | // until the end of the line |
| block comment | /* anywhere */ |
| nested block comment | /* outer /* inner */ still a comment */ |
| 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.
| 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
0xhex,0ooctal,0bbinary. A sign may precede the prefix. The uppercase prefixes0X,0Oand0Bare errors. - Underscores may appear between digits, but not right after a base prefix:
0x_1is an error. - Leading zeros are allowed in decimal:
007is 7. - Suffixes:
i8,i16,i32,i64,i128,u8,u16,u32,u64,u128.isizeandusizeare not accepted (1usizeis an error). A suffixed literal must fit its type, so256u8and-1u32are errors. - Unsuffixed integers that fit into
i128oru128(-2^127 to 2^128-1) are stored asrustyon.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 (340282366920938463463374607431768211456is3.402823669209385e+38).
| 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 anf32/f64suffix. - An integer suffix on a float is an error:
1.5u8. - Values out of range become infinities. With the
f32suffix, the value is parsed atfloat32precision. -
infandNaN, with or without a sign, accept anf32/f64suffix (inff32,-inff32). To use one of these words as an identifier, write it as a raw identifier:r#inff32.
| 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,\fand\/are not valid escapes; they are anunknown escape charactererror, 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, sor##"has "# inside"##works.
| Input | Kind | Canonical |
|---|---|---|
'a' |
char | 'a' |
'\'' |
char | '\'' |
'\u{263A}' |
char | '☺' |
A char literal holds exactly one Unicode code point.
| 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 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 |
| 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.
| 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()andName( )are both a named empty tuple. - A parenthesized group whose first element is
identifier:is a struct; otherwise it is a tuple.
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} |
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).
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.
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 nestedSome(...)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.
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/ronrsis a small Rust crate, the oracle. It pinsron = "=0.12.3"and, for each document it receives, answers eitherOKwith a canonical form of the resultingron::ValueorERRwith ron-rs's error message. -
compat_test.gosends each document to the oracle, parses it withrustyon.Parsetoo, 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/*.txtis 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.FuzzCompatmutates these seeds and compares the results again.compat_typed_test.gochecks 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 compatThis 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.
| 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.
rustyon is licensed under the BSD-3-Clause license. It is an independent implementation of RON and is not affiliated with the ron-rs project.