Crate wavedrom

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:

§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;json5
pub use serde_json;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.

Crate wavedromCopy item path