Skip to content

Latest commit

 

History

History
196 lines (170 loc) · 7.41 KB

msgenny.md

File metadata and controls

196 lines (170 loc) · 7.41 KB

MsGenny

Low effort labeling. Auto declarations

mscgen already is a simple, concise, well readable language. Write-ability leaves room for improvement, though. The MsGenny language is our attempt to fill that room. It does away with some of MscGen's more fancy features in favor of low effort labeling and automatic entity declarations. This enables you to set up a sequence chart very fast. See below for a complete comparison chart.

To have our cake and eat it too we made the mscgenjs online interpreter translate between the two with the flick of a switch. The interpreter also contains a complete tutorial on _MsGenny.

Example

a -> b : ab();
a => c : automatically declares entities used in arcs;
c =>> c : process(1);
b <<= c : Has all mscgen arc types... ;
b note b: ...notes + boxes ...;
|||;
--- : Labels usually don't need enclosing quotes;
--- : "except when they contain , or ;";
...;

this renders as

MsGenny sample

(open this chart in the online interpreter)

The equivalent mscgen program would have looked like this:

msc {
  a, b, c;

  a -> b [label="ab()"];
  a => c [label="automatically declares entities used in arcs"];
  c =>> c [label="process(1)"];
  b <<= c [label="Has all mscgen arc types... "];
  b note b [label="...notes + boxes ..."];
  |||;
  --- [label="Labels usually don't need enclosing quotes"];
  --- [label="except when they contain , or ;"];
  ...;
}

(open in the mscgen_js online interpreter)

Usage scenarios

We often find ourselves starting a sequence chart in MsGenny, and, when we're done, converting it to MscGen (one click in the on line interpreter). After that we either finish it with coloring or directly save the source to the documentation.

When in a hurry we directly use the rendered output from MsGenny.

A note on quotes

Just like in MscGen, in MsGenny labels need to be surrounded by quotes. To simplify entry, however, in most cases MsGenny allows you to skip the quotes. It only needs quotes when a label contains a comma or a semicolon:

    a => b : "hello b";  # works
    a => b :  hello b;   # works
    a => b : "hello; b"; # works
    a => b :  hello; b;  # doesn't work; confuses the parser to think the arc line stops after hello
    a => b : "hello, b"; # works
    a => b :  hello, b;  # doesn't work; confuses the parser to think the arc stops after hello

Formal syntax

The formal syntax is described in a parsing expression grammar. This grammar is used to generate the MsGenny parser as well.

Feature comparison

As mentioned above the online interpreter converts between MscGen and MsGenny, but the command line interface also does:

# Translate MsGenny => MscGen
mscgen_js -T mscgen -i yourchart.msgenny -o yourchart.mscgen

# Translate MscGen => MsGenny
mscgen_js -T msgenny -i yourchart.mscgen -o yourchart.msgenny
featureMscGenMsGenny
explicit entity declaration mandatory supported
implicit entity declaration not supported supported
Characters allowed in unquoted entity names A-Z0-9 Every unicode character, except;,"=-><:*{} and spaces ( \t\n\r)
Characters allowed in quoted entity names Every unicode character same as MscGen
labels on entities entity_name [label="this is the label"] entity_name : this is the label
labels on arcs, notes, boxes a =>> b [label="this is the label"]; a =>> b : this is the label;
explicit declaration of start and end of the program A mscgen program must start with msc { and must be ended by a } Needed nor supported
arc types a lot same as MscGen
notes, boxes, empty arcs supported same as MscGen
parallel calls use a comma between arcs: a=>b, a=>c; same as MscGen
broadcasts Use an asterisk as to or from: a=>*; same as MscGen
options hscale, arcgradient, width, wordwraparcs same as mscgen, plus "wordwrapentities", "wordwrapboxes" and "watermark" (which work as in xù)
comments # single line-style, // C++ type single line-style and /* multi line */-style same as MscGen
entity names alphanumericalstrings, "quoted strings" and 481 numbers same as MscGen
colors lines, text, background on entities, arcs and notes not supported
coloring all arcs departing from an entity declare by using the arc* property variants on the entity, e.g. arclinecolor="blue" not supported
id, url, idurl supported not supported
inline expressions (loop, alt, opt, neg, ...) not supported supported as it is in xù,