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