Dictim

Mac+Linux builds Windows builds

Dictim syntax is an edn/ json syntax for expressing a graph diagram. Dictim is a library for compiling it to either d2's or Graphviz's text languages, and parsing any piece of d2 (back) into dictim syntax.

Dictim supprts both Clojure and Babashka and comes as a library, a command line tool and a microservice (see dictim.server below). Clojurescript support is experimental.

Rationale

Diagrams as data: dynamically generate rather than locking away information in hand produced diagrams. Dynamic diagrams create opportunities to better understand the information being visualized, e.g. group this way or that, style one way or another, dynamically include/ exclude information.

Why parse d2 into dictim syntax?

Terrastruct, the company behind d2, have a commercial diagramming IDE ('D2 Studio') which allows you to build diagrams with d2 or by drag and drop and have the diagram and d2 stay in sync.

Library Release Information

Latest release:

deps.edn dependency information:

As a git dep:

io.github.judepayne/dictim {:git/tag "0.8.8" :git/sha "75723f0"}

d2 version compatibility: 0.6.5

Docs & API

• Wiki

Basic usage

Let's round trip from dictim to d2, and back!

From dictim to d2

dictim and d2 have three principle types of elements: shapes, connections and containers.

Here's an example of producing a d2 specifiction of a diagram with two shapes and a connection:

user=> (use 'dictim.d2.compile)
nil
user=> (d2 [:s1 "Shape 1"][:s2 "Shape 2"][:s1 "->" :s2 "reln"])
"s1: Shape 1\ns2: Shape 2\ns1 -> s2: reln"

When sent to the d2 CLI executable:

From d2 to dictim

let's turn the above d2 string back into dictim.

user=> (use 'dictim.d2.parse)
nil
user> (dictim "s1: Shape 1\ns2: Shape 2\ns1 -> s2: reln" :key-fn keyword)
([:s1 "Shape 1"] [:s2 "Shape 2"] [:s1 "->" :s2 "reln"])

For details on dictim syntax, the compile, parse and other operations, please see the wiki.

Command line tool

This project contains a command line tool version (a babashka script) that you can install and use to play with dictim on the command line. You can easily create a toolchain that goes directly from dictim edn to a diagram. See the wiki for details.

Related Projects

This project is the base project for a number of other projects:

• dictim.graph Convert a representation of a graph into dictim: ideal for boxes and arrows/ network diagrams
• dictim.cookbook Examples of dictim in action!
• dictim.server A easy-to-deploy microservice for converting dictim into d2 diagrams.

License

Copyright © 2024 Jude Payne

Distributed under the MIT License