Skip to main content

Crate sirene_core

Crate sirene_core 

Source
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_col gives 1-based positions, diagnostic::LineIndex many of them). The diagram is still drawn.
  • A diagram’s own theme and themeVariables apply over the theme passed in.
  • Lowered::scene gives the display list for other renderers, with text measured by any scene::TextMetrics.
  • scene::png (feature png) writes PNGs with embedded Noto Sans faces, so images are the same on every machine.
  • flowchart::parse and flowchart::edit give the flowchart syntax tree and turn changes to the diagram into minimal source edits.
  • Rendering returns sirene_core::Result. Errors retain typed causes through std::error::Error::source(); use error.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): theme and themeVariables from its frontmatter config: 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’s src/themes/ (Copyright (c) 2014-2022 Knut Sveidqvist; MIT) and khroma’s adjust, lighten, darken, and invert; 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.

Structs§

TextRange
A range in text, represented as a pair of TextSize.
TextSize
A measure of text length. Also, equivalently, an index into text.