Module `Merlin_utils.Format_doc`

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 = Merlin_utils.Format_doc.Doc.t

type t = Merlin_utils.Format_doc.doc

type formatter

type 'a printer = Merlin_utils.Format_doc.formatter -> 'a -> unit

val formatter : 
  Merlin_utils.Format_doc.doc Stdlib.ref ->
  Merlin_utils.Format_doc.formatter

formatter rdoc creates a formatter that updates the rdoc reference

type 'a format_printer = Stdlib.Format.formatter -> 'a -> unit

Translate a Format_doc printer to a Format one.

val compat : 
  'a Merlin_utils.Format_doc.printer ->
  'a Merlin_utils.Format_doc.format_printer

val compat1 : 
  ('p1 -> 'a Merlin_utils.Format_doc.printer) ->
  'p1 ->
  'a Merlin_utils.Format_doc.format_printer

val compat2 : 
  ('p1 -> 'p2 -> 'a Merlin_utils.Format_doc.printer) ->
  'p1 ->
  'p2 ->
  'a Merlin_utils.Format_doc.format_printer

val deprecated_printer : 
  (Stdlib.Format.formatter -> unit) ->
  Merlin_utils.Format_doc.formatter ->
  unit

If necessary, embbed a Format printer inside a formatting instruction stream. This breaks every guarantees provided by Format_doc.

val deprecated : 
  'a Merlin_utils.Format_doc.format_printer ->
  'a Merlin_utils.Format_doc.printer

val deprecated1 : 
  ('p1 -> 'a Merlin_utils.Format_doc.format_printer) ->
  'p1 ->
  'a Merlin_utils.Format_doc.printer

Format string interpreters

val fprintf : 
  Merlin_utils.Format_doc.formatter ->
  ('a, Merlin_utils.Format_doc.formatter, unit) Stdlib.format ->
  'a

val kfprintf : 
  (Merlin_utils.Format_doc.formatter -> 'a) ->
  Merlin_utils.Format_doc.formatter ->
  ('b, Merlin_utils.Format_doc.formatter, unit, 'a) Stdlib.format4 ->
  'b

val asprintf : 
  ('a, Merlin_utils.Format_doc.formatter, unit, string) Stdlib.format4 ->
  'a

val kasprintf : 
  (string -> 'a) ->
  ('b, Merlin_utils.Format_doc.formatter, unit, 'a) Stdlib.format4 ->
  'b

val dprintf : 
  ('a,
    Merlin_utils.Format_doc.formatter,
    unit,
    Merlin_utils.Format_doc.formatter ->
    unit)
    Stdlib.format4 ->
  'a

val kdprintf : 
  ((Merlin_utils.Format_doc.formatter -> unit) -> 'a) ->
  ('b, Merlin_utils.Format_doc.formatter, unit, 'a) Stdlib.format4 ->
  'b

val doc_printf : 
  ('a, Merlin_utils.Format_doc.formatter, unit, Merlin_utils.Format_doc.doc)
    Stdlib.format4 ->
  'a

doc_printf and kdoc_printf creates a document directly

val kdoc_printf : 
  (Merlin_utils.Format_doc.doc -> 'r) ->
  ('a, Merlin_utils.Format_doc.formatter, unit, 'r) Stdlib.format4 ->
  'a

Compatibility with `Doc`

val doc_printer : 
  'a Merlin_utils.Format_doc.printer ->
  'a Merlin_utils.Format_doc.Doc.printer

val pp_doc : Merlin_utils.Format_doc.doc Merlin_utils.Format_doc.printer

Source compatibility with Format

String printers

val pp_print_string : string Merlin_utils.Format_doc.printer

val pp_print_substring : 
  pos:int ->
  len:int ->
  string Merlin_utils.Format_doc.printer

val pp_print_text : string Merlin_utils.Format_doc.printer

val pp_print_bytes : bytes Merlin_utils.Format_doc.printer

val pp_print_as : Merlin_utils.Format_doc.formatter -> int -> string -> unit

val pp_print_substring_as : 
  pos:int ->
  len:int ->
  Merlin_utils.Format_doc.formatter ->
  int ->
  string ->
  unit

Primitive type printers

val pp_print_char : char Merlin_utils.Format_doc.printer

val pp_print_int : int Merlin_utils.Format_doc.printer

val pp_print_float : float Merlin_utils.Format_doc.printer

val pp_print_bool : bool Merlin_utils.Format_doc.printer

val pp_print_nothing : unit Merlin_utils.Format_doc.printer

Printer combinators

val pp_print_iter : 
  ?pp_sep:unit Merlin_utils.Format_doc.printer ->
  (('a -> unit) -> 'b -> unit) ->
  'a Merlin_utils.Format_doc.printer ->
  'b Merlin_utils.Format_doc.printer

val pp_print_list : 
  ?pp_sep:unit Merlin_utils.Format_doc.printer ->
  'a Merlin_utils.Format_doc.printer ->
  'a list Merlin_utils.Format_doc.printer

val pp_print_array : 
  ?pp_sep:unit Merlin_utils.Format_doc.printer ->
  'a Merlin_utils.Format_doc.printer ->
  'a array Merlin_utils.Format_doc.printer

val pp_print_seq : 
  ?pp_sep:unit Merlin_utils.Format_doc.printer ->
  'a Merlin_utils.Format_doc.printer ->
  'a Stdlib.Seq.t Merlin_utils.Format_doc.printer

val pp_print_option : 
  ?none:unit Merlin_utils.Format_doc.printer ->
  'a Merlin_utils.Format_doc.printer ->
  'a option Merlin_utils.Format_doc.printer

val pp_print_result : 
  ok:'a Merlin_utils.Format_doc.printer ->
  error:'e Merlin_utils.Format_doc.printer ->
  ('a, 'e) Stdlib.result Merlin_utils.Format_doc.printer

val pp_print_either : 
  left:'a Merlin_utils.Format_doc.printer ->
  right:'b Merlin_utils.Format_doc.printer ->
  ('a, 'b) Stdlib.Either.t Merlin_utils.Format_doc.printer

Boxes and tags

val pp_open_stag : Stdlib.Format.stag Merlin_utils.Format_doc.printer

val pp_close_stag : unit Merlin_utils.Format_doc.printer

val pp_open_box : int Merlin_utils.Format_doc.printer

val pp_close_box : unit Merlin_utils.Format_doc.printer

Break hints

val pp_print_space : unit Merlin_utils.Format_doc.printer

val pp_print_cut : unit Merlin_utils.Format_doc.printer

val pp_print_break : Merlin_utils.Format_doc.formatter -> int -> int -> unit

val pp_print_custom_break : 
  Merlin_utils.Format_doc.formatter ->
  fits:((string * int * string) as 'c) ->
  breaks:'c ->
  unit

Tabulations

val pp_open_tbox : unit Merlin_utils.Format_doc.printer

val pp_close_tbox : unit Merlin_utils.Format_doc.printer

val pp_set_tab : unit Merlin_utils.Format_doc.printer

val pp_print_tab : unit Merlin_utils.Format_doc.printer

val pp_print_tbreak : Merlin_utils.Format_doc.formatter -> int -> int -> unit

Newlines and flushing

val pp_print_if_newline : unit Merlin_utils.Format_doc.printer

val pp_force_newline : unit Merlin_utils.Format_doc.printer

val pp_print_flush : unit Merlin_utils.Format_doc.printer

val pp_print_newline : unit Merlin_utils.Format_doc.printer

Compiler specific functions

Separators

val comma : unit Merlin_utils.Format_doc.printer

val semicolon : unit Merlin_utils.Format_doc.printer

Compiler output

val pp_two_columns : 
  ?sep:string ->
  ?max_lines:int ->
  Merlin_utils.Format_doc.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

Module Merlin_utils.Format_doc