README.md

mscgen_js - command line interface

Render sequence charts from the command line

What's this do?

• It makes sequence charts (in svg, png or jpeg) from your MscGen scripts. From the command line.
• It also does so for your Xù and MsGenny scripts.
• There's a boatload of other things it can do - see below.

Cool. How do I install it?

npm install --global mscgenjs-cli

How do I use this?

mscgenjs coolchart.mscgen

This will generate coolchart.svg from coolchart.mscgen:

But I want png's!

mscgenjs -T png coolchart.mscgen

But ...

• But isn't it more practical to have an interactive interpreter for this?
  When you edit sequence charts: definitely!
  • Scoot over to mscgen.js.org for an on line interpreter.
  • If you're using atom you'll love the mscgen-preview package.
• But there's also the original mscgen.
  • Yes there is. The original is a lot faster too. And it's the reference implementation for MscGen.
  • It also provides .eps as an output format, which mscgenjs doesn't.
• So, why should I use this instead?
  • mscgenjs understand Xù or MsGenny - so if you'd want to use things like alt or loop you can just do that.
  • It converts to other formats, a.o. to graphviz dot so you can present your chart as a directed graph.
  • mscgenjs' graphics look a bit different - you might like em better (but then again, you might not)

More options?

Yes. Run mscgenjs with -h or --help to get them all:

  Usage: mscgen_js [options] [infile]

  Options:

    -V, --version                    output the version number
    -T --output-type <type>          svg|png|jpeg|mscgen|msgenny|xu|json|ast|dot|doxygen
    -I --input-type <type>           mscgen|msgenny|xu|json|ast
    -i --input-from <file>           File to read from. use - for stdin.
    -o --output-to <file>            File to write to. use - for stdout.
    -p --parser-output               Print parsed msc output
    -s --css <string>                Additional styles to use. Experimental
    -n --named-style <style>         basic|lazy|classic|noentityboxes
    -m --mirror-entities             Repeat the entities on the chart's
                                     bottom
    -v --vertical-alignment <align>  Vertical alignment of labels on regular
                                     arcs. Experimental
                                     above|middle|below (default: middle)
    --puppeteer-options <file>       (advanced) pass puppeteer launch options
                                     see README.md for details
    -l --license                     Display license and exit
    -h, --help                       output usage information

Basic use: produce pictures from a script

This will generate a sequence chart called intro02_starter.svg in the same directory as the intro02_start.mscgen script

mscgenjs intro02_starter.mscgen

If you want to have the output go somewhere else, specify it:

mscgenjs -o othername.svg intro02_starter.mscgen

mscgenjs will try to guess the type of script from the extension. Here it will guess the input to be Xù. If it doesn't know, it'll assume it got MscGen passed.

mscgenjs test51_with_alt.xu

If you want to override the guessing use -I, so to force the input to be parsed as MscGen:

mscgenjs -I mscgen test51_with_alt.xu

Conversion

When presented with an output file name, mscgenjs will try to guess the type of output desired from the extension.

mscgenjs w00t.xu -o myoutput.png # writes a chart in png format to myoutput.png
mscgenjs w00t.xu -o flatter.msc # converts w00t.xu to MscGen and writes it to flatter.msc

