module Fmt:sig
..end
Format
pretty-printer combinators.
Consult naming conventions for your pretty-printers.
References
Format
module documentation.Format
module
tutorial.val stdout : Stdlib.Format.formatter
stdout
is the standard output formatter.
val stderr : Stdlib.Format.formatter
stderr
is the standard error formatter.
val pf : Stdlib.Format.formatter ->
('a, Stdlib.Format.formatter, unit) Stdlib.format -> 'a
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
Fmt.utf_8
and Fmt.style_renderer
are
always respectively set to true
and `None
. See also
Fmt.str_like
.
val kpf : (Stdlib.Format.formatter -> 'a) ->
Stdlib.Format.formatter ->
('b, Stdlib.Format.formatter, unit, 'a) Stdlib.format4 -> 'b
kpf
is Format.kfprintf
.
val kstr : (string -> 'a) ->
('b, Stdlib.Format.formatter, unit, 'a) Stdlib.format4 -> 'b
kstr
is like Fmt.str
but continuation based.
val str_like : Stdlib.Format.formatter ->
('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a
str_like ppf
is like Fmt.str
except its Fmt.utf_8
and Fmt.style_renderer
settings are those of ppf
.
val with_buffer : ?like:Stdlib.Format.formatter -> Stdlib.Buffer.t -> Stdlib.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).
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 Fmt.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 ...
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
.
val fmt : ('a, Stdlib.Format.formatter, unit) Stdlib.format ->
Stdlib.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 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
";@ "
.
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 Fmt.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 Fmt.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
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 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 Fmt.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 Fmt.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
val hovbox : ?indent:int -> 'a t -> 'a t
hovbox
is a condensed Fmt.box
. See Format.pp_open_hovbox
.
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).
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.
Formatters for structures 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 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 d
th 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 d
th 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 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) 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
val array : ?sep:unit t -> 'a t -> 'a array t
val seq : ?sep:unit t -> 'a t -> 'a Stdlib.Seq.t t
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 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 Stdlib.Queue.t t
val stack : ?sep:unit t -> 'a t -> 'a Stdlib.Stack.t t
module Dump:sig
..end
Formatters for inspecting OCaml values.
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
).
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) string
s.
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 Fmt.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).
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 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.
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 Fmt.nop
).1
, formats the element with pp_v
.2
, formats "either %a or %a"
with the list elementsn
, formats "one of %a, ... or %a"
with the list elementsval 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 Fmt.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.
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:
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
Fmt.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
.
Invalid_argument
if ppf
is Format.str_formatter
: it is
is always UTF-8 enabled.typecolor =
[ `Black | `Blue | `Cyan | `Green | `Magenta | `Red | `White | `Yellow ]
The type for colors.
typestyle =
[ `Bg of
[ `Black
| `Blue
| `Cyan
| `Green
| `Hi of color
| `Magenta
| `Red
| `White
| `Yellow ]
| `Black
| `Blue
| `Bold
| `Cyan
| `Faint
| `Fg of
[ `Black
| `Blue
| `Cyan
| `Green
| `Hi of color
| `Magenta
| `Red
| `White
| `Yellow ]
| `Green
| `Italic
| `Magenta
| `None
| `Red
| `Reverse
| `Underline
| `White
| `Yellow ]
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
.
typestyle_renderer =
[ `Ansi_tty | `None ]
The type for style renderers.
`Ansi_tty
, renders styles using
ANSI escape sequences.`None
, styled rendering has no effect.val style_renderer : Stdlib.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 : Stdlib.Format.formatter -> style_renderer -> unit
set_style_renderer ppf r
sets the style renderer of ppf
to r
.
Invalid_argument
if ppf
is Format.str_formatter
: its
renderer is always `None
.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
.
val strf : ('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a
Fmt.str
instead.val kstrf : (string -> 'a) ->
('b, Stdlib.Format.formatter, unit, 'a) Stdlib.format4 -> 'b
Fmt.kstr
instead.val strf_like : Stdlib.Format.formatter ->
('a, Stdlib.Format.formatter, unit, string) Stdlib.format4 -> 'a
Fmt.str_like
instead.val always : (unit, Stdlib.Format.formatter, unit) Stdlib.format -> 'a t
Fmt.any
instead.val unit : (unit, Stdlib.Format.formatter, unit) Stdlib.format -> unit t
Fmt.any
.val prefix : unit t -> 'a t -> 'a t
Fmt.(++)
.val suffix : unit t -> 'a t -> 'a t
Fmt.(++)
.val styled_unit : style ->
(unit, Stdlib.Format.formatter, unit) Stdlib.format -> unit t
styled s (any fmt)
insteadGiven a type ty
use:
pp_ty
for a pretty printer that provides full control to the
client and does not wrap the formatted value in an enclosing
box. See these examples.pp_dump_ty
for a pretty printer that provides little control
over the pretty-printing process, wraps the rendering in an
enclosing box and tries as much as possible to respect the
OCaml syntax. These pretty-printers should make it easy to
inspect and understand values of the given type, they are
mainly used for quick printf debugging and/or toplevel interaction.
See these examples.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.pp_dump
.