Data.GraphViz.Commands

graphviz-2999.18.1.0: Bindings to Graphviz for graph visualisation.

Copyright | (c) Matthew Sackman, Ivan Lazar Miljenovic
License | 3-Clause BSD-style
Maintainer | Ivan.Miljenovic@gmail.com
Safe Haskell | None
Language | Haskell2010

Data.GraphViz.Commands

Contents

- The different Graphviz tools available.
- The possible outputs that Graphviz supports.
- Running Graphviz.
- Testing if Graphviz is installed

Description

This module defines functions to call the various Graphviz commands.

Whilst various output formats are supported (see `GraphvizOutput` for a complete list), it is not yet possible to choose a desired renderer and formatter. Being able to determine which renderers and formatters are applicable for a specific `GraphvizOutput` is not easy (there is no listing of available renderers or formatters on the Graphviz website), and for the most part the default ones do the job well.

Please note that for `GraphvizOutput` and `GraphvizCanvas`, you will see that they are instances of a `GraphvizResult` class; this is an internal class that should not be visible outside this module, but Haddock is being too helpful for its own good.

Synopsis

- data GraphvizCommand
  - = Dot
  - | Neato
  - | TwoPi
  - | Circo
  - | Fdp
  - | Sfdp
  - | Osage
  - | Patchwork
- dirCommand :: GraphvizCommand
- undirCommand :: GraphvizCommand
- commandFor :: DotRepr dg n => dg n -> GraphvizCommand
- data GraphvizOutput
  - = Bmp
  - | Canon
  - | DotOutput
  - | XDot (Maybe Version)
  - | Eps
  - | Fig
  - | Gd
  - | Gd2
  - | Gif
  - | Ico
  - | Imap
  - | Cmapx
  - | ImapNP
  - | CmapxNP
  - | Jpeg
  - | Pdf
  - | Plain
  - | PlainExt
  - | Png
  - | Ps
  - | Ps2
  - | Svg
  - | SvgZ
  - | Tiff
  - | Vml
  - | VmlZ
  - | Vrml
  - | WBmp
  - | WebP
- data GraphvizCanvas
  - = Gtk
  - | Xlib
- runGraphviz :: PrintDotRepr dg n => dg n -> GraphvizOutput -> FilePath -> IO FilePath
- runGraphvizCommand :: PrintDotRepr dg n => GraphvizCommand -> dg n -> GraphvizOutput -> FilePath -> IO FilePath
- addExtension :: (GraphvizOutput -> FilePath -> a) -> GraphvizOutput -> FilePath -> a
- runGraphvizCanvas :: PrintDotRepr dg n => GraphvizCommand -> dg n -> GraphvizCanvas -> IO ()
- runGraphvizCanvas' :: PrintDotRepr dg n => dg n -> GraphvizCanvas -> IO ()
- graphvizWithHandle :: PrintDotRepr dg n => GraphvizCommand -> dg n -> GraphvizOutput -> (Handle -> IO a) -> IO a
- isGraphvizInstalled :: IO Bool
- quitWithoutGraphviz :: String -> IO ()

# The different Graphviz tools available.

data GraphvizCommand

