Command Line

You can install dictim as a command line tool directly without needing to have downloaded this project or required it as a dependency.

Installation Instructions

There are two ways to install the dictim command line tool; as a native build for mac, linux and Windows or as a universal script that runs under babashka.

The native builds under available to download from the dictim github releases page. Instructions for the babashka script are as follows..

Prerequisites for babashka script

1. install babshka the awesome Clojure scripting runtime.

2. install bbin the script installation tool for babashka.

In your terminal run

bbin install https://github.com/judepayne/dictim/releases/latest/download/dictim.jar

That's it!

Try

dictim -h

to see the help.

If the dictim script generated by bbin is not found, then it's probable that the folder where bbin stores scripts ~/.local/bin has not been put on your path by bbin and you may need to add it manually in your ~/.zprofile (or similar).

Installation without bbin

If you're not using bbin, you'll still need babashka installed and will need to build dictim.jar

Clone the dictim repo locally, cd into it and run

bb build

This will build a dictim.jar in the repo folder which you can run by

bb dictim.jar -h

(to see the help)

Using the dictim command line tool

Here's the help of the dictim tool

  -c,  --compile   Compiles supplied dictim to d2
                   The value supplied to --compile may be either
                     - a edn/ json dictim syntax string (in single quotes)
                     - ommitted in which case *std-in* is read

                   An edn/ json template file may be specified via
                   --template/ -t which causes the template to be applied
                   during compilation.

                   compile may be used with watch (--watch/ -w) in which
                   case, the watched file will be recompiled whenever it
                   changes. If a --template/-t file is also specified then
                   that file will also be watched. When used with watch, an
                   output file must be specified via the --output/ -o flag.
  -p,  --parse     Parses supplied d2 into dictim
                   The value supplied to --parse may be either
                     - a d2 string (in single quotes)
                     - ommitted in which case *std-in* is read

                   parse may be used with watch (--watch/ -w) in which
                   case, the watched file will be recompiled whenever it
                   changes. When used with watch, an output file must be
                   specified via the --output/ -o flag.

                   --parse has various other supplemental flags:
       --k         Convert keys to keywords when parsing d2 to dictim syntax edn
       --j         Converts the output of parse to dictim syntax json
       --b         Additional to  -j: prettifies the json output of parse
  -w,  --watch     When used on its own, Watches an edn/ json dictim syntax file
                   and serves the resultant diagram in the default browser.
                   watch requires d2 to be installed and available on your
                   path. watch has sub option settings:
                   (d2) layout, (d2) theme, scale and debug:
  -l,  --layout    d2 layout engine name; dagre/ elk/ tala
  -th, --theme     d2 theme id. See https://d2lang.com/tour/themes
       --d         debug for Watch: Shows interim d2 in the browser.
  -s,  --scale     determines the svg scaling factor used by d2. default is 1.0
  -a,  --apply-tmp Applies a dictim template to d2.
                   Parses suppled d2 into dictim (taking the usual optional
                   supplemental flags for parse), merges in a dictim template
                   specified via the --template/ -t otpion, and compiles the
                   result back into d2.

                   apply-tmp may be used with watch (--watch/ -w) in which
                   case, the watched file will be round-tripped whenever it
                   changes. The specified template file will also be
                   watched. When used with watch, an output file must be
                   specified via the --output/ -o flag.
  -v,  --version   Returns the version of dictm
  -h,  --help      Displays this help

The main functions are --compile (or -c), --parse (or -p), --apply-tmp (or a) short for apply-template, and --watch (or -w)

Compile

Compile accepts either a string, or if the arguement is omitted, then standard in is read.

Examples at the terminal command line:

$ dictim -c '["John" "Manager"] ["Pauli" "Developer"] ["John" "->" "Pauli" "I wish I still had your job"]'
John: Manager

hmm, where did the other dictim expressions go? The command line tool expects either a single expression or a sequence of expression, so let's put them in a list. Using a list for this purpose is recommended because Edn's list notation () is not used anywhere in the dictim syntax.

$ dictim -c '(["John" "Manager"] ["Pauli" "Developer"] ["John" "->" "Pauli" "I wish I still had your job"])'
John: Manager
Pauli: Developer
John -> Pauli: I wish I still had your job

If you feed this to d2 and then on to a file

dictim -c '(["John" "Manager"] ["Pauli" "Developer"] ["John" "->" "Pauli" "I wish I still had your job"])' | d2 - >> out.svg

(the d2 tool uses - to represent stdin and stdout.)

You'll get an svg image like this

To pass the contents of a file to compile

$ dictim -c < my_diagram_definition.edn
...

Compile can be given a dictim template file to merge into the dictim before it is compiled via the --template\ -t flag. Here is an example template file called 'tmp.edn'

