package pprint

The abstract type of documents.

empty is the empty document.

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

string s is an atomic document that consists of the string s. This string must not contain a newline. The printing engine assumes that the ideal width of this string is String.length s. This assumption is safe if this is an ASCII string. Otherwise, fancystring or utf8string should be preferred.

substring s ofs len is an atomic 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. substring s ofs len is equivalent to string (String.sub s ofs len), but is expected to be more efficient, as the substring is not actually extracted.

fancystring s alen is an atomic 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 characters, etc. Thus, its apparent length (which measures how many columns the text will take up on screen) differs from its length in bytes. The printing engine assumes that its apparent length is alen.

fancysubstring s ofs len alen is equivalent to fancystring (String.sub s ofs len) alen.

utf8string s is an atomic document that consists of the UTF-8-encoded string s. This string must not contain a newline. utf8string s is equivalent to fancystring s (utf8_length s), where utf8_length s is the apparent length of the UTF-8-encoded string s.

utf8format format <args>... is equivalent to utf8string (Printf.sprintf format <args>...).

The atomic document hardline represents a forced newline. This document has infinite ideal width: thus, if there is a choice between printing it in flat mode and printing it in normal mode, normal mode is preferred. In other words, when hardline is placed directly inside a group, this group is dissolved: group hardline is equivalent to hardline. This combinator should be seldom used; consider using break instead.

The atomic document blank n consists of n blank characters. A blank character is like an ordinary ASCII space character char ' ', except that blank characters that appear at the end of a line are automatically suppressed.

space is a synonym for blank 1. It consists of one blank character. It is therefore not equivalent to char ' '.

The document break n is a breakable blank of width n. It produces n blank characters if the printing engine is in flat mode, and a single newline character if the printing engine is in normal mode. break 1 is equivalent to ifflat (blank 1) hardline.

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

group doc encodes a choice. If the document doc fits on the current line, then it is rendered on a single line, in flat mode. (All group combinators inside it are then ignored.) Otherwise, this group is dissolved, and doc is rendered in normal mode. There might be more groups within doc, whose presence leads to further choices being explored.

ifflat doc1 doc2 is rendered as doc1 if the printing engine is in flat mode, that is, if the printing engine has determined that some enclosing group fits on the current line. Otherwise, it is rendered as doc2. Use this combinator with caution! Because the printing engine is free to choose between doc1 and doc2, these documents must be semantically equivalent. It is up to the user to enforce this property.

To render the document nest j doc, the printing engine temporarily increases the current indentation level by j, then renders doc. The effect of the current indentation level is as follows: every time a newline character is emitted, it is immediately followed by n blank characters, where n is the current indentation level. Thus, one may think of nest j doc roughly as the document doc in which j blank characters have been inserted after every newline character.

To render align doc, the printing engine sets the current indentation level to the current column, then renders doc. In other words, the document doc is rendered within a box whose upper left corner is the current position of the printing engine.

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

A range is a pair of points.

The document range hook doc is printed 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.

This signature describes the document renderers in a manner that is independent of the type of the output channel.

This renderer sends its output into an output channel.

This renderer sends its output into a memory buffer.

This renderer sends its output into a formatter channel.

A width requirement is expressed as an integer. The value max_int is reserved and represents infinity.

infinity represents an infinite width requirement.

An output channel is abstractly represented as an object equipped with methods for displaying one character and for displaying a substring.

The internal state of the rendering engine is exposed to the user who wishes to define custom documents. However, its structure is subject to change in future versions of the library.

A custom document is defined by implementing an object of class custom.

custom constructs a custom document out an object of type custom.

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

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

compact output doc prints the document doc. See the documentation of the method compact in the class custom.

precede l x is l ^^ x.

terminate r x is x ^^ r.

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

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

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

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

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

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

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

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.

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

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.

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.

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.

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.

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).

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

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.

hang n doc is analogous to align, but additionally indents all lines, except the first one, by n. Thus, the text in the box forms a hanging indent.

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).

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

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).

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).

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.

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.

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).

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

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

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

This module offers document combinators that help print OCaml values. The strings produced by rendering these documents are supposed to be accepted by the OCaml parser as valid values.