Skip to content

Commit 40a06a1

Browse files
MingunMingun
committed
Replace chapter "Enum::Unit Variants As a Text" with "Enum Representations"
1 parent 478e19a commit 40a06a1

File tree

2 files changed

+96
-76
lines changed

2 files changed

+96
-76
lines changed

‎src/de/mod.rs‎

Lines changed: 57 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@
2020
//! - [Choices (`xs:choice` XML Schema type)](#choices-xschoice-xml-schema-type)
2121
//! - [Sequences (`xs:all` and `xs:sequence` XML Schema types)](#sequences-xsall-and-xssequence-xml-schema-types)
2222
//! - [Composition Rules](#composition-rules)
23+
//! - [Enum Representations](#enum-representations)
24+
//! - [Normal enum variant](#normal-enum-variant)
25+
//! - [`$text` enum variant](#text-enum-variant)
2326
//! - [Difference between `$text` and `$value` special names](#difference-between-text-and-value-special-names)
2427
//! - [`$text`](#text)
2528
//! - [`$value`](#value)
@@ -29,7 +32,6 @@
2932
//! - [Frequently Used Patterns](#frequently-used-patterns)
3033
//! - [`<element>` lists](#element-lists)
3134
//! - [Overlapped (Out-of-Order) Elements](#overlapped-out-of-order-elements)
32-
//! - [Enum::Unit Variants As a Text](#enumunit-variants-as-a-text)
3335
//! - [Internally Tagged Enums](#internally-tagged-enums)
3436
//!
3537
//!
@@ -1351,6 +1353,58 @@
13511353
//!
13521354
//!
13531355
//!
1356+
//! Enum Representations
1357+
//! ====================
1358+
//!
1359+
//! `quick-xml` represents enums differently in normal fields, `$text` fields and
1360+
//! `$value` fields. A normal representation is compatible with serde's adjacent
1361+
//! and internal tags feature -- tag for adjacently and internally tagged enums
1362+
//! are serialized using [`Serializer::serialize_unit_variant`] and deserialized
1363+
//! using [`Deserializer::deserialize_enum`].
1364+
//!
1365+
//! Use those simple rules to remember, how enum would be represented in XML:
1366+
//! - In `$value` field the representation is always the same as top-level representation;
1367+
//! - In `$text` field the representation is always the same as in normal field,
1368+
//! but surrounding tags with field name are removed;
1369+
//! - In normal field the representation is always contains a tag with a field name.
1370+
//!
1371+
//! Normal enum variant
1372+
//! -------------------
1373+
//!
1374+
//! To model an `xs:choice` XML construct use `$value` field.
1375+
//! To model a top-level `xs:choice` just use the enum type.
1376+
//!
1377+
//! |Kind |Top-level and in `$value` field |In normal field |In `$text` field |
1378+
//! |-------|-----------------------------------------|---------------------|---------------------|
1379+
//! |Unit |`<Unit/>` |`<field>Unit</field>`|`Unit` |
1380+
//! |Newtype|`<Newtype>42</Newtype>` |Err(Unsupported) |Err(Unsupported) |
1381+
//! |Tuple |`<Tuple>42</Tuple><Tuple>answer</Tuple>` |Err(Unsupported) |Err(Unsupported) |
1382+
//! |Struct |`<Struct><q>42</q><a>answer</a></Struct>`|Err(Unsupported) |Err(Unsupported) |
1383+
//!
1384+
//! `$text` enum variant
1385+
//! --------------------
1386+
//!
1387+
//! |Kind |Top-level and in `$value` field |In normal field |In `$text` field |
1388+
//! |-------|-----------------------------------------|---------------------|---------------------|
1389+
//! |Unit |_(empty)_ |`<field/>` |_(empty)_ |
1390+
//! |Newtype|`42` |Err(Unsupported) [^1]|Err(Unsupported) [^2]|
1391+
//! |Tuple |`42 answer` |Err(Unsupported) [^3]|Err(Unsupported) [^4]|
1392+
//! |Struct |Err(Unsupported) |Err(Unsupported) |Err(Unsupported) |
1393+
//!
1394+
//! [^1]: If this serialize as `<field>42</field>` then it will be ambiguity during deserialization,
1395+
//! because it clash with `Unit` representation in normal field.
1396+
//!
1397+
//! [^2]: If this serialize as `42` then it will be ambiguity during deserialization,
1398+
//! because it clash with `Unit` representation in `$text` field.
1399+
//!
1400+
//! [^3]: If this serialize as `<field>42 answer</field>` then it will be ambiguity during deserialization,
1401+
//! because it clash with `Unit` representation in normal field.
1402+
//!
1403+
//! [^4]: If this serialize as `42 answer` then it will be ambiguity during deserialization,
1404+
//! because it clash with `Unit` representation in `$text` field.
1405+
//!
1406+
//!
1407+
//!
13541408
//! Difference between `$text` and `$value` special names
13551409
//! =====================================================
13561410
//!
@@ -1733,75 +1787,6 @@
17331787
//! }
17341788
//! ```
17351789
//!
1736-
//! Enum::Unit Variants As a Text
1737-
//! -----------------------------
1738-
//! One frequent task and a typical mistake is to creation of mapping a text
1739-
//! content of some tag to a Rust `enum`. For example, for the XML:
1740-
//!
1741-
//! ```xml
1742-
//! <some-container>
1743-
//! <field>EnumValue</field>
1744-
//! </some-container>
1745-
//! ```
1746-
//! one could create an _incorrect_ mapping
1747-
//!
1748-
//! ```
1749-
//! # use serde::{Deserialize, Serialize};
1750-
//! #
1751-
//! #[derive(Serialize, Deserialize)]
1752-
//! enum SomeEnum {
1753-
//! EnumValue,
1754-
//! # /*
1755-
//! ...
1756-
//! # */
1757-
//! }
1758-
//!
1759-
//! #[derive(Serialize, Deserialize)]
1760-
//! #[serde(rename = "some-container")]
1761-
//! struct SomeContainer {
1762-
//! field: SomeEnum,
1763-
//! }
1764-
//! ```
1765-
//!
1766-
//! Actually, those types will be serialized into:
1767-
//! ```xml
1768-
//! <some-container>
1769-
//! <EnumValue/>
1770-
//! </some-container>
1771-
//! ```
1772-
//! and will not be able to be deserialized.
1773-
//!
1774-
//! You can easily see what's wrong if you think about attributes, which could
1775-
//! be defined in the `<field>` tag:
1776-
//! ```xml
1777-
//! <some-container>
1778-
//! <field some="attribute">EnumValue</field>
1779-
//! </some-container>
1780-
//! ```
1781-
//!
1782-
//! After that you can find the correct solution, using the principles explained
1783-
//! above. You should wrap `SomeEnum` into wrapper struct under the [`$text`](#text)
1784-
//! name:
1785-
//! ```
1786-
//! # use serde::{Serialize, Deserialize};
1787-
//! # type SomeEnum = ();
1788-
//! #[derive(Serialize, Deserialize)]
1789-
//! struct Field {
1790-
//! // Use a special name `$text` to map field to the text content
1791-
//! #[serde(rename = "$text")]
1792-
//! content: SomeEnum,
1793-
//! }
1794-
//!
1795-
//! #[derive(Serialize, Deserialize)]
1796-
//! #[serde(rename = "some-container")]
1797-
//! struct SomeContainer {
1798-
//! field: Field,
1799-
//! }
1800-
//! ```
1801-
//!
1802-
//! If you still want to keep your struct untouched, you can instead use the
1803-
//! helper module [`text_content`].
1804-
//!
18051790
//!
18061791
//! Internally Tagged Enums
18071792
//! -----------------------
@@ -1819,7 +1804,8 @@
18191804
//! [specification]: https://www.w3.org/TR/xmlschema11-1/#Simple_Type_Definition
18201805
//! [`deserialize_with`]: https://serde.rs/field-attrs.html#deserialize_with
18211806
//! [#497]: https://github.com/tafia/quick-xml/issues/497
1822-
//! [`text_content`]: crate::serde_helpers::text_content
1807+
//! [`Serializer::serialize_unit_variant`]: serde::Serializer::serialize_unit_variant
1808+
//! [`Deserializer::deserialize_enum`]: serde::Deserializer::deserialize_enum
18231809
//! [Tagged enums]: https://serde.rs/enum-representations.html#internally-tagged
18241810
//! [serde#1183]: https://github.com/serde-rs/serde/issues/1183
18251811
//! [serde#1495]: https://github.com/serde-rs/serde/issues/1495