The available Graphviz commands. The following directions are based upon those in the Graphviz man page (available online at http://graphviz.org/pdf/dot.1.pdf, or if installed on your system `man graphviz`). Note that any command can be used on both directed and undirected graphs.

When used with the `Layout` attribute, it overrides any actual command called on the dot graph.

Constructors

Dot | For hierachical graphs (ideal for directed graphs).
Neato | For symmetric layouts of graphs (ideal for undirected graphs).
TwoPi | For radial layout of graphs.
Circo | For circular layout of graphs.
Fdp | Spring-model approach for undirected graphs.
Sfdp | As with Fdp, but ideal for large graphs.
Osage | Filter for drawing clustered graphs, requires Graphviz >= 2.28.0.
Patchwork | Draw clustered graphs as treemaps, requires Graphviz >= 2.28.0.

Instances

Bounded GraphvizCommand |
Enum GraphvizCommand |
Eq GraphvizCommand |
Ord GraphvizCommand |
Read GraphvizCommand |
Show GraphvizCommand |
ParseDot GraphvizCommand |
PrintDot GraphvizCommand |

dirCommand :: GraphvizCommand

The default command for directed graphs.

undirCommand :: GraphvizCommand

The default command for undirected graphs.

commandFor :: DotRepr dg n => dg n -> GraphvizCommand

The appropriate (default) Graphviz command for the given graph.

# The possible outputs that Graphviz supports.

The list of output types supported by Graphviz is dependent upon how it is built on your system. To determine which actual formats are available on your system, run `dot -T?`. Trying to use an output type that is not supported by your installation of Graphviz will result in an error.

The outputs defined here in `GraphvizOutput` and `GraphvizCanvas` are those from the default list of available outputs. For more information, see: http://graphviz.org/doc/info/output.html

data GraphvizOutput

The possible Graphviz output formats (that is, those that actually produce a file).

Constructors

Bmp | Windows Bitmap Format.
Canon | Pretty-printed Dot output with no layout performed.
DotOutput | Reproduces the input along with layout information.
XDot (Maybe Version) | As with `DotOutput`, but provides even more information on how the graph is drawn. The optional `Version` is the same as specifying the `XDotVersion` attribute.
Eps | Encapsulated PostScript.
Fig | FIG graphics language.
Gd | Internal GD library format.
Gd2 | Compressed version of `Gd`.
Gif | Graphics Interchange Format.
Ico | Icon image file format.
Imap | Server-side imagemap.
Cmapx | Client-side imagemap.
ImapNP | As for `Imap`, except only rectangles are used as active areas.
CmapxNP | As for `Cmapx`, except only rectangles are used as active areas.
Jpeg | The JPEG image format.
Pdf | Portable Document Format.
Plain | Simple text format.
PlainExt | As for `Plain`, but provides port names on head and tail nodes when applicable.
Png | Portable Network Graphics format.
Ps | PostScript.
Ps2 | PostScript for PDF.
Svg | Scalable Vector Graphics format.
SvgZ | Compressed SVG format.
Tiff | Tagged Image File Format.
Vml | Vector Markup Language; `Svg` is usually preferred.
VmlZ | Compressed VML format; `SvgZ` is usually preferred.
Vrml | Virtual Reality Modeling Language format; requires nodes to have a third dimension set via the `Pos` attribute (and with a `Dim` value of at least `3`).
WBmp | Wireless BitMap format; monochrome format usually used for mobile computing devices.
WebP | Google's WebP format; requires Graphviz >= 2.29.0.

Instances

Eq GraphvizOutput |
Ord GraphvizOutput |
Read GraphvizOutput |
Show GraphvizOutput |

data GraphvizCanvas

Unlike `GraphvizOutput`, these items do not produce an output file; instead, they directly draw a canvas (i.e. a window) with the resulting image.

Constructors

Gtk |
Xlib |

Instances

Bounded GraphvizCanvas |
Enum GraphvizCanvas |
Eq GraphvizCanvas |
Ord GraphvizCanvas |
Read GraphvizCanvas |
Show GraphvizCanvas |

# Running Graphviz.

runGraphviz :: PrintDotRepr dg n => dg n -> GraphvizOutput -> FilePath -> IO FilePath

Run the recommended Graphviz command on this graph, saving the result to the file provided (note: file extensions are not checked).

runGraphvizCommand :: PrintDotRepr dg n => GraphvizCommand -> dg n -> GraphvizOutput -> FilePath -> IO FilePath

Run the chosen Graphviz command on this graph, saving the result to the file provided (note: file extensions are not checked).

addExtension :: (GraphvizOutput -> FilePath -> a) -> GraphvizOutput -> FilePath -> a

Append the default extension for the provided `GraphvizOutput` to the provided `FilePath` for the output file.

runGraphvizCanvas :: PrintDotRepr dg n => GraphvizCommand -> dg n -> GraphvizCanvas -> IO ()

Run the chosen Graphviz command on this graph and render it using the given canvas type.

runGraphvizCanvas' :: PrintDotRepr dg n => dg n -> GraphvizCanvas -> IO ()

Run the recommended Graphviz command on this graph and render it using the given canvas type.

graphvizWithHandle

Arguments

:: PrintDotRepr dg n |
=> GraphvizCommand | Which command to run
-> dg n | The `DotRepr` to use
-> GraphvizOutput | The `GraphvizOutput` type
-> (Handle -> IO a) | Extract the output
-> IO a | The error or the result.

Run the chosen Graphviz command on this graph, but send the result to the given handle rather than to a file.

Note that the ``Handle` -> `IO` a` function must fully consume the input from the `Handle`; e.g. use strict `ByteStrings` rather than lazy ones.

If the command was unsuccessful, then a `GraphvizException` is thrown.

# Testing if Graphviz is installed

isGraphvizInstalled :: IO Bool

Is the Graphviz suite of tools installed? This is determined by whether `dot` is available in the `PATH`.

quitWithoutGraphviz :: String -> IO ()

If Graphviz does not seem to be available, print the provided error message and then exit fatally.