Merge pull request #490 from Mingun/ser

Rewrite serializer

Author: Mingun

Cargo.toml

@@ -179,11 +179,6 @@ name = "encodings"
 required-features = ["encoding"]
 path = "tests/encodings.rs"
 
-[[test]]
-name = "serde_attrs"
-required-features = ["serialize"]
-path = "tests/serde_attrs.rs"
-
 [[test]]
 name = "serde_roundtrip"
 required-features = ["serialize"]

Changelog.md

@@ -14,8 +14,39 @@
 
 ### Bug Fixes
 
+- [#490]: Ensure that serialization of map keys always produces valid XML names.
+  In particular, that means that maps with numeric and numeric-like keys (for
+  example, `"42"`) no longer can be serialized because [XML name] cannot start
+  from a digit
+
 ### Misc Changes
 
+- [#490]: Removed `$unflatten=` special prefix for fields for serde (de)serializer, because:
+  - it is useless for deserializer
+  - serializer was rewritten and does not require it anymore
+
+  This prefix allowed you to serialize struct field as an XML element and now
+  replaced by a more thoughtful system explicitly indicating that a field should
+  be serialized as an attribute by prepending `@` character to its name
+- [#490]: Removed `$primitive=` prefix. That prefix allowed you to serialize struct
+  field as an attribute instead of an element and now replaced by a more thoughtful
+  system explicitly indicating that a field should be serialized as an attribute
+  by prepending `@` character to its name
+- [#490]: In addition to the `$value` special name for a field a new `$text`
+  special name was added:
+  - `$text` is used if you want to map field to text content only. No markup is
+    expected (but text can represent a list as defined by `xs:list` type)
+  - `$value` is used if you want to map elements with different names to one field,
+    that should be represented either by an `enum`, or by sequence of `enum`s
+    (`Vec`, tuple, etc.), or by string. Use it when you want to map field to any
+    content of the field, text or markup
+
+  Refer to [documentation] for details.
+
+[#490]: https://github.com/tafia/quick-xml/pull/490
+[XML name]: https://www.w3.org/TR/xml11/#NT-Name
+[documentation]: https://docs.rs/quick-xml/0.27.0/quick_xml/de/index.html#difference-between-text-and-value-special-names
+
 ## 0.26.0 -- 2022-10-23
 
 ### Misc Changes

README.md

@@ -119,46 +119,18 @@ quick-xml follows its convention for deserialization, including the
 
 ### Parsing the "value" of a tag
 
-If you have an input of the form `<foo abc="xyz">bar</foo>`, and you want to get at the `bar`, you can use the special name `$value`:
+If you have an input of the form `<foo abc="xyz">bar</foo>`, and you want to get at the `bar`,
+you can use either the special name `$text`, or the special name `$value`:
 
 ```rust,ignore
 struct Foo {
     pub abc: String,
-    #[serde(rename = "$value")]
+    #[serde(rename = "$text")]
     pub body: String,
 }
 ```
 
-### Unflattening structs into verbose XML
-
-If your XML files look like `<root><first>value</first><second>value</second></root>`, you can
-(de)serialize them with the special name prefix `$unflatten=`:
-
-```rust,ignore
-struct Root {
-    #[serde(rename = "$unflatten=first")]
-    first: String,
-    #[serde(rename = "$unflatten=second")]
-    other_field: String,
-}
-```
-
-### Serializing unit variants as primitives
-
-The `$primitive` prefix lets you serialize enum variants without associated values (internally referred to as _unit variants_) as primitive strings rather than self-closing tags. Consider the following definitions:
-
-```rust,ignore
-enum Foo {
-    #[serde(rename = "$primitive=Bar")]
-    Bar
-}
-
-struct Root {
-    foo: Foo
-}
-```
-
-Serializing `Root { foo: Foo::Bar }` will then yield `<Root foo="Bar"/>` instead of `<Root><Bar/></Root>`.
+Read about the difference in the [documentation](https://docs.rs/quick-xml/latest/quick_xml/de/index.html#difference-between-text-and-value-special-names).
 
 ### Performance
 

benches/microbenches.rs

@@ -24,7 +24,7 @@ volutpat sed cras ornare arcu dui vivamus arcu. Cursus in hac habitasse platea d
 purus. Consequat id porta nibh venenatis cras sed felis.";
 
 /// Benchmarks the `Reader::read_event` function with all XML well-formless
-/// checks disabled (with and without trimming content of #text nodes)
+/// checks disabled (with and without trimming content of $text nodes)
 fn read_event(c: &mut Criterion) {
     let mut group = c.benchmark_group("read_event");
     group.bench_function("trim_text = false", |b| {
@@ -70,7 +70,7 @@ fn read_event(c: &mut Criterion) {
 }
 
 /// Benchmarks the `NsReader::read_resolved_event_into` function with all XML well-formless
-/// checks disabled (with and without trimming content of #text nodes)
+/// checks disabled (with and without trimming content of $text nodes)
 fn read_resolved_event_into(c: &mut Criterion) {
     let mut group = c.benchmark_group("NsReader::read_resolved_event_into");
     group.bench_function("trim_text = false", |b| {