|
1 | 1 | //! Serde `Deserializer` module. |
2 | 2 | //! |
3 | | -//! Due to the complexity of the XML standard and the fact that serde was developed |
4 | | -//! with JSON in mind, not all serde concepts apply smoothly to XML. This leads to |
5 | | -//! that fact that some XML concepts are inexpressible in terms of serde derives |
| 3 | +//! Due to the complexity of the XML standard and the fact that Serde was developed |
| 4 | +//! with JSON in mind, not all Serde concepts apply smoothly to XML. This leads to |
| 5 | +//! that fact that some XML concepts are inexpressible in terms of Serde derives |
6 | 6 | //! and may require manual deserialization. |
7 | 7 | //! |
8 | 8 | //! The most notable restriction is the ability to distinguish between _elements_ |
|
49 | 49 | //! |
50 | 50 | //! <div style="background:rgba(120,145,255,0.45);padding:0.75em;"> |
51 | 51 | //! |
52 | | -//! NOTE: examples, marked with `FIXME:` does not work yet -- any PRs that fixes |
53 | | -//! that are welcome! The message after marker is a test failure message. |
54 | | -//! Also, all that tests are marked with an `ignore` option, although their |
55 | | -//! compiles. This is by intention, because rustdoc marks such blocks with |
56 | | -//! an information icon unlike `no_run` blocks. |
| 52 | +//! NOTE: All tests are marked with an `ignore` option, even though they do |
| 53 | +//! compile. This is because rustdoc marks such blocks with an information |
| 54 | +//! icon unlike `no_run` blocks. |
57 | 55 | //! |
58 | 56 | //! </div> |
59 | 57 | //! |
60 | 58 | //! <table> |
61 | 59 | //! <thead> |
62 | | -//! <tr><th>To parse all these XML's...</th><th>...use that Rust type(s)</th></tr> |
| 60 | +//! <tr><th>To parse all these XML's...</th><th>...use these Rust type(s)</th></tr> |
63 | 61 | //! </thead> |
64 | 62 | //! <tbody style="vertical-align:top;"> |
65 | 63 | //! <tr> |
|
262 | 260 | //! ``` |
263 | 261 | //! </td> |
264 | 262 | //! <td> |
265 | | -//! A structure where an each XML child element are mapped to the field. |
| 263 | +//! A structure where each XML child element is mapped to the field. |
266 | 264 | //! Each element name becomes a name of field. The name of the struct itself |
267 | 265 | //! does not matter: |
268 | 266 | //! |
|
364 | 362 | //! ## Optional attributes and elements |
365 | 363 | //! |
366 | 364 | //! </th></tr> |
367 | | -//! <tr><th>To parse all these XML's...</th><th>...use that Rust type(s)</th></tr> |
| 365 | +//! <tr><th>To parse all these XML's...</th><th>...use these Rust type(s)</th></tr> |
368 | 366 | //! <!-- 6 ===================================================================================== --> |
369 | 367 | //! <tr> |
370 | 368 | //! <td> |
|
458 | 456 | //! ## Choices (`xs:choice` XML Schema type) |
459 | 457 | //! |
460 | 458 | //! </th></tr> |
461 | | -//! <tr><th>To parse all these XML's...</th><th>...use that Rust type(s)</th></tr> |
| 459 | +//! <tr><th>To parse all these XML's...</th><th>...use these Rust type(s)</th></tr> |
462 | 460 | //! <!-- 8 ===================================================================================== --> |
463 | 461 | //! <tr> |
464 | 462 | //! <td> |
|
479 | 477 | //! </td> |
480 | 478 | //! <td> |
481 | 479 | //! |
482 | | -//! An enum where each variant have a name of the possible root tag. The name of |
| 480 | +//! An enum where each variant has the name of a possible root tag. The name of |
483 | 481 | //! the enum itself does not matter. |
484 | 482 | //! |
485 | | -//! If you need to get a textual content, mark a variant with `#[serde(rename = "$text")]`. |
| 483 | +//! If you need to get the textual content, mark a variant with `#[serde(rename = "$text")]`. |
486 | 484 | //! |
487 | 485 | //! All these structs can be used to deserialize from any XML on the |
488 | 486 | //! left side depending on amount of information that you want to get: |
|
840 | 838 | //! ## Sequences (`xs:all` and `xs:sequence` XML Schema types) |
841 | 839 | //! |
842 | 840 | //! </th></tr> |
843 | | -//! <tr><th>To parse all these XML's...</th><th>...use that Rust type(s)</th></tr> |
| 841 | +//! <tr><th>To parse all these XML's...</th><th>...use these Rust type(s)</th></tr> |
844 | 842 | //! <!-- 13 ==================================================================================== --> |
845 | 843 | //! <tr> |
846 | 844 | //! <td> |
|
864 | 862 | //! </td> |
865 | 863 | //! <td> |
866 | 864 | //! |
867 | | -//! A structure with a field which have a sequence type, for example, [`Vec`]. |
| 865 | +//! A structure with a field which is a sequence type, for example, [`Vec`]. |
868 | 866 | //! Because XML syntax does not distinguish between empty sequences and missed |
869 | 867 | //! elements, we should indicate that on the Rust side, because serde will require |
870 | 868 | //! that field `item` exists. You can do that in two possible ways: |
|
928 | 926 | //! <!-- 14 ==================================================================================== --> |
929 | 927 | //! <tr> |
930 | 928 | //! <td> |
931 | | -//! A sequence with a strict order, probably with a mixed content |
| 929 | +//! A sequence with a strict order, probably with mixed content |
932 | 930 | //! (text / CDATA and tags): |
933 | 931 | //! |
934 | 932 | //! ```xml |
|
1303 | 1301 | //! Composition Rules |
1304 | 1302 | //! ================= |
1305 | 1303 | //! |
1306 | | -//! XML format is very different from other formats supported by `serde`. |
| 1304 | +//! The XML format is very different from other formats supported by `serde`. |
1307 | 1305 | //! One such difference it is how data in the serialized form is related to |
1308 | 1306 | //! the Rust type. Usually each byte in the data can be associated only with |
1309 | 1307 | //! one field in the data structure. However, XML is an exception. |
|
1352 | 1350 | //! how you want to serialize certain constructs, which could be represented |
1353 | 1351 | //! through XML in multiple different ways. |
1354 | 1352 | //! |
1355 | | -//! The only difference in how complex types and sequences are serialized. |
| 1353 | +//! The only difference is in how complex types and sequences are serialized. |
1356 | 1354 | //! If you doubt which one you should select, begin with [`$value`](#value). |
1357 | 1355 | //! |
1358 | 1356 | //! ## `$text` |
|
1401 | 1399 | //! |
1402 | 1400 | //! NOTE: a name `#content` would better explain the purpose of that field, |
1403 | 1401 | //! but `$value` is used for compatibility with other XML serde crates, which |
1404 | | -//! uses that name. This allow you to switch XML crate more smoothly if required. |
| 1402 | +//! uses that name. This will allow you to switch XML crates more smoothly if required. |
1405 | 1403 | //! </div> |
1406 | 1404 | //! |
1407 | 1405 | //! Representation of primitive types in `$value` does not differ from their |
|
1500 | 1498 | //! |
1501 | 1499 | //! ### Structs and sequences of structs |
1502 | 1500 | //! |
1503 | | -//! Note, that structures does not have serializable name as well (name of the |
1504 | | -//! type are never used), so it is impossible to serialize non-unit struct or |
| 1501 | +//! Note, that structures do not have a serializable name as well (name of the |
| 1502 | +//! type is never used), so it is impossible to serialize non-unit struct or |
1505 | 1503 | //! sequence of non-unit structs in `$value` field. (sequences of) unit structs |
1506 | | -//! are serialized as empty string, although, because units itself serializing |
| 1504 | +//! are serialized as empty string, because units itself serializing |
1507 | 1505 | //! to nothing: |
1508 | 1506 | //! |
1509 | 1507 | //! ``` |
|
1721 | 1719 | //! </some-container> |
1722 | 1720 | //! ``` |
1723 | 1721 | //! |
1724 | | -//! After that you can find the correct solution, using the principles, explained |
| 1722 | +//! After that you can find the correct solution, using the principles explained |
1725 | 1723 | //! above. You should wrap `SomeEnum` into wrapper struct under the [`$text`](#text) |
1726 | 1724 | //! name: |
1727 | 1725 | //! ``` |
|
1749 | 1747 | //! ----------------------- |
1750 | 1748 | //! [Tagged enums] are currently not supported because of an issue in the Serde |
1751 | 1749 | //! design (see [serde#1183] and [quick-xml#586]) and missing optimizations in |
1752 | | -//! serde which could be useful for XML case ([serde#1495]). This can be worked |
| 1750 | +//! Serde which could be useful for XML parsing ([serde#1495]). This can be worked |
1753 | 1751 | //! around by manually implementing deserialize with `#[serde(deserialize_with = "func")]` |
1754 | 1752 | //! or implementing [`Deserialize`], but this can get very tedious very fast for |
1755 | | -//! files with large amounts of tagged enums. To help with this issue the quick-xml |
| 1753 | +//! files with large amounts of tagged enums. To help with this issue quick-xml |
1756 | 1754 | //! provides a macro [`impl_deserialize_for_internally_tagged_enum!`]. See the |
1757 | 1755 | //! macro documentation for details. |
1758 | 1756 | //! |
|
0 commit comments