Dictim Syntax

Dictim is two formats: 'dictim' and 'flat dictim'. The former is nested and closely matches the structure of d2. 'flat dictim' is produced from a piece of dictim and is represented as a sequence of Clojure maps. Its flat nature makes it easier to manipulate, for example to break apart for storage.

Dictim Syntax

Dictim is a series of dictim elements - each one closely matching in syntax their d2 equivalent. The d2 tour explains the semantics of the language.

A dictim element can be one of six principal types: comments, shapes, connections, containers, attributes and lists.

Shapes

The syntax for a shape is:

[<shape-key> <label>(optional) <attribute-map>(optional)]

for example:

[:personA "Person A" {:style {:fill "red"}}]

which is represented in d2 as:

personA: Person A {style {fill "red"}}

The shape-key can be either a string or a keyword. The label should be a string. The attribute map should be a map whose keys are either keywords or strings, and whose values are either strings or numbers.

In dictim, the elements of a shape are laid out in a Clojure vector.

Examples with the optional parts missing:

[:personA "Person A" {:style {:fill "red"}}]
[:personA "Person A"]
[:personA {:style {:fill "red"}}]
[:personA]
["person A" "A person called Mike"]
["person A"]
[:people.personA]

are all valid shapes. The last one denotes that 'personA' is inside a container called people

Multi-line labels

For shapes (and connections and containers), if you wish to have a multi-line label, use \\n at the desired point in the label string. \n must be escaped, so always \\n.

Connections

There are two types of connections; single connections and multiple connections.

Single Connections

Syntax:

[<key1> <direction> <key2> <label>(optional) <attribute-map>(optional)]

for example:

[:personA "--" :personB "brothers" {:style.stroke-width 2}]

which is represented in d2 as:

personA -- personB: brothers {style.stroke-width: 2}

key1 and key2 must each be either the key of a shape or a container direction must be one of "<>" "--" "<-" "->"

Multiple Connections

Multiple connections are expressed all in one go..

Syntax:

[<key1> <dir1> <key2> <dir2> <key2> ... <keyN>  <label>(optional) <attribute-map>(optional)]

for example:

[:a "<-" :b "->" :c "children" {:style.stroke-width 2}]

which is represented in d2 as:

a <- b -> c: children {style.stroke-width: 2}

Multiple connections have to share the same label and attributes if those are specified.

Containers

The syntax for containers is the same as for shapes, except that at the end you put the set of contained elements, which may be of any number and each of any of the six types.

Syntax:

[<ctr-key> <label>(optional) <attribute-map>(optional) <nested elem1> <nested elem2> ... <nested elemN>]]

for example:

[:family1 "The Jones'" {:style {:fill "red"}}
  [:personA "Henrick"]
  [:personB "Michael"]
  [:personA "--" :personB "brothers"]]

which in d2 is:

family1: The Jones' {
  style:  {
    fill: red
  }
  personA: Henrick
  personB: Michael
  personA -- personB: brothers
}

Containers may nest other containers which may nest ... and so on.

Attributes

We've seen attibutes already; attribute maps can belong to shapes, connections and containers to specify d2 rendering instructions.

They can also appear at the top level, i.e. an attribute map can exist as a top level element.

An example is the :direction/ direction: reserved keyword, e.g.

{:direction "right"}

which compiles to d2:

direction: right

note the lack of brackets in d2 for top level attributes, i.e. those occurring at diagram level.

Comments

In d2 comment lines are started with the character #.

Dictim uses a two element vector where the first element is :comment and the second a string to model a comment.

[:comment "Hans, accused of cheating"]

In d2:

"# Hans, accused of cheating"

This means that :comment is a reserved word in dictim. Your shapes, connections and containers should not have the key :comment.

Lists

Lists are a second type of container, for a sequence of elements that should all be put on one line separated by semicolons:

[:list [:a-shape "A shape"] [:b-shape "B Shape"] [:comment "all on one line"]]

In d2:

"a-shape: A shape; b-shape: B shape; # all on one line"

Lists may not nest other lists.

In d2, putting elements on one line doesn't have especially meaning except inside sequence_diagrams where it denotes the order of the actors.

(Empty) Lines

The goal of this project is to allow for both ways faithful conversion between clojure data structures (e.g. 'dictim') and d2. In d2, to improve readability, you'll often leave empty lines to separate different parts of the file.

Empty lines are parsed into dictim as:

[:line 1]

where the '1' indicates the number of empty lines at this point.

Reserved d2 keywords

Something to watch out for!

d2 has a number of reserved keywords which are worth avoiding when you name the keys in shapes and containers.

The list of reserved keywords:

'shape' 'label' 'source-arrowhead' 'target-arrowhead' 'near' 'icon' 'width' 'height' 'constraint' 'direction' 'tooltip' 'style'

and sub-keys of style....

'opacity' 'fill' 'stroke' 'stroke-width' 'stroke-dash' 'border-radius' 'font-color' 'shadow' 'multiple' '3d' 'animated' 'link' 'filled'

and don't forget the dictim reserved keywords:

:comment :list and :line

keywords cannot be used in your shapes, connections and containers.

Types

Dictim is quite flexible with types. Element keys can be keywords or strings. In attr maps, the values can be integers, floats , booleans or strings. Non-string types will be converted to strings during compilation. Values in attr maps will be converted back to the primitive type during parsing, and there are the optional key-fn and label-fn functions in parsing that can be used to convert the type or format of keys and labels.

For details of what these all do, please see the d2 [tour] (https://d2lang.com/tour/intro) of the d2 language.

Flat Dictim syntax

In flat dictim, every element is represented by a Clojure map with the same form:

{:type <element type i.e. :shape/:ctr/:conn/:cmt/:attrs>
 :key <key for the element>
 :meta <a map of all other meta data about the element, e.g. it's label and attrs>
 :parent <the key of the parent element (lists and containers)>
 .. <any other keys you'd like to add!>}

The flat, homogenous nature of the syntax makes it easier to manipulate than dictim.

The dicitim.flat namespace has utility functions for flattening and (re)building dictim to\from flat dictim.

:key is a key generated for the element. For a shape or container, it is its key. For a connection, the connection information as a vector e.g. [:a "->" :b], for a comment, the comment string itself, for an attribute map, the map itself and for a list a sequence of the contained elements' keys.

:meta is all the other information needed in the 'dictim format (as opposed to 'flat dictim') element. It's a map with up to two keys; :label and :attrs

:parent is created during the flattening process (dictim -> flat dictim) and use in the rebuilding process.

Please see the Uitilties page for more information about working with flat dictim.