Utilities

Validation

The dictim.validate namespace provides the function valid-element? for validating dictim.

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-element? elem)
true

valid-element? will throw a meaningful error for when a (nested) dictim element fails validation.

Flat Dictim Utilities

(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.

The dictim.flat namespace provides a few public functions for working with flat dictim.

To convert from dictim to flat dictim, use disassemble

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> (disassemble ex)
({:type :attrs,
  :key -1701918333,
  :meta {:direction "right"},
  :posn [0]}
 {:type :ctr, :key :mike, :meta {:label "Old friends"}, :posn [1]}
 {:type :cmt, :key "a diagram of friends", :meta nil, :posn [1 0]}
 {:type :ctr,
  :key :t1,
  :meta {:label "T Boggs expanded"},
  :posn [1 1]}
 {:type :shape, :key :tris, :meta {:label "TAB"}, :posn [1 1 0]}
 {:type :shape, :key :mads, :meta {:label "Madeline"}, :posn [1 1 1]}
 {:type :conn,
  :key [:tris "--" :maddie],
  :meta {:label "wedding bells?"},
  :posn [1 1 2]})

To convert it back again, use assemble

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

To insert an element into the flat dictim, use insert

dictim.flat> (insert {:type :shape :key :sam} (disassemble ex))
Execution error at dictim.utils/error (utils.cljc:6).
No position specified for insertion of elem {:type :shape, :key :sam}

A position can be specified in a few ways. A :posn vector can be assoc'd into the element map to be inserted, or either a :before or :after keyword argument can be supplied. These both take either a :key (that is in the piece of flat dictim) or a position vector, e.g.:

dictim.flat> (insert {:type :shape :key :sam} (disassemble ex) :before "a diagram of friends")
[{:type :attrs,
  :key -1701918333,
  :meta {:direction "right"},
  :posn [0]}
 {:type :ctr, :key :mike, :meta {:label "Old friends"}, :posn [1]}
 {:type :shape, :key :sam, :posn [1 0]}
 {:type :cmt, :key "a diagram of friends", :meta nil, :posn [1 1]}
 {:type :ctr,
  :key :t1,
  :meta {:label "T Boggs expanded"},
  :posn [1 2]}
 {:type :shape, :key :tris, :meta {:label "TAB"}, :posn [1 2 0]}
 {:type :shape, :key :mads, :meta {:label "Madeline"}, :posn [1 2 1]}
 {:type :conn,
  :key [:tris "--" :maddie],
  :meta {:label "wedding bells?"},
  :posn [1 2 2]}]

To delete an element, use delete

dictim.flat> (delete [1 0] (disassemble ex))
[{:type :attrs,
  :key -1701918333,
  :meta {:direction "right"},
  :posn [0]}
 {:type :ctr, :key :mike, :meta {:label "Old friends"}, :posn [1]}
 {:type :ctr,
  :key :t1,
  :meta {:label "T Boggs expanded"},
  :posn [1 0]}
 {:type :shape, :key :tris, :meta {:label "TAB"}, :posn [1 0 0]}
 {:type :shape, :key :mads, :meta {:label "Madeline"}, :posn [1 0 1]}
 {:type :conn,
  :key [:tris "--" :maddie],
  :meta {:label "wedding bells?"},
  :posn [1 0 2]}]

or a key may be specified

dictim.flat> (delete "a diagram of friends" (disassemble ex))
[{:type :attrs,
  :key -1701918333,
  :meta {:direction "right"},
  :posn [0]}
 {:type :ctr, :key :mike, :meta {:label "Old friends"}, :posn [1]}
 {:type :ctr,
  :key :t1,
  :meta {:label "T Boggs expanded"},
  :posn [1 0]}
 {:type :shape, :key :tris, :meta {:label "TAB"}, :posn [1 0 0]}
 {:type :shape, :key :mads, :meta {:label "Madeline"}, :posn [1 0 1]}
 {:type :conn,
  :key [:tris "--" :maddie],
  :meta {:label "wedding bells?"},
  :posn [1 0 2]}]

If a container element (:type :ctr) is deleted, its contained elements will also be deleted.