Module Fmt

Standard outputs
Formatting
Formatters
Separators
Sequencing
Boxes
Brackets
Records
Stdlib types
Magnitudes
Binary data
Words, paragraphs, text and lines
HCI fragments
Conditional UTF-8 formatting
Styled formatting
- Style rendering control
Converting with string value converters
Deprecated
Naming conventions

Instructions: Use this module in your project

In the IDE (CLion, Visual Studio Code, Xcode, etc.) you use for your DkSDK project:

Add the following to your project's dependencies/CMakeLists.txt:

Copy

DkSDKProject_DeclareAvailable(fmt
    CONSTRAINT "= 0.9.0+dune"
    FINDLIBS fmt fmt.cli fmt.top fmt.tty)
DkSDKProject_MakeAvailable(fmt)

Add the Findlib::fmt library to any desired targets in src/*/CMakeLists.txt:

Copy

target_link_libraries(YourPackage_YourLibraryName
     # ... existing libraries, if any ...
     Findlib::fmt)

Click your IDE's Build button

Not using DkSDK?

FIRST, do one or all of the following:

Run:
Copy
```
opam install fmt.0.9.0+dune
```

Edit your dune-project and add:

Copy

(package
  (name YourExistingPackage)
  (depends
  ; ... existing dependenices ...
  (fmt (>= 0.9.0+dune))))

Then run:

Copy

dune build *.opam # if this fails, run: dune build

Edit your <package>.opam file and add:

Copy

depends: [
  # ... existing dependencies ...
  "fmt" {>= "0.9.0+dune"}
]

Then run:

Copy

opam install . --deps-only

FINALLY, add the fmt library to any desired (library)and/or (executable) targets in your **/dune files:

Copy

(library
  (name YourLibrary)
  ; ... existing library options ...
  (libraries
    ; ... existing libraries ...
    fmt))

(executable
  (name YourExecutable)
  ; ... existing executable options ...
  (libraries
    ; ... existing libraries ...
    fmt))

Standard outputs

valstdout :Stdlib.Format.formatter

stdout is the standard output formatter.

valstderr :Stdlib.Format.formatter

stderr is the standard error formatter.

Formatting

