Skip to content

Commit 216e4e9

Browse files
committed
Add EBNF/Railroad diagram support to Mermaid
1 parent caaf9fa commit 216e4e9

2 files changed

Lines changed: 226 additions & 0 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'mermaid': minor
3+
---
4+
5+
feat: Add support for Railroad Diagrams (Syntax Diagrams) with EBNF notation. This new diagram type allows developers to visually document programming language grammars, DSL syntax, and formal language specifications using Extended Backus-Naur Form. Supports both W3C and ISO 14977 EBNF notation styles.
Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# Railroad Diagrams (v<MERMAID_RELEASE_VERSION>+)
2+
3+
> Railroad diagrams (also known as syntax diagrams or grammar diagrams) are a visual representation of context-free grammars using EBNF (Extended Backus-Naur Form) notation. They provide a graphical way to understand and document language syntax, making complex grammar rules easier to comprehend.
4+
5+
Railroad diagrams were first popularized by Niklaus Wirth in his "Pascal User Manual" (1974) and remain widely used today, notably on [JSON.org](https://www.json.org/) for documenting the JSON syntax.
6+
7+
Mermaid can render Railroad diagram visualizations from EBNF notation.
8+
9+
```mermaid-example
10+
railroad-diagram
11+
title "Digit Definition"
12+
13+
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
14+
```
15+
16+
## Syntax
17+
18+
Railroad diagrams use EBNF (Extended Backus-Naur Form) notation to define grammar rules. Mermaid supports both W3C and ISO 14977 EBNF notation styles.
19+
20+
### Basic Structure
21+
22+
- Start with `railroad-diagram` keyword to begin the diagram
23+
- Optionally add a `title` followed by a quoted string
24+
- Define grammar rules using the format: `rule_name = definition ;`
25+
- Each rule must end with a semicolon (`;`)
26+
27+
### EBNF Notation
28+
29+
#### Terminals and Non-terminals
30+
31+
Terminals are literal strings enclosed in quotes:
32+
- `"text"` - double quotes
33+
- `'text'` - single quotes
34+
35+
Non-terminals are identifiers that reference other rules:
36+
- `identifier` - references another rule
37+
38+
```mermaid-example
39+
railroad-diagram
40+
letter = "a" | "b" | "c" ;
41+
identifier = letter ;
42+
```
43+
44+
#### Sequence (Concatenation)
45+
46+
Elements appearing one after another define a sequence:
47+
- W3C notation: `A B C`
48+
- ISO 14977 notation: `A , B , C`
49+
50+
```mermaid-example
51+
railroad-diagram
52+
greeting = "Hello" " " "World" ;
53+
```
54+
55+
#### Choice (Alternation)
56+
57+
The pipe symbol (`|`) indicates alternatives:
58+
59+
```mermaid-example
60+
railroad-diagram
61+
sign = "+" | "-" ;
62+
```
63+
64+
#### Optional Elements
65+
66+
Optional elements can appear zero or one time:
67+
- W3C notation: `A?`
68+
- ISO 14977 notation: `[ A ]`
69+
70+
```mermaid-example
71+
railroad-diagram
72+
title "Optional Sign"
73+
74+
sign = "+" | "-" ;
75+
number = sign? digit+ ;
76+
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
77+
```
78+
79+
#### Repetition
80+
81+
Zero or more repetitions:
82+
- W3C notation: `A*`
83+
- ISO 14977 notation: `{ A }`
84+
85+
One or more repetitions:
86+
- W3C notation: `A+`
87+
88+
```mermaid-example
89+
railroad-diagram
90+
title "Identifier with Repetition"
91+
92+
identifier = letter ( letter | digit | "_" )* ;
93+
letter = "a" | "b" | "c" | "d" | "e" ;
94+
digit = "0" | "1" | "2" ;
95+
```
96+
97+
#### Grouping
98+
99+
Parentheses group elements together:
100+
- `( A B )`
101+
102+
```mermaid-example
103+
railroad-diagram
104+
expression = term ( ( "+" | "-" ) term )* ;
105+
term = "number" ;
106+
```
107+
108+
#### Comments
109+
110+
Comments can be added using either style:
111+
- W3C notation: `/* comment */`
112+
- ISO 14977 notation: `(* comment *)`
113+
114+
Comments are ignored during parsing and do not appear in the rendered diagram.
115+
116+
#### Special Sequences
117+
118+
Special sequences (ISO 14977 only) describe elements that cannot be easily expressed in EBNF:
119+
- `? description ?`
120+
121+
#### Exception
122+
123+
The minus operator excludes certain alternatives:
124+
- `A - B` (match A but not B)
125+
126+
## Examples
127+
128+
### Simple Number Grammar
129+
130+
```mermaid-example
131+
railroad-diagram
132+
title "Number Grammar"
133+
134+
sign = "+" | "-" ;
135+
number = sign? digit+ ;
136+
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
137+
```
138+
139+
### Expression Grammar
140+
141+
```mermaid-example
142+
railroad-diagram
143+
title "Arithmetic Expression Grammar"
144+
145+
expression = term ( ( "+" | "-" ) term )* ;
146+
term = factor ( ( "*" | "/" ) factor )* ;
147+
factor = number | "(" expression ")" ;
148+
number = digit+ ;
149+
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
150+
```
151+
152+
### JSON Grammar (Simplified)
153+
154+
```mermaid-example
155+
railroad-diagram
156+
title "JSON Grammar"
157+
158+
json = element ;
159+
element = object | array | string | number | "true" | "false" | "null" ;
160+
object = "{" [ member ( "," member )* ] "}" ;
161+
array = "[" [ element ( "," element )* ] "]" ;
162+
member = string ":" element ;
163+
```
164+
165+
### URL Grammar
166+
167+
```mermaid-example
168+
railroad-diagram
169+
title "URL Grammar"
170+
171+
url = protocol "://" domain path? ;
172+
protocol = "http" | "https" | "ftp" ;
173+
domain = label ( "." label )* ;
174+
label = letter ( letter | digit | "-" )* ;
175+
path = "/" segment ( "/" segment )* ;
176+
letter = "a" | "b" | "c" ;
177+
digit = "0" | "1" | "2" ;
178+
segment = letter+ ;
179+
```
180+
181+
## Visual Elements
182+
183+
Railroad diagrams use distinct visual elements to represent different grammar constructs:
184+
185+
- Terminals: Rounded rectangles with pale yellow background
186+
- Non-terminals: Regular rectangles with white background
187+
- Lines and Arrows: Black paths connecting elements
188+
- Start/End Markers: Small circles at the beginning and end of rules
189+
- Branches: Curved paths for choices
190+
- Loops: Backward paths for repetition
191+
192+
## Notation Reference
193+
194+
| Feature | W3C Notation | ISO 14977 Notation | Description |
195+
|---------|-------------|-------------------|-------------|
196+
| Terminal | `"text"` or `'text'` | `"text"` or `'text'` | Literal string |
197+
| Non-terminal | `identifier` | `identifier` | Rule reference |
198+
| Sequence | `A B` | `A , B` | Concatenation |
199+
| Choice | `A \| B` | `A \| B` | Alternative |
200+
| Optional | `A?` | `[ A ]` | Zero or one |
201+
| Repetition (0+) | `A*` | `{ A }` | Zero or more |
202+
| Repetition (1+) | `A+` | - | One or more |
203+
| Grouping | `( A B )` | `( A B )` | Group elements |
204+
| Comment | `/* text */` | `(* text *)` | Comment |
205+
| Special | - | `? text ?` | Special sequence |
206+
| Exception | `A - B` | `A - B` | Exclusion |
207+
208+
## Best Practices
209+
210+
1. Keep rules simple: Break complex rules into smaller, reusable components
211+
2. Use meaningful names: Choose descriptive names for non-terminals
212+
3. Add titles: Use the `title` keyword to provide context for the grammar
213+
4. Group related rules: Define related grammar rules together
214+
5. Use consistent notation: Stick to either W3C or ISO 14977 notation style throughout your diagram
215+
216+
## References
217+
218+
- [ISO/IEC 14977:1996 - EBNF Standard](https://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf)
219+
- [W3C EBNF Notation](https://www.w3.org/TR/xml/#sec-notation)
220+
- [Wikipedia: Extended Backus-Naur Form](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form)
221+
- [Wikipedia: Syntax Diagram](https://en.wikipedia.org/wiki/Syntax_diagram)

0 commit comments

Comments
 (0)