Module PPrint

A package of all of the above.

include PPrintEngine

Building documents

type document

This is the abstract type of documents.

val empty : document

empty is the empty document.

val char : char -> document

char c is a document that consists of the single character c. This character must not be a newline.

val string : string -> document

string s is a document that consists of the string s. This string must not contain a newline.

val substring : string -> int -> int -> document

substring s ofs len is a document that consists of the portion of the string s delimited by the offset ofs and the length len. This portion must not contain a newline.

val fancystring : string -> int -> document

fancystring s apparent_length is a document that consists of the string s. This string must not contain a newline. The string may contain fancy characters: color escape characters, UTF-8 or multi-byte characters, etc. Thus, its apparent length (which measures how many columns the text will take up on screen) differs from its length in bytes.

val fancysubstring : string -> int -> int -> int -> document

fancysubstring s ofs len apparent_length is a document that consists of the portion of the string s delimited by the offset ofs and the length len. This portion must contain a newline. The string may contain fancy characters.

val utf8string : string -> document

utf8string s is a document that consists of the UTF-8-encoded string s. This string must not contain a newline.

val hardline : document

hardline is a forced newline document. This document forces all enclosing groups to be printed in non-flattening mode. In other words, any enclosing groups are dissolved.

val blank : int -> document

blank n is a document that consists of n blank characters.

val break : int -> document

break n is a document which consists of either n blank characters, when forced to display on a single line, or a single newline character, otherwise. Note that there is no choice at this point: choices are encoded by the group combinator.

val (^^) : document -> document -> document

doc1 ^^ doc2 is the concatenation of the documents doc1 and doc2.

val nest : int -> document -> document

nest j doc is the document doc, in which the indentation level has been increased by j, that is, in which j blanks have been inserted after every newline character. Read this again: indentation is inserted after every newline character. No indentation is inserted at the beginning of the document.

val group : document -> document

group doc encodes a choice. If possible, then the entire document group doc is rendered on a single line. Otherwise, the group is dissolved, and doc is rendered. There might be further groups within doc, whose presence will lead to further choices being explored.

val ifflat : document -> document -> document

ifflat doc1 doc2 is rendered as doc1 if part of a group that can be successfully flattened, and is rendered as doc2 otherwise. Use this operation with caution. Because the pretty-printer is free to choose between doc1 and doc2, these documents should be semantically equivalent.

val align : document -> document

align doc is the document doc, in which the indentation level has been set to the current column. Thus, doc is rendered within a box whose upper left corner is the current position.

type point = int * int

A point is a pair of a line number and a column number.

type range = point * point

A range is a pair of points.

val range : (range -> unit) -> document -> document

range hook doc is printed exactly like the document doc, but allows the caller to register a hook that is applied, when the document is printed, to the range occupied by this document in the output text. This offers a way of mapping positions in the output text back to (sub)documents.

Rendering documents

module ToChannel = PPrintEngine.ToChannel

This renderer sends its output into an output channel.

module ToBuffer = PPrintEngine.ToBuffer

This renderer sends its output into a memory buffer.

module ToFormatter = PPrintEngine.ToFormatter

This renderer sends its output into a formatter channel.

Defining custom documents

type requirement = int
val infinity : requirement
class type output = object ... end
type state = {
width : int;

The line width. This parameter is fixed throughout the execution of the renderer.

ribbon : int;

The ribbon width. This parameter is fixed throughout the execution of the renderer.

mutable last_indent : int;

The number of blanks that were printed at the beginning of the current line. This field is updated (only) when a hardline is emitted. It is used (only) to determine whether the ribbon width constraint is respected.

mutable line : int;

The current line. This field is updated (only) when a hardline is emitted. It is not used by the pretty-printing engine itself.

mutable column : int;

The current column. This field must be updated whenever something is sent to the output channel. It is used (only) to determine whether the width constraint is respected.

}
class type custom = object ... end
val custom : custom -> document

The function custom constructs a custom document. In other words, it converts an object of type custom to a document.

val requirement : document -> requirement

requirement doc computes the width requirement of the document doc. It works in constant time.

val pretty : output -> state -> int -> bool -> document -> unit

pretty output state indent flatten doc prints the document doc. See the documentation of the method pretty.

val compact : output -> document -> unit

compact output doc prints the document doc. See the documentation of the method compact.

include PPrintCombinators

Single characters

val lparen : PPrintEngine.document
val rparen : PPrintEngine.document
val langle : PPrintEngine.document
val rangle : PPrintEngine.document
val lbrace : PPrintEngine.document
val rbrace : PPrintEngine.document
val lbracket : PPrintEngine.document
val rbracket : PPrintEngine.document
val squote : PPrintEngine.document
val dquote : PPrintEngine.document
val bquote : PPrintEngine.document
val semi : PPrintEngine.document
val colon : PPrintEngine.document
val comma : PPrintEngine.document
val space : PPrintEngine.document
val dot : PPrintEngine.document
val sharp : PPrintEngine.document
val slash : PPrintEngine.document
val backslash : PPrintEngine.document
val equals : PPrintEngine.document
val qmark : PPrintEngine.document
val tilde : PPrintEngine.document
val at : PPrintEngine.document
val percent : PPrintEngine.document
val dollar : PPrintEngine.document
val caret : PPrintEngine.document
val ampersand : PPrintEngine.document
val star : PPrintEngine.document
val plus : PPrintEngine.document
val minus : PPrintEngine.document
val underscore : PPrintEngine.document
val bang : PPrintEngine.document
val bar : PPrintEngine.document

Delimiters

val precede : PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

precede l x is l ^^ x.

val terminate : PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

terminate r x is x ^^ r.

