mscgen_js - core package
Implementation of MscGen and two derived languages in JavaScript.
This is the JavaScript library that takes care of parsing and
rendering MscGen into sequence diagrams. You might be looking for one
of these in stead:
Features
- Parses and renders MscGen
- Accepts all valid MscGen programs and render them correctly to
sequence diagrams.
- All valid MscGen programs accepted by mscgen_js are also accepted and
rendered correctly by the original
mscgen
command. - If you find proof to the contrary: tell us.
- Parses and renders Xù
Xù is a strict superset of MscGen. It adds things like alt
and
loop
. - Parses and renders MsGenny
Same as Xù, but with a simpler syntax. - Translates between these three languages
- Spits out svg, GraphViz dot, doxygen and JSON.
- runs in all modern browsers (and in Node.js).
I'm still here. How can I use this?
Prerequisites
mscgenjs works in anything with an implementation of the document object model
(DOM). This includes web-browsers, client-side application shells like electron
and even headless browsers like chrome headless and phantomjs. It does _not
include nodejs (although it is possible to get it sorta to work even there with
jsdom or with a headless browser).
Get it
npm install mscgenjs
Import it
You'll have to import the mscgenjs module somehow. There's a commonjs, an es2015
and a requirejs variant, all distributed in the mscgenjs
npm module
(repo: mscgenjs/mscgenjs-core).
const mscgenjs = require("mscgenjs");
const mscgenjs = require("mscgenjs/dist/cjs/index-lazy");
define(["./node_modules/mscgenjs/dist/bundle/index.min"], function (mscgenjs) {
});
define(function (require) {
var mscgenjs = require("./node_modules/mscgenjs/dist/bundle/index.min");
});
import { renderMsc } from "mscgenjs";
Previously, as a workaround for webpack
issue webpack/webpack#5316
you needed to include webpack-issue-5316-workaround
from the
dist
folder. That's not necessary anymore; using require('mscgenjs')
or import {renderMsc} from 'mcgenjs'
works fine.
Use it
- use the root module directly => recommended
e.g. atom-mscgen-preview takes that approach. See the samples below - individually do calls to the parse and render steps => do this when you have
special needs.
This is the approach the mscgen_js and mscgenjs-inpage script take. The main
reason these aren't using the root module directly is that it did not exist
at the time they were written (JUN 2013 and APR 2014 respectively).
Link to where this happens in mscgen_js
and one
where it happens in mscgenjs-inpage.
Here's some some samples for using the root module directly:
mscgenjs.renderMsc (
'msc { a,b; a=>>b[label="render this"; }',
{
elementId: "yourCoolId"
}
);
If you want to do error handling, or act on the created svg: provide a callback:
mscgenjs.renderMsc(
'msc { a,b; a=>>b[label="render this"; }',
{
elementId: "yourOtherCoolId",
},
handleRenderMscResult
);
function handleRenderMscResult(pError, pSuccess) {
if (Boolean(pError)) {
console.log(pError);
return;
} else if (Boolean(pSuccess)) {
console.log("That worked - cool!");
return;
}
console.log("Wat! Error nor success?");
}
The second parameter in the renderMsc
call takes some options that influence rendering e.g.
mscgenjs.renderMsc (
'a=>>b:render this;',
{
elementId: "yourThirdCoolId",
inputType: "msgenny",
mirrorEntitiesOnBottom: true,
additionalTemplate: "lazy",
includeSource: false,
},
In doc/samples you'll find a simple dynamic integration using
webpack and one using requirejs.
Transpiling
You can use the second function of the root module for transpiling to and from
msgenny, mscgen, xù and json and for exporting to dot and doxygen. This function
does not depend on the DOM so you can use it not only in browsers &
browser-likes, but also hack-free in node.
try {
let lResult = mscgenjs.translateMsc(
'wordwraparcs=on; you =>> me: can we translate this to Mscgen please?; me >> you: "yes, you can - use translateMsc";',
{
inputType: "msgenny",
outputType: "mscgen",
}
);
console.log(lResult);
} catch (pError) {
console.error(pError);
}
Battle tested implementations
Software that uses mscgenjs
:
Hacking on mscgenjs itself
Building mscgenjs
See build.md.
How does mscgenjs work?
You can start reading about that over here
License
This software is free software licensed under GPLv3.
This means (a.o.) you can use it as part of other free software, but
not as part of non free software.
Dependencies and their licenses
We built mscgen_js on various libraries, each of which have their own
license:
It uses tslint and dependency-cruiser to maintain some
modicum of verifiable code quality. You can see the build history in
GitHub actions.
Thanks
- Mike McTernan for creating the wonderful
MscGen language, the accompanying c implementation and for releasing both
to the public domain (the last one under a GPLv2 license
to be precise).
- David Majda for cooking the fantastic and lightning fast
peggy parser generator.
- Elijah Insua for jsdom, which allows us to
test rendering vector graphics in Node.js without having to resort
to outlandish hacks.
Build status