The s-graphviz Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The s-graphviz Reference Manual

This is the s-graphviz Reference Manual, version 2.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 19:05:56 2020 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

# -*- Mode: POLY-ORG ;-*- ---
#+Title: a 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 a 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][lang 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                                    |
  |---------------+------------------------------------+-----------------------------------------+--------------------------------------------|
  | =             | a assignment of a single attribute | (= key value)                           | (= :rank :same)                            |
  | :->           | a directed edge                    | (:-> attribute-list node1 node2 ...)    | (:-> ((:arrowsize 2)) a b c)               |
  | :--           | a 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 a edge              | (:edge . attribute-list)                | (:edge (:shape :circle) (:style :filled))  |
  | :{}           | a new statement list               | (:{} . graph-statement-list)            | (:{} (= :rank :same) (b) (d))              |
  | :subgraph     | a subgraph                         | (: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 ~:dot~, 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 a 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 a S-Graphviz expression to a image type,it accepts the following arguments.
- a ~file-name~ for the target image,it can be a string or a pathname.
- a ~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 a S-Graphviz expression to a 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)
  (graphviz:render-graph
   (merge-pathnames
    (format nil "images/~a.png" name)
    (asdf:component-pathname (asdf:find-system :s-graphviz)))
   s-expression))
#+END_SRC

** a finite state machine
The original example is [[https://graphviz.gitlab.io/_pages/Gallery/directed/fsm.html][here]].
#+BEGIN_SRC lisp :load demo
(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
[[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
(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
[[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
(render-graphviz-demo
 "port"
 '(:digraph nil
   (:-> nil (node1 :e) (node2 :s))))
#+END_SRC
[[file:./images/port.png]]


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 s-graphviz

Author

Xu Jingtao <jingtaozf@gmail.com>

License

MIT

Description

a s-expression presentation of GraphViz DOT language

Version

2.0

Defsystem Dependency

literate-lisp

Dependency

iterate (at least version 1.5)

Source

s-graphviz.asd (file)

Component

demo (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 s-graphviz/demo

Parent

s-graphviz (system)

Location

Component

s-graphviz.org (file)


Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 s-graphviz.asd

Location

s-graphviz.asd

Systems

s-graphviz (system)

Packages

s-graphviz.system


Previous: , Up: Lisp files   [Contents][Index]

4.1.2 s-graphviz/demo/s-graphviz.org

Parent

demo (module)

Location

s-graphviz.org

Packages

s-graphviz

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 s-graphviz.system

Source

s-graphviz.asd

Use List

Previous: , Up: Packages   [Contents][Index]

5.2 s-graphviz

Source

s-graphviz.org (file)

Nickname

graphviz

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Functions

Function: format-graph S-EXPRESSION &key STREAM
Package

s-graphviz

Source

s-graphviz.org (file)

Function: render-graph FILE-NAME S-EXPRESSION &key FORMAT DOT-EXE DOT-OPTIONS DOT-OUTPUT-FORMAT-SWITCH
Package

s-graphviz

Source

s-graphviz.org (file)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *dot-stream*
Package

s-graphviz

Source

s-graphviz.org (file)

Special Variable: *indent-spaces*
Package

s-graphviz

Source

s-graphviz.org (file)

Special Variable: *indent-tab-size*
Package

s-graphviz

Source

s-graphviz.org (file)

Special Variable: *valid-graph-predicates*
Package

s-graphviz

Source

s-graphviz.org (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Functions

Function: format-attr-list ATTR-LIST
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-attr-stmt STMT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-attribute STMT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-edge-stmt STMT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-id ID
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-node-id ID-PORT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-node-stmt STMT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-port PORT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-stmt STMT
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-stmt-list STMT-LIST
Package

s-graphviz

Source

s-graphviz.org (file)

Function: format-subgraph-stmt STMT
Package

s-graphviz

Source

s-graphviz.org (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M   S  
Index Entry  Section

F
File, Lisp, s-graphviz.asd: The s-graphviz․asd file
File, Lisp, s-graphviz/demo/s-graphviz.org: The s-graphviz/demo/s-graphviz․org file

L
Lisp File, s-graphviz.asd: The s-graphviz․asd file
Lisp File, s-graphviz/demo/s-graphviz.org: The s-graphviz/demo/s-graphviz․org file

M
Module, s-graphviz/demo: The s-graphviz/demo module

S
s-graphviz.asd: The s-graphviz․asd file
s-graphviz/demo: The s-graphviz/demo module
s-graphviz/demo/s-graphviz.org: The s-graphviz/demo/s-graphviz․org file

Jump to:   F   L   M   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   F   R  
Index Entry  Section

F
format-attr-list: Internal functions
format-attr-stmt: Internal functions
format-attribute: Internal functions
format-edge-stmt: Internal functions
format-graph: Exported functions
format-id: Internal functions
format-node-id: Internal functions
format-node-stmt: Internal functions
format-port: Internal functions
format-stmt: Internal functions
format-stmt-list: Internal functions
format-subgraph-stmt: Internal functions
Function, format-attr-list: Internal functions
Function, format-attr-stmt: Internal functions
Function, format-attribute: Internal functions
Function, format-edge-stmt: Internal functions
Function, format-graph: Exported functions
Function, format-id: Internal functions
Function, format-node-id: Internal functions
Function, format-node-stmt: Internal functions
Function, format-port: Internal functions
Function, format-stmt: Internal functions
Function, format-stmt-list: Internal functions
Function, format-subgraph-stmt: Internal functions
Function, render-graph: Exported functions

R
render-graph: Exported functions

Jump to:   F   R  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*dot-stream*: Internal special variables
*indent-spaces*: Internal special variables
*indent-tab-size*: Internal special variables
*valid-graph-predicates*: Internal special variables

S
Special Variable, *dot-stream*: Internal special variables
Special Variable, *indent-spaces*: Internal special variables
Special Variable, *indent-tab-size*: Internal special variables
Special Variable, *valid-graph-predicates*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, s-graphviz: The s-graphviz package
Package, s-graphviz.system: The s-graphviz․system package

S
s-graphviz: The s-graphviz system
s-graphviz: The s-graphviz package
s-graphviz.system: The s-graphviz․system package
System, s-graphviz: The s-graphviz system

Jump to:   P   S