Untagged and internally tagged enums

[dtolnay]

Fixes #415 and fixes serde-rs/json#67.

The attribute for untagged enums is:

#[derive(Serialize, Deserialize)]
#[serde(untagged)]
enum E {
    /* variants */
}

During serialization, the variant is serialized as though it were not part of an enum. Struct variants are serialized as structs, tuple variants are serialized as tuples, unit variants are serialized as unit, and newtype variants are serialized as the value.

During deserialization, we buffer the content of the Deserializer and try it against each variant in order, returning the first one that deserializes successfully from that content.

The attribute for internally tagged enums is:

#[derive(Serialize, Deserialize)]
#[serde(tag = "type")]
enum E {
    /* variants */
}

The enum must contain only unit, newtype and struct variants. Tuple variants are not supported. During serialization unit variants are serialized as structs with a single field: {"type": "T"}, struct variants are serialized with "type": "T" inserted as the first field, and newtype variants must contain either a struct or a map and are serialized with "type": "T" inserted as the first field.

During deserialization, we buffer the content of the Deserializer, pull out the tag, and deserialize the rest of the content against the correct variant.

The use case from #415 looks like:

#[derive(Serialize, Deserialize, Debug)]
#[serde(tag = "type")]
enum Motion {
    Column { content: i32 },
    Line { content: i32 },
}

#[derive(Serialize, Deserialize, Debug)]
#[serde(tag = "type")]
enum Command {
    Move { content: Motion },
    Delete { content: Motion },
    Input { content: String },
}

And the use case from serde-rs/json#67 looks like:

#[derive(Serialize, Deserialize, Debug)]
#[serde(tag = "type")]
enum Message {
    #[serde(rename = "ok")]
    Ok { response: Response },
    #[serde(rename = "error")]
    Error { message: String },
}

cc @sfackler who asked about this in IRC and @alexcrichton who is removing this functionality from toml.

[alexcrichton]

Awesome, thanks @dtolnay!

[sfackler]

Yay!

[sfackler]

Out of curiosity, why is Content not public API?

[dtolnay]

I would prefer to be able to iterate on the implementation for a few releases and only have to think about backward compatibility for the attributes rather than the entire mechanism. This is quite a large PR and I think we can reach consensus on the attributes and the semantics significantly sooner than we could reach consensus on the entire Content API. The focus of this PR should be whether these two attributes solve the right problem in the right way, and not on designing a large API that we feel comfortable supporting for the rest of the year.

Once this merges I will file a ticket to follow up on polishing and exposing some of the pieces.

[sfackler]

Cool, sounds good.

[oli-obk]

cool! yes let's delay iterating on the exact structures later.

Implementation looks good to me.

[oli-obk]

hide the entire module with ![doc(hidden)] or at least write a doc comment stating that nothing in this module should be used outside of generated code. The PR comments contains all of that already, maybe just place them here?

[dtolnay]

I added a comment in 066c9a1 and filed #741 to follow up on making it public.

[oli-obk]

We could find some way to support other formats through some rewinding API. This would also have uses for streaming.

[dtolnay]

I filed #742 to follow up on this.