Graphvix

Graphviz in Elixir

Installation

If available in Hex, the package can be installed as:

Add graphvix to your list of dependencies in mix.exs:

def deps do
  [{:graphvix, "~> 1.0.0"}]
end

Usage

See the wiki for examples.

API Overview

Create a new graph

Graphvix.Graph.new/0
Add a vertex to a graph

Graphvix.Graph.add_vertex/2 Graphvix.Graph.add_vertex/3
Add an edge between two vertices

Graphvix.Graph.add_edge/3 Graphvix.Graph.add_edge/4
Create a vertex with type record

Graphvix.Record.new/1 Graphvix.Record.new/2
Add a record vertex to a graph

Graphvix.Graph.add_record/2
Create a vertex using HTML table markup

Graphvix.HTMLRecord.new/1 Graphvix.HTMLRecord.new/2
Add an HTML table vertex to a graph

Graphvix.Graph.add_html_record/2
Save a graph to disk in .dot format

Graphvix.Graph.write/2
Save and compile a graph (defaults to .png)

Graphvix.Graph.compile/2 Graphvix.Graph.compile/3
Save, compile and open a graph (defaults to .png and your OS's default image viewer)

Graphvix.Graph.graph/2 Graphvix.Graph.graph/3

Basic Usage

Alias the necessary module for ease of use
```
alias Graphvix.Graph
```
Create a new graph.
```
graph = Graph.new()
```

Add a simple vertex with a label

{graph, vertex_id} = Graph.add_vertex(graph, "vertex label")

Add a vertex with a label and attributes

{graph, vertex2_id} = Graph.add_vertex(
  graph,
  "my other vertex",
  color: "blue", shape: "diamond"
)

Add an edge between two existing vertices

{graph, edge_id} = Graph.add_edge(
  graph,
  vertex_id, vertex2_id,
  label: "Edge", color: "green"
)

Add a cluster containing one or more nodes

{graph, cluster_id} = Graph.add_cluster(graph, [vertex_id, vertex2_id])

Records

Alias the necessary module for ease of use
```
alias Graphvix.Record
```
Create a simple record that contains only a row of cells
```
record = Record.new(Record.row(["a", "b", "c"]))
```
- A record with a top-level row can also be created by just passing a list
```
record = Record.new(["a", "b", "c"])
```

Create a record with a single column of cells

record = Record.new(Record.column(["a", "b", "c"]))

Create a record with nested rows and columns

import Graphvix.Record, only: [column: 1, row: 1]

record = Record.new(row([
  "a",
  column([
    "b",
    row(["c", "d", "e"]),
    "f"
  ]),
  "g"
])

Ports

Ports can be attached to record cells by passing a tuple of {port_name, label}

import Graphvix.Record, only: [column: 1, row: 1]

record = Record.new(row([
  {"port_a", "a"},
  column([
    "b",
    row(["c", {"port_d", "d"}, "e"]),
    "f"
  ]),
  "g"
])

Edges can be drawn from specific ports on a record

{graph, record_id} = Graph.add_record(graph, record)

{graph, _edge_id} = Graph.add_edge({record_id, "port_a"}, vertex_id)

HTML Table Records

Alias the necessary modules for ease of use
```
alias Graphvix.HTMLRecord
```

Create a simple table

record = HTMLRecord.new([
  tr([
    td("a"),
    td("b"),
    td("c")
  ]),
  tr([
    td("d", port: "port_d"),
    td("e"),
    td("f")
  ])
])

Or a more complex table

record = HTMLRecord.new([
  tr([
    td("a", rowspan: 3),
    td("b", colspan: 2),
    td("f", rowspan: 3)
  ]),
  tr([
    td("c"),
    td("d")
  ])
  tr([
    td("e", colspan: 2)
  ])
])

Cells can also use the font/2 and br/0 helper methods to add font styling and forced line breaks. See the documentation for Graphvix.HTMLRecord for examples.

Output

Convert the graph to DOT format

Graph.to_dot(graph)
"""
digraph G {
  cluster c0 {
    v0 [label="vertex label"]
    v1 [label="my other vertex",color="blue",shape="diamond"]

    v0 -> v1 [label="Edge",color="green"]
  }
}
"""

Save the graph to a .dot file, with an optional filename

Graph.write(graph, "first_graph") #=> creates "first_graph.dot"

Compile the graph to a .png or .pdf using the dot command

## creates first_graph.dot and first_graph.png
Graph.compile(graph, "first_graph")

## creates first_graph.dot and first_graph.pdf
Graph.compile(graph, "first_graph", :pdf)

Compile the graph using the dot command and open the resulting file

## creates first_graph.dot and first_graph.pdf; opens first_graph.png
Graph.graph(graph, "first_graph")

## creates first_graph.dot and first_graph.pdf; opens first_graph.pdf
Graph.graph(graph, "first_graph", :pdf)

ssajnani/graphvix