Module Containers_ppSource

Pretty printing of documents.

A document is a structured tree of text with formatting instructions.

It can be rendered into a string ("pretty printed"), see Pretty.

This follows Wadler's paper "A prettier printer", but with some changes in the rendering part because we can't rely on lazyness to make the algebraic implementation efficient.

Some general considerations: the type t is the type of documents, a tree with text leaves that is pretty printed within a given width.

Layout is controlled via the combination of a few primitives:

Core

Sourcetype 'a iter = ('a -> unit) -> unit
Sourcetype t

The type of documents

Sourceval nil : t

Empty document

Sourceval char : char -> t

Single char.

Sourceval text : string -> t

Text. The string will be split on '\n', which are replaced by newline.

Sourceval textpf : ('a, unit, string, t) format4 -> 'a

Text, with a Printf-compatible format.

For example, textpf "%d-%d" 4 2 is like text "4-2".

Sourceval textf : ('a, Format.formatter, unit, t) format4 -> 'a

Text, with a Format-compatible format.

Note that this will bake-in any formatting done by Format. Newlines introduced by format will become hard newlines in the resulting document.

Sourceval nest : int -> t -> t

nest n d increases indentation by n inside d. If current indentation is m, then every newline inside d will be followed by n + m leading spaces.

Sourceval group : t -> t

Group the documents inside this.

Newlines immediately inside this group will either render as new lines or as spaces, depending on the width available.

Sourceval append : t -> t -> t

Concatenation.

Sourceval newline : t

A line break.

Sourceval newline_or_spaces : int -> t

newline_or_spaces n either prints a newline (respecting indentation), or prints n spaces. newline is basically newline_or_spaces 1.

  • since 3.13
Sourceval nl : t

Alias for newline

Sourceval fill : t -> t list -> t

fill sep l resembles group (append_l ~sep l), except it tries to put as many items of l as possible on each line.

In terms of Format, this is like the hov box.

Output device

Sourcemodule Out : sig ... end

Arbitrary output.

Extensibility

Sourcemodule Ext : sig ... end

Extension node.

Sourceval ext : 'a Ext.t -> 'a -> t -> t

ext e v d wraps d with value v.

It is a document that has the same shape (and size) as d, except that additional data will be output when it is rendered using extension e.

When this is rendered, first e.pre out v is called; then d is printed; then e.post out v is called. Here out is the output buffer/stream for rendering.

Pretty print and rendering

Sourcemodule Pretty : sig ... end

Pretty-printing.

Sourcemodule Flatten : sig ... end

Trivial printing, on a single line.

Sourceval pp : Format.formatter -> t -> unit

Pretty-print, using Pretty and an unspecified margin.

Sourceval debug : Format.formatter -> t -> unit

Debug printer. This prints the structure of the document, it does not pretty-print it. See pp or Pretty.

Convenience functions

Sourcemodule Infix : sig ... end
include module type of Infix
Sourceval (^) : t -> t -> t

Alias of append.

Sourceval (^+) : t -> t -> t

x ^+ y is x ^ text " " ^ y

Sourceval (^/) : t -> t -> t

x ^/ y is x ^ newline ^ y

Sourceval sp : t

A single space

Sourceval append_l : ?sep:t -> t list -> t

append_l ?sep l is the concatenation of elements of l, separated by sep (default nil)

Sourceval append_sp : t list -> t

append_sp l is the concatenation of elements of l, separated by ' '

Sourceval append_nl : t list -> t

Same as append_l with sep=nl

Sourceval fill_map : t -> ('a -> t) -> 'a list -> t

fill_map sep f l is fill sep (List.map f l)

Sourceval bool : bool -> t
Sourceval int : int -> t
Sourceval float : float -> t
Sourceval float_hex : float -> t
Sourceval text_quoted : string -> t

text_quoted s is text (spf "%S" s)

Sourceval text_zero_width : string -> t

Text but we assume it takes no space on screen.

Sourceval of_list : ?sep:t -> ('a -> t) -> 'a list -> t

of_list f l maps each element of l to a document and concatenates them.

  • parameter sep

    separator inserted between elements (default nil)

Sourceval of_seq : ?sep:t -> ('a -> t) -> 'a Seq.t -> t

Same as of_list but with sequences.

Sourceval bracket : string -> t -> string -> t

bracket l d r groups d, between brackets l and r

Sourceval bracket2 : string -> t -> string -> t

bracket2 l d r groups d, indented by 2, between brackets l and r

Sourceval sexp_apply : string -> t list -> t

sexp_apply a l is the S-expr "(text a …l)", pretty-printed

Sourceval sexp_l : t list -> t

sexp_l [l1;…ln] is the S-expr "(l1 l2…ln)", pretty-printed

Sourcemodule Dump : sig ... end

Printers that correspond closely to OCaml's syntax.

Sourcemodule Term_color : sig ... end

Simple colors in terminals

Sourcemodule Char : sig ... end
Sourceval surround : ?width:int -> t -> t -> t -> t

Generalization of bracket

  • since 3.13.1