Fmt (b0.B0_std.Fmt)

Standard outputs

val stdout : Stdlib.Format.formatter

stdout outputs to standard output.

val stderr : Stdlib.Format.formatter

stderr outputs to standard error.

Formatting

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

pf is Format.printf.

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

epr is Format.eprintf.

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

str is Format.asprintf.

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 Format.kasprintf.

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

failwith fmt ... is kstr failwith fmt ...

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

failwith_notrace is like failwith but Failure is raised with raise_notrace.

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

failwith_line fmt … is failwith ("%d:" ^^ fmt) ….

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

invalid_arg fmt ... is kstr invalid_arg fmt ...

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

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

Formatters

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

The type for formatter of values of type 'a.

val flush : 'a t

flush has the effect of Format.pp_print_flush.

val flush_nl : 'a t

flush_nl has the effect of Format.pp_print_newline.

val nop : 'a t

nop formats nothing.

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

any fmt formats any value with fmt.

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

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

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 ";@ ".

val suffix_lines : suffix:string -> 'a t -> 'a t

suffix_lines ~suffix pp adds suffix to the lines formatted by pp. Note. Not very compositional: first formats to a string, cuts the string and then formats the lines.

Sequencing

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

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 concatenates the formatters pps separating them with sep (defaults to cut).

Boxes

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

