README.md

Serializable Enum

Overview

Provides two macros to facilitate easier serialization / deserialization of enums with variants having no data. The default serialization for serde when serializing enums with no data is of the form: {"Variant": []}. While this works for most use cases, you may want the enum to be serialized as "variant" instead. The two macros in this crate help make this serialization/deserialization easier.

These macros are designed to be used with serde only.

Usage

Add this to your Cargo.toml:

[dependencies]
serializable_enum = "0.1.0"

And to your crate:

#[macro_use] extern crate serializable_enum;

Example

Consider this struct:

#[derive(Serialize, Deserialize)]
struct Post {
    title: String,
    content: String,
    content_format: ContentFormat,
}

pub enum ContentFormat {
    Html,
    Markdown,
}

Assume an instance of Post:

let p = Post {
    title: String::from("I <3 serde"),
    content: String::from("awesome content"),
    content_format: ContentFormat::Markdown,
};

Upon serializing Post you want the following output (json):

{
  "title": "I <3 serde",
  "content": "awesome content",
  "content_format": "markdown",
}

Using the macros in this crate, we can achieve this through the following (assuming implementation of Post above):

extern crate serde;
extern crate serde_json;
#[macro_use] extern crate serializable_enum;

#[derive(Debug)]
pub enum Error {
    Parse(String)
}

// You will need display implemented for Error (you should already have this).
impl ::std::fmt::Display for Error {
   fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
       write!(f, "{:?}", self)
   }
}

serializable_enum! {
    /// Supported content formats
    #[derive(Debug, PartialEq)]
    pub enum ContentFormat {
        /// Markdown
        Markdown,
        /// HTML
        Html,
    }
    ContentFormatVisitor
}

impl_as_ref_from_str! {
    ContentFormat {
        Markdown => "markdown",
        Html => "html",
    }
    Error::Parse
}

fn main() {
    let md = ContentFormat::Markdown;
    assert_eq!(serde_json::to_string(&md).unwrap(), "\"markdown\"");
    let des_md: ContentFormat = serde_json::from_str("\"markdown\"").unwrap();
    assert_eq!(md, des_md);
}

serializable_enum sets up the serde serialization and deserialization using the visitor type provided, in this case ContentFormatVisitor.

impl_as_ref_from_str provides implementations for AsRef and FromStr traits for the enum using the mappings provided, which are used for serialization and deserialization. Error::Parse is a variant of an Error enum defined in your crate with String data. This variant is used as the Err type for FromStr.

Note: the serializable_enum macro invocation requires:

1. Doc-comments for each variant.

For more details, head over to the documentation.

License

This library is distributed under similar terms to Rust: dual licensed under the MIT license and the Apache license (version 2.0).

See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details.