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.

{{< figure src="/images/posts/example_mermaid.svg" title="example_mermaid.svg" >}}

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.

{{< figure src="/images/posts/example_pyviewer.svg" title="example_pyviewer.svg" >}}

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

Live viewer command line script

The bash script below uses feh, an X11 image viewing utility, inotify-tools and ImageMagic from the command line to provide a live view of a mmd file that is built as changes are made to the file.

#!/usr/bin/env bash
function usage() {
  usage_str="$(basename "${BASH_SOURCE[0]}") IN_FILE OUT_FILE"
  usage_str+="[ --config=<Config File> | -c <Config File> ] "
  usage_str+="[ -h | --help ]"
  cat <<<"
Usage:
  $usage_str
Options:
  -c | --config:      Specify CSS style for Mermaid diagram
                      Default: None
  -h | --help:        Displays this menu
  "
  exit 1
}
function main() {
  local ARGS=("-i" "$1" "-o" "$2")
  case "$1" in
    -c)            ARGS=("-i" "$3" "-o" "$4" "-c" "$2");;
    --config=*)    ARGS=("-i" "$2" "-o" "$3" "-c" "${1#*=}");;
    -h|--help)     usage;;
    -*)            echo "Invalid Option: $1"; usage ;;
  esac
  # echo "IN:${ARGS[1]}  OUT:${ARGS[3]}"
  mmdc ${ARGS[@]} &> /dev/null
  mogrify -trim "${ARGS[3]}"
  feh --reload 2 "${ARGS[3]}" &
  sleep 0.1
  inotifywait -qm --event modify --format '%w' "${ARGS[1]}" | \
   ( mmdc ${ARGS[@]} ; mogrify -trim "${ARGS[3]}" ) &> /dev/null
}
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  if [ "$#" -lt 2 ] || [ "$#" -gt 4 ] ; then
    usage
  fi
  main "$@"
fi