Merge pull request #77 from cgreeno/feat/seq-alt

feat(sequence): render alt/else fragments

Author: AlexanderGrooff

README.md

@@ -555,7 +555,8 @@ Note that with `--coords` enabled, the grid-coords shown show the starting locat
 - [x] `autonumber`
 - [x] Notes (`Note over A`, `Note over A,B`, `Note left of A`, `Note right of A`)
 - [ ] Activation boxes
-- [ ] `alt`/`else`, `par`, `critical`, `break`, `rect` blocks
+- [x] `alt`/`else` blocks (incl. multiple else, nesting)
+- [ ] `par`, `critical`, `break`, `rect` blocks
 
 ## TODOs
 
@@ -584,7 +585,8 @@ The baseline components for Mermaid work, but there are a lot of things that are
 - [ ] Activation boxes (activate/deactivate)
 - [x] Notes (`Note over`/`left of`/`right of`)
 - [x] `loop` and `opt` blocks
-- [ ] `alt`, `par`, `critical`, `break`, and `rect` blocks
+- [x] `alt`/`else` blocks
+- [ ] `par`, `critical`, `break`, and `rect` blocks
 
 ### General
 

cmd/testdata/sequence-ascii/alt_basic.txt

@@ -0,0 +1,25 @@
+sequenceDiagram
+    A->>B: request
+    alt is valid
+        B-->>A: success
+    else is invalid
+        B-->>A: error
+    end
+---
++---+     +---+
+| A |     | B |
++-+-+     +-+-+
+  |         |
+  | request |
+  +-------->|
++-[alt is valid]-+
+| |         |    |
+| | success |    |
+| |<........+    |
++.[is invalid]...+
+| |         |    |
+| | error   |    |
+| |<........+    |
+| |         |    |
++----------------+
+  |         |

cmd/testdata/sequence/alt_basic.txt

@@ -0,0 +1,25 @@
+sequenceDiagram
+    A->>B: request
+    alt is valid
+        B-->>A: success
+    else is invalid
+        B-->>A: error
+    end
+---
+┌───┐     ┌───┐
+│ A │     │ B │
+└─┬─┘     └─┬─┘
+  │         │
+  │ request │
+  ├────────►│
+┌─[alt is valid]─┐
+│ │         │    │
+│ │ success │    │
+│ │◄┈┈┈┈┈┈┈┈┤    │
+├┈[is invalid]┈┈┈┤
+│ │         │    │
+│ │ error   │    │
+│ │◄┈┈┈┈┈┈┈┈┤    │
+│ │         │    │
+└────────────────┘
+  │         │

cmd/testdata/sequence/alt_multiple_else.txt

@@ -0,0 +1,27 @@
+sequenceDiagram
+    alt a
+        A->>B: 1
+    else b
+        A->>B: 2
+    else c
+        A->>B: 3
+    end
+---
+┌───┐     ┌───┐
+│ A │     │ B │
+└─┬─┘     └─┬─┘
+┌─[alt a]─────┐
+│ │         │ │
+│ │ 1       │ │
+│ ├────────►│ │
+├┈[b]┈┈┈┈┈┈┈┈┈┤
+│ │         │ │
+│ │ 2       │ │
+│ ├────────►│ │
+├┈[c]┈┈┈┈┈┈┈┈┈┤
+│ │         │ │
+│ │ 3       │ │
+│ ├────────►│ │
+│ │         │ │
+└─────────────┘
+  │         │

pkg/sequence/alt_test.go

