Module `B0_std.Fmt`Source

Textual formatters.

Helpers for dealing with Format.

Standard outputs

Sourceval stdout : Format.formatter

stdout outputs to standard output.

Sourceval stderr : Format.formatter

stderr outputs to standard error.

Formatting

Sourceval pf : Format.formatter -> ('a, Format.formatter, unit) format -> 'a

pf is Format.fprintf.

Sourceval pr : ('a, Format.formatter, unit) format -> 'a

pf is Format.printf.

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

epr is Format.eprintf.

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

str is Format.asprintf.

Source

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

kpf is Format.kfprintf.

Sourceval kstr : (string -> 'a) -> ('b, Format.formatter, unit, 'a) format4 -> 'b

kstr is Format.kasprintf.

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

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

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

failwith_notrace is like failwith but Failure is raised with raise_notrace.

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

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

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

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

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

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

Formatters

Sourcetype 'a t = Format.formatter -> 'a -> unit

The type for formatter of values of type 'a.

Sourceval flush : 'a t

flush has the effect of Format.pp_print_flush.

Sourceval flush_nl : 'a t

flush_nl has the effect of Format.pp_print_newline.

Sourceval nop : 'a t

nop formats nothing.

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

any fmt formats any value with fmt.

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

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

Separators

Sourceval cut : 'a t

cut has the effect of Format.pp_print_cut.

Sourceval sp : 'a t

sp has the effect of Format.pp_print_space.

Sourceval sps : int -> 'a t

sps n has the effect of Format.pp_print_break n 0.

Sourceval comma : 'a t

comma is Fmt.any ",@ ".

Sourceval semi : 'a t

semi is Fmt.any ";@ ".

Sourceval 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

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

Source

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

Sourceval append : 'a t -> 'a t -> 'a t

append pp_v0 pp_v1 ppf v is pp_v0 ppf v; pp_v1 ppf v.

Sourceval (++) : 'a t -> 'a t -> 'a t

( ++ ) is append.

Sourceval concat : ?sep:unit t -> 'a t list -> 'a t

concat ~sep pps concatenates the formatters pps separating them with sep (defaults to cut).

Boxes

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

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

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

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

Sourceval hovbox : ?indent:int -> 'a t -> 'a t

hovbox is a condensed box, see Format.pp_open_hovbox.

Brackets

Sourceval parens : 'a t -> 'a t

parens pp_v ppf is pf "@[<1>(%a)@]" pp_v.

Sourceval brackets : 'a t -> 'a t

brackets pp_v ppf is pf "@[<1>[%a]@]" pp_v.

Sourceval braces : 'a t -> 'a t

braces pp_v ppf is pf "@[<1>{%a}@]" pp_v.

Sourceval 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

Source

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

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

Sourcemodule OCaml : sig ... end

Formatting OCaml literal values.

Sourceval bool : bool t

bool is Format.pp_print_bool.

Sourceval int : int t

int is Format.pp_print_int.

Sourceval uint32 : int32 t

uint32 is pf ppf "%lu".

Sourceval int32 : int32 t

int32 is pf ppf "%ld".

Sourceval int64 : int64 t

int64 is pf ppf "%Ld".

Sourceval uint64 : int64 t

uint64 is pf ppf "%Lu".

Sourceval nativeint : nativeint t

nativeint is pf ppf "%nd".

Sourceval nativeuint : nativeint t

nativeuint is pf ppf "%nu".

Sourceval float : float t

float is pf ppf "%g".

Sourceval char : char t

char is Format.pp_print_char.

Sourceval string : string t

string is Format.pp_print_string.

Sourceval binary_string : string t

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

Sourceval bytes : bytes t

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

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

Sourceval backtrace : Printexc.raw_backtrace t

backtrace formats a backtrace.

Sourceval exn : exn t

exn formats an exception using Printexc.to_string.

Sourceval exn_backtrace : (exn * Printexc.raw_backtrace) t

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

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

Sourceval none : unit t

none is any "<none>".

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

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

Sourceval result : ok:'a t -> error:'b t -> ('a, 'b) result t

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

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

Sourceval 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

Sourceval text : string t

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

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

Sourceval lines : string t

lines formats lines by replacing newlines ('\n') in the string with calls to Format.pp_force_newline.

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

Sourceval ascii_char : char t

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

Sourceval ascii_string : string t

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

Sourceval text_uchar : 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).

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

Sourceval styled_text_string : string t

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

Sourceval text_bytes : bytes t

text_bytes is like text_string but on bytes values.

FIXME. Get rid of these in favour of OCaml

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

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

Sourceval styled_text_string_literal : string t

styled_text_string_literal combines text_string_literal and styled_text_string.

Magnitudes

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

Sourceval byte_size : int t

byte_size is si_size ~scale:0 "B".

Sourceval 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

Sourceval 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

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

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

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

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

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

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

Source

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.

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

Source

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.

Sourcetype styler =

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

The kind of styler.

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

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

Sourceval strip_styles : 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.

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

Sourcetype style = [

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

]

The type for text styles.

Sourceval st : style list -> string t

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

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

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

Sourceval code : string t

code is st [`Bold].

Sourceval code' : 'a t -> 'a t

code' is st' [`Bold].

Sourceval hey : string t

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

Sourceval puterr : unit t

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

Sourceval putwarn : unit t

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

Sourceval putnote : unit t

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

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/b0.std/B0_std/Fmt/index.html

Module `B0_std.Fmt`Source

Standard outputs

Formatting

Formatters

Separators

Sequencing

Boxes

Brackets

Records

Stdlib types

Text and lines

Magnitudes

HCI fragments

Text styling

package b0

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/b0.std/B0_std/Fmt/index.html

Module B0_std.FmtSource

Standard outputs

Formatting

Formatters

Separators

Sequencing

Boxes

Brackets

Records

Stdlib types

Text and lines

Magnitudes

HCI fragments

Text styling

dune-project
Dependency

Module `B0_std.Fmt`Source