An opaque data type with a Pretty instance, for printing to a console. Build a table with makeTable, and show it with the pretty-printing functions re-exported from this module.

A single horizontal row of a Table. Each row is visually separated from the next by a vertical line. Each row in the table must contain the same number of elements (however, any number of them can be Nothing).

A single horizontal slice of a Table, containing one or more TableRows. Each slice is visually separated from the next by a horizontal line.

Make a Table from a list of headers and a list of TableSlices, each of which contains a list of TableRows, each of which contain a list of Values. It is assumed that all dimensions align properly (e.g. each row contains the same number of elements, which is equal to the length of the list of headers).

Each top-level object is flattened into one column per leaf. Note that this means it is not possible to distinguish between e.g. {"foo":{"bar":5}} and {"foo.bar":5}. Hopefully this is not too much of a problem in practice.

Each vertically aligned element need not contain the same set of keys; for example, the table corresponding to

[ [{"foo": "bar"}], [{"baz": "qux"}] ] -- one TableSlice

will simply look like

+-------------+
| foo   baz   |
+=============+
| "bar"       |
|       "qux" |
+-------------+

That is, each missing value is simply not displayed.

Like makeTable, but takes explicit rendering functions. This is useful for adding ANSI escape codes to color output, or for rendering values depending on what their key is.

For example, you may wish to render Strings with a "timestamp" key without quotation marks.

The Int argument is the header's index. The (Int, Int) argument is the (absolute, relative) index of the key and value. Visually,

+-------------+-------------+
| 0           | 1           |
|             |             |
| (0,0) (1,1) | (2,0) (3,1) |
+=============+=============+
| (0,0) (1,1) | (2,0) (3,1) |
| (0,0) (1,1) | (2,0) (3,1) |
+-------------+-------------+

This function is (unfortunately) String-based as of 0.3.0.0, because the pretty printing and ANSI escape code functions are String-based, too.

Pretty-print a Value in one line.

Flatten an Value so that it contains no top-level Value values.

The abstract data type Doc represents pretty documents.

Doc is an instance of the Show class. (show doc) pretty prints document doc with a page width of 100 characters and a ribbon width of 40 characters.

show (text "hello" `above` text "world")

Which would return the string "hello\nworld", i.e.

hello
world

The action (putDoc doc) pretty prints document doc to the standard output, with a page width of 100 characters and a ribbon width of 40 characters.

main :: IO ()
main = do{ putDoc (text "hello" <+> text "world") }

Which would output

hello world

(hPutDoc handle doc) pretty prints document doc to the file handle handle with a page width of 100 characters and a ribbon width of 40 characters.

main = do{ handle <- openFile "MyFile" WriteMode
         ; hPutDoc handle (vcat (map text
                           ["vertical","text"]))
         ; hClose handle
         }

The member prettyList is only used to define the instance Pretty a => Pretty [a]. In normal circumstances only the pretty function is used.

The data type SimpleDoc represents rendered documents and is used by the display functions.

The Int in SText contains the length of the string. The Int in SLine contains the indentation for that line. The library provides two default display functions displayS and displayIO. You can provide your own display function by writing a function from a SimpleDoc to your own output format.

This is the default pretty printer which is used by show, putDoc and hPutDoc. (renderPretty ribbonfrac width x) renders document x with a page width of width and a ribbon width of (ribbonfrac * width) characters. The ribbon width is the maximal amount of non-indentation characters on a line. The parameter ribbonfrac should be between 0.0 and 1.0. If it is lower or higher, the ribbon width will be 0 or width respectively.

(renderCompact x) renders document x without adding any indentation. Since no 'pretty' printing is involved, this renderer is very fast. The resulting output contains fewer characters than a pretty printed version and can be used for output that is read by other programs.

A slightly smarter rendering algorithm with more lookahead. It provides provide earlier breaking on deeply nested structures. For example, consider this python-ish pseudocode: fun(fun(fun(fun(fun([abcdefg, abcdefg]))))) If we put a softbreak (+ nesting 2) after each open parenthesis, and align the elements of the list to match the opening brackets, this will render with renderPretty and a page width of 20c as: fun(fun(fun(fun(fun([ | abcdef, | abcdef, ] ))))) | Where the 20c. boundary has been marked with |. Because renderPretty only uses one-line lookahead, it sees that the first line fits, and is stuck putting the second and third lines after the 20c mark. In contrast, renderSmart will continue to check the potential document up to the end of the indentation level. Thus, it will format the document as:

fun(                |
  fun(              |
    fun(            |
      fun(          |
        fun([       |
              abcdef,
              abcdef,
            ]       |
  )))))             |

Which fits within the 20c. mark. In addition, renderSmart uses this lookahead to minimize the number of lines printed, leading to more compact and visually appealing output. Consider this example using the same syntax as above: aaaaaaaaaaa([abc, def, ghi]) When rendered with renderPretty and a page width of 20c, we get: aaaaaaaaaaa([ abc , def , ghi ]) Whereas when rendered with renderSmart and a page width of 20c, we get: aaaaaaaaaaa( [abc, def, ghi])

(displayS simpleDoc) takes the output simpleDoc from a rendering function and transforms it to a ShowS type (for use in the Show class).

showWidth :: Int -> Doc -> String
showWidth w x   = displayS (renderPretty 0.4 w x) ""

(displayIO handle simpleDoc) writes simpleDoc to the file handle handle. This function is used for example by hPutDoc:

hPutDoc handle doc  = displayIO handle (renderPretty 0.4 100 doc)