With -T (or --output-type you can specify the type of output if you want to override the output type. By default mscgen.js assumes svg.

Some other formats:

To convert an Xù or MsGenny script with advanced options back to vanilla MscGen (without advanced options):

mscgenjs  -T mscgen -i funky.xu funky.mscgen

To convert an MscGen script to graphviz dot:

mscgenjs -T dot -i intro02_starter.mscgen intro02_starter.dot

To convert to raster graphics ('png' and 'jpeg')

mscgenjs -T png -i dolores.mscgen -o dolores.png

You can also send specify standard output as a destination, so you can pipe the output to something else. E.g. to graphviz dot to further process a dot program:

mscgenjs -T dot -i intro02_starter.mscgen -o - | dot -Tsvg > communicationsdiagram.svg

Parser output and input

To show how the parser interpreted your input into an abstract syntax tree you can - just like in the original mscgen program - use the -p option

mscgenjs -p -o parsed.json intro02_starter.mscgen

... but the abstract syntax tree is a full fledged output format, so you can also do this:

mscgenjs -i intro02_starter.mscgen -o parsed.json

You can in turn render the abstract syntax tree by specifying it as input type:

mscgenjs parsed.json

Named styles

mscgenjs contains a few 'baked in' styles that tweak the way its output looks a bit.

mscgenjs -i samples/recaptcha-integration.msgenny -n lazy

mscgenjs currently recognizes these styles:

• lazy
  • uses a bold font for entity names (instead of underlining them)
  • gives notes a soft yellow background
  • prints return value text in italics
  • inline expression boxes get a dark grey outline (instead of the default black)
• classic mimics the vanilla mscgen output
  • makes all lines 1 pixel wide
  • entities are just text - not boxes
• cygne a light blue/ orange scheme. If your chart already contains colors this named style will probably be unhelpful.
• pegasse a dark blue/ red scheme. Also not very helpful for already colored charts.

samples/style-variants shows how these look when you apply them on the cheat sheet.

Although not mentioned in the command line interface's --help, grayscaled and inverted are also valid named styles. They insert a css filter into the svg to do what their names imply. This works splendidly in many browsers, but it doesn't in some (safari, IE). Hence use with caution.

Manual styles (experimental)

You can influence a how charts look even further by providing css rules that override the ones baked into mscgenjs. It's quite raw, the interface might change in the next version and does not read style rules from external files (yet), but it is working for the brave of heart.

E.g. to override the default sans-serif font with a serif one

mscgenjs -i samples/recaptcha-integration.msgenny -s "svg{font-family:serif}"

... or to use bold instead of underlined entity labels

mscgenjs -i samples/recaptcha-integration.msgenny -s "text.entity-text{font-weight:bold;text-decoration:none}"

Near the bottom of this README you'll find a list of elements and class names that can occur in generated svg's.

Elements and classes you can style

Note: experimental. Class names are subject to change (as is the whole styling feature), and mscgenjs might not respond to all style rules yet due to the way it constructs the svg at the moment. E.g. coloring arcs won't work as mscgenjs inserts a style attribute to set the color of these and executes some voodoo to make sure the arrow heads are in the same color as the arc.

• svg, line, rect, path, text
• rect: .entity .box .rbox .inline_expression .label-text-background .bglayer
• line and path (for selfs): .arc .directional .nondirectional, .bidirectional .signal .method .return .callback .lost .emphasised
• line and path: .box
• line only: .comment .inline_expression_divider
• path only: .note .abox .inline_expression_label
• text: .entity-text .box-text .note-text .rbox-text .abox-text .empty-row-text .directional-text .nondirectional-text .bidirectional-text .signal-text .method-text .return-text .callback-text .lost-text .emphasised-text
• .watermark

Vertical alignment

By default on regular arcs (->, =>, =>>, --, -x :>) longer labels vertically align so the arc itself stays in the middle. It's possible to influence that by making the label stay above the arc.

By default it looks like this:

When you run the command with --vertical-alignment above:

Puppeteer options (advanced)

Under the hood mscgenjs-cli uses puppeteer - the javascript wrapper around Chrome headless - for rendering graphics. puppeteer does a good job of abstracting a lot and running out of the box in most enviromnents, but on some it needs some convincing. For this it has a host of launch options, and some guidance.

mscgenjs-cli's --puppeteer-options takes a JSON file with (a subset of the) puppeteer options which it passes 1:1 to puppeteer.

mscgenjs coolchart.mscgen --puppeteer-options puppeteer-config.json

The puppeteer options mscgenjs-cli accepts:

• args
• devtools
• headless
• executablePath
• slowMo
• timeout

An example puppeteer-config.json to make things work on Fedora (assuming google-chrome is installed in /usr/bin):

{
  "executablePath": "/usr/bin/google-chrome",
  "args": ["--no-sandbox", "--disable-setuid-sandbox"]
}

You can also use this to make visible what mscgenjs-cli is doing under the hood by adding some debugging options:

{
  "headless": false,
  "slowMo": 500,
  "devtools": true
}

What is the license?

GPL-3.0

How does mscgenjs render?

• It uses the (pure javascript) mscgen_js library.
• For graphical formats (svg, png, jpeg) it uses mscgen_js in chrome headless via the puppeteer library.