Module Fmt

Format pretty-printer combinators.

Consult naming conventions for your pretty-printers.

References

Standard outputs

stdout is the standard output formatter.

stderr is the standard error formatter.

Formatting

pf is Format.fprintf.

val pr : ('a, Stdlib.Format.formatter, unit) Stdlib.format -> 'a

pr is pf stdout.

val epr : ('a, Stdlib.Format.formatter, unit) Stdlib.format -> 'a

epr is pf stderr.

val str : ('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a

str is Format.asprintf.

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

kpf is Format.kfprintf.

val kstr : (string -> 'a) -> ('b, Stdlib.Format.formatter, unit, 'a) Stdlib.format4 -> 'b

kstr is like str but continuation based.

val str_like : Stdlib.Format.formatter -> ('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a

str_like ppf is like str except its utf_8 and style_renderer settings are those of ppf.

with_buffer ~like b is a formatter whose utf_8 and style_renderer settings are copied from those of like (if provided).

val failwith : ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a

failwith is kstr failwith, raises Stdlib.Failure with a pretty-printed string argument.

val failwith_notrace : ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a

failwith_notrace is like failwith but raises with raise_notrace.

val invalid_arg : ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a

invalid_arg is kstr invalid_arg, raises Stdlib.Invalid_argument with a pretty-printed string argument.

val error : ('b, Stdlib.Format.formatter, unit, ('a, string) Stdlib.result) Stdlib.format4 -> 'b

error fmt ... is kstr (fun s -> Error s) fmt ...

val error_msg : ('b, Stdlib.Format.formatter, unit, ('a, [ `Msg of string ]) Stdlib.result) Stdlib.format4 -> 'b

error_msg fmt ... is kstr (fun s -> Error (`Msg s)) fmt ...

Formatters

type 'a t = Stdlib.Format.formatter -> 'a -> unit

The type for formatters of values of type 'a.

val flush : 'a t

flush has the effect of Format.pp_print_flush

val nop : 'a t

nop formats nothing.

val any : (unit, Stdlib.Format.formatter, unit) Stdlib.format -> 'a t

any fmt ppf v formats any value with the constant format fmt.

val using : ('a -> 'b) -> 'b t -> 'a t

using f pp ppf v ppf ppf (f v).

val const : 'a t -> 'a -> 'b t

const pp_v v always formats v using pp_v.

fmt fmt ppf is pf ppf fmt. If fmt is used with a single non-constant formatting directive, generates a value of type t.

Separators

val cut : 'a t

cut has the effect of Format.pp_print_cut.

val sp : 'a t

sp has the effect of Format.pp_print_space.

val sps : int -> 'a t

sps n has the effect of Format.pp_print_break n 0.

val comma : 'a t

comma is Fmt.any ",@ ".

val semi : 'a t

semi is Fmt.any ";@ ".

Sequencing

val append : 'a t -> 'a t -> 'a t

append pp_v0 pp_v1 ppf v is pp_v0 ppf v; pp_v1 ppf v.

val (++) : 'a t -> 'a t -> 'a t

( ++ ) is append.

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

concat ~sep pps formats a value using the formaters pps and separting each format with sep (defaults to cut).

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 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 cut).

Boxes

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

box ~indent pp ppf wraps pp in a pretty-printing box. The box tries to print as much as possible on every line, while emphasizing the box structure (see Format.pp_open_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 box but is a horizontal box: the line is not split in this box (but may be in sub-boxes). See Format.pp_open_hbox.

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

vbox is like box but is a vertical box: every break hint leads to a new line which adds indent to the current indentation (defaults to 0). See Format.pp_open_vbox.

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

hvbox is like hbox if it fits on a single line, or like vbox otherwise. See Format.pp_open_hvbox.

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

hovbox is a condensed box. See Format.pp_open_hovbox.

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).

Records

val id : 'a -> 'a

id is Fun.id.

val field : ?⁠label:string t -> ?⁠sep:unit t -> string -> ('b -> 'a) -> 'a t -> 'b t

field ~label ~sep l prj pp_v pretty prints a labelled field value as pf "@[<1>%a%a%a@]" label l sep () (using prj pp_v). label defaults to styled `Yellow string and sep to any ":@ ".

val record : ?⁠sep:unit t -> 'a t list -> 'a t

record ~sep fields pretty-prints a value using the concatenation of fields, separated by sep (defaults to cut) and framed in a vertical box.

Stdlib types

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 : Stdlib.Buffer.t t

buffer formats a Buffer.t value's current contents.

val exn : exn t

exn formats an exception.

val exn_backtrace : (exn * Stdlib.Printexc.raw_backtrace) t

exn_backtrace formats an exception backtrace.

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 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 nop).

val result : ok:'a t -> error:'b t -> ('a, 'b) Stdlib.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 cut). If the list is empty, this is 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 cut). If the array is empty, this is nop.

val seq : ?⁠sep:unit t -> 'a t -> 'a Stdlib.Seq.t t

seq sep pp_v formats sequence elements. Each element of the sequence is formatted in order with pp_v. Elements are separated by sep (defaults to cut). If the sequence is empty, this is nop.

val hashtbl : ?⁠sep:unit t -> ('a * 'b) t -> ('a, 'b) Stdlib.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 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 nop.

val queue : ?⁠sep:unit t -> 'a t -> 'a Stdlib.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 cut). If the queue is empty, this is nop.

val stack : ?⁠sep:unit t -> 'a t -> 'a Stdlib.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 cut). If the stack is empty, this is nop.

module Dump : sig ... end

Formatters for inspecting OCaml values.

Magnitudes

val si_size : scale:int -> string -> int t

si_size ~scale unit formats a non negative integer representing unit unit at scale 10scale * 3, depending on its magnitude, using power of 3 SI prefixes (i.e. all of them except deca, hector, deci and centi). Only US-ASCII characters are used, µ (10-6) is written using u.

scale indicates the scale 10scale * 3 an integer represents, for example -1 for munit (10-3), 0 for unit (100), 1 for kunit (103); it must be in the range [-8;8] or Invalid_argument is raised.

Except at the maximal yotta scale always tries to show three digits of data with trailing fractional zeros omited. Rounds towards positive infinity (over approximates).

val byte_size : int t

byte_size is si_size ~scale:0 "B".

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).

val uint64_ns_span : int64 t

uint64_ns_span formats an unsigned nanosecond time span according to its magnitude using SI prefixes on seconds and accepted non-SI units. Years are counted in Julian years (365.25 SI-accepted days) as defined by the International Astronomical Union (IAU). Only US-ASCII characters are used (us is used for µs).

Binary data

type 'a vec = int * (int -> 'a)

The type for random addressable, sized sequences. Each (n, f) represents the sequence f 0, ..., f (n - 1).

val on_bytes : char vec t -> bytes t

on_bytes pp is pp adapted to format (entire) bytes.

val on_string : char vec t -> string t

on_string pp is pp adapted to format (entire) strings.

val ascii : ?⁠w:int -> ?⁠subst:unit t -> unit -> char vec t

ascii ~w ~subst () formats character sequences by printing characters in the printable US-ASCII range ([0x20];[0x7E]) as is, and replacing the rest with subst (defaults to fmt "."). w causes the output to be right padded to the size of formatting at least w sequence elements (defaults to 0).

val octets : ?⁠w:int -> ?⁠sep:unit t -> unit -> char vec t

octets ~w ~sep () formats character sequences as hexadecimal digits. It prints groups of successive characters of unspecified length together, separated by sep (defaults to sp). w causes the output to be right padded to the size of formatting at least w sequence elements (defaults to 0).

val addresses : ?⁠addr:int t -> ?⁠w:int -> 'a vec t -> 'a vec t

addresses pp formats sequences by applying pp to consecutive subsequences of length w (defaults to 16). addr formats subsequence offsets (defaults to an unspecified hexadecimal format).

val hex : ?⁠w:int -> unit -> char vec t

hex ~w () formats character sequences as traditional hex dumps, matching the output of xxd and forcing line breaks after every w characters (defaults to 16).

Words, paragraphs, text and lines

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 truncated : max:int -> string t

truncated ~max formats a string using at most max characters. If the string doesn't fit, it is truncated and ended with three consecutive dots which do count towards max.

val text_loc : ((int * int) * (int * int)) t

text_loc formats a line-column text range according to GNU conventions.

HCI fragments

val one_of : ?⁠empty:unit t -> 'a t -> 'a list t

one_of ~empty pp_v ppf l formats according to the length of l

  • 0, formats empty (defaults to nop).
  • 1, formats the element with pp_v.
  • 2, formats "either %a or %a" with the list elements
  • n, formats "one of %a, ... or %a" with the list elements
val did_you_mean : ?⁠pre:unit t -> ?⁠post:unit t -> kind:string -> 'a t -> ('a * 'a list) t

did_you_mean ~pre kind ~post pp_v formats a faulty value v of kind kind and a list of hints that v could have been mistaken for.

pre defaults to unit "Unknown", post to nop they surround the faulty value before the "did you mean" part as follows "%a %s %a%a." pre () kind pp_v v post (). If hints is empty no "did you mean" part is printed.

Conditional UTF-8 formatting

val if_utf_8 : 'a t -> 'a t -> 'a t

if_utf_8 pp_u pp ppf v is:

  • pp_u ppf v if utf_8 ppf is true.
  • pp ppf v otherwise.
val utf_8 : Stdlib.Format.formatter -> bool

utf_8 ppf is true if UTF-8 output is enabled on ppf. If set_utf_8 hasn't been called on ppf this is true.

val set_utf_8 : Stdlib.Format.formatter -> bool -> unit

set_utf_8 ppf b enables or disables conditional UTF-8 formatting on ppf.

raises Invalid_argument

if ppf is Format.str_formatter: it is is always UTF-8 enabled.

Styled formatting

type color = [
| `Black
| `Blue
| `Cyan
| `Green
| `Magenta
| `Red
| `White
| `Yellow
]

The type for colors.

type style = [
| `None
| `Bold
| `Faint
| `Italic
| `Underline
| `Reverse
| `Fg of [ color | `Hi of color ]
| `Bg of [ color | `Hi of color ]
| color
]

The type for styles:

  • `None resets the styling.
  • `Bold, `Faint, `Italic, `Underline and `Reverse are display attributes.
  • `Fg _ is the foreground color or high-intensity color on `Hi _.
  • `Bg _ is the foreground color or high-intensity color on `Hi _.
  • #color is the foreground colour, deprecated use `Fg #color instead.
val styled : style -> 'a t -> 'a t

styled s pp formats like pp but styled with s.

Style rendering control

type style_renderer = [
| `Ansi_tty
| `None
]

The type for style renderers.

val style_renderer : Stdlib.Format.formatter -> style_renderer

style_renderer ppf is the style renderer used by ppf. If set_style_renderer has never been called on ppf this is `None.

val set_style_renderer : Stdlib.Format.formatter -> style_renderer -> unit

set_style_renderer ppf r sets the style renderer of ppf to r.

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.

Deprecated

val strf : ('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a
deprecated

use str instead.

val kstrf : (string -> 'a) -> ('b, Stdlib.Format.formatter, unit, 'a) Stdlib.format4 -> 'b
deprecated

use kstr instead.

val strf_like : Stdlib.Format.formatter -> ('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a
deprecated

use str_like instead.

val always : (unit, Stdlib.Format.formatter, unit) Stdlib.format -> 'a t
deprecated

use any instead.

val unit : (unit, Stdlib.Format.formatter, unit) Stdlib.format -> unit t
deprecated

use any.

val prefix : unit t -> 'a t -> 'a t
deprecated

use ( ++ ).

val suffix : unit t -> 'a t -> 'a t
deprecated

use ( ++ ).

val styled_unit : style -> (unit, Stdlib.Format.formatter, unit) Stdlib.format -> unit t
deprecated

, use styled s (any fmt) instead

Naming conventions