package pp

  1. Overview
  2. Docs
Pretty-printing library

Install 

dune-project
 Dependency

github.com Readme Changelog MIT License Edit opam file Versions (4)

Authors

  1. J
    Jane Street Group, LLC <opensource@janestreet.com>
  2. J
    Jeremie Dimino <jeremie@dimino.org>

Maintainers

  1. J
    Jeremie Dimino <jeremie@dimino.org>

Sources

pp-2.0.0.tbz
sha256=8651351518b092b4a2def4e08171c276152f92fb6a84a8b19b6b929ccdb44419
sha512=78cb68f35c0b975dd1e91bd83d5e33bcec1ee642431585d55864c483c70a032755dfcf21ec5697691e7e7554381ddb580639fd149e28ba6f74d04d2ee43d360d

doc/pp/Pp/index.html

Module PpSource

Pretty-printing.

Sourcetype +'tag t

'tag t represents a document that is not yet rendered. The argument 'tag is the type of tags in the document. For instance tags might be used for styles.

If you want to serialise and deserialise this datastructure, you can use the Ast.t type together with the of_ast and to_ast functions.

Basic combinators

Sourceval nop : 'tag t

A pretty printer that prints nothing

Sourceval seq : 'tag t -> 'tag t -> 'tag t

seq x y prints x and then y

Sourceval concat : ?sep:'tag t -> 'tag t list -> 'tag t

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

Sourceval concat_map : ?sep:'tag t -> 'a list -> f:('a -> 'tag t) -> 'tag t

Convenience function for List.map followed by concat.

Sourceval concat_mapi : ?sep:'tag t -> 'a list -> f:(int -> 'a -> 'tag t) -> 'tag t

Convenience function for List.mapi followed by concat.

Sourceval verbatim : string -> 'tag t

An indivisible block of text.

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

Same as verbatim but take a format string as argument.

Sourceval char : char -> 'tag t

A single character.

Sourceval text : string -> 'tag t

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

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

Same as text but take a format string as argument.

Break hints

Sourceval space : 'tag 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".

Sourceval cut : 'tag 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".

Sourceval break : nspaces:int -> shift:int -> 'tag 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.

Sourceval custom_break : fits:(string * int * string) -> breaks:(string * int * string) -> 'tag 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.

Sourceval newline : 'tag t

Force a newline to be printed. Usage is discourage since it breaks printing with boxes. If you need to add breaks to your text, put your items into boxes and concat with a separating space afterwhich wrapping it in a vbox.

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
Sourceval box : ?indent:int -> 'tag t -> 'tag 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).

Sourceval vbox : ?indent:int -> 'tag t -> 'tag t

Always break the line when encountering a break hint.

Sourceval hbox : 'tag t -> 'tag t

Print everything on one line, no matter what

Sourceval hvbox : ?indent:int -> 'tag t -> 'tag t

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

Sourceval hovbox : ?indent:int -> 'tag t -> 'tag 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.

Tags

Tags are arbitrary pieces of information attached to a document. They can be used to add styles to pretty-printed text, for instance to print to the terminal with colors.

Sourceval tag : 'tag -> 'tag t -> 'tag t

tag x t Tag the material printed by t with x

Sourceval map_tags : 'from_tag t -> f:('from_tag -> 'to_tag) -> 'to_tag t

Convert tags in a documents

Sourceval filter_map_tags : 'from_tag t -> f:('from_tag -> 'to_tag option) -> 'to_tag t

Convert tags in a documents, possibly removing some tags.

Convenience functions

Sourceval paragraph : string -> 'tag t

paragraph s is hovbox (text s). This is useful to preserve the structure of a paragraph of text without worrying about it being broken by a vbox.

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

paragraphf s is textf s followed by a hovbox. The textf version of paragraph.

Sourceval enumerate : 'a list -> f:('a -> 'tag t) -> 'tag t

enumerate l ~f produces an enumeration of the form:

  - item1
  - item2
  - item3
  ...
Sourceval chain : 'a list -> f:('a -> 'tag t) -> 'tag 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

Sourcemodule O : sig ... end

Infix operators for Pp.t

Rendering

Sourceval to_fmt : Format.formatter -> 'tag t -> unit

Render a document to a classic formatter

Sourceval to_fmt_with_tags : Format.formatter -> 'tag t -> tag_handler:(Format.formatter -> 'tag -> 'tag t -> unit) -> unit

Ast

Sourcemodule Ast : sig ... end

Stable representation of Pp.t useful for serialization

Sourceval of_ast : 'tag Ast.t -> 'tag t

of_ast t converts an Ast.t to a Pp.t.

Sourceval to_ast : 'tag t -> 'tag Ast.t

to_ast t converts a Pp.t to an Ast.t.

Comparison

Sourceval compare : ('tag -> 'tag -> int) -> 'tag t -> 'tag t -> int

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