Release 0.8.3

Re-enable clippy

.travis.yml

@@ -29,9 +29,7 @@ script:
 - (cd examples/serde-syntex-example && travis-cargo --only nightly run -- --no-default-features --features unstable)
 - (cd serde && travis-cargo --only stable doc)
 after_success:
-- (cd serde && travis-cargo --only stable doc-upload --branch docs)
 - (cd testing && travis-cargo --only stable coveralls --no-sudo)
 env:
   global:
   - TRAVIS_CARGO_NIGHTLY_FEATURE=""
-  - secure: Jcd11Jy0xLyacBUB+oKOaxKBm9iZNInenRDtNBY8GKOtqF5fHUfEjgDf538hwRl5L0FP7DLr8oK0IHmzA7lPjJxlzoKVKV3IM7bRZEYzW5DMonf/lcliuGte7SH0NVFhifM87T8HI2hjGdAb+7+m34siBR7M3AY/XjLInrvUFvY=

README.md

@@ -1,214 +1,21 @@
-Serde Rust Serialization Framework
-==================================
+# Serde   [![Build Status](https://api.travis-ci.org/serde-rs/serde.svg?branch=master)](https://travis-ci.org/serde-rs/serde) [![Coverage Status](https://coveralls.io/repos/serde-rs/serde/badge.svg?branch=master&service=github)](https://coveralls.io/github/serde-rs/serde?branch=master) [![Latest Version](https://img.shields.io/crates/v/serde.svg)](https://crates.io/crates/serde) [![Clippy Linting Result](https://clippy.bashy.io/github/serde-rs/serde/master/badge.svg)](https://clippy.bashy.io/github/serde-rs/serde/master/log)
 