‎src/serde_helpers.rs‎

Lines changed: 39 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -199,11 +199,6 @@ macro_rules! impl_deserialize_for_internally_tagged_enum {
199199
/// [`#[serde(with = "...")]`][with], [`#[serde(deserialize_with = "...")]`][de-with]
200200
/// and [`#[serde(serialize_with = "...")]`][se-with].
201201
///
202-
/// When you serialize unit variants of enums, they are serialized as an empty
203-
/// element, like `<Unit/>`. If your enum consist only of unit variants,
204-
/// it is frequently required to serialize them as string content of an
205-
/// element, like `<field>Unit</field>`. To make this possible use this module.
206-
///
207202
/// ```
208203
/// # use pretty_assertions::assert_eq;
209204
/// use quick_xml::de::from_str;
@@ -258,6 +253,45 @@ macro_rules! impl_deserialize_for_internally_tagged_enum {
258253
/// ```
259254
/// Read about the meaning of a special [`$text`] field.
260255
///
256+
/// In versions of quick-xml before 0.31.0 this module used to represent enum
257+
/// unit variants as `<field>EnumUnitVariant</field>` instead of `<EnumUnitVariant/>`.
258+
/// Since version 0.31.0 this is default representation of enums in normal fields,
259+
/// and `<EnumUnitVariant/>` requires `$value` field:
260+
///
261+
/// ```
262+
/// # use pretty_assertions::assert_eq;
263+
/// use quick_xml::de::from_str;
264+
/// use quick_xml::se::to_string;
265+
/// use serde::{Serialize, Deserialize};
266+
///
267+
/// #[derive(Serialize, Deserialize, PartialEq, Debug)]
268+
/// enum SomeEnum {
269+
/// // Default implementation serializes enum as an `<EnumValue/>` element
270+
/// EnumValue,
271+
/// # /*
272+
/// ...
273+
/// # */
274+
/// }
275+
///
276+
/// #[derive(Serialize, Deserialize, PartialEq, Debug)]
277+
/// #[serde(rename = "some-container")]
278+
/// struct SomeContainer {
279+
/// #[serde(rename = "$value")]
280+
/// field: SomeEnum,
281+
/// }
282+
///
283+
/// let container = SomeContainer {
284+
/// field: SomeEnum::EnumValue,
285+
/// };
286+
/// let xml = "\
287+
/// <some-container>\
288+
/// <EnumValue/>\
289+
/// </some-container>";
290+
///
291+
/// assert_eq!(to_string(&container).unwrap(), xml);
292+
/// assert_eq!(from_str::<SomeContainer>(xml).unwrap(), container);
293+
/// ```
294+
///
261295
/// [with]: https://serde.rs/field-attrs.html#with
262296
/// [de-with]: https://serde.rs/field-attrs.html#deserialize_with
263297
/// [se-with]: https://serde.rs/field-attrs.html#serialize_with

0 commit comments

Comments
 (0)