Module Format

module Format: sig .. end

---

Boxes

let open_box: int => unit;

let close_box: unit => unit;

Formatting functions

let print_string: string => unit;

let print_as: (int, string) => unit;

let print_int: int => unit;

let print_float: float => unit;

let print_char: char => unit;

let print_bool: bool => unit;

Break hints

let print_space: unit => unit;

let print_cut: unit => unit;

let print_break: (int, int) => unit;

let print_flush: unit => unit;

let print_newline: unit => unit;

let force_newline: unit => unit;

let print_if_newline: unit => unit;

Margin

let set_margin: int => unit;

let get_margin: unit => int;

Maximum indentation limit

let set_max_indent: int => unit;

let get_max_indent: unit => int;

Formatting depth: maximum number of boxes allowed before ellipsis

let set_max_boxes: int => unit;

let get_max_boxes: unit => int;

let over_max_boxes: unit => bool;

Advanced formatting

let open_hbox: unit => unit;

let open_vbox: int => unit;

let open_hvbox: int => unit;

let open_hovbox: int => unit;

Tabulations

let open_tbox: unit => unit;

let close_tbox: unit => unit;

let print_tbreak: (int, int) => unit;

let set_tab: unit => unit;

let print_tab: unit => unit;

Ellipsis

let set_ellipsis_text: string => unit;

let get_ellipsis_text: unit => string;

Semantics Tags

type tag = string;

Semantics tags (or simply tags) are used to decorate printed entities for user's defined purposes, e.g. setting font and giving size indications for a display device, or marking delimitation of semantics entities (e.g. HTML or TeX elements or terminal escape sequences).

By default, those tags do not influence line breaking calculation: the tag 'markers' are not considered as part of the printing material that drives line breaking (in other words, the length of those strings is considered as zero for line breaking).

Thus, tag handling is in some sense transparent to pretty-printing and does not interfere with usual indentation. Hence, a single pretty printing routine can output both simple 'verbatim' material or richer decorated output depending on the treatment of tags. By default, tags are not active, hence the output is not decorated with tag information. Once set_tags is set to true, the pretty printer engine honours tags and decorates the output accordingly.

When a tag has been opened (or closed), it is both and successively 'printed' and 'marked'. Printing a tag means calling a formatter specific function with the name of the tag as argument: that 'tag printing' function can then print any regular material to the formatter (so that this material is enqueued as usual in the formatter queue for further line-breaking computation). Marking a tag means to output an arbitrary string (the 'tag marker'), directly into the output device of the formatter. Hence, the formatter specific 'tag marking' function must return the tag marker string associated to its tag argument. Being flushed directly into the output device of the formatter, tag marker strings are not considered as part of the printing material that drives line breaking (in other words, the length of the strings corresponding to tag markers is considered as zero for line breaking). In addition, advanced users may take advantage of the specificity of tag markers to be precisely output when the pretty printer has already decided where to break the lines, and precisely when the queue is flushed into the output device.

In the spirit of HTML tags, the default tag marking functions output tags enclosed in "<" and ">": hence, the opening marker of tag t is "<t>" and the closing marker "</t>".

Default tag printing functions just do nothing.

Tag marking and tag printing functions are user definable and can be set by calling set_formatter_tag_functions.

let open_tag: tag => unit;

let close_tag: unit => unit;

let set_tags: bool => unit;

let set_print_tags: bool => unit;

let set_mark_tags: bool => unit;

let get_print_tags: unit => bool;

let get_mark_tags: unit => bool;

Redirecting the standard formatter output

let set_formatter_out_channel: Pervasives.out_channel => unit;

let set_formatter_output_functions:
  ((string, int, int) => unit, unit => unit) => unit;

let get_formatter_output_functions:
  unit => ((string, int, int) => unit, unit => unit);

Changing the meaning of standard formatter pretty printing

Changing the meaning of standard formatter pretty printing

The Format module is versatile enough to let you completely redefine the meaning of pretty printing: you may provide your own functions to define how to handle indentation, line breaking, and even printing of all the characters that have to be printed!

type formatter_out_functions = {

	out_string : string -> int -> int -> unit;
	out_flush : unit -> unit;
	out_newline : unit -> unit;
	out_spaces : int -> unit;

}

