an S-expression presentation of GraphViz DOT language

Table of Contents

• Introduction
• The S-Graphviz Language
• Exported Functions
  • format-graph
  • render-graph
• Examples
  • Preparation
  • a finite state machine
  • a cluster
  • add compass point value in a node id

Introduction

This is an S-expression presentation of 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 language definition.

The S-Graphviz Language

We have a similar presentation with the original DOT Language, but in a single list.

(graph-type graph-id . graph-statement-list)

• 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

(graphviz:format-graph '(:digraph nil
                    (node1
                     (:label "nice node")
                     (:shape :box)
                     (:fontname "Arial")
                     (:fontcolor "#AA0000"))))

Will return the following string

digraph {
  node1 [label = "nice node", shape = box, fontname = "Arial", fontcolor = "#AA0000"];
}

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.

(graphviz:render-graph "/tmp/test1.png"
                  '(:digraph ()
                    (= :rankdir "LR")
                    (:-> nil a b c)
                    (:-> nil d e f)
                    (:-> nil b d)
                    (:{} (= :rank :same) (b) (d))))

Examples

Preparation

We will store all images in this section in the subdirectory images

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

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

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

a cluster

The original example is here.

(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"))
   ))

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:

(render-graphviz-demo
 "port"
 '(:digraph nil
   (:-> nil (node1 :e) (node2 :s))))