An abstract document data type with O(1) time concatenation (the current implementation uses difference lists). Here s is the type of abstract symbols or strings (text or binary). Doc s is a Monoid, therefore mempty corresponds to the empty document and two documents can be concatenated with mappend (or operator <>). Documents comprising a single symbol or string can be constructed using the function literal. Alternatively, you can construct documents as string literals, e.g. simply as "alga", by using the OverloadedStrings GHC extension. To extract the document contents use the function render.

Note that the document comprising a single empty string is considered to be different from the empty document. This design choice is motivated by the desire to support string types s that have no Eq instance, such as Data.ByteString.Builder, for which there is no way to check whether a string is empty or not. As a consequence, the Eq and Ord instances are defined as follows:

mempty /= literal ""
mempty <  literal ""

Check if a document is empty. The result is the same as when comparing the given document to mempty, but this function does not require the Eq s constraint. Note that the document comprising a single empty string is considered to be different from the empty document.

isEmpty mempty       == True
isEmpty (literal "") == False
isEmpty x            == (x == mempty)

Construct a document comprising a single symbol or string. If s is an instance of class IsString, then documents of type Doc s can be constructed directly from string literals (see the second example below).

literal "Hello, " <> literal "World!" == literal "Hello, World!"
literal "I am just a string literal"  == "I am just a string literal"
render . literal                      == id

Render the document as a single string. An inverse of the function literal.

render (literal "al" <> literal "ga") :: (IsString s, Monoid s) => s
render (literal "al" <> literal "ga") == "alga"
render mempty                         == mempty
render . literal                      == id

Concatenate two documents, separated by a single space, unless one of the documents is empty. The operator <+> is associative with identity mempty.

x <+> mempty         == x
mempty <+> x         == x
x <+> (y <+> z)      == (x <+> y) <+> z
"name" <+> "surname" == "name surname"

Wrap a document in square brackets.

brackets "i"    == "[i]"
brackets mempty == "[]"

Wrap a document into double quotes.

doubleQuotes "/path/with spaces"   == "\"/path/with spaces\""
doubleQuotes (doubleQuotes mempty) == "\"\"\"\""

Prepend a given number of spaces to a document.

indent 0        == id
indent 1 mempty == " "

Concatenate documents after appending a terminating newline symbol to each.

unlines []                    == mempty
unlines [mempty]              == "\n"
unlines ["title", "subtitle"] == "title\nsubtitle\n"

Export a graph into a document given two functions that construct documents for individual vertices and edges. The order of export is: vertices, sorted by Ord a, and then edges, sorted by Ord (a, a).

For example:

vDoc x   = literal (show x) <> "\n"
eDoc x y = literal (show x) <> " -> " <> literal (show y) <> "\n"
> putStrLn $ render $ export vDoc eDoc (1 + 2 * (3 + 4) :: Graph Int)

1
2
3
4
2 -> 3
2 -> 4