1# Make a struct or enum parseable from XML
 2
 3This derives the [`FromXml`] trait on a struct or enum. It is the counterpart
 4to [`macro@IntoXml`].
 5
 6## Example
 7
 8```rust
 9# use xso::FromXml;
10#[derive(FromXml, Debug, PartialEq)]
11#[xml(namespace = "urn:example", name = "foo")]
12struct Foo;
13
14let foo: Foo = xso::from_bytes(b"<foo xmlns='urn:example'/>").unwrap();
15assert_eq!(foo, Foo);
16```
17
18## Attributes
19
20The derive macros need to know which XML namespace and name the elements it
21is supposed have. This must be specified via key-value pairs on the type the
22derive macro is invoked on. These are specified as Rust attributes. In order
23to disambiguate between XML attributes and Rust attributes, we are going to
24refer to Rust attributes using the term *meta* instead, which is consistent
25with the Rust language reference calling that syntax construct *meta*.
26
27All key-value pairs interpreted by these derive macros must be wrapped in a
28`#[xml( ... )]` *meta*. The following keys are defined on structs:
29
30| Key | Value type | Description |
31| --- | --- | --- |
32| `namespace` | *string literal* or *path* | The XML element namespace to match. If it is a *path*, it must point at a `&'static str`. |
33| `name` | *string literal* or *path* | The XML element name to match. If it is a *path*, it must point at a `&'static NcNameStr`. |
34
35Note that the `name` value must be a valid XML element name, without colons.
36The namespace prefix, if any, is assigned automatically at serialisation time
37and cannot be overridden. The following will thus not compile:
38
39```compile_fail
40# use xso::FromXml;
41#[derive(FromXml, Debug, PartialEq)]
42#[xml(namespace = "urn:example", name = "fnord:foo")]  // colon not allowed
43struct Foo;
44```
45
46## Limitations
47
48Supports only empty structs currently. For example, the following will not
49work:
50
51```compile_fail
52# use xso::FromXml;
53#[derive(FromXml, Debug, PartialEq)]
54#[xml(namespace = "urn:example", name = "foo")]
55struct Foo {
56    some_field: String,
57}
58```