# RON grammar
This file describes the structure of a RON file in [EBNF notation][ebnf].
If extensions are enabled, some rules will be replaced. For that, see the
[extensions document][exts] which describes all extensions and what they override.
[ebnf]: https://en.wikipedia.org/wiki/Extended_Backus–Naur_form
[exts]: ./extensions.md
## RON file
```ebnf
RON = ws, [extensions], ws, value, ws;
```
## Whitespace and comments
```ebnf
ws = { ws_single | comment };
ws_single = "\n" | "\t" | "\r" | " " | U+000B | U+000C | U+0085 | U+200E | U+200F | U+2028 | U+2029;
no_newline = ? any character except "\n" ?;
```
## Commas
```ebnf
comma = ws, ",", ws;
```
## Extensions
```ebnf
extensions = { "#", ws, "!", ws, "[", ws, extensions_inner, ws, "]", ws };
extensions_inner = "enable", ws, "(", extension_name, { comma, extension_name }, [comma], ws, ")";
For the extension names see the [`extensions.md`][exts] document.
## Value
```ebnf
## Numbers
```ebnf
digit_octal = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7";
digit_hexadecimal = digit | "A" | "a" | "B" | "b" | "C" | "c" | "D" | "d" | "E" | "e" | "F" | "f";
integer = ["+" | "-"], unsigned, [integer_suffix];
integer_suffix = ("i", "u"), ("8", "16", "32", "64", "128");
unsigned_octal = "0o", digit_octal, { digit_octal | "_" };
unsigned_hexadecimal = "0x", digit_hexadecimal, { digit_hexadecimal | "_" };
unsigned_decimal = digit, { digit | "_" };
byte = "b", "'", byte_content, "'";
byte_content = ascii | ("\", (escape_ascii | escape_byte));
ascii = ? any ASCII character in range 0x00 ..= 0x7F ?;
float_int = digit, { digit | "_" };
float_std = digit, { digit | "_" }, ".", [digit, { digit | "_" }];
float_frac = ".", digit, { digit | "_" };
float_exp = ("e" | "E"), ["+" | "-"], { digit | "_" }, digit, { digit | "_" };
float_suffix = "f", ("32", "64");
```
> Note: `ascii` refers to any ASCII character, i.e. any byte in range `0x00 ..= 0x7F`.
## String
```ebnf
string = string_std | string_raw;
string_std = '"', { unicode_without_double_quotation_marks_or_backslash | string_escape }, '"';
string_escape = "\", (escape_ascii | escape_byte | escape_unicode | escape_line);
string_raw = "r", string_raw_content;
unicode_without_double_quotation_marks_or_backslash = ? any character except backslash or double quotation mark ?;
escape_ascii = "'" | '"' | "\" | "n" | "r" | "t" | "0";
escape_byte = "x", digit_hexadecimal, digit_hexadecimal;
escape_unicode = "u", "{", digit_hexadecimal, [digit_hexadecimal, [digit_hexadecimal, [digit_hexadecimal, [digit_hexadecimal, [digit_hexadecimal]]]]], "}";
escape_line = ("\n" | "\r\n"), { "\t" | "\n" | "\r" | " " };
```
> Note: A Unicode escape is written as `\u{...}` with 1 to 6 hex digits, and
the value has to be a valid Unicode scalar value, so `\u{D800}` or
`\u{110000}` are rejected.
> Note: RON supports [Rust-style string continuation escapes]. A backslash
immediately before LF removes that LF and all subsequent spaces, tabs,
carriage returns, and line feeds. RON also accepts CRLF at the continuation
site, treating it as LF. String continuation escapes are supported in both
standard strings and standard byte strings. Raw strings and raw byte strings
keep string continuation escapes as-is. Rust warns when a continuation skips
additional lines; RON accepts them without a warning.
> Note: Raw strings start with an `r`, followed by n `#`s and a quotation mark
`"`. They may contain any characters or escapes (except the end sequence).
A raw string ends with a quotation mark (`"`), followed by n `#`s. n may be
any number, including zero.
Example:
```rust
r##"This is a "raw string". It can contain quotations or
backslashes (\)!"##
```
Raw strings cannot be written in EBNF, as they are context-sensitive.
Also see [the Rust document] about context-sensitivity of raw strings.
[the Rust document]: https://github.com/rust-lang/rust/blob/d046ffddc4bd50e04ffc3ff9f766e2ac71f74d50/src/grammar/raw-string-literal-ambiguity.md
[Rust-style string continuation escapes]: https://doc.rust-lang.org/reference/expressions/literal-expr.html#string-continuation-escapes
## Byte String
```ebnf
byte_string = byte_string_std | byte_string_raw;
```
> Note: Byte strings are similar to normal strings but are not required to
contain only valid UTF-8 text. RON's byte strings follow the updated Rust
byte string literal rules as proposed in [RFC #3349], i.e. byte strings
allow the exact same characters and escape codes as normal strings.
[RFC #3349](https://github.com/rust-lang/rfcs/pull/3349)
> Note: Raw byte strings start with an `br` prefix and follow the same rules
as raw strings, which are outlined above.
## Char
```ebnf
unicode_without_apostrophe_or_backslash = ? any character except backslash or apostrophe ?;
```
> Note: A char accepts the same escapes as a string, except for string
continuation escapes. A `\x` escape in a char must be a single ASCII
character (`\x00` to `\x7F`), so several byte escapes can't be combined
into one UTF-8 character like they can in a string.
## Boolean
```ebnf
## Optional
```ebnf
```
## Range
```ebnf
range_from_to_exclusive = number, "..", number;
range_from = number, "..";
range_to_inclusive = "..=", number;
range_to_exclusive = "..", number;
range_full = "..";
```
> Note: Alternatives are ordered by specificity — `..=` must be matched before `..`
to avoid ambiguity. A parser should attempt the longer token (`..=`) first.
The six range forms correspond directly to Rust's range types:
`x..y` → `Range`, `x..=y` → `RangeInclusive`, `x..` → `RangeFrom`,
`..y` → `RangeTo`, `..=y` → `RangeToInclusive`, `..` → `RangeFull`.
## List
```ebnf
list = "[", [value, { comma, value }, [comma]], "]";
```
## Map
```ebnf
map = "{", [map_entry, { comma, map_entry }, [comma]], "}";
map_entry = value, ws, ":", ws, value;
```
## Tuple
```ebnf
tuple = "(", [value, { comma, value }, [comma]], ")";
```
## Struct
```ebnf
tuple_struct = [ident], ws, tuple;
named_struct = [ident], ws, "(", ws, [named_field, { comma, named_field }, [comma]], ")";
named_field = ident, ws, ":", ws, value;
```
## Enum
```ebnf
enum_variant = enum_variant_unit | enum_variant_tuple | enum_variant_named;
enum_variant_unit = ident;
enum_variant_tuple = ident, ws, tuple;
enum_variant_named = ident, ws, "(", [named_field, { comma, named_field }, [comma]], ")";
```
## Identifier
```ebnf
ident = ident_std | ident_raw;
ident_std = ident_std_first, { ident_std_rest };
ident_std_first = XID_Start | "_";
ident_std_rest = XID_Continue;
ident_raw = "r", "#", ident_raw_rest, { ident_raw_rest };
XID_Continue = ? any character in the Unicode XID_Continue character set ?;
```
> Note: [XID_Start](http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Start%3A%5D&abb=on&g=&i=) and [XID_Continue](http://unicode.org/cldr/utility/list-unicodeset.jsp?a=%5B%3AXID_Continue%3A%5D&abb=on&g=&i=) refer to Unicode character sets.