Rx marbles diagram generator

Posted on 2 mins read

With my recent fascination to reactive programming, I’ve decided to write a small and relatively simple marbles diagram generator.

marbles diagrams are great to explain how various reactive algorithms and operators work and are a nice tool to specify or document of what is expected to happen within a time, with given example inputs, particular scenario etc.

To get marble diagrams generation simple and user-friendly, I’ve decided to take simple human-readable ASCII text as format that describes a marble diagram and let the generator parse and produce a nice SVG diagram out of it.

I’ve chosen Python (good old 2.7) to do the tool, primarily to be able to:

  • get some results quickly (even for the price of little dirty code)
  • use pyparsing which is great for building simple text parsers

Overall, it turned to be a good choice and I quickly came with a small and already usable program with actually just couple of hundreds of lines of code.

This is an example of the input text file the generator takes:

marble my_diagram
{
    source a:             +--1-2-3--4--|
    operator myOperator:  +--A-B-C--D--|
}

If the diagram file as above is stored in my_diagram.txt file, getting a SVG diagram out of it is as simple as executing the marblesgen.py this way:

python marblesgen.py my_diagram.txt

The generator will spit out my_diagram.svg file looking like this:

my_diagram.svg

The output produced is a simple static graphics and not so fancy-interactive as the diagrams on rxmarbles.com, but it is possible to embed them in almost any kind of documentation (online as well as offline), so I think there is a general use case for it.

The generator maintains a small level of abstraction on what the assets used for rendering are. So it it be possible to keep tailoring the visual look & feel of the rendered diagrams.

Currently it accepts --theme command line option, where only default or pencil values are accepted.

The default theme looks like on the diagram above, while the pencil style gives this:

my_diagram.svg

You can check out the generator source code from its repository on Bitbucket.

More details on what is currently supported, as well as how more complex diagrams can be produced, can be found on these documentation pages:

So shout if there is a particular killing feature you are missing, or even better - do the pull request and contribute!

comments powered by Disqus