OCaml compiler library : Format_doc

# Module Format_doc

    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, embbed a `Format` printer inside a formatting instruction stream. This breaks every guarantees provided by `Format_doc`.

    val deprecated : 'a format_printer -> 'a printer

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

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

`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