hugo-site/content/posts/2021/mermaid-uml.md

title	date	draft	toc	images	tags
Unified Modelling Language 🐬	2021-10-30T15:42:47+02:00	false	false		svg uml code

Mermaid CLI

Mermaid is a JS based diagram and charting tool which aspires to generate diagrams in a markdown fashion. The main advantage here is that Mermaid is well integrated into quite a few editing and content management packages. There is command-line node-package that installs on both linux and WSL environments. You do need NPM version 10+ so installing in Windows takes a few extra steps in order to get the latest version.

npm install @mermaid-js/mermaid-cli

Additionally this package will sandbox a instance of chromium which doesn't operate correctly with WLS version 1. Upgrading to WLS version 2 will allow you to run the following example using mmdc -i input.mmd -o output.svg -c config.json.

graph LR
    S[fa:fa-dot] --> A
    A{foo}
    A --> B(bar)
    A --> C(baz)
    style S fill:none, stroke:none

This example generates the diagram show below.

There are four base themes: dark, default, forest, neutral. Additional customization is possible. The config.json is shown below which sets similar styling as [before]({{< relref "building-svg.md" >}} "building svg") using the other command-line tools.

{
  "theme": "neutral",
  "themeVariables": {
      "fontFamily":"monospace",
      "fontSize":"14px",
      "classText" : "white",
      "nodeBorder" : "white",
      "nodeTextColor" : "white",
      "lineColor" : "white",
      "arrowheadColor" : "white",
      "mainBkg" : "none"
  }
}

UML diagrams

Mermaid is quite a bit more versatile and is geared towards making structured diagrams of classes and inter-related structures. For example the UML diagram below presents the overall composition of [pyviewer]({{< relref "pyside.md" >}} "pyside") which is image simple browsing utility for compressed archives.

This does quite well at illustrating how classes are composed and which methods are available at various scopes. It also helps organizing and structuring a code-base when there means to reason in a visual way. The source code for this diagram is shown below for reference.

classDiagram
     class ApplicationWindow{
          int[2] layout
          int max_count
          navigate(keyPress)
          update()
      }
      class PyViewer{
        signal image_changed
        load_file_map(str path)
        load_archive(int index)
        set_max_count(int max_count)
      }
      class ArchiveLoader{
        generate_map(str path)
        extract_current_index()
        check_media()
      }
      class ArchiveManager{
          int max_count
          Qbyte[] images
          load_archive(str archive_path)
      }
      class TagManager{
          int index
          dict media_map
          dict tag_filter
          list tag_history
          update_filter(str tag, bool state)
          undo_last_filter()
          adjust_index(int change)
          tag_at(int index)
          set_index(str tag_name)
      }
      ArchiveLoader <|-- TagManager
      ArchiveLoader <|-- ArchiveManager
      PyViewer <-- ArchiveLoader
      PyViewer <-- ApplicationWindow