let set_formatter_out_functions: formatter_out_functions => unit;

let get_formatter_out_functions: unit => formatter_out_functions;

Changing the meaning of printing semantics tags

type formatter_tag_functions = {

	mark_open_tag : tag -> string;
	mark_close_tag : tag -> string;
	print_open_tag : tag -> unit;
	print_close_tag : tag -> unit;

}

let set_formatter_tag_functions: formatter_tag_functions => unit;

let get_formatter_tag_functions: unit => formatter_tag_functions;

Multiple formatted output

type formatter;

let formatter_of_out_channel: Pervasives.out_channel => formatter;

let std_formatter: formatter;

let err_formatter: formatter;

let formatter_of_buffer: Buffer.t => formatter;

let stdbuf: Buffer.t;

let str_formatter: formatter;

let flush_str_formatter: unit => string;

let make_formatter: ((string, int, int) => unit, unit => unit) => formatter;

Basic functions to use with formatters

let pp_open_hbox: (formatter, unit) => unit;

let pp_open_vbox: (formatter, int) => unit;

let pp_open_hvbox: (formatter, int) => unit;

let pp_open_hovbox: (formatter, int) => unit;

let pp_open_box: (formatter, int) => unit;

let pp_close_box: (formatter, unit) => unit;

let pp_open_tag: (formatter, string) => unit;

let pp_close_tag: (formatter, unit) => unit;

let pp_print_string: (formatter, string) => unit;

let pp_print_as: (formatter, int, string) => unit;

let pp_print_int: (formatter, int) => unit;

let pp_print_float: (formatter, float) => unit;

let pp_print_char: (formatter, char) => unit;

let pp_print_bool: (formatter, bool) => unit;

let pp_print_break: (formatter, int, int) => unit;

let pp_print_cut: (formatter, unit) => unit;

let pp_print_space: (formatter, unit) => unit;

let pp_force_newline: (formatter, unit) => unit;

let pp_print_flush: (formatter, unit) => unit;

let pp_print_newline: (formatter, unit) => unit;

let pp_print_if_newline: (formatter, unit) => unit;

let pp_open_tbox: (formatter, unit) => unit;

let pp_close_tbox: (formatter, unit) => unit;

let pp_print_tbreak: (formatter, int, int) => unit;

let pp_set_tab: (formatter, unit) => unit;

let pp_print_tab: (formatter, unit) => unit;

let pp_set_tags: (formatter, bool) => unit;

let pp_set_print_tags: (formatter, bool) => unit;

let pp_set_mark_tags: (formatter, bool) => unit;

let pp_get_print_tags: (formatter, unit) => bool;

let pp_get_mark_tags: (formatter, unit) => bool;

let pp_set_margin: (formatter, int) => unit;

let pp_get_margin: (formatter, unit) => int;

let pp_set_max_indent: (formatter, int) => unit;

let pp_get_max_indent: (formatter, unit) => int;

let pp_set_max_boxes: (formatter, int) => unit;

let pp_get_max_boxes: (formatter, unit) => int;

let pp_over_max_boxes: (formatter, unit) => bool;

let pp_set_ellipsis_text: (formatter, string) => unit;

let pp_get_ellipsis_text: (formatter, unit) => string;

let pp_set_formatter_out_channel: (formatter, Pervasives.out_channel) => unit;

let pp_set_formatter_output_functions:
  (formatter, (string, int, int) => unit, unit => unit) => unit;

let pp_get_formatter_output_functions:
  (formatter, unit) => ((string, int, int) => unit, unit => unit);

let pp_set_formatter_tag_functions:
  (formatter, formatter_tag_functions) => unit;

let pp_get_formatter_tag_functions:
  (formatter, unit) => formatter_tag_functions;

let pp_set_formatter_out_functions:
  (formatter, formatter_out_functions) => unit;

let pp_get_formatter_out_functions:
  (formatter, unit) => formatter_out_functions;

Convenience formatting functions.

