708 lines
27 KiB
OCaml
708 lines
27 KiB
OCaml
(*---------------------------------------------------------------------------
|
|
Copyright (c) 2014 The fmt programmers. All rights reserved.
|
|
SPDX-License-Identifier: ISC
|
|
---------------------------------------------------------------------------*)
|
|
|
|
(** {!Format} pretty-printer combinators.
|
|
|
|
Consult {{!nameconv}naming conventions} for your pretty-printers.
|
|
|
|
{b References}
|
|
{ul
|
|
{- The {!Format} module documentation.}
|
|
{- The required reading {!Format} module
|
|
{{:https://ocaml.org/learn/tutorials/format.html}tutorial}.}} *)
|
|
|
|
(** {1:stdos Standard outputs} *)
|
|
|
|
val stdout : Format.formatter
|
|
(** [stdout] is the standard output formatter. *)
|
|
|
|
val stderr : Format.formatter
|
|
(** [stderr] is the standard error formatter. *)
|
|
|
|
(** {1:formatting Formatting} *)
|
|
|
|
val pf : Format.formatter -> ('a, Format.formatter, unit) Stdlib.format -> 'a
|
|
(** [pf] is {!Format.fprintf}. *)
|
|
|
|
val pr : ('a, Format.formatter, unit) format -> 'a
|
|
(** [pr] is [pf stdout]. *)
|
|
|
|
val epr : ('a, Format.formatter, unit) format -> 'a
|
|
(** [epr] is [pf stderr]. *)
|
|
|
|
val str : ('a, Format.formatter, unit, string) format4 -> 'a
|
|
(** [str] is {!Format.asprintf}.
|
|
|
|
{b Note.} When using [str] {!utf_8} and {!val-style_renderer} are
|
|
always respectively set to [true] and [`None]. See also
|
|
{!str_like}. *)
|
|
|
|
val kpf : (Format.formatter -> 'a) -> Format.formatter ->
|
|
('b, Format.formatter, unit, 'a) Stdlib.format4 -> 'b
|
|
(** [kpf] is {!Format.kfprintf}. *)
|
|
|
|
val kstr :
|
|
(string -> 'a) -> ('b, Format.formatter, unit, 'a) format4 -> 'b
|
|
(** [kstr] is like {!str} but continuation based. *)
|
|
|
|
val str_like :
|
|
Format.formatter -> ('a, Format.formatter, unit, string) format4 -> 'a
|
|
(** [str_like ppf] is like {!str} except its {!utf_8} and {!val-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 {!utf_8} and
|
|
{!val-style_renderer} settings are copied from those of [like]
|
|
(if provided). *)
|
|
|
|
val failwith : ('a, Format.formatter, unit, 'b) format4 -> 'a
|
|
(** [failwith] is [kstr failwith], raises {!Stdlib.Failure} with
|
|
a pretty-printed string argument. *)
|
|
|
|
val failwith_notrace : ('a, Format.formatter, unit, 'b) format4 -> 'a
|
|
(** [failwith_notrace] is like {!failwith} but raises with {!raise_notrace}. *)
|
|
|
|
val invalid_arg : ('a, Format.formatter, unit, 'b) format4 -> 'a
|
|
(** [invalid_arg] is [kstr invalid_arg], raises
|
|
{!Stdlib.Invalid_argument} with a pretty-printed string argument. *)
|
|
|
|
val error : ('b, Format.formatter , unit, ('a, string) result) format4 -> 'b
|
|
(** [error fmt ...] is [kstr (fun s -> Error s) fmt ...] *)
|
|
|
|
val error_msg :
|
|
('b, Format.formatter , unit, ('a, [> `Msg of string]) result) format4 -> 'b
|
|
(** [error_msg fmt ...] is [kstr (fun s -> Error (`Msg s)) fmt ...] *)
|
|
|
|
(** {1 Formatters} *)
|
|
|
|
type 'a t = 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, 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 if' : bool -> 'a t -> 'a t
|
|
(** [if' bool pp] is [pp] if [bool] is [true] and {!nop} otherwise. *)
|
|
|
|
val fmt : ('a, Format.formatter, unit) Stdlib.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
|
|
{!t}. *)
|
|
|
|
(** {1:seps 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}[ ";@ "]. *)
|
|
|
|
(** {1:seq 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}). *)
|
|
|
|
(** {1:boxes 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}. *)
|
|
|
|
(** {1:bracks 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). *)
|
|
|
|
(** {1:records 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. *)
|
|
|
|
(** {1:stdlib Stdlib types}
|
|
|
|
Formatters for structures give full control to the client over the
|
|
formatting process and do not wrap the formatted structures with
|
|
boxes. Use the {!Dump} module to quickly format values for
|
|
inspection. *)
|
|
|
|
val bool : bool t
|
|
(** [bool] is {!Format.pp_print_bool}. *)
|
|
|
|
val int : int t
|
|
(** [int ppf] 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 {e 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 {e 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].
|
|
|
|
{b 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. *)
|
|
|
|
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) 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 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) 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 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 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}. *)
|
|
|
|
(** Formatters for inspecting OCaml values.
|
|
|
|
Formatters of this module dump OCaml value with little control
|
|
over the representation but with good default box structures and,
|
|
whenever possible, using OCaml syntax. *)
|
|
module Dump : sig
|
|
|
|
(** {1:stdlib Stdlib types} *)
|
|
|
|
val signal : int t
|
|
(** [signal] formats an OCaml {{!Sys.sigabrt}signal number} as a C
|
|
POSIX
|
|
{{:http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html}
|
|
constant} or ["SIG(%d)"] the signal number is unknown. *)
|
|
|
|
val uchar : Uchar.t t
|
|
(** [uchar] formats an OCaml {!Uchar.t} value using only US-ASCII
|
|
encoded characters according to the Unicode
|
|
{{:http://www.unicode.org/versions/latest/appA.pdf}notational
|
|
convention} for code points. *)
|
|
|
|
val string : string t
|
|
(** [string] is [pf ppf "%S"]. *)
|
|
|
|
val pair : 'a t -> 'b t -> ('a * 'b) t
|
|
(** [pair pp_fst pp_snd] formats an OCaml pair using [pp_fst] and [pp_snd]
|
|
for the first and second projection. *)
|
|
|
|
val option : 'a t -> 'a option t
|
|
(** [option pp_v] formats an OCaml option using [pp_v] for the [Some]
|
|
case. No parentheses are added. *)
|
|
|
|
val result : ok:'a t -> error:'b t -> ('a, 'b) result t
|
|
(** [result ~ok ~error] formats an OCaml result using [ok] for the [Ok]
|
|
case value and [error] for the [Error] case value. No parentheses
|
|
are added. *)
|
|
|
|
val list : 'a t -> 'a list t
|
|
(** [list pp_v] formats an OCaml list using [pp_v] for the list
|
|
elements. *)
|
|
|
|
val array : 'a t -> 'a array t
|
|
(** [array pp_v] formats an OCaml array using [pp_v] for the array
|
|
elements. *)
|
|
|
|
val seq : 'a t -> 'a Seq.t t
|
|
(** [seq pp_v] formats an OCaml sequence using [pp_v] for the sequence
|
|
elements. *)
|
|
|
|
val hashtbl : 'a t -> 'b t -> ('a, 'b) Hashtbl.t t
|
|
(** [hashtbl pp_k pp_v] formats an unspecified representation of the
|
|
bindings of a hash table using [pp_k] for the keys and [pp_v]
|
|
for the values. If the hash table has multiple bindings for a
|
|
given key, all bindings are formatted, with the most recent
|
|
binding first. *)
|
|
|
|
val queue : 'a t -> 'a Queue.t t
|
|
(** [queue pp_v] formats an unspecified representation of an OCaml
|
|
queue using [pp_v] to format its elements, in least recently added
|
|
order. *)
|
|
|
|
val stack : 'a t -> 'a Stack.t t
|
|
(** [stack pp_v] formats an unspecified representation of an OCaml
|
|
stack using [pp_v] to format its elements in top to bottom order. *)
|
|
|
|
(** {1:record Records} *)
|
|
|
|
val field : ?label:string t -> string -> ('b -> 'a) -> 'a t -> 'b t
|
|
(** [field ~label l prj pp_v] pretty prints a named field using [label]
|
|
(defaults to [styled `Yellow string]) for the label, and [using prj pp_v]
|
|
for the field value. *)
|
|
|
|
val record : 'a t list -> 'a t
|
|
(** [record fields] pretty-prints a value using the concatenation of
|
|
[fields], separated by [";@,"], framed in a vertical
|
|
box and surrounded by {!braces}. *)
|
|
|
|
(** {1:seq Sequencing}
|
|
|
|
These are akin to {!iter} and {!iter_bindings} but
|
|
delimit the sequences with {!parens}. *)
|
|
|
|
val iter : (('a -> unit) -> 'b -> unit) -> 'b t -> 'a t -> 'b t
|
|
(** [iter iter pp_name pp_elt] formats an unspecified representation
|
|
of the iterations of [iter] over a value using [pp_elt]. The
|
|
iteration is named by [pp_name]. *)
|
|
|
|
val iter_bindings : (('a -> 'b -> unit) -> 'c -> unit) -> 'c t -> 'a t
|
|
-> 'b t -> 'c t
|
|
(** [iter_bindings ~sep iter pp_name pp_k pp_v] formats an
|
|
unspecified representation of the iterations of [iter] over a
|
|
value using [pp_k] and [pp_v]. The iteration is named by
|
|
[pp_name]. *)
|
|
end
|
|
|
|
(** {1:mgs Magnitudes} *)
|
|
|
|
val si_size : scale:int -> string -> int t
|
|
(** [si_size ~scale unit] formats a non negative integer
|
|
representing unit [unit] at scale 10{^scale * 3}, depending on
|
|
its magnitude, using power of 3
|
|
{{:https://www.bipm.org/en/publications/si-brochure/chapter3.html}
|
|
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 10{^scale * 3} an integer
|
|
represents, for example [-1] for m[unit] (10{^-3}), [0] for
|
|
[unit] (10{^0}), [1] for [kunit] (10{^3}); 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 {{:https://en.wikipedia.org/wiki/Binary_prefix}binary prefixes}
|
|
up to pebi bytes (2{^15}). *)
|
|
|
|
val uint64_ns_span : int64 t
|
|
(** [uint64_ns_span] formats an {e unsigned} nanosecond time span
|
|
according to its magnitude using
|
|
{{:http://www.bipm.org/en/publications/si-brochure/chapter3.html}SI
|
|
prefixes} on seconds and
|
|
{{:http://www.bipm.org/en/publications/si-brochure/table6.html}accepted
|
|
non-SI units}. Years are counted in Julian years (365.25 SI-accepted days)
|
|
as {{:http://www.iau.org/publications/proceedings_rules/units/}defined}
|
|
by the International Astronomical Union (IAU). Only US-ASCII characters
|
|
are used ([us] is used for [µs]). *)
|
|
|
|
(** {1:binary 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) [string]s. *)
|
|
|
|
val ascii : ?w:int -> ?subst:unit t -> unit -> char vec t
|
|
(** [ascii ~w ~subst ()] formats character sequences by printing
|
|
characters in the {e 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 {e xxd} and forcing line breaks after every
|
|
[w] characters (defaults to 16). *)
|
|
|
|
(** {1:text Words, paragraphs, text and lines}
|
|
|
|
{b 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}.
|
|
|
|
{b 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
|
|
{{:http://www.gnu.org/prep/standards/standards.html#Errors}
|
|
GNU conventions}. *)
|
|
|
|
(** {1:hci 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]
|
|
{ul
|
|
{- [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. *)
|
|
|
|
val cardinal : ?zero:int t -> one:int t -> ?other:int t -> unit -> int t
|
|
(** [cardinal ?zero ~one ?other ()] formats an integer by selecting a
|
|
formatter according to the cardinal english plural form of its absolute
|
|
value [n]:
|
|
{ul
|
|
{- [zero], if [n = 0]. Defaults to [other] (as per
|
|
{{:https://www.unicode.org/cldr/charts/47/supplemental/language_plural_rules.html#en}english rules}).}
|
|
{- [one], if [n = 1].}
|
|
{- [other], otherwise. Defaults to [one] followed by a ['s'] character.}} *)
|
|
|
|
val ordinal :
|
|
?zero:int t -> ?one:int t -> ?two:int t -> ?three:int t -> ?other:int t ->
|
|
unit -> int t
|
|
(** [ordinal ?zero ?one ?two ?three ?other ()] formats an integer by selecting a
|
|
formatter according to the ordinal english plural form of its absolute
|
|
value [n]:
|
|
{ul
|
|
{- [zero], if [n = 0]. Defaults to [other] (as per
|
|
{{:https://www.unicode.org/cldr/charts/47/supplemental/language_plural_rules.html#en}english rules}).}
|
|
{- [one], if [n mod 10 = 1 && n mod 100 <> 11]. Defaults to ["%dst"].}
|
|
{- [two], if [n mod 10 = 2 && n mod 100 <> 12]. Defaults to ["%dnd"].}
|
|
{- [three], if [n mod 10 = 3 && n mod 100 <> 13]. Defaults to ["%drd"].}
|
|
{- [other] otherwise. Defaults to ["%dth"].}} *)
|
|
|
|
(** {1:utf8_cond Conditional UTF-8 formatting}
|
|
|
|
{b 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:
|
|
{ul
|
|
{- [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
|
|
{!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].
|
|
|
|
@raise Invalid_argument if [ppf] is {!Format.str_formatter}: it is
|
|
is always UTF-8 enabled. *)
|
|
|
|
(** {1:styled 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 (** deprecated *) ]
|
|
(** The type for styles:
|
|
{ul
|
|
{- [`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 background color or high-intensity color on [`Hi _].}
|
|
{- [#color] is the foreground color, {b deprecated} use [`Fg
|
|
#color] instead.}} *)
|
|
|
|
val styled : style -> 'a t -> 'a t
|
|
(** [styled s pp] formats like [pp] but styled with [s]. *)
|
|
|
|
(** {2 Style rendering control} *)
|
|
|
|
type style_renderer = [ `Ansi_tty | `None ]
|
|
(** The type for style renderers.
|
|
{ul
|
|
{- [`Ansi_tty], renders styles using
|
|
{{:http://www.ecma-international.org/publications/standards/Ecma-048.htm}
|
|
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
|
|
{!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].
|
|
|
|
@raise Invalid_argument if [ppf] is {!Format.str_formatter}: its
|
|
renderer is always [`None]. *)
|
|
|
|
(** {1:stringconverters 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]. *)
|
|
|
|
(** {1:deprecated Deprecated} *)
|
|
|
|
val strf : ('a, Format.formatter, unit, string) format4 -> 'a
|
|
[@@ocaml.deprecated "use Fmt.str instead."]
|
|
(** @deprecated use {!str} instead. *)
|
|
|
|
val kstrf : (string -> 'a) -> ('b, Format.formatter, unit, 'a) format4 -> 'b
|
|
[@@ocaml.deprecated "use Fmt.kstr instead."]
|
|
(** @deprecated use {!kstr} instead. *)
|
|
|
|
val strf_like :
|
|
Format.formatter -> ('a, Format.formatter, unit, string) format4 -> 'a
|
|
[@@ocaml.deprecated "use Fmt.str_like instead."]
|
|
(** @deprecated use {!str_like} instead. *)
|
|
|
|
val always : (unit, Format.formatter, unit) Stdlib.format -> 'a t
|
|
[@@ocaml.deprecated "use Fmt.any instead."]
|
|
(** @deprecated use {!any} instead. *)
|
|
|
|
val unit : (unit, Format.formatter, unit) Stdlib.format -> unit t
|
|
[@@ocaml.deprecated "use Fmt.any instead."]
|
|
(** @deprecated use {!any}. *)
|
|
|
|
val prefix : unit t -> 'a t -> 'a t
|
|
[@@ocaml.deprecated "use Fmt.(++) instead."]
|
|
(** @deprecated use {!( ++ )}. *)
|
|
|
|
val suffix : unit t -> 'a t -> 'a t
|
|
[@@ocaml.deprecated "use Fmt.(++) instead."]
|
|
(** @deprecated use {!( ++ )}. *)
|
|
|
|
val styled_unit :
|
|
style -> (unit, Format.formatter, unit) Stdlib.format -> unit t
|
|
[@@ocaml.deprecated "use Fmt.(styled s (any fmt)) instead."]
|
|
(** @deprecated use [styled s (any fmt)] instead *)
|
|
|
|
(** {1:nameconv Naming conventions}
|
|
|
|
Given a type [ty] use:
|
|
|
|
{ul
|
|
{- [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 {{!stdlib}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 {{!Fmt.Dump.stdlib}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]. *)
|