script

mscgen_js' innards

Here's some notes to ease the job of maintaining mscgen_js. It attempts to describe how it does what it does and it tries to explain some of the choices.

The main steps mscgen_js takes to get from a textual description to a picture:

• lexical analysis and parsing to an abstract syntax tree.
• rendering that abstract syntax tree into a picture.
• Besides these two steps it is useful to have some sort of controler program that handles interaction with the user. We have four of them:
  • for embedding textual descriptions in html
  • for the interactive interpreter
  • for the command line interface
  • for the atom editor package

Lexical analysis and parsing

📃 code in parse/peg

We wrote the parsers for mscgen, msgenny and xù with PEG.js. This is a parser generator that smashes the tasks of lexical analysis and parsing together. In the parser folder we describe

• how to generate the parsers from pegjs
• the structure of and principles behind the abstract syntax trees

Rendering

Rendering graphics

📃 code in render/graphics/

mscgen_js by default renders its graphics to scalable vector graphics (SVG). In the render folder we

• motivate this choice,
• describe how our SVG is structured and
• how the rendering programs fill it.

Rendering text

📃 code in render/text/

To translate between the three sequence chart languages it supports and to generate and manipulate other languages.

Raster graphics?

📃 code in ui/interpreter/raster-exporter.js

You might have noticed the interpreter also renders to jpeg and png. It uses the canvas methods drawImage() (to render it on the canvas) and toDataURL to extract the raster.

The controllers

Embedding

📃 code in mscgen-inpage.js

The controller for embedding is actually very simple. Details on how it works and what design choices we made you can find here.

Interactive interpreter

📃 code in ui/interpreter

The controller for the interpreter UI is less trivial.

Testing

📃 code in test/

About 300 automated tests (and counting) make sure we can refactor most of the back end code (parsing and rendering) safely.

The ui controller tests are inherently harder to test automated. This is why we did testing with a pair of eyeballs until now. We plan to change that.