module Fmt:sig
..end
Format
pretty-printer combinators.
Consult naming conventions for your pretty-printers.
References
Format
module documentation.Format
module
tutorial.
Release 0.7.1 - Daniel Bünzli <daniel.buenzl i@erratique.ch>
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
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).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
.type'a
t =Format.formatter -> 'a -> unit
'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
.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 : Buffer.t t
buffer
formats a Buffer.t
value's current contents.
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 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
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
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 text : string t
text
formats text by replacing spaces and newlines in the string
with calls to Format.pp_print_space
and Format.pp_force_newline
.
Note. This function will only work on US-ASCII strings. If you
are dealing with UTF-8 text you should use the pretty-printers
from Uuseg_string
.
val lines : string t
lines
formats lines by replacing newlines ('\n'
) in the string
with calls to Format.pp_force_newline
.
Note. This function will only work on US-ASCII string and with
newlines. If you are dealing with UTF-8 strings and different
kinds of line endings you should use the pretty-printers from
Uuseg_string
.
val text_range : ((int * int) * (int * int)) t
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
.val byte_size : int t
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).
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 : 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.
typestyle =
[ `Black
| `Blue
| `Bold
| `Cyan
| `Green
| `Magenta
| `None
| `Red
| `Underline
| `White
| `Yellow ]
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)
.typestyle_renderer =
[ `Ansi_tty | `None ]
`Ansi_tty
, renders styles using
ANSI escape sequences.`None
, styled rendering has no effect.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
.
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
.
Given 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.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.dump
.