hvbox is like box but is either hbox if its fits on a single line or vbox otherwise.

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 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 st [`Yellow] 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

Formatters for structures give full control to the client over the formatting process and do not wrap the formatted structures with boxes. If you want to print literal OCaml values use the OCaml module.

module OCaml : sig ... end

Formatting OCaml literal values.

val bool : bool t

bool is Format.pp_print_bool.

val int : int t

int is Format.pp_print_int.

val uint32 : int32 t

uint32 is pf ppf "%lu".

val int32 : int32 t

int32 is pf ppf "%ld".

val int64 : int64 t

int64 is pf ppf "%Ld".

val uint64 : int64 t

uint64 is pf ppf "%Lu".

val nativeint : nativeint t

nativeint is pf ppf "%nd".

val nativeuint : nativeint t

nativeuint is pf ppf "%nu".

val float : float t

float is pf ppf "%g".

val char : char t

char is Format.pp_print_char.

val string : string t

string is Format.pp_print_string.

val binary_string : string t

binary_string formats strings as ASCII hex. See also Text and lines.

val bytes : bytes t

bytes formats bytes as ASCII hex. See also Text and lines.

val sys_signal : int t

sys_signal formats an OCaml signal number as a C POSIX constant or "SIG(%d)" if the signal number is unknown.

val backtrace : Stdlib.Printexc.raw_backtrace t

backtrace formats a backtrace.

val exn : exn t

exn formats an exception using Printexc.to_string.

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

exn_backtrace formats an exception backtrace using exn and the format use by the OCaml runtime system.

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 none : unit t

none is any "<none>".

val option : ?none:unit t -> 'a t -> 'a option t

option ~none pp_v formats an option. The Some case uses pp_v and None uses none (defaults to nop).

val either : left:'a t -> right:'b t -> ('a, 'b) Either.t t

either ~left ~right formats an Either.t value. The Left case uses left and the Right cases uses right.

val result : ok:'a t -> error:'b t -> ('a, 'b) Stdlib.result t

result ~ok ~error formats a result value. The Ok case uses ok and the Error case uses error.

val list : ?empty:unit t -> ?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 empty (defaults to nop).

val array : ?empty:unit t -> ?sep:unit t -> 'a t -> 'a array t

array ~sep pp_v formats array elements. Each element of the array is formatted in in order with pp_v. Elements are seperated by sep (defaults to cut). If the array is empty this is empty (defauls to nop).

Text and lines

val text : string t

text is Format.pp_print_text. FIXME. replace this by the behaviour of styledtext.

val styled_text : string t

styled_text formats ANSI escape sequences as zero width characters, collapses multiple newlines and spaces to a single Fmt.sp and preserves blank lines and suppresses trailing space and newlines.

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 … (U+2026) which does count towards max.

val ascii_char : char t

ascii_char prints Char.Ascii.is_print characters and hex escapes for other characters.

val ascii_string : string t

ascii_string prints Char.Ascii.is_print characters and hex escapes for other characters.

val text_uchar : Stdlib.Uchar.t t

text_uchar formats an UTF-8 encoded Unicode character or its scalar value in U+%04X representation if u is in C0 control characters (U+0000-U+001F), C1 control characters (U+0080-U+009F), line separator (U+2028), paragraph separator (U+2029), left-to-right mark (U+200E) or right-to-left mark (U+200F).

val text_string : string t

text_string formats an UTF-8 encoded string but escapes: C0 control characters (U+0000-U+001F), C1 control characters (U+0080-U+009F), line separator (U+2028) and paragraph separator (U+2029). Decoding errors are replaced by literal Uchar.rep characters.

val styled_text_string : string t

styled_text_string is like text_string but ANSI escape sequences are detected and output as zero width strings.

val text_bytes : bytes t

text_bytes is like text_string but on bytes values.

FIXME. Get rid of these in favour of OCaml

val ascii_string_literal : string t

ascii_string_literal is like ascii_string but between double quotes '\"'. Double quotes are also escaped and CR an LF are escaped by '\r' and '\n'. The result is a valid, single line, OCaml string.

val text_string_literal : string t

text_string_literal is like text_string but between double quotes '\"'. Double quotes are also escaped an CR and LF are escaped by '\r' and '\n'. The result is a valid, single line, OCaml string.

val styled_text_string_literal : string t

styled_text_string_literal combines text_string_literal and styled_text_string.

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 SI prefixes (i.e. all of them except deca, hector, deci and centi). The output is UTF-8 encoded, it uses U+03BC for µ (10^-6).

scale indicates the scale 10^{scale * 3} an integer represents, for example -1 for munit (10^-3), 0 for unit (10⁰), 1 for kunit (10³); 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 uint64_ns_span : int64 t

uint64_ns_span formats an unsigned nanosecond time span according to its magnitude using SI prefixes on seconds and non-SI units. Years are counted in Julian years (365.25 SI-accepted days) as defined by the International Astronomical Union.

Rounds towards positive infinity, i.e. over approximates, no duration is formatted shorter than it is.

The output is UTF-8 encoded, it uses U+03BC for µs (10^-6s).

HCI fragments

val and_enum : ?empty:unit t -> 'a t -> 'a list t

and_enum ~empty pp_v ppf l formats l according to its length.

0, formats empty (defaults to nop).
1, formats the element with pp_v.
2, formats "%a and %a" with the list elements
n, formats "%a, ... and %a" with the list elements

val or_enum : ?empty:unit t -> 'a t -> 'a list t

or_enum is like and_enum but uses "or" instead of "and".

val did_you_mean : 'a t -> 'a list t

did_you_mean pp_v formats "Did you mean %a ?" with or_enum if the list is non-empty and nop otherwise.

val must_be : 'a t -> 'a list t

must_be pp_v formats "Must be %a." with or_enum if the list is non-empty and nop otherwise.

val unknown : kind:unit t -> 'a t -> 'a t

unknown ~kind pp_v formats "Unknown %a %a." kind () pp_v.

val unknown' : 
  kind:unit t ->
  'a t ->
  hint:('a t -> 'a list t) ->
  ('a * 'a list) t

unknown ~kind pp_v ~hint (v, hints) formats unknown followed by a space and hint pp_v hints if hints is non-empty.

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:

zero, if n = 0. Defaults to other (as per 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:

zero, if n = 0. Defaults to other (as per 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".

Text styling

Text styling control happens via ANSI escape sequences and is handled globally. See the cookbook for more information.

type styler =

| Ansi
(*
Style with ANSI escapes.
*)
| Plain
(*
No styles, plain text.
*)

The kind of styler.

val set_styler : styler -> unit

set_styler styler sets the global styler to styler.

Use B0_std_cli.set_no_color to set this from the command line.

val styler : unit -> styler

styler is the global styler. The initial value is Ansi or Plain if one of the following conditions is satisified:

The NO_COLOR environment variable is set and different from the empty string. Yes, even if you have NO_COLOR=0, that's what the dumb https://no-color.org standard says.
The TERM environment variable is dumb.
The TERM environment variable is unset and Sys.backend_type is not Other "js_of_ocaml" (browser consoles support ANSI escapes).

val strip_styles : Stdlib.Format.formatter -> unit

strip_styles ppf, this overrides the formatter's out_string function to strip out styling information. See also String.strip_ansi_escapes.

Note. This assumes ppf is not used to write data that uses raw U+001B characters.

type color = [

| `Default
| `Black
(* *)
| `Black_bright
(* *)
| `Red
(* *)
| `Red_bright
(* *)
| `Green
(* *)
| `Green_bright
(* *)
| `Yellow
(* *)
| `Yellow_bright
(* *)
| `Blue
(* *)
| `Blue_bright
(* *)
| `Magenta
(* *)
| `Magenta_bright
(* *)
| `Cyan
(* *)
| `Cyan_bright
(* *)
| `White
(* *)
| `White_bright
(* *)

]

The type for colors.

Note. The actual color may differ in terminals. See for example the table here and check out the output of the b0-sttyle tool.

type style = [

| `Bold
| `Faint
| `Italic
| `Underline
| `Blink of [ `Slow | `Rapid ]
| `Reverse
| `Fg of color
| `Bg of color

]

The type for text styles.

val st : style list -> string t

st styles ppf s formats s on ppf styled by styles.

val st' : style list -> 'a t -> 'a t

st' styles pp_v ppf v formats v with pp_v on ppf styled by styles.

val code : string t

code is st [`Bold].

val code' : 'a t -> 'a t

code' is st' [`Bold].

val hey : string t

hey is st [`Bold; `Fg `Red].

val puterr : unit t

puterr formats Error: with [`Fg `Red].

val putwarn : unit t

putwarn formats Warning: with [`Fg `Yellow].

val putnote : unit t

putnote formats Note: with [`Fg `Blue].