Data.GraphViz.Types

This module defines the overall types and methods that interact with them for the Graphviz library. The specifications are based loosely upon the information available at: http://graphviz.org/doc/info/lang.html

Printing of Dot code is done as strictly as possible, whilst parsing is as permissive as possible. For example, if the types allow it then "2" will be parsed as an Int value. Note that quoting and escaping of String values is done automagically.

A summary of known limitations/differences:

• When creating GraphID values for graphID and subGraphID, you should ensure that none of them have the same printed value as one of the nodeID values to avoid any possible problems.
• If you want any GlobalAttributes in a DotSubGraph and want them to only apply to that DotSubGraph, then you must ensure it does indeed have a valid GraphID.
• All DotSubGraphs with isCluster = True must have unique subGraphID values (well, only if you want them to be generated sensibly).
• If eventually outputting to a format such as SVG, then you should make sure that your DotGraph has a graphID, as that is used as the title of the resulting image.
• Whilst DotGraph, etc. are polymorphic in their node type, you should ensure that you use a relatively simple node type (that is, it only covers a single line, etc.).
• Also, whilst Graphviz allows you to mix the types used for nodes, this library requires/assumes that they are all the same type.
• DotEdge defines an edge (a, b) (with an edge going from a to b); in Dot parlance the edge has a head at a and a tail at b. Care must be taken when using the related Head* and Tail* Attributes. See the differences section in Data.GraphViz.Attributes for more information.
• It is common to see multiple edges defined on the one line in Dot (e.g. n1 -> n2 -> n3 means to create a directed edge from n1 to n2 and from n2 to n3). These types of edge definitions are parseable; however, they are converted to singleton edges.
• It is not yet possible to create or parse edges with subgraphs/clusters as one of the end points.
• When either creating a DotGraph by hand or parsing one, it is possible to specify that directedGraph = d, but DotEdge values with directedEdge = not d.
• Cannot place items in an arbitrary order: in particular, this means that it is not possible to use the normal Graphviz hack of having graph attributes that do not apply to subgraphs/clusters by listing them after the subgraphs/clusters. If you wish to be able to use an arbitrary ordering, you may wish to use Data.GraphViz.Types.Generalised.
• The parser will strip out comments and pre-processor lines, join together multiline statements and concatenate split strings together. However, pre-processing within HTML-like labels is currently not supported.
• Graphviz allows a node to be "defined" twice (e.g. the actual node definition, and then in a subgraph with extra global attributes applied to it). This actually represents the same node, but when parsing they will be considered as separate DotNodes (such that graphNodes will return both "definitions"). The canonical form (see prettyPrint in Data.GraphViz) combines the "definitions" into one.

See Data.GraphViz.Attributes for more limitations.

Abstraction from the representation type

class (PrintDot (dg n), ParseDot (dg n)) => DotRepr dg n where

This class is used to provide a common interface to different ways of representing a graph in Dot form.

Methods

getID :: dg n -> Maybe GraphID

Return the ID of the graph.

graphIsDirected :: dg n -> Bool

Is this graph directed?

graphIsStrict :: dg n -> Bool

Is this graph strict?

makeStrict :: dg n -> dg n

A strict graph disallows multiple edges.

setID :: GraphID -> dg n -> dg n

Set the ID of the graph.

graphStructureInformation :: dg n -> (GlobalAttributes, ClusterLookup)

Return information on all the clusters contained within this DotRepr, as well as the top-level GraphAttrs for the overall graph.

nodeInformation :: Bool -> dg n -> NodeLookup n

Return information on the DotNodes contained within this DotRepr. The Bool parameter indicates if applicable NodeAttrs should be included.

edgeInformation :: Bool -> dg n -> [DotEdge n]

Return information on the DotEdges contained within this DotRepr. The Bool parameter indicates if applicable EdgeAttrs should be included.

Instances

(Ord n, PrintDot n, ParseDot n) => DotRepr DotGraph n

(Ord n, PrintDot n, ParseDot n) => DotRepr GDotGraph n

Helper types for looking up information within a DotRepr.

type ClusterLookup = Map (Maybe GraphID) ([Path], GlobalAttributes)

The available information for each cluster; the [Path] denotes all locations where that particular cluster is located (more than one location can indicate possible problems).

type NodeLookup n = Map n (Path, Attributes)

The available information on each DotNode (both explicit and implicit).

type Path = Seq (Maybe GraphID)

The path of clusters that must be traversed to reach this spot.

Obtaining the DotNodes and DotEdges.

graphNodes :: (DotRepr dg n, Ord n) => dg n -> [DotNode n]

Returns all resultant DotNodes in the DotRepr (not including NodeAttrs).

graphEdges :: DotRepr dg n => dg n -> [DotEdge n]

Returns all resultant DotEdges in the DotRepr (not including EdgeAttrs).

Printing and parsing a DotRepr.

