This is the top-level module for the graphviz library. It provides functions to convert Graphs into the Dot language used by the Graphviz suite of programs (as well as a limited ability to perform the reverse operation).

If you wish to construct a Haskell representation of a Dot graph yourself rather than using the conversion functions here, please see the Data.GraphViz.Types module as a starting point for how to do so.

Information about Graphviz and the Dot language can be found at: http://graphviz.org/

A GraphvizParams value contains all the information necessary to manipulate Graphs with this library. As such, its components deal with:

• Whether to treat graphs as being directed or not;
• Which top-level GlobalAttributes values should be applied;
• How to define (and name) clusters;
• How to format clusters, nodes and edges.

Apart from not having to pass multiple values around, another advantage of using GraphvizParams over the previous approach is that there is no distinction between clustering and non-clustering variants of the same functions.

Example usages of GraphvizParams follow:

• Quickly visualise a graph using the default parameters. Note the usage of nonClusteredParams over defaultParams to avoid type-checking problems with the cluster type.

 defaultVis :: (Graph gr) => gr nl el -> DotGraph Node
 defaultVis = graphToDot nonClusteredParams

• As with defaultVis, but determine whether or not the graph is directed or undirected.

 checkDirectednessVis :: (Graph gr, Ord el) => gr nl el -> DotGraph Node
 checkDirectednessVis = setDirectedness graphToDot nonClusteredParams

• Clustering nodes based upon whether they are even or odd. We have the option of either constructing a GraphvizParams directly, or using blankParams. Using the latter to avoid setting isDirected:

 evenOdd :: (Graph gr, Ord el) => gr Int el -> DotGraph Node
 evenOdd = setDirectedness graphToDot params
   where
     params = blankParams { globalAttributes = []
                          , clusterBy        = clustBy
                          , clusterID        = Int
                          , fmtCluster       = clFmt
                          , fmtNode          = const []
                          , fmtEdge          = const []
                          }
     clustBy (n,l) = C (n `mod` 2) $ N (n,l)
     clFmt m = [GraphAttrs [toLabel $ "n == " ++ show m ++ " (mod 2)"]]

For more examples, see the source of dotizeGraph and preview.

The following functions provide support for passing a Graph through the appropriate GraphvizCommand to augment the Graph by adding positional information, etc.

A CustomAttribute is used to distinguish multiple edges between two nodes from each other.

Note that the reason that most of these functions do not have unsafePerformIO applied to them is because if you set a global Attribute of:

    Start (StartStyle RandomStyle)

then it will not necessarily be referentially transparent (ideally, no matter what the seed is, it will still eventually be drawn to the same optimum, but this can't be guaranteed). As such, if you are sure that you're not using such an Attribute, then you should be able to use unsafePerformIO directly in your own code.

This section allows you to manually augment graphs by providing fine-grained control over the augmentation process (the standard augmentation functions compose these together). Possible reasons for manual augmentation are:

• Gain access to the intermediary DotRepr used.
• Convert the default DotGraph to a GDotGraph (found in Data.GraphViz.Types.Generalised) so as to have greater control over the generated Dot code.
• Use a specific GraphvizCommand rather than the default.

Note that whilst these functions provide you with more control, you must be careful how you use them: if you use the wrong DotRepr for a Graph, then the behaviour of augmentGraph (and all functions that use it) is undefined. The main point is to make sure that the defined DotNode and DotEdge values aren't removed (or their ID values - or the Attributes for the DotEdges - altered) to ensure that it is possible to match up the nodes and edges in the Graph with those in the DotRepr.