Crate wavedrom

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:

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:

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

• pub use json5;
• pub use serde_json;

Modules

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

Structs

• AssembledFigure
  A Figure that has been assembled with the Figure::assemble or Figure::assemble_with_options methods.
• AssembledLine
  A line of the AssembledFigure.
• AssembledSignalPath
  A SignalPath that is assembled and ready to be rendered.
• Color
  An Red, Green, Blue color structure that can be parsed from and to a CSS compatible string.
• CycleOffset
  The cycle offset within multiple clock cycles. This is precise up until a quarter of a cycle.
• Figure
  An encapsulation of everything to form a Digital Timing Diagram
• FigureSectionGroup
  A section of the figure’s group
• Font
  The font that is used by the svg assembler to calculate text widths.
• PathAssembleOptions
  The options that are used during assembly of a Figure or SignalPath.
• Signal
  A diagram signal line with a set of cycles.
• SignalPath
  The path given for a Signal
• SignalPathSegment
  A segment in an AssembledSignalPath
• SignalSegmentItem
  A item given by the SignalSegmentIter
• SignalSegmentIter
  An iterator over assembled signal segments

Enums

• CycleState
  A state that a signal can be at any cycle
• FigureSection
  A section of the figure’s signals
• InCycleOffset
  The cycle offset within a single-clock cycle.
• PathCommand
  A command for a signal path to take with relative coordinates.
• PathSegmentBackground
  A background for a path segment
• RenderJson5Errorjson5
  An error with the render_json5 or render_json5_with_options functions.
• RenderJsonErrorserde and serde_json
  An error with the render_json or render_json_with_options functions.

Functions

• render_jsonserde and serde_json
  Render the contents of a json file to a writer.
• render_json5json5
  Render the contents of a json5 file to a writer.
• render_json5_with_optionsjson5
  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.