Expand description
§sirene-core
Diagram parsing, layout, and rendering for sirene: Mermaid,
Graphviz DOT, and PlantUML sources read into lossless syntax trees with diagnostics, diagram
models, layouts, and output as ASCII, SVG, or (with the png feature) PNG. It renders files
without the sirene CLI, with the same output.
use std::path::Path;
use sirene_core::diagram::{self, Lang};
use sirene_core::scene::Theme;
let path = Path::new("login.mmd");
// UTF-8 of at most 64 MiB, with errors naming the file.
let src = &sirene_core::source::read(path)?;
// The extension picks DOT (`.dot`, `.gv`) or PlantUML (`.puml`, ...); otherwise the source's
// header picks the diagram type.
let lowered = diagram::lower_as(src, Lang::of_path(path));
for d in &lowered.diagnostics {
let (line, col) = d.line_col(src);
eprintln!("{line}:{col}: {}", d.message);
}
// What `sirene ascii`, `sirene svg`, and `sirene png` write.
let text = lowered.ascii(&Default::default())?;
assert!(text.contains("Start"));
let svg = lowered.svg(&Theme::LIGHT)?;
assert!(svg.starts_with("<svg"));
#[cfg(feature = "png")]
{
use sirene_core::scene::png::Quality;
let png = lowered.png(&Theme::LIGHT, Quality::Fine, None)?;
assert!(png.starts_with(b"\x89PNG"));
}
// Each diagram block of a Markdown file.
let md = "# Notes\n\n```dot\ndigraph { a -> b }\n```\n";
for block in sirene_core::markdown::mermaid_blocks(md) {
let lowered = diagram::lower_as(&block.code, Some(block.lang));
assert!(lowered.svg(&Theme::DARK)?.contains("<svg"));
}- Reading never fails: problems are
Diagnostics with byte ranges (Diagnostic::line_colgives 1-based positions,diagnostic::LineIndexmany of them). The diagram is still drawn. - A diagram’s own
themeandthemeVariablesapply over the theme passed in. Lowered::scenegives the display list for other renderers, with text measured by anyscene::TextMetrics.scene::png(featurepng) writes PNGs with embedded Noto Sans faces, so images are the same on every machine.flowchart::parseandflowchart::editgive the flowchart syntax tree and turn changes to the diagram into minimal source edits.- Rendering returns
sirene_core::Result. Errors retain typed causes throughstd::error::Error::source(); useerror.report()to display the full causal chain.
The behavior is specified in the repository’s spec/ directory.
Re-exports§
pub use diagnostic::Diagnostic;pub use diagnostic::Severity;pub use error::Error;pub use error::Result;
Modules§
- architecture
- Mermaid architecture diagrams (MARCH-*): services and junctions, nested groups, and edges that leave and enter by a named side.
- ascii
- Terminal text rendering of flowcharts (ASCIIR-*).
- block
- Mermaid block diagrams (MBLOCK-*): blocks placed in a grid of columns, nested groups, and edges between blocks.
- c4
- Mermaid C4 diagrams (MC4-*): people, systems, containers, components, and deployment nodes in nested boundaries, with relations between them.
- class
- Mermaid class diagrams (MCLASS-*), lowered to the flowchart model.
- cynefin
- Mermaid Cynefin diagrams (MCYN-*): items placed in the five domains of the Cynefin framework, with transitions between domains.
- diagnostic
- Parse and validation diagnostics.
- diagram
- The entry point for every Mermaid diagram type sirene draws (LANGS-2).
- dot
- Graphviz DOT (DOT-*), lowered to the graph model.
- er
- Mermaid entity relationship diagrams (MER-*), lowered to the flowchart model.
- error
- Errors retain their underlying causes until a caller presents them.
- eventmodel
- Mermaid event modeling diagrams (MEVM-*): UI, processor, command, read model, and event frames on a timeline, in swimlanes by type and namespace, with relations between them.
- flowchart
- Mermaid flowchart parsing and lowering.
- gantt
- Mermaid gantt charts (MGANTT-*): tasks on a time axis, grouped in sections.
- git
- Mermaid git graphs (MGIT-*): branches as lanes of commits, with merges and cherry-picks.
- info
- Mermaid info diagrams (MINFO-*): the version of the tool drawing them.
- ishikawa
- Mermaid ishikawa (fishbone) diagrams (MISH-*): an effect and the causes that lead to it, nested by indentation.
- items
- Drawing edits to diagrams that are lists of labeled items (WYSIWY-28): each item is named by
its index in the lowered model and drawn as
Owner::Node(index), and can be renamed, added after another or at the end, and deleted. - journey
- Mermaid user journeys (MJOUR-*): tasks in sections, each scored and done by actors.
- kanban
- Mermaid kanban boards (MKAN-*): columns of cards, parsed with the mindmap grammar.
- layout
- Layered layout of compound graphs into integer cells (LAYOUT-*).
- markdown
- Diagram code blocks in Markdown (MARKDO-1).
- mindmap
- Mermaid mindmaps (MMIND-*): a tree of ideas drawn out from a root.
- packet
- Mermaid packet diagrams (MPKT-*): bit fields laid out in rows.
- pie
- Mermaid pie charts (MPIE-*): labeled values drawn as slices of a circle.
- plantuml
- PlantUML diagrams (PUML-): sequence diagrams lowered to the sequence model (PSEQ-), and the other kinds lowered to the graph model, one module each.
- profile
- Phase timing (ERRORH-8): how long each stage of reading, layout, and drawing takes, logged
at trace level under the target
TARGET. Nothing is measured unless that target is enabled, e.g.SIRENE_LOG=sirene_core::profile=trace. - quadrant
- Mermaid quadrant charts (MQUAD-*): points on two axes split into four quadrants.
- radar
- Mermaid radar charts (MRADAR-*): axes around a circle, and a closed curve per series.
- railroad
- Mermaid railroad diagrams (MRAIL-*): grammar rules written in EBNF, ABNF, PEG, or Mermaid’s constructor notation, drawn as syntax diagrams.
- requirement
- Mermaid requirement diagrams (MREQ-*), lowered to the flowchart model.
- sankey
- Mermaid sankey diagrams (MSANKEY-*): flows between nodes, as bands as wide as their values.
- scene
- Backend-independent drawing of diagrams as paths and text (DISPLA-*).
- sequence
- Mermaid sequence diagrams (MSEQ-*): participants exchanging messages over time.
- source
- Reading diagram sources from files and streams (WORKSP-10).
- state
- Mermaid state diagrams (MSTATE-*), lowered to the flowchart model.
- syntax
- Syntax kinds and rowan tree types shared by all diagram parsers.
- theme
- A diagram’s own theme (MTHEME-1):
themeandthemeVariablesfrom its frontmatterconfig:or an%%{init: ...}%%directive, resolved to drawing colors as Mermaid 12.3’s themes resolve them. The palettes and the color derivations are ported from Mermaid’ssrc/themes/(Copyright (c) 2014-2022 Knut Sveidqvist; MIT) and khroma’sadjust,lighten,darken, andinvert; see THIRD-PARTY-NOTICES. - timeline
- Mermaid timelines (TIMELI-*): time periods with their events, grouped in sections.
- timing
- Timing diagrams (TIMING-*): signals whose state changes over time, with messages, constraints, and highlights between them. PlantUML timing diagrams lower to this model.
- treemap
- Mermaid treemaps (MTREE-*): nested sections and leaves, as rectangles sized by value.
- treeview
- Mermaid tree views (MTREEV-*): a directory-like hierarchy of files and folders, nested by indentation or drawn with box-drawing characters.
- usecase
- Mermaid use case diagrams (MUSE-*), lowered to the flowchart model.
- venn
- Mermaid venn diagrams (MVENN-*): sets drawn as circles sized and overlapped by their sizes.
- wardley
- Mermaid Wardley maps (MWARD-*): components placed by visibility and evolution, linked along their value chain.
- xychart
- Mermaid XY charts (MXY-*): bar and line series over a category or numeric x-axis.
- zenuml
- ZenUML sequence diagrams (MZEN-*), lowered to the sequence diagram model.