Module CCFormat

Helpers for Format

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

Documentation for the standard Format module

include module type of struct include Stdlib.Format 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_bytes : formatter -> bytes -> unit
val print_bytes : bytes -> 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 std_formatter : formatter
val err_formatter : formatter
val formatter_of_buffer : Stdlib.Buffer.t -> formatter
val stdbuf : Stdlib.Buffer.t
val str_formatter : formatter
val flush_str_formatter : unit -> string
val make_formatter : ( string -> int -> int -> unit ) -> ( unit -> unit ) -> formatter
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 pp_print_either : left:( formatter -> 'a -> unit ) -> right:( formatter -> 'b -> unit ) -> formatter -> ( 'a, 'b ) Stdlib.Either.t -> unit
val printf : ( 'a, formatter, unit ) Stdlib.format -> 'a
val eprintf : ( 'a, formatter, unit ) 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 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".

In the tuple printers, the sep argument is only available.

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:

Example:

set_color_default true;;

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

status: unstable

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.

val styling : ANSI_codes.style list -> 'a printer -> 'a printer

styling st p is the same printer as p, except it locally sets the style st.

Example:

open CCFormat;
set_color_default true;
sprintf
  "what is your %a? %a! No, %a! Ahhhhhhh@."
  (styling [`FG `White; `Bold] string) "favorite color"
  (styling [`FG `Blue] string) "blue"
  (styling [`FG `Red] string) "red"

Available only on OCaml >= 4.08.

  • since 3.7
val with_styling : ANSI_codes.style list -> t -> ( unit -> 'a ) -> 'a

with_styling style fmt f sets the given style on fmt, calls f(), then restores the previous style. It is useful in imperative-style printers (a sequence of "print a; print b; …").

Available only on OCaml >= 4.08.

  • since 3.7

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