val enclose : PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

enclose l r x is l ^^ x ^^ r.

val squotes : PPrintEngine.document -> PPrintEngine.document
val dquotes : PPrintEngine.document -> PPrintEngine.document
val bquotes : PPrintEngine.document -> PPrintEngine.document
val braces : PPrintEngine.document -> PPrintEngine.document
val parens : PPrintEngine.document -> PPrintEngine.document
val angles : PPrintEngine.document -> PPrintEngine.document
val brackets : PPrintEngine.document -> PPrintEngine.document

Repetition

val twice : PPrintEngine.document -> PPrintEngine.document

twice doc is the document obtained by concatenating two copies of the document doc.

val repeat : int -> PPrintEngine.document -> PPrintEngine.document

repeat n doc is the document obtained by concatenating n copies of the document doc.

Lists and options

val concat : PPrintEngine.document list -> PPrintEngine.document

concat docs is the concatenation of the documents in the list docs.

val separate : PPrintEngine.document -> PPrintEngine.document list -> PPrintEngine.document

separate sep docs is the concatenation of the documents in the list docs. The separator sep is inserted between every two adjacent documents.

val concat_map : ('a -> PPrintEngine.document) -> 'a list -> PPrintEngine.document

concat_map f xs is equivalent to concat (List.map f xs).

val separate_map : PPrintEngine.document -> ('a -> PPrintEngine.document) -> 'a list -> PPrintEngine.document

separate_map sep f xs is equivalent to separate sep (List.map f xs).

val separate2 : PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document list -> PPrintEngine.document

separate2 sep last_sep docs is the concatenation of the documents in the list docs. The separator sep is inserted between every two adjacent documents, except between the last two documents, where the separator last_sep is used instead.

val optional : ('a -> PPrintEngine.document) -> 'a option -> PPrintEngine.document

optional f None is the empty document. optional f (Some x) is the document f x.

Text

val lines : string -> PPrintEngine.document list

lines s is the list of documents obtained by splitting s at newline characters, and turning each line into a document via substring. This code is not UTF-8 aware.

val arbitrary_string : string -> PPrintEngine.document

arbitrary_string s is equivalent to separate (break 1) (lines s). It is analogous to string s, but is valid even if the string s contains newline characters.

val words : string -> PPrintEngine.document list

words s is the list of documents obtained by splitting s at whitespace characters, and turning each word into a document via substring. All whitespace is discarded. This code is not UTF-8 aware.

val split : (char -> bool) -> string -> PPrintEngine.document list

split ok s splits the string s before and after every occurrence of a character that satisfies the predicate ok. The substrings thus obtained are turned into documents, and a list of documents is returned. No information is lost: the concatenation of the documents yields the original string. This code is not UTF-8 aware.

val flow : PPrintEngine.document -> PPrintEngine.document list -> PPrintEngine.document

flow sep docs separates the documents in the list docs with the separator sep and arranges for a new line to begin whenever a document does not fit on the current line. This is useful for typesetting free-flowing, ragged-right text. A typical choice of sep is break b, where b is the number of spaces that must be inserted between two consecutive words (when displayed on the same line).

val flow_map : PPrintEngine.document -> ('a -> PPrintEngine.document) -> 'a list -> PPrintEngine.document

flow_map sep f docs is equivalent to flow sep (List.map f docs).

val url : string -> PPrintEngine.document

url s is a possible way of displaying the URL s. A potential line break is inserted immediately before and immediately after every slash and dot character.

Alignment and indentation

val hang : int -> PPrintEngine.document -> PPrintEngine.document
val prefix : int -> int -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

prefix n b left right has the following flat layout:

left right

and the following non-flat layout:

left
  right

The parameter n controls the nesting of right (when not flat). The parameter b controls the number of spaces between left and right (when flat).

val jump : int -> int -> PPrintEngine.document -> PPrintEngine.document

jump n b right is equivalent to prefix n b empty right.

val infix : int -> int -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

infix n b middle left right has the following flat layout:

left middle right

and the following non-flat layout:

left middle
  right

The parameter n controls the nesting of right (when not flat). The parameter b controls the number of spaces between left and middle (always) and between middle and right (when flat).

val surround : int -> int -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

surround n b opening contents closing has the following flat layout:

opening contents closing

and the following non-flat layout:

opening
  contents
closing

The parameter n controls the nesting of contents (when not flat). The parameter b controls the number of spaces between opening and contents and between contents and closing (when flat).

val soft_surround : int -> int -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

soft_surround is analogous to surround, but involves more than one group, so it offers possibilities other than the completely flat layout (where opening, contents, and closing appear on a single line) and the completely developed layout (where opening, contents, and closing appear on separate lines). It tries to place the beginning of contents on the same line as opening, and to place closing on the same line as the end of contents, if possible.

val surround_separate : int -> int -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document list -> PPrintEngine.document

surround_separate n b void opening sep closing docs is equivalent to surround n b opening (separate sep docs) closing, except when the list docs is empty, in which case it reduces to void.

val surround_separate_map : int -> int -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document -> ('a -> PPrintEngine.document) -> 'a list -> PPrintEngine.document

surround_separate_map n b void opening sep closing f xs is equivalent to surround_separate n b void opening sep closing (List.map f xs).

Short-hands

val (!^) : string -> PPrintEngine.document

!^s is a short-hand for string s.

val (^/^) : PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

x ^/^ y separates x and y with a breakable space. It is a short-hand for x ^^ break 1 ^^ y.

val (^//^) : PPrintEngine.document -> PPrintEngine.document -> PPrintEngine.document

x ^//^ y is a short-hand for prefix 2 1 x y.

module OCaml = PPrintOCaml