MermaidJS::Grammar

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

Languages and formats Mermaid-JS is translated to:

• DONE Raku
  • DONE Flowcharts
    • Translation to Raku hashmap structure with keys "nodes", "edges", and "styles".
  • DONE Mind-maps
  • TODO Class diagrams
    • This can be very involved.
    • It is the inverse operation of the ones provided by "UML::Translators", [AAp1].
• DONE JSON
  • Simple JSON serialization from Raku-actions results.
  • DONE Flowcharts
  • DONE Mind-maps
• 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
  • TODO Flowcharts
    • DONE Basic vertexes and edges
    • TODO Vertex styles
    • TODO Edge styles
  • TODO Mind-maps
    • In principle, it can be done from the Raku interpretations by "Mathematica::Serializer", [AAp2].
    • Maybe, it is better not to have the dependency, though.

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

• DONE Flowcharts
• TODO Class diagrams
• TODO Mind-maps
  • Much simpler to parse and interpret than class diagrams.
• TODO Sequence diagrams
• TODO ERD diagrams

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

---

Installation

From Zef ecosystem:

zef install MermaidJS::Grammar

---

Usage examples

Flowcharts

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

flowchart TD
  A[Start] --> B{Decide}
  B -->|Yes| C[Do thing]
  B -->|No| D[Stop]

Loading

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 => [], type => flowchart}

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}]

Mind-maps

Here is Mermaid-JS mind-map spec:

my $spec = q:to/EOF/,
mindmap
    root((Joke))
        "Characters"
            "Priest"
            "Rabbit"
            "Minister"
        "Setting"
            "Bar"
        "Action"
            "Walkintobar"
            "Bartender asks rabbit"
                "What to drink"
            "Rabbit's response"
                "No idea"
                "Autocorrect"
EOF

mindmap
    root((Joke))
        "Characters"
            "Priest"
            "Rabbit"
            "Minister"
        "Setting"
            "Bar"
        "Action"
            "Walkintobar"
            "Bartender asks rabbit"
                "What to drink"
            "Rabbit's response"
                "No idea"
                "Autocorrect"

Loading

Translate the mind-map into a Raku hashmap of hashmaps:

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

# {root => {Joke => {Action => {Bartender asks rabbit => {What to drink => {}}, Rabbit's response => {Autocorrect => {}, No idea => {}}, Walkintobar => {}}, Characters => {Minister => {}, Priest => {}, Rabbit => {}}, Setting => {Bar => {}}}}, type => mindmap}

---

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 <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, UML::Translators. Raku package, (2021-2024), GitHub/antononcube.

[AAp2] Anton Antonov, Mathematica::Serializer. Raku package, (2021-2022), GitHub/antononcube.

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