Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Code generation

The primary benefit of a schema modeling system, is that you can consume this type information to generate code into multiple output formats. This is a common pattern in many languages, and is a great way to reduce boilerplate.

In the context of Rust, why use multiple disparate crates, each with their own unique implementations and #[derive] macros, just to generate some output. With Schematic, you can ditch all of these and use a single standardized approach.

Usage

To make use of the generator, import and instantiate our SchemaGenerator. This is typically done within a one-off main function that can be ran from Cargo.

#![allow(unused)]
fn main() {
use schematic::schema::SchemaGenerator;

let mut generator = SchemaGenerator::default();
}

Adding types

From here, for every type that implements Schematic and you want to include in the generated output, call SchemaGenerator::add(). If you already have a Schema rather than a type, you can use the SchemaGenerator::add_schema() method instead.

#![allow(unused)]
fn main() {
use schematic::schema::SchemaGenerator;

let mut generator = SchemaGenerator::default();
generator.add::<FirstConfig>();
generator.add::<SecondConfig>();
generator.add::<ThirdConfig>();
}

We’ll recursively add referenced and nested schemas for types that are added. No need to explicitly add all required types!

Schemas are keyed by name, so adding two different types that report the same one panics. Rendering both is impossible, and silently keeping one would leave every reference to the other pointing at the wrong type. Adding the same type twice is fine.

Generating output

From here, call SchemaGenerator::generate() to render the schemes with a chosen renderer to an output file of your choice. This method can be called multiple times, each with a different output file or renderer.

#![allow(unused)]
fn main() {
use schematic::schema::SchemaGenerator;

let mut generator = SchemaGenerator::default();
generator.add::<FirstConfig>();
generator.add::<SecondConfig>();
generator.add::<ThirdConfig>();
generator.generate(PathBuf::from("output/file"), CustomRenderer::default())?;
generator.generate(PathBuf::from("output/another/file"), AnotherRenderer::default())?;
}

Renderers

The following built-in renderers are available, but custom renderers can be created as well by implementing the SchemaRenderer trait.