graphvix v0.5.0 Graphvix.Graph

Graphvix.Graph manages saving, loading, and presenting the state of a graph.

NB. All examples below assume you have run

iex> alias Graphvix.{Graph, Node, Edge, Cluster}

Overview

To reduce user effort, the module keeps only a single graph in state at any given time. Graphs can be saved and reloaded to switch between working with several different graphs at a time.

iex> Graph.new(:first_graph)

iex> ... # Add some data to the first graph

iex> Graph.switch(:second_graph) # Creates a new graph and loads it, saving the old graph at the same time.

iex> ... # Add some data to the second graph

iex> Graph.switch(:first_graph) # Saves `:second_graph` and reloads `first_graph`

State

State is managed by the Graphvix.State module. This module is responsible for maintaining in memory the state of any created graphs, as well as persisting the data to disk and loading it back into memory. The State module should never be accessed directly. All interaction with it occurs through functions availabel on Graph.

In the event of a process crash, the supervision tree managing State and Graph will make sure that the most current state of a graph is saved and reloaded when the Graph process restarts.

Modifying graphs

Elements are added and removed from the graph using the Node, Edge, and Cluster modules.

iex> {n_id, node} = Node.new(label: "Start", color: "blue")
iex> {n2_id, node2} = Node.new(label: "End", color: "red")
iex> {e_id, edge} = Edge.new(n_id, n2_id, color: "green")
iex> {c_id, cluster} = Cluster.new([n_id, n2_id])

Settings can be added to an element. Setting an attribute’s value to nil will remove the attribute.

iex> Node.update(n_id, shape: "triangle")
iex> Node.update(n2_id, color: nil) # Removes the key `color` from the node`s attributes keyword map

A cluster’s contents can be updated using add and remove

iex> {n3_id, node3} = Node.new(label: "Something else")
iex> Cluster.add(c_id, n3_id)
iex> Cluster.remove(c_id, n_id)

Saving and viewing graphs

Graphs can be easily saved in .dot format

iex> Graph.save # Saves the current state of the graph as a .dot file

These files can then be compiled to .pdf/.png/etc at the command line, or via additional helper functions on the Graph module

iex> Graph.compile # Generates dot and pdf files named for the graph
iex> Graph.compile(:png) # Generates dot and png files named for the graph

To immediately view the current state of a graph, there is Graph.graph

iex> Graph.graph # Generates dot and pdf files named for the graph, and opens the PDF in your OS's default viewer
iex> Graph.graph(:png) # Same as above, but generates and opens a .png file

Summary

Functions

clear()

Empties the stored state of Graphvix

compile(filetype \\ :pdf)

Writes the current graph to a .dot file and compiles it

current_graph()

Returns the name of the current graph

get()

Returns the Elixir map form of the current graph

graph(filetype \\ :pdf)

Writes the current graph to a .dot file, compiles it, and opens the compiled graph

ls()

Returns a list of graphs currently stored by Graphvix

new(name)

Creates a new graph named name and sets it to the current graph

save()

Saves the current graph to a .dot file

switch(name)

Switches the current graph to the graph named name

update(attrs)

Updates a graph-wide setting

write()

Returns a string of the current graph in .dot format

Functions

clear()

clear :: :ok

Empties the stored state of Graphvix.

Caution: Will delete all stored data from disk.

iex> Graph.clear
iex> Graph.ls
[]

compile(filetype \\ :pdf)

compile(atom | nil) :: :ok

Writes the current graph to a .dot file and compiles it.

Defaults to pdf.

iex> Graph.new(:first)
iex> Graph.compile
:ok #=> creates "first.dot" and "first.pdf"
iex> Graph.compile(:png)
:ok #=> creates "first.dot" and "first.png"

current_graph()

current_graph :: {atom, map}

Returns the name of the current graph.

iex> Graph.new(:first)
iex> Graph.current_graph
:first

get()

get :: map

Returns the Elixir map form of the current graph.

iex> Graph.new(:first)
iex> Graph.get
%{
  nodes: %{},
  edges: %{},
  clusters: %{},
  attrs: []
}

graph(filetype \\ :pdf)

graph(atom | nil) :: :ok

Writes the current graph to a .dot file, compiles it, and opens the compiled graph.

Defaults to pdf.

iex> Graph.new(:first)
iex> Graph.graph
:ok #=> creates "first.dot" and "first.pdf"; opens "first.pdf"
iex> Graph.graph(:png)
:ok #=> creates "first.dot" and "first.png"; opens "first.png"

ls()

ls :: [atom]

Returns a list of graphs currently stored by Graphvix

iex> Graph.new(:first)
iex> Graph.ls
[:first]

new(name)

new(atom) :: :ok

Creates a new graph named name and sets it to the current graph

iex> Graph.new(:first)
:ok

save()

save :: :ok

Saves the current graph to a .dot file.

iex> Graph.new(:first)
iex> Graph.save
:ok #=> creates "first.dot"

switch(name)

switch(atom) :: :ok

Switches the current graph to the graph named name.

Creates a new graph if it doesn’t exist.

iex> Graph.new(:first)
iex> Graph.switch(:second) # creates a graph named `:second`
iex> Graph.switch(:first) # loads the existing graph named `:first`

update(attrs)

update(Keyword.t) :: :ok

Updates a graph-wide setting.

iex> Graph.new(:first)
iex> Graph.update(size: "4, 4")
:ok

write()

write :: String.t

Returns a string of the current graph in .dot format.

iex> Graph.new(:first)
iex> Graph.write
"digraph G {
}"