Utilities

Conversion to/ from json

The dictim.json names provides two public functions to-json and from-json for converting dictim to json and back. Under the covers, the Cheshire library is used.

Validation

The dictim.validate namespace provides the functions valid? and all-valid? for validating dictim. The first for a single element, the second for a collection of multiple elements.

user> (in-ns 'dictim.validate)
#namespace[dictim.validate]
dictim.validate> (def elem
                   [:mike
                    "Old friends"
                    [:comment "a diagram of friends"]
                    [:t1
                     "T Boggs expanded"
                     [:tris "TAB"]
                     [:mads "Madeline"]
                     [:tris "--" :maddie "wedding bells?"]]])
#'dictim.validate/elem
dictim.validate> (valid? elem)
true

A meaningful error will be thrown if a particular element fails validation.

Formatting d2

The dictim.format namespace exposes one public function, fmt which will clean up and re-format a d2 string.

user=> (use 'dictim.format)
nil
user=> (println d2-messy)
family1: The Jones' {
style:  {   fill: red;
  }; personA: Henrick
personB: Michael
     personA -- personB:   brothers;}
nil
user=> (println (fmt d2-messy))
family1: The Jones' {
  style:  {
     fill: red
  }
  personA: Henrick
  personB: Michael
  personA -- personB: brothers
}
nil

fmt can take one keyword argument :tab to set the number of spaces used for an indentation step. The default is 2.

The fmt fuunction is invoked by default on d2 compiled from dicitm.

Template related utilities

The dictim.template namespace exposes some additional useful functions asides from its core functions add-styles and remove-styles (which are covered on the Template wiki page.

Walking dictim

Similar to clojure.walk the functions walk-dictim, prewalk-dictim and postwalk-dictim allow you to traverse any dictim diagram spec.

Dictim element accessors

Multimethods are accessing parts of a dictim element are used in the test functionality of add-styles but could be useful elsewhere.

These are key, keys, label, children, element-type

Flat Dictim

(Also covered on the Dictim Syntax page)

Flat dictim is a secondary format (to dictim itself) where every element is represented as a Clojure map with the same set of keys. Flat dictim is easier to work with than dictim itself due to its flat, homogenous nature. Example use cases are for flattening before storing, or flattening in order to insert or delete nodes.

The dictim.flat namespace provides two public functions for working with flat dictim.

To convert from dictim to flat dictim, use flat

dictim.flat> (in-ns 'dictim.flat)
#namespace[dictim.flat]
dictim.flat> (def ex '({:direction "right"}
                       [:mike "Old friends"
                        [:comment "a diagram of friends"]
                        [:t1 "T Boggs expanded"
                         [:tris "TAB"]
                         [:mads "Madeline"]
                         [:tris "--" :maddie "wedding bells?"]]]))
#'dictim.flat/ex
dictim.flat> (flat ex)
({:type :attrs, :key {:direction "right"}, :meta nil, :parent nil}
 {:type :ctr, :key :mike, :meta {:label "Old friends"}, :parent nil}
 {:type :cmt, :key "a diagram of friends", :meta nil, :parent :mike}
 {:type :ctr,
  :key :t1,
  :meta {:label "T Boggs expanded"},
  :parent :mike}
 {:type :shape, :key :tris, :meta {:label "TAB"}, :parent :t1}
 {:type :shape, :key :mads, :meta {:label "Madeline"}, :parent :t1}
 {:type :conn,
  :key [:tris "--" :maddie],
  :meta {:label "wedding bells?"},
  :parent :t1})

To convert it back again, use build

dictim.flat> (build (flat ex))
({:direction "right"}
 [:mike
  "Old friends"
  [:comment "a diagram of friends"]
  [:t1
   "T Boggs expanded"
   [:tris "TAB"]
   [:mads "Madeline"]
   [:tris "--" :maddie "wedding bells?"]]])