Thursday, 14 March 2013

Ultra Light Graphs (ULG)

Ultra Light Graphs, or ULG for short, is a tool that allows you to create basic graphs using nothing more than a few lines of text. The text format is designed to be meaningful in itself, which makes ULG a sort of markup language for graphs. It isn't intended to replace something more comprehensive like graphml or dot, but it does allow you to quickly write something that is readable in your favourite text editor and can be turned into an image that you might want to insert into documentation etc.


Installation can do be done using ruby gems:

$ gem install ulg

Using ULG

ULG is very easy to use. Just give it a file with the text in it and it will generate a png by default.

$ ulg -h
Usage: ulg.rb [-o OUTPUT] [-s FILE] [-d] FILE FILE...

Reads from stdin if no input FILE given

Other options:

  -o OUTPUT  Output format (png, dot, svg). Default png
  -s FILE    Save to file
  -d         Debug mode
  -h         This help

For example

$ ulg basic.ulg
Reading basic.ulg
Saving output to basic.ulg.png

Basic example

Right, lets say you want to draw a basic graph. You open up your favourite text editor such as vim. You want two nodes and an arrow, so you might intuitively type something like this:

internet ==> web dmz

Now, this is what ULG would make of just that one line:

Nice and simple.

Node shapes

Maybe you don't want two boxes. Perhaps you want one of them to be oval. That's easy too:

(internet) ==> [web dmz]

That would give you:

Notice also how we've also explicitly marked "web dmz" as a box.

Edge label

You've probably noticed that the arrow, or edge in graph-speak, doesn't have a label. We can give it one by just inserting some text somewhere inside the arrow:

(internet) ==http==> [web dmz]

This would give us:


You can also control the shape of the arrow head, for example:

(internet) ==http==<> [web dmz]

Gives us:

Edge line

Of course, you might like your lines to be dashed instead of solid. No problem:

(internet) --http--> [web dmz]

Here we go:

Interesting example

Now, lets make things a little bit more interesting. I'll show you the text and image first, then I'll explain a few things afterwards:

option layout dot
option overlap false
option splines true

include backoffice.ulg

Internet        ==http==>       (web dmz|orange)

web dmz         ==8080==>       [app stack 1|blue]
web dmz         ==8000==>       [app stack 2|purple]

app stack 1     ==25==>         internet
app stack 2     ==5432|red==>   [database|green]

Where backoffice.ulg is

(back office) ==5432|red==> database
(back office) ==80==> (internet|red)

This would result in this rather pretty graph:

Quite a few things have happened here. Looking at the text, you will have noticed three lines starting with the word "option". These are basically just option names and values that get passed directly to Graphviz as global options.

We also include a ULG file called "backoffice.ulg", the contents of which is shown afterwards. You'll see that backoffice defines an "internet" node and the main text refers to an "Internet" and an "internet" node and that the graph only shows one "internet" node. This is because ULG ignores case and spaces when determining what the node is. So "Internet", "internet" and "inter net" would all be the same thing. This allows you to be a little be messy and inconsistent with your typing ;)

The "internet" node was labelled "internet" and not "Internet". This is because ULG defines styles based on the first occurrence of the node or edge. Because we included backoffice.ulg first, it defined the style for the internet node. This also means that once we have defined a node, such as the "(web dmz|orange)" we ignore any style characters and simply use the label. The next two occurrences were referred to as just "web dmz".

Another thing you will have noticed is the use of colour. This is achieved by simply adding "|colour" to the node or edge label. Any colours Graphviz understands should be fine.

Its probably also worth mentioning at this point that ULG doesn't care about whitespace between nodes and arrows, so you can use spaces or tabs - whatever is easiest to read. It does however require that an arrow is made up of at least two line characters (such as == or --)

Other things you can do

Finally, this example shows the different combinations of supported node and arrow styles.

# This line is ignored

# Include a file
include common-opts.ulg

# An option
option rankdir TB

# Graph
[box]   = normal ==>    (oval|blue)
oval    =dot|red=o      <diamond>
oval      box
box     --diamond--<>   diamond

another box     === no arrow ==     {hexagon}

This gives us:

Hopefully this example speaks for itself.


  1. Nice. Just a thought, would import/export to a graphviz format script be worth adding?

  2. Already supported ;)

    $ ulg -o dot interesting.ulg
    Reading interesting.ulg
    Reading backoffice.ulg
    Saving output to
    $ head
    digraph G {
    graph [layout=dot, overlap=false, splines=true];
    node [label="\N"];
    graph [bb="0,0,269,402"];

    From there you can convert dot to whatever you like.

  3. Cool! I will bear this in mind next time I need to produce a graph...