Adding upstream version 110.0.1.upstream/110.0.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

2 files changed, 256 insertions, 0 deletions

diff --git a/third_party/rust/ron/docs/extensions.md b/third_party/rust/ron/docs/extensions.md
new file mode 100644
index 0000000000..a849220222
--- /dev/null
+++ b/third_party/rust/ron/docs/extensions.md
@@ -0,0 +1,116 @@
+## RON extensions
+
+RON has extensions that can be enabled by adding the following attribute at the top of your RON document:
+
+`#![enable(...)]`
+
+# unwrap_newtypes
+
+You can add this extension by adding the following attribute at the top of your RON document:
+
+`#![enable(unwrap_newtypes)]`
+
+This feature enables RON to automatically unwrap simple tuples.
+
+```rust
+struct NewType(u32);
+struct Object {
+    pub new_type: NewType,
+}
+```
+
+Without `unwrap_newtypes`, because the value `5` can not be saved into `NewType(u32)`, your RON document would look like this:
+
+``` ron
+(
+    new_type: (5),
+)
+```
+
+With the `unwrap_newtypes` extension, this coercion is done automatically. So `5` will be interpreted as `(5)`.
+
+``` ron
+#![enable(unwrap_newtypes)]
+(
+    new_type: 5,
+)
+```
+
+# implicit_some
+
+You can add this extension by adding the following attribute at the top of your RON document:
+
+`#![enable(implicit_some)]`
+
+This feature enables RON to automatically convert any value to `Some(value)` if the deserialized type requires it.
+
+```rust
+struct Object {
+    pub value: Option<u32>,
+}
+```
+
+Without this feature, you would have to write this RON document.
+
+```ron
+(
+    value: Some(5),
+)
+```
+
+Enabling the feature would automatically infer `Some(x)` if `x` is given. In this case, RON automatically casts this `5` into a `Some(5)`.
+
+```ron
+(
+    value: 5,
+)
+```
+
+With this extension enabled, explicitly given `None` and `Some(..)` will be matched eagerly on `Option<Option<Option<u32>>>`, i.e.
+* `5` -> `Some(Some(Some(5)))`
+* `None` -> `None`
+* `Some(5)` -> `Some(Some(Some(5)))`
+* `Some(None)` -> `Some(None)`
+* `Some(Some(5))` -> `Some(Some(Some(5)))`
+* `Some(Some(None))` -> `Some(Some(None))`
+* `Some(Some(Some(5)))` -> `Some(Some(Some(5)))`
+
+# unwrap_variant_newtypes
+
+You can add this extension by adding the following attribute at the top of your RON document:
+
+`#![enable(unwrap_variant_newtypes)]`
+
+This feature enables RON to automatically unwrap newtype enum variants.
+
+```rust
+#[derive(Deserialize)]
+struct Inner {
+    pub a: u8,
+    pub b: bool,
+}
+#[derive(Deserialize)]
+pub enum Enum {
+    A(Inner),
+    B,
+}
+```
+
+Without `unwrap_variant_newtypes`, your RON document would look like this:
+
+``` ron
+(
+    variant: A(Inner(a: 4, b: true)),
+)
+```
+
+With the `unwrap_variant_newtypes` extension, the first structural layer inside a newtype variant will be unwrapped automatically:
+
+``` ron
+#![enable(unwrap_newtypes)]
+(
+    variant: A(a: 4, b: true),
+)
+```
+
+Note that when the `unwrap_variant_newtypes` extension is enabled, the first layer inside a newtype variant will **always** be unwrapped, i.e. it is no longer possible to write `A(Inner(a: 4, b: true))` or `A((a: 4, b: true))`.
diff --git a/third_party/rust/ron/docs/grammar.md b/third_party/rust/ron/docs/grammar.md
new file mode 100644
index 0000000000..5c88107e76
--- /dev/null
+++ b/third_party/rust/ron/docs/grammar.md
@@ -0,0 +1,140 @@
+# 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 = [extensions], ws, value, ws;
+```
+
+## Whitespace and comments
+
+```ebnf
+ws = { ws_single | comment };
+ws_single = "\n" | "\t" | "\r" | " ";
+comment = ["//", { no_newline }, "\n"] | ["/*", { ? any character ? }, "*/"];
+```
+
+## 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
+value = unsigned | signed | float | string | char | bool | option | list | map | tuple | struct | enum_variant;
+```
+
+## Numbers
+
+```ebnf
+digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+hex_digit = "A" | "a" | "B" | "b" | "C" | "c" | "D" | "d" | "E" | "e" | "F" | "f";
+unsigned = (["0", ("b" | "o")], digit, { digit | '_' } |
+             "0x", (digit | hex_digit), { digit | hex_digit | '_' });
+signed = ["+" | "-"], unsigned;
+float = ["+" | "-"], ("inf" | "NaN" | float_num);
+float_num = (float_int | float_std | float_frac), [float_exp];
+float_int = digit, { digit };
+float_std = digit, { digit }, ".", {digit};
+float_frac = ".", digit, {digit};
+float_exp = ("e" | "E"), ["+" | "-"], digit, {digit};
+```
+
+## String
+
+```ebnf
+string = string_std | string_raw;
+string_std = "\"", { no_double_quotation_marks | string_escape }, "\"";
+string_escape = "\\", ("\"" | "\\" | "b" | "f" | "n" | "r" | "t" | ("u", unicode_hex));
+string_raw = "r" string_raw_content;
+string_raw_content = ("#", string_raw_content, "#") | "\"", { unicode_non_greedy }, "\"";
+```
+
+> 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
+
+## Char
+
+```ebnf
+char = "'", (no_apostrophe | "\\\\" | "\\'"), "'";
+```
+
+## Boolean
+
+```ebnf
+bool = "true" | "false";
+```
+
+## Optional
+
+```ebnf
+option = "None" | option_some;
+option_some = "Some", ws, "(", ws, value, ws, ")";
+```
+
+## 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
+struct = unit_struct | tuple_struct | named_struct;
+unit_struct = ident | "()";
+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]], ")";
+```