-- Mode: POLY-ORG ;-- ---

#+Title: an S-expression presentation of GraphViz DOT language #+OPTIONS: tex:t toc:2 \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t #+STARTUP: latexpreview #+STARTUP: noindent #+STARTUP: inlineimages #+PROPERTY: literate-lang lisp #+PROPERTY: literate-load no

• Table of Contents :noexport:TOC:

• [[#introduction][Introduction]]
• [[#the-s-graphviz-language][The S-Graphviz Language]]
• [[#exported-functions][Exported Functions]]
  • [[#format-graph][format-graph]]
  • [[#render-graph][render-graph]]
• [[#examples][Examples]]
  • [[#preparation][Preparation]]
  • [[#a-finite-state-machine][a finite state machine]]
  • [[#a-cluster][a cluster]]
  • [[#add-compass-point-value-in-a-node-id][add compass point value in a node id]]

• Introduction This is an S-expression presentation of [[http://www.graphviz.org/][AT&T GraphViz]]. The original idea is from http://www.martin-loetzsch.de/S-DOT, but with a full compatiblity of original DOT syntax by following its [[https://www.graphviz.org/doc/info/lang.html][language definition]].

• The S-Graphviz Language We have a similar presentation with the original [[https://graphviz.gitlab.io/_pages/doc/info/lang.html][DOT Language]], but in a single list. #+begin_src lisp :load no (graph-type graph-id . graph-statement-list) #+end_src

• ~graph-type~ can be any of the following items. #+title valid graph type |--------+----------+------------------+---------------------| | :graph | :digraph | (:strict :graph) | (:strict :subgraph) | |--------+----------+------------------+---------------------|
• ~graph-id~ can be nil or any valid lisp atom.
• ~graph-statement-list~ is a list of statements for this graph. \ each statement is a list that first element in it can indicate the type of this statement. #+title valid statement type |---------------+------------------------------------+-----------------------------------------+--------------------------------------------| | first element | statement type | syntax | Example | |---------------+------------------------------------+-----------------------------------------+--------------------------------------------| | = | an assignment of a single attribute | (= key value) | (= :rank :same) | | :-> | a directed edge | (:-> attribute-list node1 node2 ...) | (:-> ((:arrowsize 2)) a b c) | | :-- | an undirected edge | (:-- attribute-list node1 node2 ...) | (:-- ((:arrowsize 2)) a b c) | | :graph | attributes for a graph | (:graph . attribute-list) | (:graph (:shape :circle) (:style :filled)) | | :node | attributes for a node | (:node . attribute-list) | (:node (:shape :circle) (:style :filled)) | | :edge | attributes for an edge | (:edge . attribute-list) | (:edge (:shape :circle) (:style :filled)) | | :{} | a new statement list | (:{} . graph-statement-list) | (:{} (= :rank :same) (b) (d)) | | :subgraph | a sub graph | (:subgraph ID . subgraph-statement-list | (:subgraph cluster_1 (:-> () node1 node2)) | | other atom | a node statement | (node-id . attribute-list) | (node1 (:label "nice node") (:shape :box)) | |---------------+------------------------------------+-----------------------------------------+--------------------------------------------|

~ID~ can be a lisp symbol or a string. If the ~ID~ is a symbol, it will be converted to a lowercase DOT symbol in order to prettify the generated DOT file.

• Exported Functions This library created a new package named as ~s-graphviz~, and it exports the following functions to convert the S-Graphviz expression to a file can be read as the DOT Language. ** format-graph This function accepts an S-expression and a keyword ~:stream~.

• The S-expression has the syntax of the S-Graphviz Language.

• The stream is nil by default which means it will return a string which can be read as the DOT Language. If the stream is not nil, then the target string will be written into this stream directly.

  For example, the following lisp expression #+BEGIN_SRC lisp :load no (graphviz:format-graph '(:digraph nil (node1 (:label "nice node") (:shape :box) (:fontname "Arial") (:fontcolor "#AA0000")))) #+END_SRC Will return the following string #+begin_src dot digraph { node1 [label = "nice node", shape = box, fontname = "Arial", fontcolor = "#AA0000"]; } #+end_src ** render-graph This function is used to render an S-Graphviz expression to an image file, it accepts the following arguments.

• a ~file-name~ for the target image, it can be a string or a path name.

• an ~S-expression~ for the graph

• a keyword ~format~ to indicate the image type, it is the file type of ~file-name~ by default.

• a keyword ~dot-exe~ for the target dot application, it is ~dot~ by default.

• a keyword ~dot-arguments~ for the additional dot arguments, it is null by default.

For example to render an S-Graphviz expression to an image file, we can run the following lisp expression. #+BEGIN_SRC lisp :load no (graphviz:render-graph "/tmp/test1.png" '(:digraph () (= :rankdir "LR") (:-> nil a b c) (:-> nil d e f) (:-> nil b d) (:{} (= :rank :same) (b) (d)))) #+end_SRC

• Examples ** Preparation We will store all images in this section in the subdirectory ~images~ #+BEGIN_SRC lisp :load demo (defun render-graphviz-demo (name s-expression) (let ((target-file (format nil "images/~a.png" name))) (graphviz:render-graph (merge-pathnames target-file (asdf:component-pathname (asdf:find-system :s-graphviz))) s-expression) target-file)) #+END_SRC In above routine, we return the target file so when you execute the following examples with =org-babel=, it could update the image file automatically.

** a finite state machine The original example is [[https://graphviz.gitlab.io/_pages/Gallery/directed/fsm.html][here]]. #+BEGIN_SRC lisp :load demo :results file :exports both (render-graphviz-demo "fsm" '(:digraph nil (= :rankdir "LR") (= :size "8,5") (:node (:shape :doublecircle)) (LR_0) (LR_3) (LR_4) (LR_8) (:node (:shape :circle)) (:-> ((:label "SS(B)")) LR_0 LR_2) (:-> ((:label "SS(S)")) LR_0 LR_1) (:-> ((:label "S($end)")) LR_1 LR_3) (:-> ((:label "SS(b)")) LR_2 LR_6) (:-> ((:label "SS(a)")) LR_2 LR_5) (:-> ((:label "S(A)")) LR_2 LR_4) (:-> ((:label "S(b)")) LR_5 LR_7) (:-> ((:label "S(a)")) LR_5 LR_5) (:-> ((:label "S(b)")) LR_6 LR_6) (:-> ((:label "S(a)")) LR_6 LR_5) (:-> ((:label "S(b)")) LR_7 LR_8) (:-> ((:label "S(a)")) LR_7 LR_5) (:-> ((:label "S(b)")) LR_8 LR_6) (:-> ((:label "S(a)")) LR_8 LR_5) )) #+END_SRC

#+RESULTS: [[file:images/fsm.png]]

** a cluster The original example is [[https://graphviz.gitlab.io/_pages/Gallery/directed/cluster.html][here]]. #+BEGIN_SRC lisp :load demo :results file :exports both (render-graphviz-demo "cluster2" '(:digraph nil (:subgraph :cluster_0 (= :style :filled) (:node (:style :filled) (:color :white)) (:-> () a0 a1 a2 a3) (= :label "process #1")) (:subgraph :cluster_1 (:node (:style :filled)) (:-> () b0 b1 b2 b3) (= :label "process #2") (= :color :blue)) (:-> () start a0) (:-> () start b0) (:-> () a1 b3) (:-> () b2 a3) (:-> () a3 a0) (:-> () a3 end) (:-> () b3 end) (start (:shape "Mdiamond")) (end (:shape "Msquare")) )) #+END_SRC

#+RESULTS: [[file:images/cluster2.png]]

** add compass point value in a node id You can add a compass point value in any node id as you can in the original DOT Language, for example: #+BEGIN_SRC lisp :load demo :results file :exports both (render-graphviz-demo "port" '(:digraph nil (:-> nil (node1 :e) (node2 :s)))) #+END_SRC

#+RESULTS: [[file:images/port.png]]