Training Guide: Advanced Usage of Msgenny

This guide provides an overview of advanced features of msgenny, a modern syntax for describing message sequence charts (MSCs). This builds on the documentation found at msgenny.

Table of Contents

1. Introduction
2. Advanced Features
   • Loops
   • Alternatives
   • Parallel Blocks
   • Grouping Messages
   • Custom Arrows and Labels
   • Annotations
3. Full Example
4. References

Introduction

Msgenny is a concise syntax for describing MSCs, which are diagrams that visually represent interactions between entities in a system. This guide covers advanced features to enhance the expressiveness of your diagrams.

To get started with msgenny, refer to the official tutorial.

Advanced Features

Loops

Loops allow you to repeat a sequence of messages multiple times. Use the loop keyword, followed by a condition or number of iterations.

A -> B: Request data
loop (i < 5) {
    B -> A: Response i
}

Alternatives

Alternatives define conditional branches in the flow of messages. Use the alt keyword to represent choices.

alt {
    A -> B: Case 1
} else {
    A -> C: Case 2
}

You can chain multiple alternatives with else if clauses:

alt {
    A -> B: Case 1
} else if {
    A -> C: Case 2
} else {
    A -> D: Default case
}

Parallel Blocks

Parallel blocks represent concurrent message exchanges. Use the par keyword.

par {
    A -> B: Task 1
    B -> C: Task 2
}

Parallel messages are executed in an interleaved manner.

Grouping Messages

To logically group related messages, use the group keyword. Groups provide a visual cue to indicate a relationship between steps.

group "Database Operations" {
    A -> DB: Insert record
    DB -> A: Record inserted
}

Custom Arrows and Labels

You can customize the appearance of arrows and add labels to messages for better clarity.

• Custom Arrows: Use symbols like ->>, <--, or --> to modify the arrow style.
• Labels: Provide additional context with labels.

A ->> B: Encrypted message
B <-- A: Acknowledgment

Annotations

Annotations let you add comments or metadata to your chart for improved understanding. Use square brackets ([]) for inline annotations.

A -> B: Start process [timeout=5s]
B -> C: Data processed [priority=high]

Annotations do not affect the logic of the chart but can convey additional context to viewers.

Full Example

Here is a complete example combining the advanced features discussed:

---
title: "Advanced MSC Example"
---

A -> B: Initiate connection
loop (i < 3) {
    A -> B: Ping i
    B -> A: Pong i
}
alt {
    A -> C: Use primary server
} else {
    A -> D: Use backup server
}
par {
    group "Primary Operations" {
        C -> DB: Query database
        DB -> C: Query results
    }
    group "Logging" {
        A -> Logger: Log query
        Logger -> A: Log acknowledged
    }
}

Happy diagramming with msgenny!