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.