package containers

  1. Overview
  2. Docs
A modular, clean and powerful extension of the OCaml standard library

Install 

dune-project
 Dependency

github.com Readme Changelog Edit opam file Versions (23)

Authors

  1. C
    c-cube

Maintainers

  1. C
    c-cube

Sources

containers-3.13.1.tbz
sha256=eb9b26eb2c3cf04fc5157d256eb49c43552ccb5c59c568772d70315db9669784
sha512=7f4cf5112c8047fd789c04129745dbe9783aa94390e8983f86408053b0af637e2a9cfce1559ce466b1b6ff7c01fd52d8685f5db1d1c0dda2c0aa138f90606a50

doc/containers.pp/Containers_pp/index.html

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:

  • newline will either print a space or a newline. It is similar to Format's "@ " in that sense. A big difference with Format is that by default newline is actually a newline. It only becomes a space if it's in a group small enough to fit in the remainder of the current line.
  • group d tries to write d on a single line if there's room. If not, it has no effect.
  • nest n d increases the indentation level inside d. Any newline that is rendered as a new line is indented by n more spaces (which are cumulative with surrounding nest calls).
  • append a b (or a ^ b) just prints a followed by b.
  • fill d is a bit like group but it will try to cram as much as possible on each line. It is not all-or-nothing like group.

Core

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