json_typegen_shared 0.2.0

Codegen from JSON samples. Not intended to be used directly. See repository for the intended crates.
Documentation

json_typegen - Rust types from JSON samples

Travis Build Status crates.io docs.rs

json_typegen is a collection of tools for generating Rust types from JSON samples, built on top of serde. I.e. you give it some JSON, it gives you the type definitions necessary to use that JSON in a Rust program. If you are familiar with F#, the procedural macro json_typegen! works as a type provider for JSON in Rust. It was inspired by and uses the same kind of inference algorithm as F# Data.

There are three interfaces to this code generation logic:

Procedural macro

The first interface to the code generation tools is a procedural macro json_typegen!. As an example, the below code generates code for the type Point.

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

json_typegen!("Point", r#"{ "x": 1, "y": 2 }"#);

fn main() {
    let mut p: Point = serde_json::from_str(r#"{ "x": 3, "y": 5 }"#).unwrap();
    println!("deserialized = {:?}", p);
    p.x = 4;
    let serialized = serde_json::to_string(&p).unwrap();
    println!("serialized = {}", serialized);
}
[dependencies]
serde = "1.0"
serde_json = "1.0"
json_typegen = "0.2"

The sample json can also come from local or remote files:

json_typegen!("Point", "json_samples/point.json");
json_typegen!("Point", "http://example.com/someapi/point.json");

The code generation can also be customized:

json_typegen!("Point", "http://example.com/someapi/point.json", {
    use_default_for_missing_fields,
    "/foo/bar": {
        use_type: "map"
    }
});

For the details, see the relevant documentation.

Conditional compilation

To avoid incurring the cost of a HTTP request per sample used for every build you can use conditional compilation to only check against remote samples when desired:

#[cfg(not(feature = "online-samples"))]
json_typegen!("Point", r#"{ "x": 1, "y": 2 }"#);
#[cfg(feature = "online-samples")]
json_typegen!("Point", "http://vestera.as/json_typegen/examples/point.json");

And in Cargo.toml:

[features]
online-samples = []

You can then verify that remote samples match your expectations in e.g. CI builds as follows:

cargo check --features "online-samples"

Command line interface

The crate json_typegen_cli provides a CLI to the same code generation as the procedural macro uses internally. This provides a useful migration path if you at some point need to customize the generated code beyond what is practical through macro arguments.

For details on usage see its readme.

Web interface

For simple testing and one-time use there is also a web interface (in json_typegen_web). An instance of this interface is currently hosted at http://vestera.as/json_typegen

License

This project is dual licensed, under either the Apache 2.0 or the MIT license, at your option.