printDotGraph :: DotRepr dg n => dg n -> String

The actual Dot code for an instance of DotRepr. Note that it is expected that parseDotGraph . printDotGraph == id (this might not be true the other way around due to un-parseable components).

parseDotGraph :: DotRepr dg n => String -> dg n

Parse a limited subset of the Dot language to form an instance of DotRepr. Each instance may have its own limitations on what may or may not be parseable Dot code.

Also removes any comments, etc. before parsing.

The overall representation of a graph in Dot format.

data DotGraph a

The internal representation of a graph in Dot form.

Constructors

DotGraph

Fields

strictGraph :: Bool

If True, no multiple edges are drawn.

directedGraph :: Bool

graphID :: Maybe GraphID

graphStatements :: DotStatements a

Instances

Functor DotGraph

(Ord n, PrintDot n, ParseDot n) => DotRepr DotGraph n

Eq a => Eq (DotGraph a)

Ord a => Ord (DotGraph a)

Read a => Read (DotGraph a)

Show a => Show (DotGraph a)

ParseDot a => ParseDot (DotGraph a)

PrintDot a => PrintDot (DotGraph a)

Reporting of errors in a DotGraph.

data DotError a

Used to record invalid Attribute usage. A Just value denotes that it was used in an explicit DotNode or DotEdge usage; Nothing means that it was used in a GlobalAttributes value.

Constructors

GraphError Attribute

NodeError (Maybe a) Attribute

EdgeError (Maybe (a, a)) Attribute

Instances

Eq a => Eq (DotError a)

Ord a => Ord (DotError a)

Read a => Read (DotError a)

Show a => Show (DotError a)

isValidGraph :: DotGraph a -> Bool

Check if all the Attributes are being used correctly.

graphErrors :: DotGraph a -> [DotError a]

Return detectable errors in the DotGraph.

Sub-components of a DotGraph.

data GraphID

A polymorphic type that covers all possible ID values allowed by Dot syntax. Note that whilst the ParseDot and PrintDot instances for String will properly take care of the special cases for numbers, they are treated differently here.

Constructors

Str String

Int Int

Dbl Double

Instances

Eq GraphID

Ord GraphID

Read GraphID

Show GraphID

ParseDot GraphID

PrintDot GraphID

data DotStatements a

Constructors

DotStmts

Fields

attrStmts :: [GlobalAttributes]

subGraphs :: [DotSubGraph a]

nodeStmts :: [DotNode a]

edgeStmts :: [DotEdge a]

Instances

Functor DotStatements

Eq a => Eq (DotStatements a)

Ord a => Ord (DotStatements a)

Read a => Read (DotStatements a)

Show a => Show (DotStatements a)

ParseDot a => ParseDot (DotStatements a)

PrintDot a => PrintDot (DotStatements a)

data GlobalAttributes

Represents a list of top-level list of Attributes for the entire graph/sub-graph. Note that GraphAttrs also applies to DotSubGraphs.

Note that Dot allows a single Attribute to be listen on a line; if this is the case then when parsing, the type of Attribute it is determined and that type of GlobalAttribute is created.

Constructors

GraphAttrs

Fields

attrs :: Attributes

NodeAttrs

Fields

attrs :: Attributes

EdgeAttrs

Fields

attrs :: Attributes

Instances

Eq GlobalAttributes

Ord GlobalAttributes

Read GlobalAttributes

Show GlobalAttributes

ParseDot GlobalAttributes

PrintDot GlobalAttributes

data DotSubGraph a

Constructors

DotSG

Fields

isCluster :: Bool

subGraphID :: Maybe GraphID

subGraphStmts :: DotStatements a

Instances

Functor DotSubGraph

Eq a => Eq (DotSubGraph a)

Ord a => Ord (DotSubGraph a)

Read a => Read (DotSubGraph a)

Show a => Show (DotSubGraph a)

ParseDot a => ParseDot (DotSubGraph a)

PrintDot a => PrintDot (DotSubGraph a)

data DotNode a

A node in DotGraph.

Constructors

DotNode

Fields

nodeID :: a

nodeAttributes :: Attributes

Instances

Functor DotNode

Eq a => Eq (DotNode a)

Ord a => Ord (DotNode a)

Read a => Read (DotNode a)

Show a => Show (DotNode a)

ParseDot a => ParseDot (DotNode a)

PrintDot a => PrintDot (DotNode a)

data DotEdge a

An edge in DotGraph.

Constructors

DotEdge

Fields

edgeFromNodeID :: a

edgeToNodeID :: a

directedEdge :: Bool

edgeAttributes :: Attributes

Instances

Functor DotEdge

Eq a => Eq (DotEdge a)

Ord a => Ord (DotEdge a)

Read a => Read (DotEdge a)

Show a => Show (DotEdge a)

ParseDot a => ParseDot (DotEdge a)

PrintDot a => PrintDot (DotEdge a)