Data.GraphViz.Commands.IO

graphviz-2999.18.1.0: Bindings to Graphviz for graph visualisation.

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

Data.GraphViz.Commands.IO

Contents

- Encoding
- Operations on files
- Operations on handles
- Special cases for standard input and output
- Running external commands

Description

Various utility functions to help with custom I/O of Dot code.

Synopsis

- toUTF8 :: ByteString -> Text
- writeDotFile :: PrintDotRepr dg n => FilePath -> dg n -> IO ()
- readDotFile :: ParseDotRepr dg n => FilePath -> IO (dg n)
- hPutDot :: PrintDotRepr dg n => Handle -> dg n -> IO ()
- hPutCompactDot :: PrintDotRepr dg n => Handle -> dg n -> IO ()
- hGetDot :: ParseDotRepr dg n => Handle -> IO (dg n)
- hGetStrict :: Handle -> IO Text
- putDot :: PrintDotRepr dg n => dg n -> IO ()
- readDot :: ParseDotRepr dg n => IO (dg n)
- runCommand :: PrintDotRepr dg n => String -> [String] -> (Handle -> IO a) -> dg n -> IO a

# Encoding

By default, Dot code should be in UTF-8. However, by usage of the charset attribute, users are able to specify that the ISO-8859-1 (aka Latin1) encoding should be used instead: http://www.graphviz.org/doc/info/attrs.html#d:charset

To simplify matters, graphviz does not work with ISO-8859-1. If you wish to deal with existing Dot code that uses this encoding, you will need to manually read that file in to a `Text` value.

If a non-UTF-8 encoding is used, then a `GraphvizException` will be thrown.

toUTF8 :: ByteString -> Text

Explicitly convert a (lazy) `ByteString` to a `Text` value using UTF-8 encoding, throwing a `GraphvizException` if there is a decoding error.

# Operations on files

writeDotFile :: PrintDotRepr dg n => FilePath -> dg n -> IO ()

Write the specified `DotRepr` to file.

readDotFile :: ParseDotRepr dg n => FilePath -> IO (dg n)

Read in and parse a `DotRepr` value from a file.

# Operations on handles

hPutDot :: PrintDotRepr dg n => Handle -> dg n -> IO ()

Output the `DotRepr` to the specified `Handle`.

hPutCompactDot :: PrintDotRepr dg n => Handle -> dg n -> IO ()

Output the `DotRepr` to the spcified `Handle` in a more compact, machine-oriented form.

hGetDot :: ParseDotRepr dg n => Handle -> IO (dg n)

Read in and parse a `DotRepr` value from the specified `Handle`.

hGetStrict :: Handle -> IO Text

Strictly read in a `Text` value using an appropriate encoding.

# Special cases for standard input and output

putDot :: PrintDotRepr dg n => dg n -> IO ()

Print the specified `DotRepr` to `stdout`.

readDot :: ParseDotRepr dg n => IO (dg n)

Read in and parse a `DotRepr` value from `stdin`.

# Running external commands

runCommand

Arguments

:: PrintDotRepr dg n |
=> String | Command to run
-> [String] | Command-line arguments
-> (Handle -> IO a) | Obtaining the output; should be strict.
-> dg n |
-> IO a |

Run an external command on the specified `DotRepr`. Remember to use `hSetBinaryMode` on the `Handle` for the output function if necessary.

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

For performance reasons, a temporary file is used to store the generated Dot code. As such, this is only suitable for local commands.