feature(*): introduce a 'module' index (#51)

Adds ES2015 modules to the distribution:

ES2015 modules in dist/es2015
a module key in package.json to indicate to webpack || rollup where to find them
a sideEffects key (with value false) to indicate there's no side-effects in this package.
Also reorganises the dist folder a bit - it now has separate folders for the cjs distribution (the default one - it's where main in package.json points to), es2015 (see above) and bundle - which is a webpack'ed, minimised version of the css distribution.

Why?

es2015 modules have some benefits in use over cjs - it a.o. enables build tools to weed out unused code ('tree shaking').

README.md

@@ -37,8 +37,8 @@ include nodejs (although it is possible to get it sorta to work even there with
 `npm install mscgenjs`
 
 ### Import it
-You'll have to import the mscgenjs module somehow. There's a commonjs and a
-requirejs variant, both of which are in the `mscgenjs`
+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](https://www.npmjs.com/package/mscgenjs)
 (repo: [mscgenjs/mscgenjs-core](https://github.com/mscgenjs/mscgenjs-core)).
 
@@ -50,27 +50,36 @@ const mscgenjs = require('mscgenjs');
 ```javascript
 // 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/index-lazy');
+const mscgenjs = require('mscgenjs/dist/cjs/index-lazy');
 ```
 
 ```javascript
 // requirejs - assuming the module is in your root and you're loading from
 //             node_modules.
-define(['./node_modules/mscgenjs/dist/index.min'], function(mscgenjs){
+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/index.min");
+    var mscgenjs = require("./node_modules/mscgenjs/dist/bundle/index.min");
     // your code here
 });
 ```
+
+```javascript
+// 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](https://github.com/webpack/webpack/issues/5316)
 > you needed to include `webpack-issue-5316-workaround` from the
 > `dist` folder. That's not necessary anymore; using `require('mscgenjs')`
-> works fine.
+> or `import {renderMsc} from 'mcgenjs'` works fine.
 
 ### Use it
 

dist/index-lazy.js → dist/cjs/index-lazy.js

@@ -1,9 +1,16 @@
 "use strict";
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
+    result["default"] = mod;
+    return result;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 exports.__esModule = true;
-var main_1 = __importDefault(require("./main"));
+var main = __importStar(require("./main"));
 var lazy_resolver_1 = __importDefault(require("./main/lazy-resolver"));
 /**
  * Exactly the same interface as @index.js - the only difference is that the
@@ -14,22 +21,22 @@ module.exports = {
      * See the function of the same name in @index.js.
      */
     renderMsc: function (pScript, pOptions, pCallBack) {
-        main_1["default"].renderMsc(pScript, pOptions || {}, pCallBack, lazy_resolver_1["default"].getParser, lazy_resolver_1["default"].getGraphicsRenderer);
+        main.renderMsc(pScript, pOptions || {}, pCallBack, lazy_resolver_1["default"].getParser, lazy_resolver_1["default"].getGraphicsRenderer);
     },
     /**
      * See the function of the same name in @index.js.
      */
     translateMsc: function (pScript, pOptions) {
-        return main_1["default"].translateMsc(pScript, pOptions || {}, lazy_resolver_1["default"].getParser, lazy_resolver_1["default"].getTextRenderer);
+        return main.translateMsc(pScript, pOptions || {}, lazy_resolver_1["default"].getParser, lazy_resolver_1["default"].getTextRenderer);
     },
     /**
      * See the variable of the same name in @index.js.
      */
-    version: main_1["default"].version,
+    version: main.version,
     /**
      * See the variable of the same name in @index.js.
      */
-    getAllowedValues: main_1["default"].getAllowedValues,
+    getAllowedValues: main.getAllowedValues,
     /**
      * See the function of the same name in @index.js
      */

dist/cjs/index.js

@@ -0,0 +1,135 @@
+"use strict";
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (Object.hasOwnProperty.call(mod, k)) result[k] = mod[k];
+    result["default"] = mod;
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+exports.__esModule = true;
+var main = __importStar(require("./main/index"));
+var static_resolver_1 = __importDefault(require("./main/static-resolver"));
+/**
+ * parses the given script and renders it in the DOM element with
+ * id pOptions.elementId.
+ *
+ * @param  {string} pScript     The script to parse and render. Assumed
+ *                              to be MscGen - unless specified
+ *                              differently in pOptions.inputType
+ * @param  {object} pOptions    options influencing parsing and
+ *                              rendering. See below for the complete
+ *                              list.
+ * @param  {function} pCallBack function with error, success
+ *                              parameters. renderMsc will pass the
+ *                              resulting svg in the success parameter
+ *                              when successful, the error message
+ *                              in the error parameter when not.
+ * @return none
+ *
+ * Options:
+ *  elementId: the id of the DOM element to render in. Defaults to
+ *             "__svg". renderMsc assumes this element to exist.
+ *  inputType: language to parse - default "mscgen"; Possible values:
+ *             allowedValues.inputType
+ *  mirrorEntitiesOnBottom: draws entities on both top and bottom of
+ *             the chart when true. Defaults to false.
+ *  additionalTemplate: use one of the predefined templates. Default
+ *             null/ empty. Possible values: allowedValues.namedStyle
+ *  includeSource: whether the generated svg should include the script
+ *             in a desc element or not. Defaults to false
+ */
+function renderMsc(pScript, pOptions, pCallBack) {
+    main.renderMsc(pScript, pOptions || {}, pCallBack, static_resolver_1["default"].getParser, static_resolver_1["default"].getGraphicsRenderer);
+}
+exports.renderMsc = renderMsc;
+/**
+ * Translates the input script to an outputscript.
+ *
+ * @param  {string} pScript     The script to translate
+ * @param  {object} pOptions    options influencing parsing & rendering.
+ *                              See below for the complete list.
+ * @return {string} - the translated script
+ * @throws {Error} - when there's something wrong
+ *
+ * Options:
+ *   inputType  : the language of pScript defaults to "mscgen". Possible
+ *                values: allowedValues.inputType
+ *   outputType : defaults to "json". Possible values:
+ *                allowedValues.outputType
+ */
+function translateMsc(pScript, pOptions) {
+    return main.translateMsc(pScript, pOptions || {}, static_resolver_1["default"].getParser, static_resolver_1["default"].getTextRenderer);
+}
+exports.translateMsc = translateMsc;
+/**
+ * The current (semver compliant) version number string of
+ * mscgenjs
+ *
+ * @type {string}
+ */
+exports.version = main.version;
+/**
+ *
+ * An object with arrays of allowed values for parameters in the
+ * renderMsc and translateMsc functions. Each entry in these
+ * arrays have a name (=the allowed value) and a boolean "experimental"
+ * attribute. If that attribute is true, you'll hit a feature that is
+ * under development when use that value.
+ *
+ * pOptions.inputType
+ * pOptions.outputType
+ * pOptions.namedStyle
+ *
+ */
+exports.getAllowedValues = main.getAllowedValues;
+/**
+ * returns a parser module for the given language. The module exposes
+ * a parse(pString) function which returns an abstract syntax tree in
+ * json format as described in the link below.
+ *
+ * https://github.com/mscgenjs/mscgenjs-core/blob/master/parse/README.md#the-abstract-syntax-tree
+ *
+ * @param {string} pLanguage the language to get a parser for
+ *                           Possible values: "mscgen", "msgenny", "xu"
+ *                           "json". Defaults to "mscgen"
+ * @return {object}
+ */
+exports.getParser = static_resolver_1["default"].getParser;
+/**
+ * returns a renderer that renders the abstract syntax tree as a scalable
+ * vector graphics (in practice: @render/graphics/renderast)
+ *
+ * @deprecated use renderMsc instead to render graphics
+ *
+ * @return {object}
+ */
+exports.getGraphicsRenderer = static_resolver_1["default"].getGraphicsRenderer;
+/**
+ * returns a renderer to the given language. The module exposes a
+ * render(pAST) function which returns a rendition of the abstract
+ * syntax tree it got passed into the given language
+ *
+ * @deprecated use translateMsc instead to render text
+ *
+ * @return {object}
+ */
+exports.getTextRenderer = static_resolver_1["default"].getTextRenderer;
+/*
+ This file is part of mscgen_js.
+
+ mscgen_js is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ mscgen_js is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with mscgen_js.  If not, see <http://www.gnu.org/licenses/>.
+ */

dist/main/index.js → dist/cjs/main/index.js

@@ -5,7 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 exports.__esModule = true;
 var allowedvalues_1 = __importDefault(require("./allowedvalues"));
 var normalizeoptions_1 = __importDefault(require("./normalizeoptions"));
-var $package = require("../../package.json");
+var $version = require("../version.json");
 function isProbablyAnASTAlready(pScript, pInputType) {
     return pInputType === "json" && typeof pScript === "object";
 }
@@ -28,40 +28,41 @@ function runCallBack(pCallBack, pError, pResult) {
         }
     }
 }
-exports["default"] = {
-    renderMsc: function (pScript, pOptions, pCallBack, pGetParser, pGetGraphicsRenderer) {
-        var lOptions = normalizeoptions_1["default"](pOptions, pScript);
-        try {
-            runCallBack(pCallBack, null, pGetGraphicsRenderer().render(getAST(pScript, lOptions.inputType, pGetParser), lOptions.window, lOptions.elementId, {
-                source: lOptions.source,
-                styleAdditions: lOptions.styleAdditions,
-                additionalTemplate: lOptions.additionalTemplate,
-                mirrorEntitiesOnBottom: lOptions.mirrorEntitiesOnBottom,
-                regularArcTextVerticalAlignment: lOptions.regularArcTextVerticalAlignment
-            }));
-        }
-        catch (pException) {
-            runCallBack(pCallBack, pException);
-        }
-    },
-    translateMsc: function (pScript, pOptions, pGetParser, pGetTextRenderer) {
-        var lOptions = Object.assign({
-            inputType: "mscgen",
-            outputType: "json"
-        }, pOptions || {});
-        if (lOptions.outputType === "ast") {
-            return pGetParser(lOptions.inputType).parse(pScript);
-        }
-        if (lOptions.outputType === "json") {
-            return JSON.stringify(pGetParser(lOptions.inputType).parse(pScript), null, "  ");
-        }
-        return pGetTextRenderer(lOptions.outputType).render(getAST(pScript, lOptions.inputType, pGetParser));
-    },
-    version: $package.version,
-    getAllowedValues: function () {
-        return allowedvalues_1["default"];
+function renderMsc(pScript, pOptions, pCallBack, pGetParser, pGetGraphicsRenderer) {
+    var lOptions = normalizeoptions_1["default"](pOptions, pScript);
+    try {
+        runCallBack(pCallBack, null, pGetGraphicsRenderer().render(getAST(pScript, lOptions.inputType, pGetParser), lOptions.window, lOptions.elementId, {
+            source: lOptions.source,
+            styleAdditions: lOptions.styleAdditions,
+            additionalTemplate: lOptions.additionalTemplate,
+            mirrorEntitiesOnBottom: lOptions.mirrorEntitiesOnBottom,
+            regularArcTextVerticalAlignment: lOptions.regularArcTextVerticalAlignment
+        }));
     }
-};
+    catch (pException) {
+        runCallBack(pCallBack, pException);
+    }
+}
+exports.renderMsc = renderMsc;
+function translateMsc(pScript, pOptions, pGetParser, pGetTextRenderer) {
+    var lOptions = Object.assign({
+        inputType: "mscgen",
+        outputType: "json"
+    }, pOptions || {});
+    if (lOptions.outputType === "ast") {
+        return pGetParser(lOptions.inputType).parse(pScript);
+    }
+    if (lOptions.outputType === "json") {
+        return JSON.stringify(pGetParser(lOptions.inputType).parse(pScript), null, "  ");
+    }
+    return pGetTextRenderer(lOptions.outputType).render(getAST(pScript, lOptions.inputType, pGetParser));
+}
+exports.translateMsc = translateMsc;
+exports.version = $version.version;
+function getAllowedValues() {
+    return allowedvalues_1["default"];
+}
+exports.getAllowedValues = getAllowedValues;
 /*
  This file is part of mscgen_js.
 

dist/cjs/version.json

@@ -0,0 +1,3 @@
+{
+  "version": "3.0.0-beta-2"
+}

dist/es2015/index-lazy.js

@@ -0,0 +1,56 @@
+import * as main from "./main";
+import resolver from "./main/lazy-resolver";
+/**
+ * Exactly the same interface as @index.js - the only difference is that the
+ * functions only load dependencies at the moment they need them.
+ */
+module.exports = {
+    /**
+     * See the function of the same name in @index.js.
+     */
+    renderMsc(pScript, pOptions, pCallBack) {
+        main.renderMsc(pScript, pOptions || {}, pCallBack, resolver.getParser, resolver.getGraphicsRenderer);
+    },
+    /**
+     * See the function of the same name in @index.js.
+     */
+    translateMsc(pScript, pOptions) {
+        return main.translateMsc(pScript, pOptions || {}, resolver.getParser, resolver.getTextRenderer);
+    },
+    /**
+     * See the variable of the same name in @index.js.
+     */
+    version: main.version,
+    /**
+     * See the variable of the same name in @index.js.
+     */
+    getAllowedValues: main.getAllowedValues,
+    /**
+     * See the function of the same name in @index.js
+     */
+    getParser: resolver.getParser,
+    /**
+     * See the function of the same name in @index.js
+     */
+    getGraphicsRenderer: resolver.getGraphicsRenderer,
+    /**
+     * See the function of the same name in @index.js
+     */
+    getTextRenderer: resolver.getTextRenderer,
+};
+/*
+This file is part of mscgen_js.
+
+mscgen_js is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+mscgen_js is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with mscgen_js.  If not, see <http://www.gnu.org/licenses/>.
+*/