valpf :Stdlib.Format.formatter -> ``('a, Stdlib.Format.formatter, unit)`` format -> 'a

pf is Format.fprintf.

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

pr is pf stdout.

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

epr is pf stderr.

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

str is Format.asprintf.

Note. When using str utf_8 and style_renderer are always respectively set to true and `None. See also str_like.

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

kpf is Format.kfprintf.

valkstr : ``(``string-> 'a)`` -> ``('b, Stdlib.Format.formatter, unit, 'a)`` format4 -> 'b

kstr is like str but continuation based.

valstr_like :Stdlib.Format.formatter -> ``('a, Stdlib.Format.formatter, unit, string)`` format4 -> 'a

str_like ppf is like str except its utf_8 and style_renderer settings are those of ppf.

val with_buffer : ``?like:Stdlib.Format.formatter -> Stdlib.Buffer.t -> Stdlib.Format.formatter

with_buffer ~like b is a formatter whose utf_8 and style_renderer settings are copied from those of like (if provided).

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

failwith is kstr failwith, raises Stdlib.Failure with a pretty-printed string argument.

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

failwith_notrace is like failwith but raises with raise_notrace.

val invalid_arg : ``('a, Stdlib.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, Stdlib.Format.formatter, unit, ``('a, string)`` result)`` format4 -> 'b

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

val error_msg : ``('b, Stdlib.Format.formatter, unit, ``('a, ``[> ``` Msg of string ``` ]) [result](../../ocaml/Stdlib/#type-result))`` [format4](../../ocaml/Stdlib/#type-format4) `-> 'b\

error_msg fmt ... is kstr (fun s -> Error (`Msg s)) fmt ...

Formatters

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

The type for formatters of values of type 'a.

valflush :'a t

flush has the effect of Format.pp_print_flush

valnop :'a t

nop formats nothing.

valany : ``(unit,Stdlib.Format.formatter, unit)`` 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).

valconst :'a t -> 'a -> 'b t

const pp_v v always formats v using pp_v.

val fmt : ``('a, Stdlib.Format.formatter, unit)`` format -> Stdlib.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.

Separators

valcut :'a t

cut has the effect of Format.pp_print_cut.

valsp :'a t

sp has the effect of Format.pp_print_space.

valsps : ``int-> 'a t

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

valcomma :'a t

comma is Fmt.any ",@ ".

valsemi :'a t

semi is Fmt.any ";@ ".

Sequencing

valappend :'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.

valconcat : ``?sep:``unitt -> 'a tlist``-> 'a t

concat ~sep pps formats a value using the formaters pps and separting each format with sep (defaults to cut).

valiter : ``?sep:``unitt -> ``(``('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).

valiter_bindings : ``?sep:``unitt -> ``(``('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).

Boxes

valbox : ``?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).

valhbox :'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.

valvbox : ``?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.

valhvbox : ``?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.

valhovbox : ``?indent:int-> 'a t -> 'a t

hovbox is a condensed box. See Format.pp_open_hovbox.

Brackets

valparens :'a t -> 'a t

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

valbrackets :'a t -> 'a t

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

valbraces :'a t -> 'a t

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

valquote : ``?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

valid :'a -> 'a

id is Fun.id.

valfield : ``?label:``stringt ->``?sep:``unitt ->``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 ":@ ".

valrecord : ``?sep:``unitt -> 'a tlist``-> '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. Use the Dump module to quickly format values for inspection.

valbool : ``boolt

bool is Format.pp_print_bool.

valint : ``intt

int ppf is pf ppf "%d".

valnativeint : ``nativeintt

nativeint ppf is pf ppf "%nd".

valint32 : ``int32t

int32 ppf is pf ppf "%ld".

valint64 : ``int64t

int64 ppf is pf ppf "%Ld".

valuint : ``intt

uint ppf is pf ppf "%u".

valunativeint : ``nativeintt

unativeint ppf is pf ppf "%nu".

valuint32 : ``int32t

uint32 ppf is pf ppf "%lu".

valuint64 : ``int64t

uint64 ppf is pf ppf "%Lu".

valfloat : ``floatt

float ppf is pf ppf "%g".

valfloat_dfrac : ``int->``floatt

float_dfrac d rounds the float to the dth decimal fractional digit and formats the result with "%g". Ties are rounded towards positive infinity. The result is only defined for 0 <= d <= 16.

valfloat_dsig : ``int->``floatt

float_dsig d rounds the normalized decimal significand of the float to the dth 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.

valchar : ``chart

char is Format.pp_print_char.

valstring : ``stringt

string is Format.pp_print_string.

valbuffer :Stdlib.Buffer.t t

buffer formats a Buffer.t value's current contents.

valexn : ``exnt

exn formats an exception.

valexn_backtrace : ``(exn *Stdlib.Printexc.raw_backtrace)`` t

exn_backtrace formats an exception backtrace.

valpair : ``?sep:``unitt -> '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).

valoption : ``?none:``unitt -> 'a t -> 'aoption``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.

vallist : ``?sep:``unitt -> 'a t -> 'alist``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.

valarray : ``?sep:``unitt -> 'a t -> 'aarray``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.

valseq : ``?sep:``unitt -> 'a t -> 'a Stdlib.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.

valhashtbl : ``?sep:``unitt -> ``('a*'b)`` t -> ``('a, 'b)`` Stdlib.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.

valqueue : ``?sep:``unitt -> 'a t -> 'a Stdlib.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.

valstack : ``?sep:``unitt -> 'a t -> 'a Stdlib.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.

module Dump:sig...end

Formatters for inspecting OCaml values.

Magnitudes

valsi_size : ``scale:int->``string->``intt

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

valbyte_size : ``intt

byte_size is si_size ~scale:0 "B".

valbi_byte_size : ``intt

bi_byte_size formats a byte size according to its magnitude using binary prefixes up to pebi bytes (2¹⁵).

valuint64_ns_span : ``int64t

uint64_ns_span formats an unsigned nanosecond time span according to its magnitude using SI prefixes on seconds and accepted non-SI units. Years are counted in Julian years (365.25 SI-accepted days) as defined by the International Astronomical Union (IAU). Only US-ASCII characters are used (us is used for µs).

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

valon_bytes : ``charvec t ->``bytest

on_bytes pp is pp adapted to format (entire) bytes.

valon_string : ``charvec t ->``stringt

on_string pp is pp adapted to format (entire) strings.

valascii : ``?w:int->``?subst:``unitt ->``unit->``charvec t

ascii ~w ~subst () formats character sequences by printing characters in the 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).

valoctets : ``?w:int->``?sep:``unitt ->``unit->``charvec 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).

valaddresses : ``?addr:``intt ->``?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).

valhex : ``?w:int->``unit->``charvec t

hex ~w () formats character sequences as traditional hex dumps, matching the output of xxd and forcing line breaks after every w characters (defaults to 16).

Words, paragraphs, text and lines

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.

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

valwords : ``stringt

words formats words by suppressing initial and trailing white space and replacing consecutive white space with a single Format.pp_print_space.

valparagraphs : ``stringt

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.

valtext : ``stringt

text formats text by respectively replacing spaces and newlines in the string with Format.pp_print_space and Format.pp_force_newline.

vallines : ``stringt

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

valtruncated : ``max:int->``stringt

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.

valtext_loc : ``(``(int * int)`` * ``(int * int)``)``t

text_loc formats a line-column text range according to GNU conventions.

HCI fragments

valone_of : ``?empty:``unitt -> 'a t -> 'alist``t

one_of ~empty pp_v ppf l formats according to the length of l

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

valdid_you_mean : ``?pre:``unitt ->``?post:``unitt ->``kind:string-> 'a t -> ``('a*'alist``)``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.

Conditional UTF-8 formatting

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.

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

valutf_8 :Stdlib.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.

valset_utf_8 :Stdlib.Format.formatter ->``bool-> unit

set_utf_8 ppf b enables or disables conditional UTF-8 formatting on ppf.

raises Invalid_argument

if ppf is Format.str_formatter: it is is always UTF-8 enabled.

Styled formatting

typecolor`` = ``[


| ``` Black ``

| ``` Blue ``

| ``` Cyan ``

| ``` Green ``

| ``` Magenta ``

| ``` Red ``

| ``` White ``

| ``` Yellow `` ]

The type for colors.

typestyle`` = ``[


| ``` None ``

| ``` Bold ``

| ``` Faint ``

| ``` Italic ``

| ``` Underline ``

| ``` Reverse ``

| ``` Fg  `of`` [ [color](#type-color) | `Hi of [color](#type-color) ]`

| ``` Bg  `of`` [ [color](#type-color) | `Hi of [color](#type-color) ]`

| color ]

The type for styles:

`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 foreground color or high-intensity color on `Hi _.
#color is the foreground colour, deprecated use `Fg #color instead.

valstyled :style -> 'a t -> 'a t

styled s pp formats like pp but styled with s.

Style rendering control

typestyle_renderer`` = ``[


| ``` Ansi_tty ``

| ``` None `` ]

The type for style renderers.

`Ansi_tty, renders styles using ANSI escape sequences.
`None, styled rendering has no effect.

valstyle_renderer :Stdlib.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.

valset_style_renderer :Stdlib.Format.formatter -> style_renderer -> unit

set_style_renderer ppf r sets the style renderer of ppf to r.

raises Invalid_argument

if ppf is Format.str_formatter: its renderer is always `None.

Converting with string value converters

val of_to_string : ``('a ->string)``-> 'a t

of_to_string f ppf v is string ppf (f v).

valto_to_string :'a t -> 'a -> string

to_to_string pp_v v is strf "%a" pp_v v.

Deprecated

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

deprecated

use str instead.

valkstrf : ``(``string-> 'a)`` -> ``('b, Stdlib.Format.formatter, unit, 'a)`` format4 -> 'b

deprecated

use kstr instead.

valstrf_like :Stdlib.Format.formatter -> ``('a, Stdlib.Format.formatter, unit, string)`` format4 -> 'a

deprecated

use str_like instead.

valalways : ``(unit,Stdlib.Format.formatter, unit)`` format -> 'a t

deprecated

use any instead.

valunit : ``(unit,Stdlib.Format.formatter, unit)`` format ->``unitt

deprecated

use any.

valprefix : ``unitt -> 'a t -> 'a t

deprecated

use (++).

valsuffix : ``unitt -> 'a t -> 'a t

deprecated

use (++).

valstyled_unit :style ->``(unit,Stdlib.Format.formatter, unit)`` format ->``unitt

deprecated

use styled s (any fmt) instead

Naming conventions

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

Module Fmt

Contents

Not using DkSDK?

Standard outputs

Formatting

Formatters

Separators

Sequencing

Boxes

Brackets

Records

Stdlib types

Magnitudes

Binary data

Words, paragraphs, text and lines

HCI fragments

Conditional UTF-8 formatting

Styled formatting

Style rendering control

Converting with string value converters

Deprecated

Naming conventions

More from the DkSDK Book