Module CCFormat

Helpers for Format

since
0.8
type 'a iter = ('a -> unit) -> unit

Documentation for the standard Format module

include module type of sig ... end
type formatter = Stdlib__format.formatter
val pp_open_box : formatter -> int -> unit
val open_box : int -> unit
val pp_close_box : formatter -> unit -> unit
val close_box : unit -> unit
val pp_open_hbox : formatter -> unit -> unit
val open_hbox : unit -> unit
val pp_open_vbox : formatter -> int -> unit
val open_vbox : int -> unit
val pp_open_hvbox : formatter -> int -> unit
val open_hvbox : int -> unit
val pp_open_hovbox : formatter -> int -> unit
val open_hovbox : int -> unit
val pp_print_string : formatter -> string -> unit
val print_string : string -> unit
val pp_print_as : formatter -> int -> string -> unit
val print_as : int -> string -> unit
val pp_print_int : formatter -> int -> unit
val print_int : int -> unit
val pp_print_float : formatter -> float -> unit
val print_float : float -> unit
val pp_print_char : formatter -> char -> unit
val print_char : char -> unit
val pp_print_bool : formatter -> bool -> unit
val print_bool : bool -> unit
val pp_print_space : formatter -> unit -> unit
val print_space : unit -> unit
val pp_print_cut : formatter -> unit -> unit
val print_cut : unit -> unit
val pp_print_break : formatter -> int -> int -> unit
val print_break : int -> int -> unit
val pp_print_custom_break : formatter -> fits:(string * int * string) -> breaks:(string * int * string) -> unit
val pp_force_newline : formatter -> unit -> unit
val force_newline : unit -> unit
val pp_print_if_newline : formatter -> unit -> unit
val print_if_newline : unit -> unit
val pp_print_flush : formatter -> unit -> unit
val print_flush : unit -> unit
val pp_print_newline : formatter -> unit -> unit
val print_newline : unit -> unit
val pp_set_margin : formatter -> int -> unit
val set_margin : int -> unit
val pp_get_margin : formatter -> unit -> int
val get_margin : unit -> int
val pp_set_max_indent : formatter -> int -> unit
val set_max_indent : int -> unit
val pp_get_max_indent : formatter -> unit -> int
val get_max_indent : unit -> int
type geometry = Stdlib__format.geometry = {
max_indent : int;
margin : int;
}
val check_geometry : geometry -> bool
val pp_set_geometry : formatter -> max_indent:int -> margin:int -> unit
val set_geometry : max_indent:int -> margin:int -> unit
val pp_safe_set_geometry : formatter -> max_indent:int -> margin:int -> unit
val safe_set_geometry : max_indent:int -> margin:int -> unit
val pp_update_geometry : formatter -> (geometry -> geometry) -> unit
val update_geometry : (geometry -> geometry) -> unit
val pp_get_geometry : formatter -> unit -> geometry
val get_geometry : unit -> geometry
val pp_set_max_boxes : formatter -> int -> unit
val set_max_boxes : int -> unit
val pp_get_max_boxes : formatter -> unit -> int
val get_max_boxes : unit -> int
val pp_over_max_boxes : formatter -> unit -> bool
val over_max_boxes : unit -> bool
val pp_open_tbox : formatter -> unit -> unit
val open_tbox : unit -> unit
val pp_close_tbox : formatter -> unit -> unit
val close_tbox : unit -> unit
val pp_set_tab : formatter -> unit -> unit
val set_tab : unit -> unit
val pp_print_tab : formatter -> unit -> unit
val print_tab : unit -> unit
val pp_print_tbreak : formatter -> int -> int -> unit
val print_tbreak : int -> int -> unit
val pp_set_ellipsis_text : formatter -> string -> unit
val set_ellipsis_text : string -> unit
val pp_get_ellipsis_text : formatter -> unit -> string
val get_ellipsis_text : unit -> string
type stag = Stdlib__format.stag = ..
type tag = string
type stag += String_tag of tag
val pp_open_stag : formatter -> stag -> unit
val open_stag : stag -> unit
val pp_close_stag : formatter -> unit -> unit
val close_stag : unit -> unit
val pp_set_tags : formatter -> bool -> unit
val set_tags : bool -> unit
val pp_set_print_tags : formatter -> bool -> unit
val set_print_tags : bool -> unit
val pp_set_mark_tags : formatter -> bool -> unit
val set_mark_tags : bool -> unit
val pp_get_print_tags : formatter -> unit -> bool
val get_print_tags : unit -> bool
val pp_get_mark_tags : formatter -> unit -> bool
val get_mark_tags : unit -> bool
val pp_set_formatter_out_channel : formatter -> Stdlib.out_channel -> unit
val set_formatter_out_channel : Stdlib.out_channel -> unit
val pp_set_formatter_output_functions : formatter -> (string -> int -> int -> unit) -> (unit -> unit) -> unit
val set_formatter_output_functions : (string -> int -> int -> unit) -> (unit -> unit) -> unit
val pp_get_formatter_output_functions : formatter -> unit -> (string -> int -> int -> unit) * (unit -> unit)
val get_formatter_output_functions : unit -> (string -> int -> int -> unit) * (unit -> unit)
type formatter_out_functions = Stdlib__format.formatter_out_functions = {
out_string : string -> int -> int -> unit;
out_flush : unit -> unit;
out_newline : unit -> unit;
out_spaces : int -> unit;
out_indent : int -> unit;
}
val pp_set_formatter_out_functions : formatter -> formatter_out_functions -> unit
val set_formatter_out_functions : formatter_out_functions -> unit
val pp_get_formatter_out_functions : formatter -> unit -> formatter_out_functions
val get_formatter_out_functions : unit -> formatter_out_functions
type formatter_stag_functions = Stdlib__format.formatter_stag_functions = {
mark_open_stag : stag -> string;
mark_close_stag : stag -> string;
print_open_stag : stag -> unit;
print_close_stag : stag -> unit;
}
val pp_set_formatter_stag_functions : formatter -> formatter_stag_functions -> unit
val set_formatter_stag_functions : formatter_stag_functions -> unit
val pp_get_formatter_stag_functions : formatter -> unit -> formatter_stag_functions
val get_formatter_stag_functions : unit -> formatter_stag_functions
val formatter_of_out_channel : Stdlib.out_channel -> formatter
val synchronized_formatter_of_out_channel : Stdlib.out_channel -> formatter Stdlib.Domain.DLS.key
val std_formatter : formatter
val get_std_formatter : unit -> formatter
val err_formatter : formatter
val get_err_formatter : unit -> formatter
val formatter_of_buffer : Stdlib.Buffer.t -> formatter
val stdbuf : Stdlib.Buffer.t
val get_stdbuf : unit -> Stdlib.Buffer.t
val str_formatter : formatter
val get_str_formatter : unit -> formatter
val flush_str_formatter : unit -> string
val make_formatter : (string -> int -> int -> unit) -> (unit -> unit) -> formatter
val make_synchronized_formatter : (string -> int -> int -> unit) -> (unit -> unit) -> formatter Stdlib.Domain.DLS.key
val formatter_of_out_functions : formatter_out_functions -> formatter
type symbolic_output_item = Stdlib__format.symbolic_output_item =
| Output_flush
| Output_newline
| Output_string of string
| Output_spaces of int
| Output_indent of int
type symbolic_output_buffer = Stdlib__format.symbolic_output_buffer
val make_symbolic_output_buffer : unit -> symbolic_output_buffer
val clear_symbolic_output_buffer : symbolic_output_buffer -> unit
val get_symbolic_output_buffer : symbolic_output_buffer -> symbolic_output_item list
val flush_symbolic_output_buffer : symbolic_output_buffer -> symbolic_output_item list
val add_symbolic_output_item : symbolic_output_buffer -> symbolic_output_item -> unit
val formatter_of_symbolic_output_buffer : symbolic_output_buffer -> formatter
val pp_print_list : ?⁠pp_sep:(formatter -> unit -> unit) -> (formatter -> 'a -> unit) -> formatter -> 'a list -> unit
val pp_print_seq : ?⁠pp_sep:(formatter -> unit -> unit) -> (formatter -> 'a -> unit) -> formatter -> 'a Stdlib.Seq.t -> unit
val pp_print_text : formatter -> string -> unit
val pp_print_option : ?⁠none:(formatter -> unit -> unit) -> (formatter -> 'a -> unit) -> formatter -> 'a option -> unit
val pp_print_result : ok:(formatter -> 'a -> unit) -> error:(formatter -> 'e -> unit) -> formatter -> ('a, 'e) Stdlib.result -> unit
val fprintf : formatter -> ('a, formatter, unit) Stdlib.format -> 'a
val printf : ('a, formatter, unit) Stdlib.format -> 'a
val eprintf : ('a, formatter, unit) Stdlib.format -> 'a
val sprintf : ('a, unit, string) Stdlib.format -> 'a
val asprintf : ('a, formatter, unit, string) Stdlib.format4 -> 'a
val dprintf : ('a, formatter, unit, formatter -> unit) Stdlib.format4 -> 'a
val ifprintf : formatter -> ('a, formatter, unit) Stdlib.format -> 'a
val kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit, 'a) Stdlib.format4 -> 'b
val kdprintf : ((formatter -> unit) -> 'a) -> ('b, formatter, unit, 'a) Stdlib.format4 -> 'b
val ikfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit, 'a) Stdlib.format4 -> 'b
val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) Stdlib.format4 -> 'b
val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) Stdlib.format4 -> 'b
val bprintf : Stdlib.Buffer.t -> ('a, formatter, unit) Stdlib.format -> 'a
val kprintf : (string -> 'a) -> ('b, unit, string, 'a) Stdlib.format4 -> 'b
val set_all_formatter_output_functions : out:(string -> int -> int -> unit) -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int -> unit) -> unit
val get_all_formatter_output_functions : unit -> (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
val pp_set_all_formatter_output_functions : formatter -> out:(string -> int -> int -> unit) -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int -> unit) -> unit
val pp_get_all_formatter_output_functions : formatter -> unit -> (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
val pp_open_tag : formatter -> tag -> unit
val open_tag : tag -> unit
val pp_close_tag : formatter -> unit -> unit
val close_tag : unit -> unit
type formatter_tag_functions = Stdlib__format.formatter_tag_functions = {
mark_open_tag : tag -> string;
mark_close_tag : tag -> string;
print_open_tag : tag -> unit;
print_close_tag : tag -> unit;
}
val pp_set_formatter_tag_functions : formatter -> formatter_tag_functions -> unit
val set_formatter_tag_functions : formatter_tag_functions -> unit
val pp_get_formatter_tag_functions : formatter -> unit -> formatter_tag_functions
val get_formatter_tag_functions : unit -> formatter_tag_functions
type t = Stdlib.Format.formatter
type -'a printer = t -> 'a -> unit

Combinators

val silent : 'a printer

Prints nothing.

val unit : unit printer

Prints "()".

val int : int printer
val string : string printer
val bool : bool printer
val float3 : float printer
val float : float printer
val exn : exn printer

Printer using Printexc.to_string.

since
3.0
val space : unit printer

Alias to pp_print_space.

since
3.2
val cut : unit printer

Alias to pp_print_cut.

since
3.2
val break : (int * int) printer

Tuple-ized printer form of pp_print_break.

since
3.2
val newline : unit printer

Force newline (see Format.pp_force_newline).

since
1.2
val substring : (string * int * int) printer

substring (s,i,len) prints the substring (s,i,len), where i is the offset in s and len the number of bytes in the substring.

raises Invalid_argument

if the triple (s,i,len) does not describe a proper substring.

since
1.2
val text : string printer

Print string, but replacing spaces with breaks and newlines with newline. See pp_print_text on recent versions of OCaml.

since
1.2
val string_lines : string printer

string_lines out s prints s with all newlines ('\n') replaced by a cut, in a vertical box. It does NOT insert breakable spaces in place of spaces, unlike text. This means an already formatted string can be displayed inside another formatter without mangling the indentation.

since
3.3
val char : char printer
since
0.14
val int32 : int32 printer
since
0.14
val int64 : int64 printer
since
0.14
val nativeint : nativeint printer
since
0.14
val flush : unit printer

Alias to Format.pp_print_flush.

since
1.2
val string_quoted : string printer

Similar to CCString.print.

since
0.14
val list : ?⁠sep:unit printer -> 'a printer -> 'a list printer
val array : ?⁠sep:unit printer -> 'a printer -> 'a array printer
val arrayi : ?⁠sep:unit printer -> (int * 'a) printer -> 'a array printer
val seq : ?⁠sep:unit printer -> 'a printer -> 'a Stdlib.Seq.t printer
val iter : ?⁠sep:unit printer -> 'a printer -> 'a iter printer
val opt : 'a printer -> 'a option printer

opt pp prints options as follows:

  • Some x will become "some foo" if pp x ---> "foo".
  • None will become "none".
val pair : ?⁠sep:unit printer -> 'a printer -> 'b printer -> ('a * 'b) printer
val triple : ?⁠sep:unit printer -> 'a printer -> 'b printer -> 'c printer -> ('a * 'b * 'c) printer
val quad : ?⁠sep:unit printer -> 'a printer -> 'b printer -> 'c printer -> 'd printer -> ('a * 'b * 'c * 'd) printer
val append : unit printer -> unit printer -> unit printer

append ppa ppb first prints ppa (), then prints ppb ().

since
3.2
val append_l : unit printer list -> unit printer

append_l pps runs the printers in pps sequentially.

since
3.2
val within : string -> string -> 'a printer -> 'a printer

within a b p wraps p inside the strings a and b. Convenient, for instances, for brackets, parenthesis, quotes, etc.

since
0.17
val map : ('a -> 'b) -> 'b printer -> 'a printer
val vbox : ?⁠i:int -> 'a printer -> 'a printer

Wrap the printer in a vertical box.

parameter i

level of indentation within the box (default 0).

since
0.16
val hvbox : ?⁠i:int -> 'a printer -> 'a printer

Wrap the printer in a horizontal/vertical box.

parameter i

level of indentation within the box (default 0).

since
0.16
val hovbox : ?⁠i:int -> 'a printer -> 'a printer

Wrap the printer in a horizontal or vertical box.

parameter i

level of indentation within the box (default 0).

since
0.16
val hbox : 'a printer -> 'a printer

Wrap the printer in an horizontal box.

since
0.16
val return : ('a, _, _, 'a) Stdlib.format4 -> unit printer

return "some_format_string" takes a argument-less format string and returns a printer actionable by (). Examples:

  • return ",@ "
  • return "@{<Red>and then@}@,"
  • return "@[<v>a@ b@]"
since
1.0
val of_to_string : ('a -> string) -> 'a printer

of_to_string f converts its input to a string using f, then prints the string.

since
1.0
val const : 'a printer -> 'a -> unit printer

const pp x is a unit printer that uses pp on x.

since
1.0
val some : 'a printer -> 'a option printer

some pp will print options as follows:

  • Some x is printed using pp on x
  • None is not printed at all
since
1.0
val const_string : string -> 'a printer

const_string s is a printer that ignores its input and always prints s.

since
3.5
val opaque : 'a printer

opaque is const_string "opaque". The exact string used is not stable.

since
3.5
val lazy_force : 'a printer -> 'a lazy_t printer

lazy_force pp out x forces x and prints the result with pp.

since
2.0
val lazy_or : ?⁠default:unit printer -> 'a printer -> 'a lazy_t printer

lazy_or ?default pp out x prints default if x is not evaluated yet, or uses pp otherwise.

since
2.0

ANSI codes

Use ANSI escape codes https://en.wikipedia.org/wiki/ANSI_escape_code to put some colors on the terminal.

This uses tags in format strings to specify the style. Current styles are the following:

  • "reset" resets style
  • "black"
  • "red"
  • "green"
  • "yellow"
  • "blue"
  • "magenta"
  • "cyan"
  • "white"
  • "bold" bold font
  • "Black" bold black
  • "Red" bold red
  • "Green" bold green
  • "Yellow" bold yellow
  • "Blue" bold blue
  • "Magenta" bold magenta
  • "Cyan" bold cyan
  • "White" bold white

Example:

set_color_default true;;

Format.printf
  "what is your @{<White>favorite color@}? @{<blue>blue@}! No, @{<red>red@}! Ahhhhhhh@.";;

status: unstable

since
0.15
val set_color_tag_handling : t -> unit

Add functions to support color tags to the given formatter.

since
0.15
val set_color_default : bool -> unit

set_color_default b enables color handling on the standard formatters (stdout, stderr) if b = true as well as on sprintf formatters; it disables the color handling if b = false.

val with_color : string -> 'a printer -> 'a printer

with_color "Blue" pp behaves like the printer pp, but with the given style.

status: unstable

since
0.16
val with_colorf : string -> t -> ('a, t, unit, unit) Stdlib.format4 -> 'a

with_colorf "Blue" out "%s %d" "yolo" 42 will behave like Format.fprintf, but wrapping the content with the given style.

status: unstable

since
0.16
val with_color_sf : string -> ('a, t, unit, string) Stdlib.format4 -> 'a

with_color_sf "Blue" out "%s %d" "yolo" 42 will behave like sprintf, but wrapping the content with the given style.

Example:

CCFormat.with_color_sf "red" "%a" CCFormat.Dump.(list int) [1;2;3] |> print_endline;;

status: unstable

since
0.21
val with_color_ksf : f:(string -> 'b) -> string -> ('a, t, unit, 'b) Stdlib.format4 -> 'a

with_color_ksf "Blue" ~f "%s %d" "yolo" 42 will behave like ksprintf, but wrapping the content with the given style.

Example: the following with raise Failure with a colored message

CCFormat.with_color_ksf "red" ~f:failwith "%a" CCFormat.Dump.(list int) [1;2;3];;
since
1.2
module ANSI_codes : sig ... end

ANSI escape codes. This contains lower level functions for them.

IO

val output : t -> 'a printer -> 'a -> unit
val to_string : 'a printer -> 'a -> string
val of_chan : Stdlib.out_channel -> t

Alias to Format.formatter_of_out_channel.

since
1.2
val with_out_chan : Stdlib.out_channel -> (t -> 'a) -> 'a

with_out_chan oc f turns oc into a formatter fmt, and call f fmt. Behaves like f fmt from then on, but whether the call to f fails or returns, fmt is flushed before the call terminates.

since
1.2
val stdout : t
val stderr : t
val tee : t -> t -> t

tee a b makes a new formatter that writes in both a and b.

since
1.0
val sprintf : ('a, t, unit, string) Stdlib.format4 -> 'a

Print into a string any format string that would usually be compatible with fprintf. Like Format.asprintf.

val sprintf_no_color : ('a, t, unit, string) Stdlib.format4 -> 'a

Like sprintf but never prints colors.

since
0.16
val sprintf_dyn_color : colors:bool -> ('a, t, unit, string) Stdlib.format4 -> 'a

Like sprintf but enable/disable colors depending on colors.

Example:

(* with colors *)
CCFormat.sprintf_dyn_color ~colors:true "@{<Red>%a@}"
  CCFormat.Dump.(list int) [1;2;3] |> print_endline;;

(* without colors *)
CCFormat.sprintf_dyn_color ~colors:false "@{<Red>%a@}"
  CCFormat.Dump.(list int) [1;2;3] |> print_endline;;
since
0.21
val fprintf : t -> ('a, t, unit) Stdlib.format -> 'a

Alias to Format.fprintf.

since
0.14
val fprintf_dyn_color : colors:bool -> t -> ('a, t, unit) Stdlib.format -> 'a

Like fprintf but enable/disable colors depending on colors.

since
0.21
val ksprintf : ?⁠margin:int -> f:(string -> 'b) -> ('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a

ksprintf fmt ~f formats using fmt, in a way similar to sprintf, and then calls f on the resulting string.

parameter margin

set margin (since 2.1)

since
0.14
val to_file : string -> ('a, t, unit, unit) Stdlib.format4 -> 'a

Print to the given file.

Dump

Print structures as OCaml values, so that they can be parsed back by OCaml (typically, in the toplevel, for debugging).

Example:

Format.printf "%a@." CCFormat.Dump.(list int) CCList.(1 -- 200);;

Format.printf "%a@." CCFormat.Dump.(array (list (pair int bool)))
  [| [1, true; 2, false]; []; [42, false] |];;
since
0.21
module Dump : sig ... end
module Infix : sig ... end
include module type of Infix
val (++) : unit printer -> unit printer -> unit printer

Alias to append.

since
3.2