unikernel/duniverse/fmt/src/fmt.mli

@@ -0,0 +1,708 @@
+(*---------------------------------------------------------------------------
+   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]. *)