MermaidJS::Grammar

Raku package with a grammar for Mermaid-JS diagram specs.

Languages and formats Mermaid-JS is translated to:

• DONE Raku

  • Translation to Raku hashmap structure with keys "nodes", "edges", and "styles".

• DONE JSON

  • Simple JSON serialization from Raku-actions results.

• DONE Graphviz DOT

• TODO PlantUML

  • PlantUML uses DOT language, so, for flowcharts this should be a very short and easy format implementation based on DOT actions.

  • The current unfinished implementation tries to reuse the Raku actions. (Without good results.)

• TODO Mathematica / Wolfram Language

  • DONE Basic vertexes and edges

  • TODO Vertex styles

  • TODO Edge styles

Currently, Only Mermaid-JS flowcharts are parsed and translated. Here is list of the parser implementation priorities (most important first):

• Flowcharts

• Class diagrams

• Mind-maps

• Sequence diagrams

• ERD diagrams

A very similar Raku package is "Graphviz::DOT::Grammar", [AAp1].

Usage examples

Here is a Mermaid-JS spec:

my $spec = q:to/END/;
flowchart TD
  A[Start] --> B{Decide}
  B -->|Yes| C[Do thing]
  B -->|No| D[Stop]
END

Translate to Raku:

use MermaidJS::Grammar;
$spec ==> mermaid-js-interpret

# {edges => [{from => A, label => (Any), to => B, type => -->} {from => B, label => Yes, to => C, type => -->} {from => B, label => No, to => D, type => -->}], nodes => [{label => Start, name => A, type => rect} {label => Decide, name => B, type => rhombus} {label => Do thing, name => C, type => rect} {label => Stop, name => D, type => rect}], styles => []}

Translate to Graphviz DOT:

$spec ==> mermaid-js-interpret(a=>'DOT')

digraph G {
  "A" [label="Start", shape=box];
  "B" [label="Decide", shape=box];
  "C" [label="Do thing", shape=box];
  "D" [label="Stop", shape=box];
  "A" -> "B";
  "B" -> "C" [label="Yes"];
  "B" -> "D" [label="No"];
}

Translate to Mathematica / Wolfram Language Graph:

$spec ==> mermaid-js-interpret(a=>'Mathematica')

Graph[{DirectedEdge["A", "B"], DirectedEdge["B", "C"], DirectedEdge["B", "D"]}, VertexLabels -> {"A" -> Placed["Start", Center], "B" -> Placed["Decide", Center], "C" -> Placed["Do thing", Center], "D" -> Placed["Stop", Center]}, VertexShapeFunction -> {"A" -> "Rectangle", "B" -> "Rectangle", "C" -> "Rectangle", "D" -> "Rectangle"}, EdgeLabels -> {DirectedEdge["B", "C"] -> "Yes", DirectedEdge["B", "D"] -> "No"}, VertexSize -> {"Scaled", 0.1}]

CLI

The package provides the Command Line Interface (CLI) script from-mermaid-js. Here is its usage message:

from-mermaid-js --help

# Usage:
#   from-mermaid-js.raku <text> [-t|--to=<Str>] [-o|--output=<Str>] -- Converts Mermaid JS language texts or files into Graphviz DOT, JSON, Mathematica, PlantUML, or Raku files.
#   
#     <text>               Input file or Mermaid-JS spec.
#     -t|--to=<Str>        Format to convert to. (One of 'json', 'mathematica', 'dot', 'plantuml', 'raku', or 'Whatever'.) [default: 'Whatever']
#     -o|--output=<Str>    Output file; if an empty string then the result is printed to stdout. [default: '']

References

[AAp1] Anton Antonov, Graphviz::DOT::Grammar. Raku package, (2024), GitHub/antononcube.