Expand description
A library to create syntax (“railroad”) diagrams as Scalable Vector Graphics (SVG).
Railroad diagrams are a graphical way to represent context-free grammar. Every diagram has exactly one starting- and one end-point; everything that belongs to the described language is represented by one of the possible paths between those points.
Using this library, diagrams are created by primitives which implemented Node.
Primitives are combined into more complex strctures by wrapping simple elements into more
complex ones.
use railroad::*;
// This diagram will be a (horizontal) sequence of simple elements
let mut seq: Sequence<Box<dyn Node>> = Sequence::default();
seq.push(Box::new(Start))
.push(Box::new(Terminal::new("BEGIN".to_owned())))
.push(Box::new(NonTerminal::new("syntax".to_owned())))
.push(Box::new(End));
// The library only computes the diagram's geometry; we use CSS for layout.
let mut dia = Diagram::new_with_stylesheet(seq, &Stylesheet::Light);
// A `Node`'s `fmt::Display` is its SVG.
println!("<html>{}</html>", dia);
// For direct streaming, render into `svg::Renderer`.
let mut streamed = String::new();
let mut renderer = svg::Renderer::new(&mut streamed);
dia.render(&mut renderer, 0, 0, svg::HDir::LTR).unwrap();
assert!(streamed.starts_with("<svg"));§Implementing custom nodes
Downstream crates can implement Node directly for custom primitives.
The main rule is simple: a node must only draw within the geometry it
advertises. If a node reports width(), height(), and entry_height(),
its drawing must stay inside that box and keep its connecting path at
y + entry_height().
For simple leaf nodes, implementing entry_height(), height(), width(),
and Node::draw is usually enough; the provided geometry-aware methods are
correct by default. For composite nodes that position child nodes, override
Node::compute_geometry and usually also Node::draw_with_geometry and
Node::render_with_geometry so child geometry is computed once and reused
during rendering.
Re-exports§
pub use crate::notactuallysvg as svg;pub use resvg;
Modules§
- notactuallysvg
- Lower-level SVG building blocks used by
railroad’s rendering layers. - render
- A shorthand for rendering diagrams to images, using
resvg’s default options.
Structs§
- Choice
- A container of elements, drawn vertically, where exactly one element has to be picked
- Comment
- A label / verbatim text drawn inline on the connecting path.
- Diagram
- The top-level container that renders a node tree as a complete SVG document.
- Empty
- A dummy-element which has no size and draws nothing.
- End
- A symbol indicating the logical end of a syntax-diagram via two vertical bars.
- Horizontal
Grid - A horizontal group of unconnected elements.
- Labeled
Box - A box drawn around the given element and a label placed inside the box, above the element.
- Link
- Wraps another primitive, making it a clickable link to some URI.
- Multi
Choice - A multi-column container where exactly one child alternative has to be picked.
- Node
Geometry - Pre-computed geometry for a node and its entire subtree.
- NonTerminal
- A
NonTerminal, drawn as a rectangle. - Optional
- Wraps another element to make that element logically optional.
- Repeat
- Wraps one element by providing a backwards-path through another element.
- Sequence
- A horizontal group of elements, connected from left to right.
- Simple
End - A symbol indicating the logical end of a syntax-diagram via a circle
- Simple
Start - A symbol indicating the logical start of a syntax-diagram via a circle
- Stack
- A vertical group of elements, drawn from top to bottom.
- Start
- A symbol indicating the logical start of a syntax-diagram via two vertical bars.
- Terminal
- A
Terminal-symbol, drawn as a rectangle with rounded corners. - Vertical
Grid - A vertical group of unconnected elements.
Enums§
- Link
Target - Possible targets for
Link. - Stylesheet
- Pre-defined stylesheets
Constants§
- DEFAULT_
CSS - Default Cascading Style Sheets for the resuling SVG.
Traits§
- Node
- A diagram primitive that participates in layout and SVG generation.
- Node
Collection - Convenience aggregation helpers for iterators and collections of
Nodes.