Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

mscgenjs

Package Overview
Dependencies
Maintainers
2
Versions
87
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

mscgenjs

Sequence chart rendering library

  • 6.0.2
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
859
decreased by-37.62%
Maintainers
2
Weekly downloads
 
Created
Source

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ù 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).

// commonjs
const mscgenjs = require("mscgenjs");
// commonjs, but with lazy loading. Useful when you're using it in
// e.g. an electron shell without a minifier.
const mscgenjs = require("mscgenjs/dist/cjs/index-lazy");
// requirejs - assuming the module is in your root and you're loading from
//             node_modules.
define(["./node_modules/mscgenjs/dist/bundle/index.min"], function (mscgenjs) {
  // your code here
});

// ... or using the alternative notation
define(function (require) {
  var mscgenjs = require("./node_modules/mscgenjs/dist/bundle/index.min");
  // your code here
});
// es2015 modules
// if you're using webpack or rollup, it'll default to the es2015
// modules distributed in dist/es2015
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:

// renders the given script in the (already existing) element with id=yourCoolId
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;
    // the svg is in the pSuccess argument
  }
  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", // language to parse - default "mscgen"; other accepted languages: "xu", "msgenny" and "json"
    mirrorEntitiesOnBottom: true, // draws entities on both top and bottom of the chart - default false
    additionalTemplate: "lazy", // use a predefined template. E.g. "lazy" or "classic". Default empty
    includeSource: false, // whether the generated svg should include the source in a desc element
  },

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", // defaults to mscgen - other accepted formats: msgenny, xu, json
      outputType: "mscgen", // defaults to json - other accepted formats: mscgen, msgenny, xu, dot, doxygen, ast
    }
  );
  console.log(lResult);
} catch (pError) {
  console.error(pError);
}

// result:
//
// msc {
//   wordwraparcs=true;
//
//   you,
//   me;
//
//   you =>> me [label="can we translate this to Mscgen please?"];
//   me >> you [label="yes, you can - use translateMsc"];
// }

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

linting & test coverage coverage report npm stable version total downloads on npm GPL-3.0

Keywords

FAQs

Package last updated on 21 Aug 2022

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc