1# RON grammar
2
3This file describes the structure of a RON file in [EBNF notation][ebnf].
4If extensions are enabled, some rules will be replaced. For that, see the
5[extensions document][exts] which describes all extensions and what they override.
6
7[ebnf]: https://en.wikipedia.org/wiki/Extended_Backus–Naur_form
8[exts]: ./extensions.md
9
10## RON file
11
12```ebnf
13RON = [extensions], ws, value, ws;
14```
15
16## Whitespace and comments
17
18```ebnf
19ws = { ws_single, comment };
20ws_single = "\n" | "\t" | "\r" | " ";
21comment = ["//", { no_newline }, "\n"] | ["/*", { ? any character ? }, "*/"];
22```
23
24## Commas
25
26```ebnf
27comma = ws, ",", ws;
28```
29
30## Extensions
31
32```ebnf
33extensions = { "#", ws, "!", ws, "[", ws, extensions_inner, ws, "]", ws };
34extensions_inner = "enable", ws, "(", extension_name, { comma, extension_name }, [comma], ws, ")";
35```
36
37For the extension names see the [`extensions.md`][exts] document.
38
39## Value
40
41```ebnf
42value = unsigned | signed | float | string | char | bool | option | list | map | tuple | struct | enum_variant;
43```
44
45## Numbers
46
47```ebnf
48digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
49hex_digit = "A" | "a" | "B" | "b" | "C" | "c" | "D" | "d" | "E" | "e" | "F" | "f";
50unsigned = (["0", ("b" | "o")], digit, { digit | '_' } |
51             "0x", (digit | hex_digit), { digit | hex_digit | '_' });
52signed = ["+" | "-"], unsigned;
53float = float_std | float_frac;
54float_std = ["+" | "-"], digit, { digit }, ".", {digit}, [float_exp];
55float_frac = ".", digit, {digit}, [float_exp];
56float_exp = ("e" | "E"), digit, {digit};
57```
58
59## String
60
61```ebnf
62string = string_std | string_raw;
63string_std = "\"", { no_double_quotation_marks | string_escape }, "\"";
64string_escape = "\\", ("\"" | "\\" | "b" | "f" | "n" | "r" | "t" | ("u", unicode_hex));
65string_raw = "r" string_raw_content;
66string_raw_content = ("#", string_raw_content, "#") | "\"", { unicode_non_greedy }, "\"";
67```
68
69> Note: Raw strings start with an `r`, followed by n `#`s and a quotation mark
70  `"`. They may contain any characters or escapes (except the end sequence).
71  A raw string ends with a quotation mark (`"`), followed by n `#`s. n may be
72  any number, including zero.
73  Example:
74  ```rust
75r##"This is a "raw string". It can contain quotations or
76backslashes (\)!"##
77  ```
78Raw strings cannot be written in EBNF, as they are context-sensitive.
79Also see [the Rust document] about context-sensitivity of raw strings.
80
81[the Rust document]: https://github.com/rust-lang/rust/blob/d046ffddc4bd50e04ffc3ff9f766e2ac71f74d50/src/grammar/raw-string-literal-ambiguity.md
82
83## Char
84
85```ebnf
86char = "'", (no_apostrophe | "\\\\" | "\\'"), "'";
87```
88
89## Boolean
90
91```ebnf
92bool = "true" | "false";
93```
94
95## Optional
96
97```ebnf
98option = "Some", ws, "(", ws, value, ws, ")";
99```
100
101## List
102
103```ebnf
104list = "[", [value, { comma, value }, [comma]], "]";
105```
106
107## Map
108
109```ebnf
110map = "{", [map_entry, { comma, map_entry }, [comma]], "}";
111map_entry = value, ws, ":", ws, value;
112```
113
114## Tuple
115
116```ebnf
117tuple = "(", [value, { comma, value }, [comma]], ")";
118```
119
120## Struct
121
122```ebnf
123struct = unit_struct | tuple_struct | named_struct;
124unit_struct = ident | "()";
125tuple_struct = [ident], ws, tuple;
126named_struct = [ident], ws, "(", [named_field, { comma, named_field }, [comma]], ")";
127named_field = ident, ws, ":", value;
128```
129
130## Enum
131
132```ebnf
133enum_variant = enum_variant_unit | enum_variant_tuple | enum_variant_named;
134enum_variant_unit = ident;
135enum_variant_tuple = ident, ws, tuple;
136enum_variant_named = ident, ws, "(", [named_field, { comma, named_field }, [comma]], ")";
137```
138