@@ -0,0 +1,107 @@
+package sequence
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/AlexanderGrooff/mermaid-ascii/pkg/diagram"
+)
+
+// altDividers returns the else-divider labels in order.
+func altDividers(sd *SequenceDiagram) []string {
+	var out []string
+	for _, ev := range sd.Events {
+		if ev.Kind == EventFragmentDivider {
+			out = append(out, ev.Fragment.Label)
+		}
+	}
+	return out
+}
+
+func hasAltStart(sd *SequenceDiagram) bool {
+	for _, ev := range sd.Events {
+		if ev.Kind == EventFragmentStart && ev.Fragment.Type == FragmentAlt {
+			return true
+		}
+	}
+	return false
+}
+
+// TestParseAlt covers the alt variants mermaid.js tests: a basic alt/else,
+// multiple elses, a no-label alt and else, and special characters.
+func TestParseAlt(t *testing.T) {
+	tests := []struct {
+		name         string
+		input        string
+		wantMessages int
+		wantDividers []string
+	}{
+		{"alt with else", "sequenceDiagram\n alt valid\n  A->>B: ok\n else invalid\n  B->>A: err\n end", 2, []string{"invalid"}},
+		{"multiple elses", "sequenceDiagram\n alt a\n  A->>B: 1\n else b\n  A->>B: 2\n else c\n  A->>B: 3\n end", 3, []string{"b", "c"}},
+		{"no-label alt and else", "sequenceDiagram\n alt\n  A->>B: 1\n else\n  A->>B: 2\n end", 2, []string{""}},
+		{"special chars in label", "sequenceDiagram\n alt <>&! ok\n  A->>B: 1\n end", 1, nil},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			sd, err := Parse(tt.input)
+			if err != nil {
+				t.Fatalf("parse: %v", err)
+			}
+			if !hasAltStart(sd) {
+				t.Error("expected an alt fragment start")
+			}
+			if len(sd.Messages) != tt.wantMessages {
+				t.Errorf("messages = %d, want %d", len(sd.Messages), tt.wantMessages)
+			}
+			got := altDividers(sd)
+			if len(got) != len(tt.wantDividers) {
+				t.Fatalf("dividers = %v, want %v", got, tt.wantDividers)
+			}
+			for i, w := range tt.wantDividers {
+				if got[i] != w {
+					t.Errorf("divider %d = %q, want %q", i, got[i], w)
+				}
+			}
+		})
+	}
+}
+
+// TestParseAltErrors covers malformed alt/else usage.
+func TestParseAltErrors(t *testing.T) {
+	tests := []struct {
+		name, input, wantErr string
+	}{
+		{"else at top level", "sequenceDiagram\n A->>B: x\n else\n", "outside an alt"},
+		{"else inside loop", "sequenceDiagram\n loop x\n  A->>B: y\n else\n end", "outside an alt"},
+		{"unclosed alt", "sequenceDiagram\n alt x\n  A->>B: y", "unclosed"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := Parse(tt.input)
+			if err == nil || !strings.Contains(err.Error(), tt.wantErr) {
+				t.Errorf("err = %v, want containing %q", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+// TestRenderAltSmoke renders an alt (incl. nested) in both charsets and checks
+// the frame + divider labels appear without panicking.
+func TestRenderAltSmoke(t *testing.T) {
+	input := "sequenceDiagram\n alt outer\n  A->>B: x\n  alt inner\n   A->>B: y\n  else inner2\n   A->>B: z\n  end\n else outer2\n  A->>B: w\n end"
+	sd, err := Parse(input)
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	for _, ascii := range []bool{false, true} {
+		out, err := Render(sd, diagram.NewTestConfig(ascii, "cli"))
+		if err != nil {
+			t.Fatalf("render ascii=%v: %v", ascii, err)
+		}
+		for _, want := range []string{"[alt outer]", "[outer2]", "[alt inner]", "[inner2]"} {
+			if !strings.Contains(out, want) {
+				t.Errorf("ascii=%v: missing %q\n%s", ascii, want, out)
+			}
+		}
+	}
+}

pkg/sequence/parser.go

@@ -29,9 +29,13 @@ var (
 	autonumberRegex = regexp.MustCompile(`^\s*autonumber\s*$`)
 
 	// fragmentStartRegex matches the opening line of a control-flow fragment,
-	// e.g. "loop every minute" or "opt is premium". Group 1 is the keyword,
-	// group 2 is the (optional) label describing the condition.
-	fragmentStartRegex = regexp.MustCompile(`^\s*(loop|opt)\b\s*(.*)$`)
+	// e.g. "loop every minute", "opt is premium", "alt is valid". Group 1 is the
+	// keyword, group 2 is the (optional) label describing the condition.
+	fragmentStartRegex = regexp.MustCompile(`^\s*(loop|opt|alt)\b\s*(.*)$`)
+
+	// fragmentElseRegex matches an "else" divider inside an alt block. Group 1 is
+	// the (optional) condition label for the following section.
+	fragmentElseRegex = regexp.MustCompile(`^\s*else\b\s*(.*)$`)
 
 	// fragmentEndRegex matches the "end" line that closes a fragment.
 	fragmentEndRegex = regexp.MustCompile(`^\s*end\s*$`)
@@ -63,6 +67,7 @@ type FragmentType int
 const (
 	FragmentLoop FragmentType = iota // loop ... end
 	FragmentOpt                      // opt ... end
+	FragmentAlt                      // alt ... else ... end
 )
 
 func (f FragmentType) String() string {
@@ -71,6 +76,8 @@ func (f FragmentType) String() string {
 		return "loop"
 	case FragmentOpt:
 		return "opt"
+	case FragmentAlt:
+		return "alt"
 	default:
 		return fmt.Sprintf("FragmentType(%d)", int(f))
 	}
@@ -87,12 +94,30 @@ type Fragment struct {
 type EventKind int
 
 const (
-	EventMessage       EventKind = iota // a message arrow
-	EventFragmentStart                  // the opening line of a loop/opt block
-	EventFragmentEnd                    // the matching "end" line
-	EventNote                           // a note annotation
+	EventMessage         EventKind = iota // a message arrow
+	EventFragmentStart                    // the opening line of a loop/opt/alt block
+	EventFragmentDivider                  // an "else" section divider within an alt
+	EventFragmentEnd                      // the matching "end" line
+	EventNote                             // a note annotation
 )
 
+func (k EventKind) String() string {
+	switch k {
+	case EventMessage:
+		return "message"
+	case EventFragmentStart:
+		return "fragment-start"
+	case EventFragmentDivider:
+		return "fragment-divider"
+	case EventFragmentEnd:
+		return "fragment-end"
+	case EventNote:
+		return "note"
+	default:
+		return fmt.Sprintf("EventKind(%d)", int(k))
+	}
+}
+
 // Event is one item in the diagram body. Exactly one payload field is set:
 // Message when Kind is EventMessage, Fragment when Kind is EventFragmentStart,
 // Note when Kind is EventNote. An EventFragmentEnd carries no payload; it just
@@ -205,10 +230,10 @@ func Parse(input string) (*SequenceDiagram, error) {
 		Autonumber:   false,
 	}
 	participantMap := make(map[string]*Participant)
-	// openFragments counts how many loop/opt blocks are currently open so we can
-	// reject an "end" with no matching opener and, at the very end, an opener
-	// with no matching "end".
-	openFragments := 0
+	// openFragments is a stack of the fragment types currently open, so we can
+	// reject an "end"/"else" with no matching opener, validate that "else" only
+	// appears inside an "alt", and detect an opener with no matching "end".
+	var openFragments []FragmentType
 
 	for i, line := range lines {
 		trimmed := strings.TrimSpace(line)
@@ -274,35 +299,44 @@ func Parse(input string) (*SequenceDiagram, error) {
 			continue
 		}
 
-		// A fragment opener ("loop"/"opt") starts a framed block.
+		// A fragment opener ("loop"/"opt"/"alt") starts a framed block.
 		if match := fragmentStartRegex.FindStringSubmatch(trimmed); match != nil {
-			fType := FragmentLoop
-			if match[1] == "opt" {
-				fType = FragmentOpt
-			}
+			fType := map[string]FragmentType{"loop": FragmentLoop, "opt": FragmentOpt, "alt": FragmentAlt}[match[1]]
 			sd.Events = append(sd.Events, Event{
 				Kind:     EventFragmentStart,
 				Fragment: &Fragment{Type: fType, Label: strings.TrimSpace(match[2])},
 			})
-			openFragments++
+			openFragments = append(openFragments, fType)
+			continue
+		}
+
+		// "else" divides an alt block into sections.
+		if match := fragmentElseRegex.FindStringSubmatch(trimmed); match != nil {
+			if len(openFragments) == 0 || openFragments[len(openFragments)-1] != FragmentAlt {
+				return nil, fmt.Errorf("line %d: %q outside an alt block", i+2, trimmed)
+			}
+			sd.Events = append(sd.Events, Event{
+				Kind:     EventFragmentDivider,
+				Fragment: &Fragment{Type: FragmentAlt, Label: strings.TrimSpace(match[1])},
+			})
 			continue
 		}
 
 		// "end" closes the most recently opened fragment.
 		if fragmentEndRegex.MatchString(trimmed) {
-			if openFragments == 0 {
-				return nil, fmt.Errorf("line %d: %q without matching loop/opt", i+2, trimmed)
+			if len(openFragments) == 0 {
+				return nil, fmt.Errorf("line %d: %q without matching loop/opt/alt", i+2, trimmed)
 			}
 			sd.Events = append(sd.Events, Event{Kind: EventFragmentEnd})
-			openFragments--
+			openFragments = openFragments[:len(openFragments)-1]
 			continue
 		}
 
 		return nil, fmt.Errorf("line %d: invalid syntax: %q", i+2, trimmed)
 	}
 
-	if openFragments > 0 {
-		return nil, fmt.Errorf("unclosed loop/opt fragment: missing %d \"end\"", openFragments)
+	if len(openFragments) > 0 {
+		return nil, fmt.Errorf("unclosed fragment: missing %d \"end\"", len(openFragments))
 	}
 
 	if len(sd.Participants) == 0 {