Module Fmt

module Fmt: sig .. end
Format pretty-printer combinators.

Consult naming conventions for your pretty-printers.

References

v0.8.0 - homepage



Formatting


val pf : Format.formatter -> ('a, Format.formatter, unit) Pervasives.format -> 'a
pf is Format.fprintf.
val kpf : (Format.formatter -> 'a) ->
Format.formatter -> ('b, Format.formatter, unit, 'a) Pervasives.format4 -> 'b
kpf is Format.kfprintf.
val strf : ('a, Format.formatter, unit, string) Pervasives.format4 -> 'a
strf is Format.asprintf.

Note. When using strf Fmt.utf_8 and Fmt.style_renderer are always respectively set to true and `None. See also Fmt.strf_like.

val kstrf : (string -> 'a) -> ('b, Format.formatter, unit, 'a) Pervasives.format4 -> 'b
kstrf is like Fmt.strf but continuation based.
val strf_like : Format.formatter ->
('a, Format.formatter, unit, string) Pervasives.format4 -> 'a
strf_like ppf is like Fmt.strf except its Fmt.utf_8 and Fmt.style_renderer settings are those of ppf.
val with_buffer : ?like:Format.formatter -> Buffer.t -> Format.formatter
with_buffer ~like b is a formatter whose Fmt.utf_8 and Fmt.style_renderer settings are copied from those of like (if provided).

Formatting to standard outputs


val stdout : Format.formatter
stdout is the standard output formatter.
val stderr : Format.formatter
stderr is the standard error formatter.
val pr : ('a, Format.formatter, unit) Pervasives.format -> 'a
pr is pf stdout.
val epr : ('a, Format.formatter, unit) Pervasives.format -> 'a
epr is pf stderr.

Formatters


type 'a t = Format.formatter -> 'a -> unit 
The type for formatters of values of type 'a.
val nop : 'a t
nop formats nothing.
val cut : unit t
cut is Format.pp_print_cut.
val sp : unit t
sp is Format.pp_print_space.
val const : 'a t -> 'a -> unit t
const pp_v v always formats v using pp_v.
val unit : (unit, Format.formatter, unit) Pervasives.format -> unit t
unit fmt formats a unit value with the format fmt.
val fmt : ('a, Format.formatter, unit) Pervasives.format -> Format.formatter -> 'a
fmt fmt ppf is pf ppf fmt. If fmt is used with a single non-constant formatting directive, generates a value of type Fmt.t.
val always : (unit, Format.formatter, unit) Pervasives.format -> 'a t
always fmt ppf v formats any value with the constant format fmt.

Base type formatters


val bool : bool t
bool is Format.pp_print_bool.
val int : int t
int is pf ppf "%d".
val nativeint : nativeint t
nativeint ppf is pf ppf "%nd".
val int32 : int32 t
int32 ppf is pf ppf "%ld".
val int64 : int64 t
int64 ppf is pf ppf "%Ld".
val uint : int t
uint ppf is pf ppf "%u".
val unativeint : nativeint t
unativeint ppf is pf ppf "%nu".
val uint32 : int32 t
uint32 ppf is pf ppf "%lu".
val uint64 : int64 t
uint64 ppf is pf ppf "%Lu".
val float : float t
float ppf is pf ppf "%g".
val float_dfrac : int -> float t
float_dfrac d rounds the float to the dth decimal fractional digit and formats the result with "%g". Ties are rounded towards positive infinity. The result is only defined for 0 <= d <= 16.
val float_dsig : int -> float t
float_dsig d rounds the normalized decimal significand of the float to the dth decimal fractional digit and formats the result with "%g". Ties are rounded towards positive infinity. The result is NaN on infinities and only defined for 0 <= d <= 16.

Warning. The current implementation overflows on large d and floats.

val char : char t
char is Format.pp_print_char.
val string : string t
string is Format.pp_print_string.
val buffer : Buffer.t t
buffer formats a Buffer.t value's current contents.
val exn : exn t
exn formats an exception.
val exn_backtrace : (exn * Printexc.raw_backtrace) t
exn_backtrace formats an exception backtrace.

Polymorphic type formatters

These formatters give full control to the client over the formatting process and do not wrap the formatted structures with boxes. Use the Fmt.Dump module to quickly format values for inspection.

val pair : ?sep:unit t -> 'a t -> 'b t -> ('a * 'b) t
pair ~sep pp_fst pp_snd formats a pair. The first and second projection are formatted using pp_fst and pp_snd and are separated by sep (defaults to Fmt.cut).
val option : ?none:unit t -> 'a t -> 'a option t
option ~none pp_v formats an optional value. The Some case uses pp_v and None uses none (defaults to Fmt.nop).
val result : ok:'a t -> error:'b t -> ('a, 'b) Result.result t
result ~ok ~error formats a result value using ok for the Ok case and error for the Error case.
val list : ?sep:unit t -> 'a t -> 'a list t
list sep pp_v formats list elements. Each element of the list is formatted in order with pp_v. Elements are separated by sep (defaults to Fmt.cut). If the list is empty, this is Fmt.nop.
val array : ?sep:unit t -> 'a t -> 'a array t
array sep pp_v formats array elements. Each element of the array is formatted in order with pp_v. Elements are separated by sep (defaults to Fmt.cut). If the array is empty, this is Fmt.nop.
val hashtbl : ?sep:unit t -> ('a * 'b) t -> ('a, 'b) Hashtbl.t t
hashtbl ~sep pp_binding formats the bindings of a hash table. Each binding is formatted with pp_binding and bindings are separated by sep (defaults to Fmt.cut). If the hash table has multiple bindings for a given key, all bindings are formatted, with the most recent binding first. If the hash table is empty, this is Fmt.nop.
val queue : ?sep:unit t -> 'a t -> 'a Queue.t t
queue ~sep pp_v formats queue elements. Each element of the queue is formatted in least recently added order with pp_v. Elements are separated by sep (defaults to Fmt.cut). If the queue is empty, this is Fmt.nop.
val stack : ?sep:unit t -> 'a t -> 'a Stack.t t
stack ~sep pp_v formats stack elements. Each element of the stack is formatted from top to bottom order with pp_v. Elements are separated by sep (defaults to Fmt.cut). If the stack is empty, this is Fmt.nop.
val iter : ?sep:unit t -> (('a -> unit) -> 'b -> unit) -> 'a t -> 'b t
iter ~sep iter pp_elt formats the iterations of iter over a value using pp_elt. Iterations are separated by sep (defaults to Fmt.cut).
val iter_bindings : ?sep:unit t ->
(('a -> 'b -> unit) -> 'c -> unit) -> ('a * 'b) t -> 'c t
iter_bindings ~sep iter pp_binding formats the iterations of iter over a value using pp_binding. Iterations are separated by sep (defaults to Fmt.cut).
val using : ('a -> 'b) -> 'b t -> 'a t
using f pp maps values using f and formats them with pp.
module Dump: sig .. end
Formatters for inspecting OCaml values.

Boxes


val box : ?indent:int -> 'a t -> 'a t
box ~indent pp ppf wraps pp in a horizontal or vertical box. Break hints that lead to a new line add indent to the current indentation (defaults to 0).
val hbox : 'a t -> 'a t
hbox is like Fmt.box but is a horizontal box: the line is not split in this box (but may be in sub-boxes).
val vbox : ?indent:int -> 'a t -> 'a t
vbox is like Fmt.box but is a vertical box: every break hint leads to a new line which adds indent to the current indentation (default to 0).
val hvbox : ?indent:int -> 'a t -> 'a t
hvbox is like Fmt.box but is either Fmt.hbox if its fits on a single line or Fmt.vbox otherwise.

Brackets


val parens : 'a t -> 'a t
parens pp_v ppf is pf "@[<1>(%a)@]" pp_v.
val brackets : 'a t -> 'a t
brackets pp_v ppf is pf "@[<1>[%a]@]" pp_v.
val braces : 'a t -> 'a t
braces pp_v ppf is pf "@[<1>{%a}@]" pp_v.
val quote : ?mark:string -> 'a t -> 'a t
quote ~mark pp_v ppf is pf "@[<1>@<1>%s%a@<1>%s@]" mark pp_v mark, mark defaults to "\"", it is always counted as spanning as single column (this allows for UTF-8 encoded marks).

Words, paragraphs, text and lines

Note. These functions only work on US-ASCII strings and/or with newlines ('\n'). If you are dealing with UTF-8 strings or different kinds of line endings you should use the pretty-printers from Uuseg_string.

White space. White space is one of the following US-ASCII characters: space ' ' (0x20), tab '\t' (0x09), newline '\n' (0x0A), vertical tab (0x0B), form feed (0x0C), carriage return '\r' (0x0D).

val words : string t
words formats words by suppressing initial and trailing white space and replacing consecutive white space with a single Format.pp_print_space.
val paragraphs : string t
paragraphs formats paragraphs by suppressing initial and trailing spaces and newlines, replacing blank lines (a line made only of white space) by a two Format.pp_force_newline and remaining consecutive white space with a single Format.pp_print_space.
val text : string t
text formats text by respectively replacing spaces and newlines in the string with Format.pp_print_space and Format.pp_force_newline.
val lines : string t
lines formats lines by replacing newlines ('\n') in the string with calls to Format.pp_force_newline.
val text_loc : ((int * int) * (int * int)) t
text_loc formats a line-column text range according to GNU conventions.

Appending


val append : 'a t -> 'b t -> ('a * 'b) t
append pp_v0 pp_v1 ppf (v0, v1) is pp_v0 ppf v0; pp_v1 ppf v1.
val prefix : unit t -> 'a t -> 'a t
prefix pp_pre pp prefixes pp by pp_pre.
val suffix : unit t -> 'a t -> 'a t
suffix pp_suf pp suffixes pp by pp_suf.

Byte sizes


val byte_size : int t
byte_size formats a byte size according to its magnitude using SI prefixes up to peta bytes (1015).
val bi_byte_size : int t
bi_byte_size formats a byte size according to its magnitude using binary prefixes up to pebi bytes (215).

Conditional UTF-8 formatting

Note. Since Format is not UTF-8 aware using UTF-8 output may derail the pretty printing process. Use the pretty-printers from Uuseg_string if you are serious about UTF-8 formatting.

val if_utf_8 : 'a t -> 'a t -> 'a t
if_utf_8 pp_u pp ppf v is:
val utf_8 : Format.formatter -> bool
utf_8 ppf is true if UTF-8 output is enabled on ppf. If Fmt.set_utf_8 hasn't been called on ppf this is true.
val set_utf_8 : Format.formatter -> bool -> unit
set_utf_8 ppf b enables or disables conditional UTF-8 formatting on ppf.

Warning. Using this function replaces any Format.tag functions that may be in place.
Raises Invalid_argument if ppf is Format.str_formatter: it is is always UTF-8 enabled.


Styled formatting


type style = [ `Black
| `Blue
| `Bold
| `Cyan
| `Green
| `Magenta
| `None
| `Red
| `Underline
| `White
| `Yellow ]
The type for styles.
val styled : style -> 'a t -> 'a t
styled s pp formats like pp but styled with s.
val styled_unit : style -> (unit, Format.formatter, unit) Pervasives.format -> unit t
styled_unit s fmt is style s (unit fmt).

Style rendering control


type style_renderer = [ `Ansi_tty | `None ] 
The type for style renderers.
val style_renderer : Format.formatter -> style_renderer
style_renderer ppf is the style renderer used by ppf. If Fmt.set_style_renderer has never been called on ppf this is `None.
val set_style_renderer : Format.formatter -> style_renderer -> unit
set_style_renderer ppf r sets the style renderer of ppf to r.

Warning. Using this function replaces any Format.tag functions that may be in place.
Raises Invalid_argument if ppf is Format.str_formatter: its renderer is always `None.


Converting with string value converters


val of_to_string : ('a -> string) -> 'a t
of_to_string f ppf v is string ppf (f v).
val to_to_string : 'a t -> 'a -> string
to_to_string pp_v v is strf "%a" pp_v v.

Naming conventions

Given a type ty use:

If you are in a situation where making a difference between dump_ty and pp_ty doesn't make sense then use pp_ty.

For a type ty that is the main type of the module (the "M.t" convention) drop the suffix, that is simply use M.pp and M.dump.