-[![Build Status](https://api.travis-ci.org/serde-rs/serde.svg?branch=master)](https://travis-ci.org/serde-rs/serde)
-[![Coverage Status](https://coveralls.io/repos/serde-rs/serde/badge.svg?branch=master&service=github)](https://coveralls.io/github/serde-rs/serde?branch=master)
-[![Latest Version](https://img.shields.io/crates/v/serde.svg)](https://crates.io/crates/serde)
-[![Clippy Linting Result](https://clippy.bashy.io/github/serde-rs/serde/master/badge.svg)](https://clippy.bashy.io/github/serde-rs/serde/master/log)
+**Serde is a framework for *ser*ializing and *de*serializing Rust data structures efficiently and generically.**
 
-Serde is a powerful framework that enables serialization libraries to
-generically serialize Rust data structures without the overhead of runtime type
-information. In many situations, the handshake protocol between serializers and
-serializees can be completely optimized away, leaving Serde to perform roughly
-the same speed as a hand written serializer for a specific type.
+---
 
-[Documentation](https://serde-rs.github.io/serde/serde/index.html)
+You may be looking for:
 
-Simple Serde Example
-====================
+- [An overview of Serde](https://serde.rs/)
+- [Data formats supported by Serde](https://serde.rs/#data-formats)
+- [Setting up `#[derive(Serialize, Deserialize)]`](https://serde.rs/codegen.html)
+- [Examples](https://serde.rs/examples.html)
+- [API documentation](https://docs.serde.rs/serde/)
 
-Here is a simple example that uses
-[serde_json](https://github.com/serde-rs/json), which uses Serde under the
-covers, to generate and parse JSON. First, lets start off with the `Cargo.toml`
-file:
-
-```toml
-[package]
-name = "serde_example"
-version = "0.1.0"
-authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
-
-[dependencies]
-serde_json = "0.8"
-```
-
-Next, the `src/main.rs` file itself:
-
-```rust,ignore
-extern crate serde_json;
-
-use std::collections::HashMap;
-use serde_json::Value;
-use serde_json::builder::{ArrayBuilder, ObjectBuilder};
-
-fn main() {
-    // Serde has support for many of the builtin Rust types, like arrays..:
-    let v = vec![1, 2];
-    let serialized = serde_json::to_string(&v).unwrap();
-    println!("serialized vec: {:?}", serialized);
-
-    let deserialized: Vec<u32> = serde_json::from_str(&serialized).unwrap();
-    println!("deserialized vec: {:?}", deserialized);
-
-    // ... and maps:
-    let mut map = HashMap::new();
-    map.insert("x".to_string(), 1);
-    map.insert("y".to_string(), 2);
-
-    let serialized = serde_json::to_string(&map).unwrap();
-    println!("serialized map: {:?}", serialized);
-
-    let deserialized: HashMap<String, u32> = serde_json::from_str(&serialized).unwrap();
-    println!("deserialized map: {:?}", deserialized);
-
-    // It also can handle complex objects:
-    let value = ObjectBuilder::new()
-        .insert("int", 1)
-        .insert("string", "a string")
-        .insert("array", ArrayBuilder::new()
-                .push(1)
-                .push(2)
-                .build())
-        .build();
-
-    let serialized = serde_json::to_string(&value).unwrap();
-    println!("serialized value: {:?}", serialized);
-
-    let deserialized: serde_json::Value = serde_json::from_str(&serialized).unwrap();
-    println!("deserialized value: {:?}", deserialized);
-}
-```
-
-This produces the following output when run:
-
-```sh
-% cargo run
-serialized vec: "[1,2]"
-deserialized vec: [1, 2]
-serialized map: "{\"y\":2,\"x\":1}"
-deserialized map: {"y": 2, "x": 1}
-serialized value: "{\"array\":[1,2],\"int\":1,\"string\":\"a string\"}"
-deserialized value: {"array":[1,2],"int":1,"string":"a string"}
-```
-
-Using Serde with Stable Rust and serde\_codegen
-===============================================
-
-The example before used `serde_json::Value` as the in-memory representation of
-the JSON value, but it's also possible for Serde to serialize to and from
-regular Rust types. However, the code to do this can be a bit complicated to
-write. So instead, Serde also has some powerful code generation libraries that
-work with Stable and Nightly Rust that eliminate much of the complexity of hand
-rolling serialization and deserialization for a given type.
-
-First lets see how we would use Stable Rust, which is currently a tad more
-complicated than Nightly Rust due to having to work around compiler plugins
-being unstable.  We will use `serde_codegen` which is based on the code
-generation library [syntex](https://github.com/serde-rs/syntex). First we need
-to setup the `Cargo.toml` that builds the project:
-
-```toml
-[package]
-name = "serde_example"
-version = "0.1.0"
-authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
-build = "build.rs"
-
-[build-dependencies]
-serde_codegen = "0.8"
-
-[dependencies]
-serde = "0.8"
-serde_json = "0.8"
-```
-
-Next, we define our source file, `src/main.rs.in`. Note this is a different
-extension than usual because we need to do code generation:
-
-```rust,ignore
-#[derive(Serialize, Deserialize, Debug)]
-struct Point {
-    x: i32,
-    y: i32,
-}
-
-fn main() {
-    let point = Point { x: 1, y: 2 };
-
-    let serialized = serde_json::to_string(&point).unwrap();
-    println!("{}", serialized);
-
-    let deserialized: Point = serde_json::from_str(&serialized).unwrap();
-    println!("{:?}", deserialized);
-}
-```
-
-To finish up the main source code, we define a very simple `src/main.rs` that
-uses the generated code.
-
-`src/main.rs`:
-
-```rust,ignore
-extern crate serde;
-extern crate serde_json;
-
-include!(concat!(env!("OUT_DIR"), "/main.rs"));
-```
-
-The last step is to actually drive the code generation, with the `build.rs` script:
-
-```rust,ignore
-extern crate serde_codegen;
-
-use std::env;
-use std::path::Path;
-
-pub fn main() {
-    let out_dir = env::var_os("OUT_DIR").unwrap();
-
-    let src = Path::new("src/main.rs.in");
-    let dst = Path::new(&out_dir).join("main.rs");
-
-    serde_codegen::expand(&src, &dst).unwrap();
-}
-```
-
-All this produces this when run:
-
-```sh
-% cargo run
-{"x":1,"y":2}
-Point { x: 1, y: 2 }
-```
-
-While this works well with Stable Rust, be aware that the error locations
-currently are reported in the generated file instead of in the source file.
-
-Using Serde with Nightly Rust and serde\_macros
-===============================================
-
-The prior example is a bit more complicated than it needs to be due to compiler
-plugins being unstable. However, if you are already using Nightly Rust, you can
-use `serde_macros`, which has a much simpler interface. First, here is the new
-`Cargo.toml`:
-
-```toml
-[package]
-name = "serde_example_nightly"
-version = "0.1.0"
-authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
-
-[dependencies]
-serde = "0.8"
-serde_json = "0.8"
-serde_macros = "0.8"
-```
-
-Note that it doesn't need a build script. Now the `src/main.rs`, which enables
-the plugin feature, and registers the `serde_macros` plugin:
+## Serde in action
 
 ```rust
-#![feature(custom_derive, plugin)]
+#![feature(plugin, custom_derive)]
 #![plugin(serde_macros)]
 
 extern crate serde_json;
@@ -222,539 +29,41 @@ struct Point {
 fn main() {
     let point = Point { x: 1, y: 2 };
 
-    let serialized = serde_json::to_string(&point).unwrap();
-    println!("{}", serialized);
-
-    let deserialized: Point = serde_json::from_str(&serialized).unwrap();
-    println!("{:?}", deserialized);
-}
-```
-
-This also produces the same output:
-
-```sh
-% cargo run
-{"x":1,"y":2}
-Point { x: 1, y: 2 }
-```
-
-You may find it easier to develop with Nightly Rust and `serde\_macros`, then
-deploy with Stable Rust and `serde_codegen`. It's possible to combine both
-approaches in one setup:
-
-`Cargo.toml`:
-
-```toml
-[package]
-name = "serde_example"
-version = "0.1.0"
-authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
-build = "build.rs"
-
-[features]
-default = ["serde_codegen"]
-nightly = ["serde_macros"]
-
-[build-dependencies]
-serde_codegen = { version = "0.8", optional = true }
-
-[dependencies]
-serde = "0.8"
-serde_json = "0.8"
-serde_macros = { version = "0.8", optional = true }
-```
-
-`build.rs`:
-
-```rust,ignore
-#[cfg(not(feature = "serde_macros"))]
-mod inner {
-    extern crate serde_codegen;
-
-    use std::env;
-    use std::path::Path;
-
-    pub fn main() {
-        let out_dir = env::var_os("OUT_DIR").unwrap();
-
-        let src = Path::new("src/main.rs.in");
-        let dst = Path::new(&out_dir).join("main.rs");
-
-        serde_codegen::expand(&src, &dst).unwrap();
-    }
-}
-
-#[cfg(feature = "serde_macros")]
-mod inner {
-    pub fn main() {}
-}
-
-fn main() {
-    inner::main();
-}
-```
-
-`src/main.rs`:
-
-```rust,ignore
-#![cfg_attr(feature = "serde_macros", feature(custom_derive, plugin))]
-#![cfg_attr(feature = "serde_macros", plugin(serde_macros))]
-
-extern crate serde;
-extern crate serde_json;
-
-#[cfg(feature = "serde_macros")]
-include!("main.rs.in");
-
-#[cfg(not(feature = "serde_macros"))]
-include!(concat!(env!("OUT_DIR"), "/main.rs"));
-```
-
-The `src/main.rs.in` is the same as before.
-
-Then to run with stable:
-
-```sh
-% cargo build
-...
-```
-
-Or with nightly:
-
-```sh
-% cargo build --features nightly --no-default-features
-...
-```
-
-Serialization without Macros
-============================
-
-Under the covers, Serde extensively uses the Visitor pattern to thread state
-between the
-[Serializer](http://serde-rs.github.io/serde/serde/serde/ser/trait.Serializer.html)
-and
-[Serialize](http://serde-rs.github.io/serde/serde/serde/ser/trait.Serialize.html)
-without the two having specific information about each other's concrete type.
-This has many of the same benefits as frameworks that use runtime type
-information without the overhead.  In fact, when compiling with optimizations,
-Rust is able to remove most or all the visitor state, and generate code that's
-nearly as fast as a hand written serializer format for a specific type.
-
-To see it in action, lets look at how a simple type like `i32` is serialized.
-The
-[Serializer](http://serde-rs.github.io/serde/serde/serde/ser/trait.Serializer.html)
-is threaded through the type:
-
-```rust,ignore
-impl serde::Serialize for i32 {
-    fn serialize<S>(&self, serializer: &mut S) -> Result<(), S::Error>
-        where S: serde::Serializer,
-    {
-        serializer.serialize_i32(*self)
-    }
-}
-```
-
-As you can see it's pretty simple. More complex types like `BTreeMap` need to
-use a multi-step process (init, elements, end) in order to walk through the
-type:
-
-```rust,ignore
-impl<K, V> Serialize for BTreeMap<K, V>
-    where K: Serialize + Ord,
-          V: Serialize,
-{
-    #[inline]
-    fn serialize<S>(&self, serializer: &mut S) -> Result<(), S::Error>
-        where S: Serializer,
-    {
-        let mut state = try!(serializer.serialize_map(Some(self.len())));
-        for (k, v) in self {
-            try!(serializer.serialize_map_elt(&mut state, k, v));
-        }
-        serializer.serialize_map_end(state)
-    }
-}
-```
-
-Serializing structs follow this same pattern. In fact, structs are represented
-as a named map, with a known length.
-
-```rust
-extern crate serde;
-extern crate serde_json;
-
-struct Point {
-    x: i32,
-    y: i32,
-}
-
-impl serde::Serialize for Point {
-    fn serialize<S>(&self, serializer: &mut S) -> Result<(), S::Error>
-        where S: serde::Serializer
-    {
-        let mut state = try!(serializer.serialize_struct("Point", 2));
-        try!(serializer.serialize_struct_elt(&mut state, "x", &self.x));
-        try!(serializer.serialize_struct_elt(&mut state, "y", &self.y));
-        serializer.serialize_struct_end(state)
-    }
-}
-
-fn main() {
-    let point = Point { x: 1, y: 2 };
+    // Convert the Point to a JSON string.
     let serialized = serde_json::to_string(&point).unwrap();
 
-    println!("{}", serialized);
-}
-```
-
-Deserialization without Macros
-==============================
-
-Deserialization is a little more complicated since there's a bit more error
-handling that needs to occur. Let's start with the simple `i32`
-[Deserialize](http://serde-rs.github.io/serde/serde/serde/de/trait.Deserialize.html)
-implementation. It passes a
-[Visitor](http://serde-rs.github.io/serde/serde/serde/de/trait.Visitor.html) to the
-[Deserializer](http://serde-rs.github.io/serde/serde/serde/de/trait.Deserializer.html).
-The [Visitor](http://serde-rs.github.io/serde/serde/serde/de/trait.Visitor.html)
-can create the `i32` from a variety of different types:
-
-```rust,ignore
-impl Deserialize for i32 {
-    fn deserialize<D>(deserializer: &mut D) -> Result<i32, D::Error>
-        where D: serde::Deserializer,
-    {
-        deserializer.deserialize(I32Visitor)
-    }
-}
-
-struct I32Visitor;
-
-impl serde::de::Visitor for I32Visitor {
-    type Value = i32;
-
-    fn visit_i16<E>(&mut self, value: i16) -> Result<i32, E>
-        where E: Error,
-    {
-        self.visit_i32(value as i32)
-    }
-
-    fn visit_i32<E>(&mut self, value: i32) -> Result<i32, E>
-        where E: Error,
-    {
-        Ok(value)
-    }
-
-    ...
-
-```
-
-Since it's possible for this type to get passed an unexpected type, we need a
-way to error out. This is done by way of the
-[Error](http://serde-rs.github.io/serde/serde/serde/de/trait.Error.html) trait,
-which allows a
-[Deserialize](http://serde-rs.github.io/serde/serde/serde/de/trait.Deserialize.html)
-to generate an error for a few common error conditions. Here's how it could be used:
-
-```rust,ignore
-    ...
-
-    fn visit_string<E>(&mut self, _: String) -> Result<i32, E>
-        where E: Error,
-    {
-        Err(serde::de::Error::custom("expect a string"))
-    }
-
-    ...
-
-```
-
-Maps follow a similar pattern as before, and use a
-[MapVisitor](http://serde-rs.github.io/serde/serde/serde/de/trait.MapVisitor.html)
-to walk through the values generated by the
-[Deserializer](http://serde-rs.github.io/serde/serde/serde/de/trait.Deserializer.html).
-
-```rust,ignore
-impl<K, V> serde::Deserialize for BTreeMap<K, V>
-    where K: serde::Deserialize + Eq + Ord,
-          V: serde::Deserialize,
-{
-    fn deserialize<D>(deserializer: &mut D) -> Result<BTreeMap<K, V>, D::Error>
-        where D: serde::Deserializer,
-    {
-        deserializer.deserialize(BTreeMapVisitor::new())
-    }
-}
-
-pub struct BTreeMapVisitor<K, V> {
-    marker: PhantomData<BTreeMap<K, V>>,
-}
-
-impl<K, V> BTreeMapVisitor<K, V> {
-    pub fn new() -> Self {
-        BTreeMapVisitor {
-            marker: PhantomData,
-        }
-    }
-}
-
-impl<K, V> serde::de::Visitor for BTreeMapVisitor<K, V>
-    where K: serde::de::Deserialize + Ord,
-          V: serde::de::Deserialize
-{
-    type Value = BTreeMap<K, V>;
-
-    fn visit_unit<E>(&mut self) -> Result<BTreeMap<K, V>, E>
-        where E: Error,
-    {
-        Ok(BTreeMap::new())
-    }
-
-    fn visit_map<V_>(&mut self, mut visitor: V_) -> Result<BTreeMap<K, V>, V_::Error>
-        where V_: MapVisitor,
-    {
-        let mut values = BTreeMap::new();
-
-        while let Some((key, value)) = try!(visitor.visit()) {
-            values.insert(key, value);
-        }
-
-        try!(visitor.end());
-
-        Ok(values)
-    }
-}
-```
-
-Deserializing structs goes a step further in order to support not allocating a
-`String` to hold the field names. This is done by custom field enum that
-deserializes an enum variant from a string. So for our `Point` example from
-before, we need to generate:
-
-```rust
-extern crate serde;
-extern crate serde_json;
-
-#[derive(Debug)]
-struct Point {
-    x: i32,
-    y: i32,
-}
-
-enum PointField {
-    X,
-    Y,
-}
-
-impl serde::Deserialize for PointField {
-    fn deserialize<D>(deserializer: &mut D) -> Result<PointField, D::Error>
-        where D: serde::de::Deserializer
-    {
-        struct PointFieldVisitor;
-
-        impl serde::de::Visitor for PointFieldVisitor {
-            type Value = PointField;
-
-            fn visit_str<E>(&mut self, value: &str) -> Result<PointField, E>
-                where E: serde::de::Error
-            {
-                match value {
-                    "x" => Ok(PointField::X),
-                    "y" => Ok(PointField::Y),
-                    _ => Err(serde::de::Error::custom("expected x or y")),
-                }
-            }
-        }
-
-        deserializer.deserialize(PointFieldVisitor)
-    }
-}
-
-impl serde::Deserialize for Point {
-    fn deserialize<D>(deserializer: &mut D) -> Result<Point, D::Error>
-        where D: serde::de::Deserializer
-    {
-        static FIELDS: &'static [&'static str] = &["x", "y"];
-        deserializer.deserialize_struct("Point", FIELDS, PointVisitor)
-    }
-}
-
-struct PointVisitor;
-
-impl serde::de::Visitor for PointVisitor {
-    type Value = Point;
-
-    fn visit_map<V>(&mut self, mut visitor: V) -> Result<Point, V::Error>
-        where V: serde::de::MapVisitor
-    {
-        let mut x = None;
-        let mut y = None;
-
-        loop {
-            match try!(visitor.visit_key()) {
-                Some(PointField::X) => { x = Some(try!(visitor.visit_value())); }
-                Some(PointField::Y) => { y = Some(try!(visitor.visit_value())); }
-                None => { break; }
-            }
-        }
-
-        let x = match x {
-            Some(x) => x,
-            None => try!(visitor.missing_field("x")),
-        };
-
-        let y = match y {
-            Some(y) => y,
-            None => try!(visitor.missing_field("y")),
-        };
-
-        try!(visitor.end());
-
-        Ok(Point{ x: x, y: y })
-    }
-}
-
-
-fn main() {
-    let serialized = "{\"x\":1,\"y\":2}";
+    // Prints serialized = {"x":1,"y":2}
+    println!("serialized = {}", serialized);
 
+    // Convert the JSON string back to a Point.
     let deserialized: Point = serde_json::from_str(&serialized).unwrap();
 
-    println!("{:?}", deserialized);
+    // Prints deserialized = Point { x: 1, y: 2 }
+    println!("deserialized = {:?}", deserialized);
 }
 ```
 
-Design Considerations and tradeoffs for Serializers and Deserializers
-=====================================================================
+## Getting help
 
-Serde serialization and deserialization implementations are written in such a
-way that they err on being able to represent more values, and also provide
-better error messages when they are passed an incorrect type to deserialize
-from. For example, by default, it is a syntax error to deserialize a `String`
-into an `Option<String>`. This is implemented such that it is possible to
-distinguish between the values `None` and `Some(())`, if the serialization
-format supports option types.
+Serde developers live in the #serde channel on
+[`irc.mozilla.org`](https://wiki.mozilla.org/IRC). The #rust channel is also a
+good resource with generally faster response time but less specific knowledge
+about Serde. If IRC is not your thing, we are happy to respond to [GitHub
+issues](https://github.com/serde-rs/serde/issues/new) as well.
 
-However, many formats do not have option types, and represents optional values
-as either a `null`, or some other value. Serde `Serializer`s and
-`Deserializer`s can opt-in support for this. For serialization, this is pretty
-easy. Simply implement these methods:
+## License
 
-```rust,ignore
-...
+Serde is licensed under either of
 
-    fn visit_none(&mut self) -> Result<(), Self::Error> {
-        self.visit_unit()
-    }
+ * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
+   http://www.apache.org/licenses/LICENSE-2.0)
+ * MIT license ([LICENSE-MIT](LICENSE-MIT) or
+   http://opensource.org/licenses/MIT)
 
-    fn visit_some<T>(&mut self, value: T) -> Result<(), Self::Error> {
-        value.serialize(self)
-    }
-...
-```
+at your option.
 
-For deserialization, this can be implemented by way of the
-`Deserializer::visit_option` hook, which presumes that there is some ability to peek at what is the
-next value in the serialized token stream. This following example is from
-[serde_tests::TokenDeserializer](https://github.com/serde-rs/serde/blob/master/serde_tests/tests/token.rs#L435-L454),
-where it checks to see if the next value is an `Option`, a `()`, or some other
-value:
+### Contribution
 
-```rust,ignore
-...
-
-    fn visit_option<V>(&mut self, mut visitor: V) -> Result<V::Value, Error>
-        where V: de::Visitor,
-    {
-        match self.tokens.peek() {
-            Some(&Token::Option(false)) => {
-                self.tokens.next();
-                visitor.visit_none()
-            }
-            Some(&Token::Option(true)) => {
-                self.tokens.next();
-                visitor.visit_some(self)
-            }
-            Some(&Token::Unit) => {
-                self.tokens.next();
-                visitor.visit_none()
-            }
-            Some(_) => visitor.visit_some(self),
-            None => Err(Error::EndOfStreamError),
-        }
-    }
-
-...
-```
-
-Annotations
-===========
-
-`serde_codegen` and `serde_macros` support annotations that help to customize
-how types are serialized. Here are the supported annotations:
-
-Container Annotations:
-
-| Annotation                                  | Function                                                                                                                                           |
-| ----------                                  | --------                                                                                                                                           |
-| `#[serde(rename="name")]`                   | Serialize and deserialize this container with the given name                                                                                       |
-| `#[serde(rename(serialize="name1"))]`       | Serialize this container with the given name                                                                                                       |
-| `#[serde(rename(deserialize="name1"))]`     | Deserialize this container with the given name                                                                                                     |
-| `#[serde(deny_unknown_fields)]`             | Always error during serialization when encountering unknown fields. When absent, unknown fields are ignored for self-describing formats like JSON. |
-| `#[serde(bound="T: MyTrait")]`              | Where-clause for the Serialize and Deserialize impls. This replaces any bounds inferred by Serde.                                                  |
-| `#[serde(bound(serialize="T: MyTrait"))]`   | Where-clause for the Serialize impl.                                                                                                               |
-| `#[serde(bound(deserialize="T: MyTrait"))]` | Where-clause for the Deserialize impl.                                                                                                             |
-
-Variant Annotations:
-
-| Annotation                              | Function                                                   |
-| ----------                              | --------                                                   |
-| `#[serde(rename="name")]`               | Serialize and deserialize this variant with the given name |
-| `#[serde(rename(serialize="name1"))]`   | Serialize this variant with the given name                 |
-| `#[serde(rename(deserialize="name1"))]` | Deserialize this variant with the given name               |
-
-Field Annotations:
-
-| Annotation                                  | Function                                                                                                                |
-| ----------                                  | --------                                                                                                                |
-| `#[serde(rename="name")]`                   | Serialize and deserialize this field with the given name                                                                |
-| `#[serde(rename(serialize="name1"))]`       | Serialize this field with the given name                                                                                |
-| `#[serde(rename(deserialize="name1"))]`     | Deserialize this field with the given name                                                                              |
-| `#[serde(default)]`                         | If the value is not specified, use the `Default::default()`                                                             |
-| `#[serde(default="$path")]`                 | Call the path to a function `fn() -> T` to build the value                                                              |
-| `#[serde(skip_serializing)]`                | Do not serialize this value                                                                                             |
-| `#[serde(skip_deserializing)]`              | Always use `Default::default()` or `#[serde(default="$path")]` instead of deserializing this value                      |
-| `#[serde(skip_serializing_if="$path")]`     | Do not serialize this value if this function `fn(&T) -> bool` returns `true`                                            |
-| `#[serde(serialize_with="$path")]`          | Call a function `fn<S>(&T, &mut S) -> Result<(), S::Error> where S: Serializer` to serialize this value of type `T`     |
-| `#[serde(deserialize_with="$path")]`        | Call a function `fn<D>(&mut D) -> Result<T, D::Error> where D: Deserializer` to deserialize this value of type `T`      |
-| `#[serde(bound="T: MyTrait")]`              | Where-clause for the Serialize and Deserialize impls. This replaces any bounds inferred by Serde for the current field. |
-| `#[serde(bound(serialize="T: MyTrait"))]`   | Where-clause for the Serialize impl.                                                                                    |
-| `#[serde(bound(deserialize="T: MyTrait"))]` | Where-clause for the Deserialize impl.                                                                                  |
-
-Using in `no_std` crates
-========================
-
-The core `serde` package defines a number of features to enable usage in a
-variety of freestanding environments. Enable any or none of the following
-features, and use `default-features = false` in your `Cargo.toml`:
-
-- `alloc` (implies `nightly`)
-- `collections` (implies `alloc` and `nightly`)
-- `std` (default)
-
-If you only use `default-features = false`, you will receive a stock `no_std`
-serde with no support for any of the collection types.
-
-Serialization Formats Using Serde
-=================================
-
-| Format      | Name                                                 |
-| ------      | ----                                                 |
-| Bincode     | [bincode](https://crates.io/crates/bincode)          |
-| env vars    | [envy](https://crates.io/crates/envy)                |
-| Hjson       | [serde\_hjson](https://crates.io/crates/serde-hjson) |
-| JSON        | [serde\_json](https://crates.io/crates/serde_json)   |
-| MessagePack | [rmp](https://crates.io/crates/rmp)                  |
-| XML         | [serde\_xml](https://github.com/serde-rs/xml)        |
-| YAML        | [serde\_yaml](https://github.com/dtolnay/serde-yaml) |
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in Serde by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.

examples/serde-syntex-example/Cargo.toml

@@ -9,9 +9,9 @@ default = ["serde_codegen"]
 unstable = ["serde_macros"]
 
 [build-dependencies]
-serde_codegen = { version = "^0.8", optional = true }
+serde_codegen = { version = "^0.8", optional = true, path = "../../serde_codegen" }
 
 [dependencies]
 serde = "^0.8"
 serde_json = "^0.8"
-serde_macros = { version = "^0.8", optional = true }
+serde_macros = { version = "^0.8", optional = true, path = "../../serde_macros" }

serde/Cargo.toml

@@ -1,11 +1,12 @@
 [package]
 name = "serde"
-version = "0.8.0"
+version = "0.8.3"
 authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
 license = "MIT/Apache-2.0"
 description = "A generic serialization/deserialization framework"
+homepage = "https://serde.rs"
 repository = "https://github.com/serde-rs/serde"
-documentation = "https://serde-rs.github.io/serde/serde/"
+documentation = "https://docs.serde.rs/serde/"
 readme = "../README.md"
 keywords = ["serde", "serialization"]
 include = ["Cargo.toml", "src/**/*.rs"]

serde/src/de/impls.rs

@@ -791,7 +791,7 @@ macro_rules! map_impl {
 #[cfg(any(feature = "std", feature = "collections"))]
 map_impl!(
     BTreeMap<K, V>,
-    BTreeMapVisitor<K: Deserialize + Eq + Ord,
+    BTreeMapVisitor<K: Deserialize + Ord,
                     V: Deserialize>,
     visitor,
     BTreeMap::new(),

serde/src/de/value.rs

@@ -128,7 +128,7 @@ impl fmt::Display for Error {
                 write!(formatter, "Unknown variant: {}", variant)
             }
             Error::UnknownField(ref field) => write!(formatter, "Unknown field: {}", field),
-            Error::MissingField(ref field) => write!(formatter, "Missing field: {}", field),
+            Error::MissingField(field) => write!(formatter, "Missing field: {}", field),
         }
     }
 }

serde/src/lib.rs

@@ -9,7 +9,7 @@
 //! For a detailed tutorial on the different ways to use serde please check out the
 //! [github repository](https://github.com/serde-rs/serde)
 
-#![doc(html_root_url="https://serde-rs.github.io/serde/serde")]
+#![doc(html_root_url="https://docs.serde.rs")]
 #![cfg_attr(not(feature = "std"), no_std)]
 #![cfg_attr(feature = "unstable", feature(reflect_marker, unicode, nonzero, plugin, step_trait, zero_one))]
 #![cfg_attr(feature = "alloc", feature(alloc))]

serde_codegen/Cargo.toml

@@ -1,11 +1,12 @@
 [package]
 name = "serde_codegen"
-version = "0.8.1"
+version = "0.8.3"
 authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
 license = "MIT/Apache-2.0"
 description = "Macros to auto-generate implementations for the serde framework"
+homepage = "https://serde.rs"
 repository = "https://github.com/serde-rs/serde"
-documentation = "https://github.com/serde-rs/serde"
+documentation = "https://serde.rs/codegen.html"
 keywords = ["serde", "serialization"]
 build = "build.rs"
 include = ["Cargo.toml", "build.rs", "src/**/*.rs", "src/lib.rs.in"]
@@ -24,14 +25,14 @@ with-syntex = [
 ]
 
 [build-dependencies]
-quasi_codegen = { version = "^0.16.0", optional = true }
-syntex = { version = "^0.39.0", optional = true }
+quasi_codegen = { version = "^0.17.0", optional = true }
+syntex = { version = "^0.41.0", optional = true }
 
 [dependencies]
-aster = { version = "^0.22.0", default-features = false }
+aster = { version = "^0.24.0", default-features = false }
 clippy = { version = "^0.*", optional = true }
-quasi = { version = "^0.16.0", default-features = false }
-quasi_macros = { version = "^0.16.0", optional = true }
-serde_codegen_internals = { version = "=0.5.0", default-features = false, path = "../serde_codegen_internals" }
-syntex = { version = "^0.39.0", optional = true }
-syntex_syntax = { version = "^0.39.0", optional = true }
+quasi = { version = "^0.17.0", default-features = false }
+quasi_macros = { version = "^0.17.0", optional = true }
+serde_codegen_internals = { version = "=0.6.1", default-features = false, path = "../serde_codegen_internals" }
+syntex = { version = "^0.41.0", optional = true }
+syntex_syntax = { version = "^0.41.0", optional = true }

serde_codegen/src/de.rs

@@ -192,7 +192,7 @@ fn deserialize_visitor(
     builder: &aster::AstBuilder,
     generics: &ast::Generics,
 ) -> (P<ast::Item>, P<ast::Ty>, P<ast::Expr>) {
-    if generics.ty_params.is_empty() {
+    if generics.lifetimes.is_empty() && generics.ty_params.is_empty() {
         (
             builder.item().unit_struct("__Visitor"),
             builder.ty().id("__Visitor"),

serde_codegen/src/env.rs

@@ -0,0 +1,36 @@
+use std::env;
+use std::ffi::OsStr;
+use std::ops::Drop;
+
+pub fn set_if_unset<K, V>(k: K, v: V) -> TmpEnv<K>
+    where K: AsRef<OsStr>,
+          V: AsRef<OsStr>,
+{
+    match env::var(&k) {
+        Ok(_) => TmpEnv::WasAlreadySet,
+        Err(_) => {
+            env::set_var(&k, v);
+            TmpEnv::WasNotSet { k: k }
+        }
+    }
+}
+
+#[must_use]
+pub enum TmpEnv<K>
+    where K: AsRef<OsStr>,
+{
+    WasAlreadySet,
+    WasNotSet {
+        k: K,
+    }
+}
+
+impl<K> Drop for TmpEnv<K>
+    where K: AsRef<OsStr>,
+{
+    fn drop(&mut self) {
+        if let TmpEnv::WasNotSet { ref k } = *self {
+            env::remove_var(k);
+        }
+    }
+}

serde_codegen/src/lib.rs

@@ -35,48 +35,62 @@ include!(concat!(env!("OUT_DIR"), "/lib.rs"));
 #[cfg(not(feature = "with-syntex"))]
 include!("lib.rs.in");
 
+#[cfg(feature = "with-syntex")]
+mod env;
+
 #[cfg(feature = "with-syntex")]
 pub fn expand<S, D>(src: S, dst: D) -> Result<(), syntex::Error>
     where S: AsRef<Path>,
           D: AsRef<Path>,
 {
-    use syntax::{ast, fold};
+    let src = src.as_ref().to_owned();
+    let dst = dst.as_ref().to_owned();
 
-    /// Strip the serde attributes from the crate.
-    #[cfg(feature = "with-syntex")]
-    fn strip_attributes(krate: ast::Crate) -> ast::Crate {
-        /// Helper folder that strips the serde attributes after the extensions have been expanded.
-        struct StripAttributeFolder;
+    let expand_thread = move || {
+        use syntax::{ast, fold};
 
-        impl fold::Folder for StripAttributeFolder {
-            fn fold_attribute(&mut self, attr: ast::Attribute) -> Option<ast::Attribute> {
-                match attr.node.value.node {
-                    ast::MetaItemKind::List(ref n, _) if n == &"serde" => { return None; }
-                    _ => {}
+        /// Strip the serde attributes from the crate.
+        #[cfg(feature = "with-syntex")]
+        fn strip_attributes(krate: ast::Crate) -> ast::Crate {
+            /// Helper folder that strips the serde attributes after the extensions have been expanded.
+            struct StripAttributeFolder;
+
+            impl fold::Folder for StripAttributeFolder {
+                fn fold_attribute(&mut self, attr: ast::Attribute) -> Option<ast::Attribute> {
+                    match attr.node.value.node {
+                        ast::MetaItemKind::List(ref n, _) if n == &"serde" => { return None; }
+                        _ => {}
+                    }
+
+                    Some(attr)
                 }
 
-                Some(attr)
+                fn fold_mac(&mut self, mac: ast::Mac) -> ast::Mac {
+                    fold::noop_fold_mac(mac, self)
+                }
             }
 
-            fn fold_mac(&mut self, mac: ast::Mac) -> ast::Mac {
-                fold::noop_fold_mac(mac, self)
-            }
+            fold::Folder::fold_crate(&mut StripAttributeFolder, krate)
         }
 
-        fold::Folder::fold_crate(&mut StripAttributeFolder, krate)
-    }
+        let mut reg = syntex::Registry::new();
 
-    let mut reg = syntex::Registry::new();
+        reg.add_attr("feature(custom_derive)");
+        reg.add_attr("feature(custom_attribute)");
 
-    reg.add_attr("feature(custom_derive)");
-    reg.add_attr("feature(custom_attribute)");
+        reg.add_decorator("derive_Serialize", ser::expand_derive_serialize);
+        reg.add_decorator("derive_Deserialize", de::expand_derive_deserialize);
 
-    reg.add_decorator("derive_Serialize", ser::expand_derive_serialize);
-    reg.add_decorator("derive_Deserialize", de::expand_derive_deserialize);
+        reg.add_post_expansion_pass(strip_attributes);
 
-    reg.add_post_expansion_pass(strip_attributes);
+        reg.expand("", src, dst)
+    };
 
-    reg.expand("", src.as_ref(), dst.as_ref())
+    // 16 MB stack unless otherwise specified
+    let _tmp_env = env::set_if_unset("RUST_MIN_STACK", "16777216");
+
+    use std::thread;
+    thread::spawn(expand_thread).join().unwrap()
 }
 
 #[cfg(not(feature = "with-syntex"))]

serde_codegen_internals/Cargo.toml

@@ -1,11 +1,12 @@
 [package]
 name = "serde_codegen_internals"
-version = "0.5.0"
+version = "0.6.1"
 authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
 license = "MIT/Apache-2.0"
 description = "AST representation used by Serde codegen. Unstable."
+homepage = "https://serde.rs"
 repository = "https://github.com/serde-rs/serde"
-documentation = "https://github.com/serde-rs/serde"
+documentation = "https://docs.serde.rs/serde_codegen_internals/"
 keywords = ["serde", "serialization"]
 include = ["Cargo.toml", "src/**/*.rs"]
 
@@ -16,5 +17,5 @@ with-syntex = ["syntex_syntax", "syntex_errors"]
 
 [dependencies]
 clippy = { version = "^0.*", optional = true }
-syntex_syntax = { version = "^0.39.0", optional = true }
-syntex_errors = { version = "^0.39.0", optional = true }
+syntex_syntax = { version = "^0.41.0", optional = true }
+syntex_errors = { version = "^0.41.0", optional = true }

serde_codegen_internals/src/attr.rs

@@ -449,12 +449,14 @@ impl Field {
     }
 }
 
+type SerAndDe<T> = (Option<Spanned<T>>, Option<Spanned<T>>);
+
 fn get_ser_and_de<T, F>(
     cx: &ExtCtxt,
     attribute: &'static str,
     items: &[P<ast::MetaItem>],
     f: F
-) -> Result<(Option<Spanned<T>>, Option<Spanned<T>>), ()>
+) -> Result<SerAndDe<T>, ()>
     where F: Fn(&ExtCtxt, &str, &ast::Lit) -> Result<T, ()>,
 {
     let mut ser_item = Attr::none(cx, attribute);
@@ -492,21 +494,21 @@ fn get_ser_and_de<T, F>(
 fn get_renames(
     cx: &ExtCtxt,
     items: &[P<ast::MetaItem>],
-) -> Result<(Option<Spanned<InternedString>>, Option<Spanned<InternedString>>), ()> {
+) -> Result<SerAndDe<InternedString>, ()> {
     get_ser_and_de(cx, "rename", items, get_str_from_lit)
 }
 
 fn get_where_predicates(
     cx: &ExtCtxt,
     items: &[P<ast::MetaItem>],
-) -> Result<(Option<Spanned<Vec<ast::WherePredicate>>>, Option<Spanned<Vec<ast::WherePredicate>>>), ()> {
+) -> Result<SerAndDe<Vec<ast::WherePredicate>>, ()> {
     get_ser_and_de(cx, "bound", items, parse_lit_into_where)
 }
 
 pub fn get_serde_meta_items(attr: &ast::Attribute) -> Option<&[P<ast::MetaItem>]> {
     match attr.node.value.node {
         ast::MetaItemKind::List(ref name, ref items) if name == &"serde" => {
-            attr::mark_used(&attr);
+            attr::mark_used(attr);
             Some(items)
         }
         _ => None
@@ -570,7 +572,7 @@ fn get_str_from_lit(cx: &ExtCtxt, name: &str, lit: &ast::Lit) -> Result<Interned
                          name,
                          lit_to_string(lit)));
 
-            return Err(());
+            Err(())
         }
     }
 }

serde_macros/.cargo/config

@@ -0,0 +1,2 @@
+# To prevent compiletest from seeing two versions of serde
+paths = ["../serde"]

serde_macros/Cargo.toml

@@ -1,11 +1,12 @@
 [package]
 name = "serde_macros"
-version = "0.8.1"
+version = "0.8.3"
 authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
 license = "MIT/Apache-2.0"
 description = "Macros to auto-generate implementations for the serde framework"
+homepage = "https://serde.rs"
 repository = "https://github.com/serde-rs/serde"
-documentation = "https://github.com/serde-rs/serde"
+documentation = "https://serde.rs/codegen.html"
 keywords = ["serde", "serialization"]
 include = ["Cargo.toml", "src/**/*.rs", "build.rs"]
 build = "build.rs"
@@ -28,17 +29,16 @@ skeptic = { version = "^0.6.0", optional = true }
 
 [dependencies]
 clippy = { version = "^0.*", optional = true }
-serde_codegen = { version = "=0.8.1", default-features = false, features = ["unstable"], path = "../serde_codegen" }
+serde_codegen = { version = "=0.8.3", default-features = false, features = ["unstable"], path = "../serde_codegen" }
 skeptic = { version = "^0.6.0", optional = true }
 serde_json = { version = "0.8.0", optional = true }
 
 [dev-dependencies]
-clippy = "^0.*"
 compiletest_rs = "^0.2.0"
 fnv = "1.0"
 rustc-serialize = "^0.3.16"
-serde = { version = "0.8.0", path = "../serde" }
-serde_test = { version = "0.8.0", path = "../serde_test" }
+serde = { version = "0.8.3", path = "../serde" }
+serde_test = { version = "0.8.3", path = "../serde_test" }
 
 [[test]]
 name = "test"

serde_test/Cargo.toml

@@ -1,14 +1,15 @@
 [package]
 name = "serde_test"
-version = "0.8.0"
+version = "0.8.3"
 authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
 license = "MIT/Apache-2.0"
 description = "Token De/Serializer for testing De/Serialize implementations"
+homepage = "https://serde.rs"
 repository = "https://github.com/serde-rs/serde"
-documentation = "https://serde-rs.github.io/serde/serde/"
+documentation = "https://docs.serde.rs/serde_test/"
 readme = "../README.md"
 keywords = ["serde", "serialization"]
 include = ["Cargo.toml", "src/**/*.rs"]
 
 [dependencies]
-serde = { version = "0.8.0", path = "../serde" }
+serde = { version = "0.8.3", path = "../serde" }

testing/Cargo.toml

@@ -1,11 +1,12 @@
 [package]
 name = "serde_testing"
-version = "0.8.0"
+version = "0.8.3"
 authors = ["Erick Tryzelaar <erick.tryzelaar@gmail.com>"]
 license = "MIT/Apache-2.0"
 description = "A generic serialization/deserialization framework"
+homepage = "https://serde.rs"
 repository = "https://github.com/serde-rs/serde"
-documentation = "http://serde-rs.github.io/serde/serde"
+documentation = "https://docs.serde.rs/serde/"
 readme = "README.md"
 keywords = ["serialization"]
 build = "build.rs"

testing/tests/test_gen.rs

@@ -6,6 +6,7 @@ extern crate serde;
 use self::serde::ser::{Serialize, Serializer};
 use self::serde::de::{Deserialize, Deserializer};
 
+use std::borrow::Cow;
 use std::marker::PhantomData;
 
 //////////////////////////////////////////////////////////////////////////
@@ -177,6 +178,15 @@ fn test_gen() {
         e: E,
     }
     assert::<WithTraits2<X, X>>();
+
+    #[derive(Serialize, Deserialize)]
+    struct CowStr<'a>(Cow<'a, str>);
+    assert::<CowStr>();
+
+    #[derive(Serialize, Deserialize)]
+    #[serde(bound(deserialize = "T::Owned: Deserialize"))]
+    struct CowT<'a, T: ?Sized + 'a + ToOwned>(Cow<'a, T>);
+    assert::<CowT<str>>();
 }
 
 //////////////////////////////////////////////////////////////////////////