pp 1.2.0 · OCaml Package

Pretty-printing.

type +'tag t

A document that is not yet rendered. The argument is the type of tags in the document. For instance tags might be used for styles.

Basic combinators

val nop : _ t

A pretty printer that prints nothing

val seq : 'a t -> 'a t -> 'a t

seq x y prints x and then y

val concat : ?sep:'a t -> 'a t list -> 'a t

concat ?sep l prints elements in l separated by sep. sep defaults to nop.

val concat_map : ?sep:'a t -> 'b list -> f:('b -> 'a t) -> 'a t

Convenience function for List.map followed by concat

val concat_mapi : ?sep:'a t -> 'b list -> f:(int -> 'b -> 'a t) -> 'a t

val verbatim : string -> _ t

An indivisible block of text

val char : char -> _ t

A single character

val text : string -> _ t

Print a bunch of text. The line may be broken at any spaces in the text.

val textf : ('a, unit, string, _ t) format4 -> 'a

Same as text but take a format string as argument.

Break hints

val space : _ t

space instructs the pretty-printing algorithm that the line may be broken at this point. If the algorithm decides not to break the line, a single space will be printed instead.

So for instance verbatim "x" ++ space ++ verbatim "y" might produce "x y" or "x\n<indentation>y".

val cut : _ t

cut instructs the pretty-printing algorithm that the line may be broken at this point. If the algorithm decides not to break the line, nothing is printed instead.

So for instance verbatim "x" ++ space ++ verbatim "y" might produce "xy" or "x\n<indentation>y".

val break : nspaces:int -> shift:int -> _ t

break is a generalisation of space and cut. It also instructs the pretty-printing algorithm that the line may be broken at this point. If it ends up being broken, shift will be added to the indentation level, otherwise nspaces spaces will be printed. shift can be negative, in which case the indentation will be reduced.

val custom_break : 
  fits:(string * int * string) ->
  breaks:(string * int * string) ->
  _ t

custom_break ~fits:(a, b, c) ~breaks:(x, y, z) is a generalisation of break. It also instructs the pretty-printing algorithm that the line may be broken at this point. If it ends up being broken, x is printed, the line breaks, y will be added to the indentation level and z is printed, otherwise a will be printed, b spaces are printed and then c is printed. The indentation y can be negative, in which case the indentation will be reduced.

val newline : _ t

Force a newline to be printed

Boxes

Boxes are the basic components to control the layout of the text. Break hints such as space and cut may cause the line to be broken, depending on the splitting rules. Whenever a line is split, the rest of the material printed in the box is indented with indent.

You can think of a box with indentation as something with this shape:

       ######################### <- first line
       <indent>#################
       <indent>#################
       <indent>#################
       <indent>#################

And the top left corner of this shape is anchored where the box was declared. So for instance, the following document:

Pp.verbatim "....." ++ Pp.box ~indent:2 (Pp.text "some long ... text")

would produce:

       .....some long ...
              text

val box : ?indent:int -> 'a t -> 'a t

Try to put as much as possible on each line. Additionally, a break hint always break the line if the breaking would reduce the indentation level inside the box (break with negative shift value).

val vbox : ?indent:int -> 'a t -> 'a t

Always break the line when encountering a break hint.

val hbox : 'a t -> 'a t

Print everything on one line, no matter what

val hvbox : ?indent:int -> 'a t -> 'a t

If possible, print everything on one line. Otherwise, behave as a vbox

val hovbox : ?indent:int -> 'a t -> 'a t

Try to put as much as possible on each line. Basically the same as box but without the rule about breaks with negative shift value.

Convenience functions

val enumerate : 'a list -> f:('a -> 'b t) -> 'b t

enumerate l ~f produces an enumeration of the form:

      - item1
      - item2
      - item3
      ...

val chain : 'a list -> f:('a -> 'b t) -> 'b t

chain l ~f is used to print a succession of items that follow each other. It produces an output of this form:

         item1
      -> item2
      -> item3
      ...

Operators

module O : sig ... end

Rendering

val to_fmt : Format.formatter -> _ t -> unit

Render a document to a classic formatter

val to_fmt_with_tags : 
  Format.formatter ->
  'a t ->
  tag_handler:(Format.formatter -> 'a -> 'a t -> unit) ->
  unit

Injection

val of_fmt : (Format.formatter -> 'a -> unit) -> 'a -> _ t

Inject a classic formatter in a document.

Disclaimer: this function is to meant to help using Pp in existing code that already use the Format module without having to port everything to Pp. It is not meant as the normal way to create Pp.t values.

Ast

module Ast : sig ... end

val of_ast : 'a Ast.t -> 'a t

of_ast t Ast.t to Pp.t

val to_ast : 'a t -> ('a Ast.t, unit) result

to_ast t will try to convert t to Ast.t. When t contains values constructed with of_fmt, this function will fail and return Error ()

Comparison

val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int

compare cmp x y compares x and y using cmp to compare tags.

raises Invalid_argument
if two of_fmt values are compared.

package pp