Format_doc(3)

📦
version 5.5.0 · 12 versions
, in arch rolling

✨ NAME ✨

Format_doc — composable document for the Format formatting engine.

Bestie, welcome to the Format_doc(3) page from the OCaml library — we're doing docs but make it cute. 💅

🧩 Module 🧩

Module Format_doc

📚 Documentation 📚

Module Format_doc : sig end

Composable document for the Format formatting engine.

This module introduces a pure and immutable document type which represents a sequence of formatting instructions to be printed by a formatting engine at later point. At the same time, it also provides format string interpreter which produces this document type from format string and their associated printers.

The module is designed to be source compatible with code defining format printers: replacing Format by Format_doc in your code will convert Format printers to Format_doc printers.

module Doc : sig end — definitions and immutable API for composing documents.

💞 Compatibility API 💞

The functions and types below provides source compatibility with format printers and conversion function from Format_doc printers to Format printers. The reverse direction is implemented using an escape hatch in the formatting instruction and should only be used to preserve backward compatibility.

  • type doc = Doc.t
  • type t = doc
  • type formatter
  • type 'a printer = formatter -> 'a -> unit
  • val formatter : doc ref -> formatter — formatter rdoc creates a Format_doc.formatter that updates the rdoc reference.
  • type 'a format_printer = Format.formatter -> 'a -> unit — translate a Format_doc printer to a Format one.
  • val compat : 'a printer -> 'a format_printer
  • val compat1 : ('p1 -> 'a printer) -> 'p1 -> 'a format_printer
  • val compat2 : ('p1 -> 'p2 -> 'a printer) -> 'p1 -> 'p2 -> 'a format_printer
  • val deprecated_printer : (Format.formatter -> unit) -> formatter -> unit — if necessary, embed a Format printer inside a formatting instruction stream.
  • val deprecated : 'a format_printer -> 'a printer
  • val deprecated1 : ('p1 -> 'a format_printer) -> 'p1 -> 'a printer
🚨 Warning: deprecated_printer breaks every guarantees provided by Format_doc.

🪄 Format string interpreters 🪄

  • val fprintf : formatter -> ('a, formatter, unit) format -> 'a
  • val kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit, 'a) format4 -> 'b
  • val asprintf : ('a, formatter, unit, string) format4 -> 'a
  • val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) format4 -> 'b
  • val dprintf : ('a, formatter, unit, formatter -> unit) format4 -> 'a
  • val kdprintf : ((formatter -> unit) -> 'a) -> ('b, formatter, unit, 'a) format4 -> 'b
  • val doc_printf : ('a, formatter, unit, doc) format4 -> 'a

Heads up bestie: Format_doc.doc_printf and Format_doc.kdoc_printf creates a document directly.

  • val kdoc_printf : (doc -> 'r) -> ('a, formatter, unit, 'r) format4 -> 'a

🫶 Compatibility with Format_doc.Doc 🫶

  • val doc_printer : 'a printer -> 'a Doc.printer
  • val pp_doc : doc printer

🧬 Source compatibility with Format 🧬

✨ String printers ✨

  • val pp_print_string : string printer
  • val pp_print_substring : pos:int -> len:int -> string printer
  • val pp_print_text : string printer
  • val pp_print_bytes : bytes printer
  • val pp_print_as : formatter -> int -> string -> unit
  • val pp_print_substring_as : pos:int -> len:int -> formatter -> int -> string -> unit

🔠 Primitive type printers 🔠

  • val pp_print_char : char printer
  • val pp_print_int : int printer
  • val pp_print_float : float printer
  • val pp_print_bool : bool printer
  • val pp_print_nothing : unit printer

🧰 Printer combinators 🧰

  • val pp_print_iter : ?pp_sep:unit printer -> (('a -> unit) -> 'b -> unit) -> 'a printer -> 'b printer
  • val pp_print_list : ?pp_sep:unit printer -> 'a printer -> 'a list printer
  • val pp_print_array : ?pp_sep:unit printer -> 'a printer -> 'a array printer
  • val pp_print_seq : ?pp_sep:unit printer -> 'a printer -> 'a Seq.t printer
  • val pp_print_option : ?none:unit printer -> 'a printer -> 'a option printer
  • val pp_print_result : ok:'a printer -> error:'e printer -> ('a, 'e) result printer
  • val pp_print_either : left:'a printer -> right:'b printer -> ('a, 'b) Either.t printer

📦 Boxes and tags 📦

  • val pp_open_stag : Format.stag printer
  • val pp_close_stag : unit printer
  • val pp_open_box : int printer
  • val pp_close_box : unit printer

✂️ Break hints ✂️

  • val pp_print_space : unit printer
  • val pp_print_cut : unit printer
  • val pp_print_break : formatter -> int -> int -> unit
  • val pp_print_custom_break : formatter -> fits:string * int * string -> breaks:string * int * string -> unit

📑 Tabulations 📑

  • val pp_open_tbox : unit printer
  • val pp_close_tbox : unit printer
  • val pp_set_tab : unit printer
  • val pp_print_tab : unit printer
  • val pp_print_tbreak : formatter -> int -> int -> unit

🌊 Newlines and flushing 🌊

  • val pp_print_if_newline : unit printer
  • val pp_force_newline : unit printer
  • val pp_print_flush : unit printer
  • val pp_print_newline : unit printer

🧑‍💻 Compiler specific functions 🧑‍💻

Separators

  • val comma : unit printer
  • val semicolon : unit printer

Compiler output

  • val pp_two_columns : ?sep:string -> ?max_lines:int -> formatter -> (string * string) list -> unit

pp_two_columns ?sep ?max_lines ppf l prints the lines in l as two columns separated by sep ("|" by default). max_lines can be used to indicate a maximum number of lines to print -- an ellipsis gets inserted at the middle if the input has too many lines.

Example:

pp_two_columns ~max_lines:3 Format.std_formatter [ "abc", "hello";
"def", "zzz"; "a"  , "bllbl"; "bb" , "dddddd"; ]

prints

abc | hello ...  bb  | dddddd

Big bye bestie 💖 — this page was served by OCamldoc, dated 2026-06-22, for Format_doc(3). Periodt. 👑

📦 where this page comes from