WaveDrom allows for the programmatic creation of beautiful Diagram Timing Diagrams in Rust. This is the crate that powers all the wavedrom tools including the editor, the command-line interface, and the mdbook preprocessor.
This crate is be used in two ways. It can be given [WaveJson][wavejson] which is a JSON format
to describe Diagram Timing Diagrams. Alternatively, you can programmatically define a
figure by building it using the [Figure
] struct.
Getting Started
Getting started with this crate is quite easy. Here, we have two examples. First, how to use [WaveJson][wavejson] as an input to your figures and second how to programmically define figures.
WaveJson
Result:
Programmically defining a Figure
use std::fs::File;
use wavedrom::{Figure, Signal};
let figure = Figure::new()
.header_text("Timing Schema")
.add_signals([
Signal::with_cycle_str("p........").name("clk"),
Signal::with_cycle_str("010......").name("req"),
Signal::with_cycle_str("0......10").name("done"),
Signal::with_cycle_str("0......10").name("done"),
Signal::with_cycle_str("==.=.=.=.").name("state")
.add_data_fields([
"Idle", "Fetch", "Calculate", "Return", "Idle",
]),
]);
let assembled_figure = figure.assemble();
let path = "path/to/file.svg";
# let path = concat!(env!("CARGO_MANIFEST_DIR"), "/assets/doc-root-programatically.svg");
let mut file = File::create(path)?;
assembled_figure.write_svg(&mut file)?;
# <Result<(), std::io::Error>>::Ok(())
Result:
Cargo Features
There are a set of cargo features, most of which are enabled by default.
serde
. Enabled by default. Adds the [wavejson
] module, which defines the serialize and deserialize formats for a wave format for a wave.embed_font
. Enabled by default. Adds an embedded Helvetica into the library which is used to find the dimensions of certain texts. When this is disabled, it is replaced by a width look-up table that is only accurate for ASCII and over-estimates the width for other UTF-8 characters.json5
. Enabled by default. The human friendly variant of JSON that can be used with theserde
feature to deserialize a WaveJson file.serde_json
. Disabled by default. Formal version of JSON that can be used with theserde
feature to deserialize a WaveJson file.skins
. Enabled by default. Adds the [skin
] module, which defines the serialize and deserialize formats for WaveDrom skins. Also adds logic to merge a skin into an existing set of options.
Rendering Process
The rendering process of this crate is done in 3 steps.
1. Create [Figure
]
A [Figure
] can be created in two ways. First, a [Figure
] can be built programmatically with
the [Figure::new
] method and the builder pattern methods. Second, a [Figure
] can be built
by loading a [WaveJson][wavejson] file. This can be done with the [Figure::from_json5
] or
[Figure::from_json
] methods.
2. Assemble [Figure
] to [AssembledFigure
]
A [Figure
] needs to be assembled. This shapes the signal waves removes any invalid groups and
edges. Assembling is done with the [Figure::assemble
] and [Figure::assemble_with_options
]
methods.
3. Render [AssembledFigure
] to SVG
An [AssembledFigure
] can be rendered by calling the [AssembledFigure::write_svg
] or
[AssembledFigure::write_svg_with_options
] methods. This will write an SVG into an
[io::Write
][std::io::Write] buffer. If a write to the [io::Write
][std::io::Write] is
expensive, it is recommended to wrap the [io::Write
][std::io::Write] in a
[std::io::BufWriter
].