Regex Visualisation: Drawing a Regular Expression as a Railroad Diagram

Introduction

Regular expressions are easy to write and hard to read. What exactly is [a-z0-9-]+\. matching? Which parentheses are groups, and which merely widen the scope of a quantifier? Instead of reasoning character by character, draw the pattern as a railroad diagram: each box is a matching unit, rounded boxes are optional segments, and arrows carry the flow.

PlantUML ships a @startregex engine that takes a raw regex and produces the railroad diagram for you. Mermaid has no regex diagram type, but a flowchart with the right nodes and edges can express exactly the same structure.

PlantUML version

The PlantUML syntax is minimal: put the pattern between @startregex and @endregex and the engine does the parsing, splitting literals, groups, character classes and quantifiers into the diagram.

1
2
3

@startregex
^(https?://)?([a-z0-9-]+\.)+[a-z]{2,}(/[\w\-./?%&=]*)?$
@endregex

The result is a classic railroad diagram: ^ and $ are the two anchors, and in between you can clearly see the optional http / s branch, the repeatable host segment, and the optional path that starts with /. PlantUML automatically turns the s in https? into an optional branch and the + into a loop arrow — none of that has to be written by hand.

If the pattern contains characters such as {} or <, PlantUML escapes them as needed; and if rendering ever fails, the quickest way forward is to locate the problem with a simpler pattern and then add the pieces back one by one.

Mermaid version

Mermaid has no regex engine, so you decompose the pattern into nodes yourself. The idea: put one “matching unit” in each box, use a rounded box ([...]) for an optional segment, a diamond {...} for a decision, and let the arrows describe the order of matching.

flowchart LR
  START(["^"]) --> SCHEME{"scheme?"}
  SCHEME -->|yes| PROTO["https?://"]
  SCHEME -->|no| HOST
  PROTO --> HOST["([a-z0-9-]+\.)+"]
  HOST --> TLD["[a-z]{2,}"]
  TLD --> PATH["(/[\w\-./?%&=]*)?$"]

Here START and PATH carry the ^ and $ anchors, SCHEME decides whether https?:// is present, HOST expresses “one or more host segments” with ([a-z0-9-]+\.)+, and PATH closes the pattern. Because Mermaid does not parse regexes, character classes such as [a-z0-9-]+\. have to be written inside quoted labels so they are treated as plain text rather than as Mermaid syntax.

Side-by-side

Aspect	PlantUML `@startregex`	Mermaid `flowchart`
Actually parses the regex	Yes, the engine decomposes it automatically	No, you split it into nodes by hand
Shape of each matching unit	Decided by the engine (box / rounded / loop)	You choose it: `[]`, `([])`, `{}`
Optional segments	Automatic: the `?` quantifier becomes a branch	Hand-written: a rounded `(["..."])` node
Repetition	Automatic: `+` / `*` render as a loop arrow	Hand-written: a self-loop or a node annotated with `+`
Cost when the regex changes	One line to edit, the diagram follows	Every node must be updated, and things get missed
Best fit	Sharing a real regex quickly	Adding Chinese labels, colours and business context

Wrap-up

@startregex means “hand the regex to the engine”: a few seconds and you get an accurate railroad diagram, which is ideal for review and debugging. A Mermaid flowchart means “translate the regex into a diagram”: it takes more work, but it accommodates plenty of commentary, colours and domain semantics. A practical workflow is to validate the pattern with PlantUML first, then decide whether the team deserves a nicer Mermaid version to share.