Crate serde_hjson

What is Hjson?

A configuration file format for humans. Relaxed syntax, fewer mistakes, more comments. See http://hjson.github.io

Data types that can be encoded are JavaScript types (see the serde_hjson:Value enum for more details):

• Boolean: equivalent to rust's bool
• I64: equivalent to rust's i64
• U64: equivalent to rust's u64
• F64: equivalent to rust's f64
• String: equivalent to rust's String
• Array: equivalent to rust's Vec<T>, but also allowing objects of different types in the same array
• Object: equivalent to rust's serde_hjson::Map<String, serde_hjson::Value>
• Null

Sample

{
    FirstName: John
    LastName: Doe
    Age: 43
    Address: {
        Street: Downing Street 10
        City: London
        Country: Great Britain
    }
    PhoneNumbers: [
        +44 1234567
        +44 2345678
    ]
}

If we assume that FirstName is optional and all other fields are mandatory, the above Hjson could correspond to the following Rust structs:

#[derive(Serialize, Deserialize)]
struct Data {
    #[serde(rename="FirstName")] // to comply with Rust coding standards
    first_name: Option<String>,
    LastName: String,
    Age: u32,
    Address: Address,
    PhoneNumbers: Vec<String>
}

#[derive(Serialize, Deserialize)]
struct Address {
    Street: String,
    City: String,
    Country: String
}

Type-based Serialization and Deserialization

Serde provides a mechanism for low boilerplate serialization & deserialization of values to and from Hjson via the serialization API. To be able to serialize a piece of data, it must implement the serde::Serialize trait. To be able to deserialize a piece of data, it must implement the serde::Deserialize trait. Serde provides provides an annotation to automatically generate the code for these traits: #[derive(Serialize, Deserialize)].

The Hjson API also provides an enum serde_hjson::Value and a method to_value to serialize objects. A serde_hjson::Value value can be serialized as a string or buffer using the functions described above.

Examples of use

Parsing a str to Value and reading the result

//#![feature(custom_derive, plugin)]
//#![plugin(serde_macros)]

extern crate serde_hjson;

use serde_hjson::Value;

fn main() {
    let data: Value = serde_hjson::from_str("{foo: 13, bar: \"baz\"}").unwrap();
    println!("data: {:?}", data);
    println!("object? {}", data.is_object());

    let obj = data.as_object().unwrap();
    let foo = obj.get("foo").unwrap();

    println!("array? {:?}", foo.as_array());
    // array? None
    println!("u64? {:?}", foo.as_u64());
    // u64? Some(13u64)

    for (key, value) in obj.iter() {
        println!("{}: {}", key, match *value {
            Value::U64(v) => format!("{} (u64)", v),
            Value::String(ref v) => format!("{} (string)", v),
            _ => format!("other")
        });
    }
    // bar: baz (string)
    // foo: 13 (u64)
}

Reexports

pub use self::de::{Deserializer, StreamDeserializer, from_iter, from_reader, from_slice, from_str};

pub use self::error::{Error, ErrorCode, Result};

pub use self::ser::{Serializer, to_writer, to_vec, to_string};

pub use self::value::{Value, Map, to_value, from_value};

Modules

builder	JSON Builders
de	Hjson Deserialization
error	JSON Errors
ser	Hjson Serialization
value	Hjson Value

Macros

forward_to_deserialize!