|
| 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