readme.md

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

Dependeny graph (generated with dependency-cruiser):

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 peggy
• 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 sverweij/mscgen_js/.../interpreter/raster-exporter.js

You might have noticed the interpreter also renders to jpeg and png. It uses the HTML5 canvas for it (and it's really trivial code).

The controllers

These are not in the 'core' package and serve as a reference of how you can use mscgenjs.

Simple samples

📃 code in samples

Implements an (on line) interpreter and renderer in a few lines of code.

Embedding

📃 code in sverweij/mscgen_js/.../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 sverweij/mscgen_js/.../interpreter

The controller for the interpreter UI is less trivial.

Command line interface

📃 code in sverweij/mscgenjs-cli

Atom preview package

📃 code in sverweij/atom-mscgen-preview

Testing

📃 code in ../test/

About 400 automated tests (and counting) make sure we can refactor the mscgen_js core modules safely.