On Diagrammatic Syntax
2025-11-12
In my view ASCII and Unicode and drawings are just “syntax”. There is no point forcing already-good syntax to be expressed in some other form.
There is nothing wrong with using a hybrid grammar - some text, some diagrams. UNIX pipelines are a better, more modern “language” for programming than singular programming languages are.
Textual syntax is good for expressing sequential, synchronous things. Diagrammatic syntax is good for expressing things that are not sequential or are asynchronous.
The question becomes: what is not synchronous, sequential and could be better served by a non-textual syntax? Off the top of my head:
fan-out
fan-in
feedback
multiple ports
timing relationships
etc.
Text is awful for expressing these kinds of things. We’ve become used to the idea of being constrained to 1-in and 1-out. Where “1” means a blob of data that is transferred all at once and can be destructured into many different sub-types. Continued use of only text for programming is a footgun. Trying to shoehorn perfectly good text into diagrammatic form is a footgun.
/bin/sh tries to deal with more than 1 FD in each direction, e.g. “2>” and friends, but, I find that syntax to be tortuous. I find that stretching textual syntax to express asynchronous things or multiple dataflows discourages the use of multiple ports (as does the notion of “functions”).
I find it easier to express and understand nesting and elision with diagrams, but, it can be argued that textual, eliding markdown editors work OK, too.
I strongly favour not building graphical editors - yet - and just using what is already available. I use draw.io, but there are other choices, e.g. Excalidraw, yEd, etc. As long as the diagrams are parseable using existing tools (I favour OhmJS and PEG over CFG-based approaches), then you can
save the diagram out in some machine-readable textual form (human-readability is unnecessary)
parse
cull out the graphical info
use standard compiler techniques to do the rest.
You don’t need to accept everything that can be drawn on diagrams, just like we don’t accept all of the text in “War and Peace” when building textual compilers. I’ve adopted an attitude of “if I can’t recognize it, it must be a comment” which gives me (the Engineer, not the Brick Layer) a wide range of drawing conventions that help the human eye but are ignored by the diagram compiler, like line thicknesses, colours, box sizes, etc.
I strongly favour transmogrification - “t2t” == OhmJS + RWR - instead of “compilation”. Convert the diagrammatic info into something that you can “compile” with standard techniques.
Drakon == wonderful notation for sequencing, better than flow charts
State Charts == wonderful notation for non-sequential control flow, better than text
Node-and-Arrow == wonderful notation for composition of concurrent units of software
[+] You can use OhmJS for parsing text that is not Javascript, e.g. XML, SVG, Neva, C, Python, Rust, etc., etc. The fact that OhmJS is written in Javascript has no bearing on what syntaxes it can work with.
[+] Note that “parsing” diagrams can mean parsing using OhmJS or some off-the-shelf XML library.
References
RWR - small DSL for writing text-to-text transformations for use with OhmJS in t2t
very simple example of transmogrification of expressions to Python, Javascript, Lisp, WASM
very simple example of using transmogrification to write an incomplete Forth interpreter in a portable meta language
search my substack and my github blog for the word “diagram” for further thoughts
ask me for kibitzing and more info (email, discord, ...)
See Also
Email: ptcomputingsimplicity@gmail.com
Substack: paultarvydas.substack.com
Videos: https://www.youtube.com/@programmingsimplicity2980
Discord: https://discord.gg/65YZUh6Jpq
Leanpub: [WIP] https://leanpub.com/u/paul-tarvydas
Twitter: @paul_tarvydas
Bluesky: @paultarvydas.bsky.social
Mastodon: @paultarvydas
(earlier) Blog: guitarvydas.github.io
References: https://guitarvydas.github.io/2024/01/06/References.html