Repository navigation
RON Syntax
A concise reference of the RON grammar rustyon accepts. It follows current ron-rs releases. 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.
#![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 |
| 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:
0x/0Xhex,0o/0Ooctal,0b/0Bbinary. A sign may precede the prefix. - Underscores may appear between digits, including right after a base prefix (
0x_1). - Leading zeros are allowed in decimal:
007is 7. - Suffixes:
i8,i16,i32,i64,i128,isize,u8,u16,u32,u64,u128,usize. A suffixed literal must fit its type (isizeandusizeare 64 bits), so256u8and-1u32are errors. - Unsuffixed integers are not range checked by the parser. They are stored as
rustyon.Int; the Go target type decides whether they fit.
| 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
|
float | inf |
-inf |
float | -inf |
NaN, -NaN
|
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. - Signed forms
+inf,-inf,+NaN,-NaNalso accept anf32/f64suffix (-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 |
\b \f
|
backspace, form feed |
\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 |
- 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 and byte literals accept ASCII only, plus \xNN escapes for any byte (\x00 to \xFF). \u escapes are not allowed in them.
Identifiers start with a letter or _ and continue with letters, digits and _. Unicode letters are allowed: Größe is an identifier.
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. 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, not an empty tuple. - A parenthesized group whose first element is
identifier:is a struct; otherwise it is a tuple.
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 |
Unknown extension names are a syntax error. rustyon records the extensions in Document.Extensions; its decoder always accepts the implicit and unwrapped forms, and does not enforce explicit_struct_names.
Nesting is limited to 1000 levels to protect against stack exhaustion on hostile input.
| Input | Error |
|---|---|
256u8 |
syntax error at 1:1: integer 256u8 out of range for u8 |
1.5u8 |
syntax error at 1:1: integer suffix "u8" on float literal |
"\xff" |
syntax error at 1:2: \x escape out of range, must be at most \x7F in strings |
b"é" |
syntax error at 1:3: non-ASCII character in byte string |
'ab' |
syntax error at 1:1: char literal must contain exactly one character |
/* open |
syntax error at 1:1: unterminated block comment |
#![enable(bogus)] 1 |
syntax error at 1:11: unknown extension "bogus" |
1 2 |
syntax error at 1:3: expected end of input, found integer 2 |
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.