Crate wavedrom

source ·
Expand description

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 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 as an input to your figures and second how to programmically define figures.

WaveJson

use std::fs::File;

let path = "path/to/file.svg";
let mut file = File::create(path)?;

wavedrom::render_json5(r##"
    { signal: [
        { name: "clk",  wave: "P......" },
        { name: "bus",  wave: "x.==.=x", data: ["head", "body", "tail", "data"] },
        { name: "wire", wave: "0.1..0." }
    ]}
"##, &mut file)?;

Result:

clkbusheadbodytailwire

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 mut file = File::create(path)?;

assembled_figure.write_svg(&mut file)?;

Result:

Timing SchemaclkreqdonedonestateIdleFetchCalculateReturnIdle

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 the serde feature to deserialize a WaveJson file.
  • serde_json. Disabled by default. Formal version of JSON that can be used with the serde 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 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 buffer. If a write to the io::Write is expensive, it is recommended to wrap the io::Write in a std::io::BufWriter.

Re-exports

Modules

  • Edges or Arrows define a set of markers and edge lines that can be put over a diagram to indicate properties.
  • A collection of markers that get overlayed onto the signal diagram.
  • All the render options
  • skinskins
    Module with a WaveDrom skin
  • The definitions for the WaveJson format.

Structs

Enums

Functions

  • render_jsonserde and serde_json
    Render the contents of a json file to a writer.
  • Render the contents of a json5 file to a writer.
  • Render the contents of a json5 file to a writer with a specific set of options.
  • render_json_with_optionsserde and serde_json
    Render the contents of a json file to a writer with a specific set of options.