In specific cases I find diagrams very good at conveying business logic or for reasoning state machines.

But I don’t like to write them, because I then need to scan them and/or they are quite difficult to read because of my horrendous drawing skills.

Up until today, I have been using wdot.rb, a small ruby script that converts a textual instructions into a graphic diagram, using graphviz behind the scenes.

It has worked beautifully. But it doesn’t render in text. And I would love to have some of those diagrams as comments in my code.

Enter Graph::Easy.

Graph::Easy is more or less the same thing. You type some text with a specific format and you get a diagram as a result. Except it can also render to text.

You can install it via cpan. After installing, it will create a utility script called graph-easy, which in my case was installed under ~/perl5.

I put the following text in a file called /tmp/bleh.txt:

[Unscheduled] --> [Scheduled]
[Scheduled] --> [SendingInProgress]
[Scheduled] --> [Canceled]
[Unscheduled] --> [Canceled]
[SendingInProgress] --> [SendingFinished]
[SendingInProgress] --> [SendingPaused]
[SendingPaused] --> [Canceled]

After executing ~/perl5/bin/graph-easy /tmp/bleh.txt --as boxart --verbose you get the following:

  ┌────────────────────────────────────────────────────────────────────────────────────────────┐
  │                                                                                            ∨
┌─────────────┐     ┌──────────────────┐     ┌───────────────────┐     ┌───────────────┐     ┌──────────┐
│ Unscheduled │ ──> │    Scheduled     │ ──> │ SendingInProgress │ ──> │ SendingPaused │ ──> │ Canceled │
└─────────────┘     └──────────────────┘     └───────────────────┘     └───────────────┘     └──────────┘
                      │                        │                                               ∧
                      └────────────────────────┼───────────────────────────────────────────────┘
                                               │
                                               │
                                               │
                                               ∨
                                             ┌───────────────────┐
                                             │  SendingFinished  │
                                             └───────────────────┘

Beautiful.