let pp_print_list:
  (
    ~pp_sep: (formatter, unit) => unit=?,
    (formatter, 'a) => unit,
    formatter,
    list('a)
  ) =>
  unit;

let pp_print_text: (formatter, string) => unit;

printf like functions for pretty-printing.

let fprintf: (formatter, Pervasives.format('a, formatter, unit)) => 'a;

fprintf ff fmt arg1 ... argN formats the arguments arg1 to argN according to the format string fmt, and outputs the resulting string on the formatter ff.

The format fmt is a character string which contains three types of objects: plain characters and conversion specifications as specified in the Printf module, and pretty-printing indications specific to the Format module.

The pretty-printing indication characters are introduced by a @ character, and their meanings are:

• @[: open a pretty-printing box. The type and offset of the box may be optionally specified with the following syntax: the < character, followed by an optional box type indication, then an optional integer offset, and the closing > character. Box type is one of h, v, hv, b, or hov, which stand respectively for an horizontal box, a vertical box, an 'horizontal-vertical' box, or an 'horizontal or vertical' box (b standing for an 'horizontal or vertical' box demonstrating indentation and hov standing for a regular'horizontal or vertical' box). For instance, @[<hov 2> opens an 'horizontal or vertical' box with indentation 2 as obtained with open_hovbox 2. For more details about boxes, see the various box opening functions open_*box.
• @]: close the most recently opened pretty-printing box.
• @,: output a good break hint, as with print_cut ().
• @ : output a good break space, as with print_space ().
• @;: output a fully specified good break as with print_break. The nspaces and offset parameters of the break may be optionally specified with the following syntax: the < character, followed by an integer nspaces value, then an integer offset, and a closing > character. If no parameters are provided, the good break defaults to a good break space.
• @.: flush the pretty printer and output a new line, as with print_newline ().
• @<n>: print the following item as if it were of length n. Hence, printf "@<0>%s" arg prints arg as a zero length string. If @<n> is not followed by a conversion specification, then the following character of the format is printed as if it were of length n.
• @{: open a tag. The name of the tag may be optionally specified with the following syntax: the < character, followed by an optional string specification, and the closing > character. The string specification is any character string that does not contain the closing character '>'. If omitted, the tag name defaults to the empty string. For more details about tags, see the functions open_tag and close_tag.
• @}: close the most recently opened tag.
• @?: flush the pretty printer as with print_flush (). This is equivalent to the conversion %!.
• @\n: force a newline, as with force_newline ().
• @@: print a single @ character.

Example: printf "@[%s@ %d@]@." "x =" 1 is equivalent to open_box (); print_string "x ="; print_space (); print_int 1; close_box (); print_newline (). It prints x = 1 within a pretty-printing box.

Note: If you need to prevent the interpretation of a @ character as a pretty-printing indication, you can also escape it with a % character.

let printf: Pervasives.format('a, formatter, unit) => 'a;

let eprintf: Pervasives.format('a, formatter, unit) => 'a;

let sprintf: Pervasives.format('a, unit, string) => 'a;

let asprintf: Pervasives.format4('a, formatter, unit, string) => 'a;

let ifprintf: (formatter, Pervasives.format('a, formatter, unit)) => 'a;

Formatted output functions with continuations.

let kfprintf:
  (formatter => 'a, formatter, Pervasives.format4('b, formatter, unit, 'a)) =>
  'b;

let ikfprintf:
  (formatter => 'a, formatter, Pervasives.format4('b, formatter, unit, 'a)) =>
  'b;

let ksprintf: (string => 'a, Pervasives.format4('b, unit, string, 'a)) => 'b;

Deprecated

let bprintf: (Buffer.t, Pervasives.format('a, formatter, unit)) => 'a;

let kprintf: (string => 'a, Pervasives.format4('b, unit, string, 'a)) => 'b;

let set_all_formatter_output_functions:
  (
    ~out: (string, int, int) => unit,
    ~flush: unit => unit,
    ~newline: unit => unit,
    ~spaces: int => unit
  ) =>
  unit;

let get_all_formatter_output_functions:
  unit => ((string, int, int) => unit, unit => unit, unit => unit, int => unit);

let pp_set_all_formatter_output_functions:
  (
    formatter,
    ~out: (string, int, int) => unit,
    ~flush: unit => unit,
    ~newline: unit => unit,
    ~spaces: int => unit
  ) =>
  unit;

let pp_get_all_formatter_output_functions:
  (formatter, unit) =>
  ((string, int, int) => unit, unit => unit, unit => unit, int => unit);