Crate serializers

Serializers

Normally when using “serde_json” and #[derive(Serialize)] you only can have one JSON representation for a type, however sometimes you might need another one which has more or less data.

This crate makes it easy to create “serializers” that take some value and turn it into JSON. You get to decide for each serializer which type it serializes, and which fields and associations it includes.

Example

#[macro_use]
extern crate serializers;
#[macro_use]
extern crate serde_json;

use serializers::*;

struct User {
    id: u64,
    name: String,
    country: Country,
    friends: Vec<User>,
}

#[derive(Clone)]
struct Country {
    id: u64,
}

serializer! {
    #[derive(Debug)]
    struct UserSerializer<User> {
        attr(id)
        attr(name)
        has_one(country, CountrySerializer)
        has_many(friends, UserSerializer)
    }
}

serializer! {
    #[derive(Debug)]
    struct CountrySerializer<Country> {
        attr(id)
    }
}

fn main() {
    let denmark = Country {
        id: 1,
    };

    let bob = User {
        id: 1,
        name: "Bob".to_string(),
        country: denmark.clone(),
        friends: vec![
            User {
                id: 2,
                name: "Alice".to_string(),
                country: denmark.clone(),
                friends: vec![],
            }
        ],
    };

    // Serializing a single user
    let json: String = UserSerializer::serialize(&bob);
    assert_eq!(
        json,
        json!({
            "country": { "id": 1 },
            "friends": [
                {
                    "country": { "id": 1 },
                    "friends": [],
                    "name": "Alice",
                    "id": 2
                }
            ],
            "name": "Bob",
            "id": 1
        }).to_string(),
    );

    // Serializing a vector of users
    let users = vec![bob];
    let json: String = UserSerializer::serialize_iter(&users);
    assert_eq!(
        json,
        json!([
            {
                "country": { "id": 1 },
                "friends": [
                    {
                        "country": { "id": 1 },
                        "friends": [],
                        "name": "Alice",
                        "id": 2
                    }
                ],
                "name": "Bob",
                "id": 1
            }
        ]).to_string(),
    );
}

See the macro docs for more information about the serializer! macro.

No macros for me

The easiest way to define serializers is using the serializer! macro, however if you don’t wish to do so you can define serializers like so:

struct UserSerializer;

impl Serializer<User> for UserSerializer {
    fn serialize_into(&self, user: &User, b: &mut Builder) {
        b.attr("id", &user.id);
        b.attr("name", &user.name);
        b.has_one("country", &user.country, &CountrySerializer);
        b.has_many("friends", &user.friends, &UserSerializer);
    }
}

Macros

serializer

This macro is the primary way to make serializers. See the top level docs for an example.

Structs

Builder

The struct responsible for gathering keys and values for the JSON.

Traits

Serializer

The trait you implement in order to make a serializer.