package alba

Pretty Printer: Generate nicely formatted ascii text.

Overview

Example

The usage of the pretty printer is best explained by an example. Suppose we want to print the function application f a b (g c d) e where the function names and arguments might have different length. We create a document which represents the structure by

let doc =
    group (
        text "f" <+> space <+>
        indent
            2
            (stack_or_pack
                " "
                [text "a";
                 text "b";
                 group (
                     text "(g" <+> space <+>
                     indent
                        2
                        (stack_or_pack " " [text "c"; text "d"])
                     <+> text ")");
                 text "e"])
    )

where text "blabla" is a document with some unbreakable text, <+> concatenates two documents, space is a break hint whose alternative text is a blank, stack_or_pack atxt [...] stacks a list of documents separated by a break hint with the alternative text atxt.

The command

let stream = layout 5 doc 

creates a stream of characters which is nicely formatted using a desired line width of 5 characters. Since 5 characters are not enough to put any of the subterms completely on a line, the output is

123456789012345
f
  a
  b
  (g
    c
    d)
  d

i.e. each break hint is printed as a newline.

If we give the pretty printer a line width of 10, it could pack the application g c d on a line and print

123456789012345
f
  a
  b
  (g c d)
  d

If the pretty printer has enough line width e.g. a line width of 15, it can put the whole expression on a line.

123456789012345
f a b (g c d) d

By using stack_or_pack we instructed the pretty printer to either print all break hints as newlines or all break hints with their alternative texts. If we use pack instead of stack_or_pack, the pretty printer tries to pack as many arguments as possible on a line.

E.g. with a line width of 11 and using pack instead of stack_or_pack we get the output

123456789012345
f
  a b
  (g c d) d

With a line width of 10 and using pack we get

123456789012345
f
  a b
  (g c d)
  d

because the pretty printer cannot pack (g c d) and d on a single line.

Character Stream

The basic type t of the pretty printer is a lazy character stream. I.e. characters are only generated if needed. The pretty printer implements the interface Module_types.READABLE to represent a character stream. You can ask the stream has_more r whether there are more characters in the stream and peek r to get the next character. The instruction advance r returns the stream r advanced by one character position.

The pretty printer has a function string_of r to return a string representation of the character stream.

However you very rarely need a string representation of a character stream. All io function in Fmlib are able to handle character streams.

Generate Documents

Clearly, it is tedious to write documents by hand. Usually you have some tree like structure and you want to generate a document from the tree structure.

Let's assume you have a tree structure like

type tree =
    { name: string; children: tree list; }

let leaf (name: string): tree =
    {name; children = [] }

let tree (name: string) (children: tree list): tree =
    {name; children}

Write a function which converts the tree structure to a document.

let doc_of_tree (tree: tree): doc =
    let rec doc is_top tree =
        match tree.children with
        | [] ->
            text tree.name
        | _ ->
            let d =
                parent_child
                    " " 2
                    (text tree.name)
                    (children tree.children ())
            in
            if is_top then
                d
            else
                char '(' <+> d <+> char ')'
    and children lst () =
        match lst with
        | [last] ->
            doc false last
        | head :: tail ->
            doc false head <+> space
            >> children tail    (* Lazy concatenation!! *)
        | [] ->
            assert false (* 'lst' is never empty *)
    in
    doc true tree

Then the simple command

tree
    "f"
    [leaf "a";
     leaf "b";
     tree "g" [leaf "c"; leaf "d"];
     leaf "e"]
|> layout 10

generates the character stream

123456789012345
f
  a
  b
  (g c d)
  e

Note the usage of the lazy concatentation operator >> in the recursive part of the function handling the children. This makes sure that even if the tree structure is hugh, the iteration over it is done only on demand. I.e. recursive calls are made only if the corresponding characters are needed when processing the character stream.

API

parent
<+> break hint
<+> nest indent (group child)
|> group