{:template
 (["matches" "key" "gui.*"] {:class "gui"}
  ["matches" "label" ".*continuous.*"] {:class "stream"}
  ["matches" "label" ".*batch.*"] {:class "batch"}
  ["matches" "key" "1STR"] {:style.fill "'#b4e7fa'"})
 :directives
 {:direction :down
  :classes
  {"stream"
   {:style
    {:stroke-dash 3
     :stroke-width 2
     :stroke "'#444499'"
     :animated true}}
   "batch"
   {:style
    {:stroke-dash 6
     :stroke-width 2
     :stroke "'#444499'"}}
   "gui"
   {:shape "rectangle"
    :style
    {:stroke-width 2
     :fill "'#c7f0c5'"
     :stroke "'#87b085'"}}}
  :vars
  {:d2-config
   {:theme-id 105
    :layout-engine :tala
    :pad 200
    :center true}}}}

A template file may be in either edn or json format (the format is auto-detected when the file is attempted to be loaded). It must be either an edn map or json object, which has a :template\ "template" entry and optionally a :directives\ "directives" entry. The syntax of the templates entry is covered on this page. This section is for selecting particular elements from the diagram and applying styles either directly or via classes (both are shown in the above example). the directives section is for defining those classes and other directives.

Compile with watch

Compile can also be used with --watch\ -w to watch a file and continuously compile it to an output file specified by the --output\ -o flag. e.g.

dictim -c -w sample.edn -o out.d2

Where sample.d2 contains the dictim that you want to compile to d2.

You can additionally specify a template file via the --template-t flag, in which case both the dictim file and the template file will be watched and any changes will result in a new d2 file.

Parse

Like compile parse accepts either a string or if the argument is omitted standard in is read.

$ dictim -p 'aShape: I am a Shape'
["aShape" "I am a Shape"]

parse has three additional flags that should be placed before -p/--parse if required.

-k converts keys to keywords, sometimes required in edn output, as dictim is agnostic to whether shape/ container/ connection keys are keywords or strings.

$ dictim -k --parse 'aShape: I am a Shape'
[:aShape "I am a Shape"]

-j converts the parsed dictim to json format.

$ dictim -j -p 'aShape: I am a Shape'
[ [ "aShape", "I am a Shape" ] ]

and -b beautifies/ prettifies the json which can be useful when parsing larger pieces of d2.

Like compile, when when the argument to parse is omitted, standard in is read.

$ dictim -j -b --parse < the_d2.d2
...

Parse with watch

Like compile, parse can also be used with --watch\ -w to watch a file and continuously compile it to an output file specified by the --output\ -o flag. e.g.

dictim -prj -w out.d2 -o out.json

Apply-template

Apply-template is for applying a template file (see above) to a piece of d2. In order to do that, the d2 is parsed to dictim, the template is applied and then the result compiled back to d2.

Example usage:

dictim -t tmp2.edn -a < sample.d2

--apply-tmp\ -a can also be used with a watch similar to compile and parse.

For example:

dictim -a -t tmp.edn -w sample.d2 -o out.d2

will continuously watch both tmp.edn and sample.d2 and put the result in out.d2 if either changes.

Watch

watch on its own (i.e. without either --compile or --parse compiles the contents of the dictim syntax edn/ json file specified to d2 and uses the d2 executable (which must be installed and on your path) to convert to an svg diagram which is displayed in the default browser. Further, when the file is changed, it will recompile and update the diagram.

watch is useful for building up a dictim syntax diagram by hand and playing around with dictim.

for example

$ dictim  -w out.edn                 
success: successfully compiled - to - in 80.909416ms      ;; msg from d2
success: successfully compiled - to - in 83.788834ms      ;; msg from d2
[10:59:42] broadcasting update                            ;; msg from dictim watch
...

--watch\ -w can be used by the --template\ -t flag to apply a dictim template file.

When watch is running, you'll see a mix of messages from the d2 executable and a broadcasting update message from the dictim command line tool when the file is changed.

If the syntax of the dictim in the file is incorrect, you'll see an error message in the browser window.

Four subcommands are available with watch; --layout/-l, --theme/-th, -d (debug) and --scale/-s which are passed into the d2 executable. These set d2's layout engine, (coloring) theme and scaling factor of the svg displayed in the browser.

A Note on Windows Command line usage

Although most of the example commands above work just fine on Windows, the exception area is strings which have to be quoted and escaped differently in the Windows command prompt.

1. Windows Command Prompt doesn't accept single quotes, so:

dictim -c '(["John" "Manager"] ["Pauli" "Developer"] ["John" "->" "Pauli" "test"])'

on mac, linux needs to become:

dictim -c "([\"john\" \"Manager\"] [\"pauli\" \"Developer\"] [\"john\" \"->\" \"pauli\"])"

however..

2. Windows Command Prompt has special characters that need to be escaped, even when in strings.

In the above example > is a special character (as is <, both very common in dictim) and needs to be escapaed with a caret ^ character.

dictim -c "([\"john\" \"Manager\"] [\"pauli\" \"Developer\"] [\"john\" \"-^>\" \"pauli\"])"

works!

The saver here is that for serious command line usage, the dictim content would probably be placed in a file in which case it does not need any escaping. e.g.

dictim -c < my_dict.edn

where the file my_dict.edn contains

(["John" "Manager"] ["Pauli" "Developer"] ["John" "->" "Pauli" "test"])

Finally

In this repo's examples/ folder are some example edn and json diagram spec files that you can use in watch to get started.