Skip to content

Commit 0c6eeb0

Browse files
authored
Merge pull request #490 from Mingun/ser
Rewrite serializer
2 parents 7c423ce + 8b50c64 commit 0c6eeb0

22 files changed

+7171
-1862
lines changed

Cargo.toml

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -179,11 +179,6 @@ name = "encodings"
179179
required-features = ["encoding"]
180180
path = "tests/encodings.rs"
181181

182-
[[test]]
183-
name = "serde_attrs"
184-
required-features = ["serialize"]
185-
path = "tests/serde_attrs.rs"
186-
187182
[[test]]
188183
name = "serde_roundtrip"
189184
required-features = ["serialize"]

Changelog.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,39 @@
1414

1515
### Bug Fixes
1616

17+
- [#490]: Ensure that serialization of map keys always produces valid XML names.
18+
In particular, that means that maps with numeric and numeric-like keys (for
19+
example, `"42"`) no longer can be serialized because [XML name] cannot start
20+
from a digit
21+
1722
### Misc Changes
1823

24+
- [#490]: Removed `$unflatten=` special prefix for fields for serde (de)serializer, because:
25+
- it is useless for deserializer
26+
- serializer was rewritten and does not require it anymore
27+
28+
This prefix allowed you to serialize struct field as an XML element and now
29+
replaced by a more thoughtful system explicitly indicating that a field should
30+
be serialized as an attribute by prepending `@` character to its name
31+
- [#490]: Removed `$primitive=` prefix. That prefix allowed you to serialize struct
32+
field as an attribute instead of an element and now replaced by a more thoughtful
33+
system explicitly indicating that a field should be serialized as an attribute
34+
by prepending `@` character to its name
35+
- [#490]: In addition to the `$value` special name for a field a new `$text`
36+
special name was added:
37+
- `$text` is used if you want to map field to text content only. No markup is
38+
expected (but text can represent a list as defined by `xs:list` type)
39+
- `$value` is used if you want to map elements with different names to one field,
40+
that should be represented either by an `enum`, or by sequence of `enum`s
41+
(`Vec`, tuple, etc.), or by string. Use it when you want to map field to any
42+
content of the field, text or markup
43+
44+
Refer to [documentation] for details.
45+
46+
[#490]: https://github.com/tafia/quick-xml/pull/490
47+
[XML name]: https://www.w3.org/TR/xml11/#NT-Name
48+
[documentation]: https://docs.rs/quick-xml/0.27.0/quick_xml/de/index.html#difference-between-text-and-value-special-names
49+
1950
## 0.26.0 -- 2022-10-23
2051

2152
### Misc Changes

README.md

Lines changed: 4 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -119,46 +119,18 @@ quick-xml follows its convention for deserialization, including the
119119

120120
### Parsing the "value" of a tag
121121

122-
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`:
122+
If you have an input of the form `<foo abc="xyz">bar</foo>`, and you want to get at the `bar`,
123+
you can use either the special name `$text`, or the special name `$value`:
123124

124125
```rust,ignore
125126
struct Foo {
126127
pub abc: String,
127-
#[serde(rename = "$value")]
128+
#[serde(rename = "$text")]
128129
pub body: String,
129130
}
130131
```
131132

132-
### Unflattening structs into verbose XML
133-
134-
If your XML files look like `<root><first>value</first><second>value</second></root>`, you can
135-
(de)serialize them with the special name prefix `$unflatten=`:
136-
137-
```rust,ignore
138-
struct Root {
139-
#[serde(rename = "$unflatten=first")]
140-
first: String,
141-
#[serde(rename = "$unflatten=second")]
142-
other_field: String,
143-
}
144-
```
145-
146-
### Serializing unit variants as primitives
147-
148-
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:
149-
150-
```rust,ignore
151-
enum Foo {
152-
#[serde(rename = "$primitive=Bar")]
153-
Bar
154-
}
155-
156-
struct Root {
157-
foo: Foo
158-
}
159-
```
160-
161-
Serializing `Root { foo: Foo::Bar }` will then yield `<Root foo="Bar"/>` instead of `<Root><Bar/></Root>`.
133+
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).
162134

163135
### Performance
164136

benches/microbenches.rs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ volutpat sed cras ornare arcu dui vivamus arcu. Cursus in hac habitasse platea d
2424
purus. Consequat id porta nibh venenatis cras sed felis.";
2525

2626
/// Benchmarks the `Reader::read_event` function with all XML well-formless
27-
/// checks disabled (with and without trimming content of #text nodes)
27+
/// checks disabled (with and without trimming content of $text nodes)
2828
fn read_event(c: &mut Criterion) {
2929
let mut group = c.benchmark_group("read_event");
3030
group.bench_function("trim_text = false", |b| {
@@ -70,7 +70,7 @@ fn read_event(c: &mut Criterion) {
7070
}
7171

7272
/// Benchmarks the `NsReader::read_resolved_event_into` function with all XML well-formless
73-
/// checks disabled (with and without trimming content of #text nodes)
73+
/// checks disabled (with and without trimming content of $text nodes)
7474
fn read_resolved_event_into(c: &mut Criterion) {
7575
let mut group = c.benchmark_group("NsReader::read_resolved_event_into");
7676
group.bench_function("trim_text = false", |b| {

0 commit comments

Comments
 (0)