package batteries

  1. Overview
  2. Docs
package batteries
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module BatFormat

Pretty printing.

This module implements a pretty-printing facility to format text within ``pretty-printing boxes''. The pretty-printer breaks lines at specified break hints, and indents lines according to the box structure.

For a gentle introduction to the basics of pretty-printing using Format, read http://caml.inria.fr/resources/doc/guides/format.html.

You may consider this module as providing an extension to the printf facility to provide automatic line breaking. The addition of pretty-printing annotations to your regular printf formats gives you fancy indentation and line breaks. Pretty-printing annotations are described below in the documentation of the function Format.fprintf.

You may also use the explicit box management and printing functions provided by this module. This style is more basic but more verbose than the fprintf concise formats.

For instance, the sequence open_box 0; print_string "x ="; print_space (); print_int 1; close_box (); print_newline () that prints x = 1 within a pretty-printing box, can be abbreviated as printf "@[%s@ %i@]@." "x =" 1, or even shorter printf "@[x =@ %i@]@." 1.

Rule of thumb for casual users of this library:

  • use simple boxes (as obtained by open_box 0);
  • use simple break hints (as obtained by print_cut () that outputs a simple break hint, or by print_space () that outputs a space indicating a break hint);
  • once a box is opened, display its material with basic printing functions (e. g. print_int and print_string);
  • when the material for a box has been printed, call close_box () to close the box;
  • at the end of your routine, flush the pretty-printer to display all the remaining material, e.g. evaluate print_newline ().

The behaviour of pretty-printing commands is unspecified if there is no opened pretty-printing box. Each box opened via one of the open_ functions below must be closed using close_box for proper formatting. Otherwise, some of the material printed in the boxes may not be output, or may be formatted incorrectly.

In case of interactive use, the system closes all opened boxes and flushes all pending text (as with the print_newline function) after each phrase. Each phrase is therefore executed in the initial state of the pretty-printer.

Warning: the material output by the following functions is delayed in the pretty-printer queue in order to compute the proper line breaking. Hence, you should not mix calls to the printing functions of the basic I/O system with calls to the functions of this module: this could result in some strange output seemingly unrelated with the evaluation order of printing commands.

  • author Pierre Weis (Base module)
  • author David Teller
Boxes
val open_box : int -> unit
val close_box : unit -> unit
Formatting functions
val print_string : string -> unit
val print_as : int -> string -> unit
val print_int : int -> unit
val print_float : float -> unit
val print_char : char -> unit
val print_bool : bool -> unit
Break hints
val print_space : unit -> unit
val print_cut : unit -> unit
val print_break : int -> int -> unit
val print_flush : unit -> unit
val print_newline : unit -> unit
val force_newline : unit -> unit
val print_if_newline : unit -> unit
Margin
val set_margin : int -> unit
val get_margin : unit -> int
Maximum indentation limit
val set_max_indent : int -> unit
val get_max_indent : unit -> int
Formatting depth: maximum number of boxes allowed before ellipsis
val set_max_boxes : int -> unit
val get_max_boxes : unit -> int
val over_max_boxes : unit -> bool
Advanced formatting
val open_hbox : unit -> unit
val open_vbox : int -> unit
val open_hvbox : int -> unit
val open_hovbox : int -> unit
Tabulations
val open_tbox : unit -> unit
val close_tbox : unit -> unit
val print_tbreak : int -> int -> unit
val set_tab : unit -> unit
val print_tab : unit -> unit
Ellipsis
val set_ellipsis_text : string -> unit
val 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 pretty-printing. 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.

val open_tag : tag -> unit
val close_tag : unit -> unit

open_tag t opens the tag named t; the print_open_tag function of the formatter is called with t as argument; the tag marker mark_open_tag t will be flushed into the output device of the formatter.

val set_tags : bool -> unit
val set_print_tags : bool -> unit

set_tags b turns on or off the treatment of tags (default is off).

val set_mark_tags : bool -> unit
val get_print_tags : unit -> bool

set_print_tags b turns on or off the printing of tags, while set_mark_tags b turns on or off the output of tag markers.

val get_mark_tags : unit -> bool
Redirecting the standard formatter output
val set_formatter_output : 'a BatIO.output -> unit
val set_formatter_output_functions : (string -> int -> int -> unit) -> (unit -> unit) -> unit
val get_formatter_output_functions : unit -> (string -> int -> int -> unit) * (unit -> unit)
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!

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)
Changing the meaning of printing semantics tags
type formatter_tag_functions = {
  1. mark_open_tag : tag -> string;
  2. mark_close_tag : tag -> string;
  3. print_open_tag : tag -> unit;
  4. print_close_tag : tag -> unit;
}
val set_formatter_tag_functions : formatter_tag_functions -> unit

set_formatter_tag_functions tag_funs changes the meaning of opening and closing tags to use the functions in tag_funs.

When opening a tag name t, the string t is passed to the opening tag marking function (the mark_open_tag field of the record tag_funs), that must return the opening tag marker for that name. When the next call to close_tag () happens, the tag name t is sent back to the closing tag marking function (the mark_close_tag field of record tag_funs), that must return a closing tag marker for that name.

The print_ field of the record contains the functions that are called at tag opening and tag closing time, to output regular material in the pretty-printer queue.

val get_formatter_tag_functions : unit -> formatter_tag_functions
Multiple formatted output
type formatter = Format.formatter
val std_formatter : formatter
val err_formatter : formatter
val formatter_of_output : _ BatIO.output -> formatter
val formatter_of_buffer : Buffer.t -> formatter
val stdbuf : Buffer.t
val str_formatter : formatter
val flush_str_formatter : unit -> string
val make_formatter : (string -> int -> int -> unit) -> (unit -> unit) -> formatter
Basic functions to use with formatters
val pp_open_hbox : formatter -> unit -> unit
val pp_open_vbox : formatter -> int -> unit
val pp_open_hvbox : formatter -> int -> unit
val pp_open_hovbox : formatter -> int -> unit
val pp_open_box : formatter -> int -> unit
val pp_close_box : formatter -> unit -> unit
val pp_open_tag : formatter -> string -> unit
val pp_close_tag : formatter -> unit -> unit
val pp_print_string : formatter -> string -> unit
val pp_print_as : formatter -> int -> string -> unit
val pp_print_int : formatter -> int -> unit
val pp_print_float : formatter -> float -> unit
val pp_print_char : formatter -> char -> unit
val pp_print_bool : formatter -> bool -> unit
val pp_print_break : formatter -> int -> int -> unit
val pp_print_cut : formatter -> unit -> unit
val pp_print_space : formatter -> unit -> unit
val pp_force_newline : formatter -> unit -> unit
val pp_print_flush : formatter -> unit -> unit
val pp_print_newline : formatter -> unit -> unit
val pp_print_if_newline : formatter -> unit -> unit
val pp_open_tbox : formatter -> unit -> unit
val pp_close_tbox : formatter -> unit -> unit
val pp_print_tbreak : formatter -> int -> int -> unit
val pp_set_tab : formatter -> unit -> unit
val pp_print_tab : formatter -> unit -> unit
val pp_set_tags : formatter -> bool -> unit
val pp_set_print_tags : formatter -> bool -> unit
val pp_set_mark_tags : formatter -> bool -> unit
val pp_get_print_tags : formatter -> unit -> bool
val pp_get_mark_tags : formatter -> unit -> bool
val pp_set_margin : formatter -> int -> unit
val pp_get_margin : formatter -> unit -> int
val pp_set_max_indent : formatter -> int -> unit
val pp_get_max_indent : formatter -> unit -> int
val pp_set_max_boxes : formatter -> int -> unit
val pp_get_max_boxes : formatter -> unit -> int
val pp_over_max_boxes : formatter -> unit -> bool
val pp_set_ellipsis_text : formatter -> string -> unit
val pp_get_ellipsis_text : formatter -> unit -> string
val pp_set_formatter_output_functions : formatter -> (string -> int -> int -> unit) -> (unit -> unit) -> unit
val pp_get_formatter_output_functions : formatter -> unit -> (string -> int -> int -> unit) * (unit -> 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_set_formatter_tag_functions : formatter -> formatter_tag_functions -> unit
val pp_get_formatter_tag_functions : formatter -> unit -> formatter_tag_functions
val pp_print_list : ?pp_sep:(formatter -> unit -> unit) -> (formatter -> 'a -> unit) -> formatter -> 'a list -> unit

pp_print_list ?pp_sep pp_v ppf l prints the list l. pp_v is used on the elements of l and each element is separated by a call to pp_sep (defaults to pp_print_cut). Does nothing on empty lists.

  • since 4.02.0
val pp_print_text : formatter -> string -> unit

pp_print_text ppf s prints s with spaces and newlines respectively printed with pp_print_space and pp_force_newline.

  • since 4.02.0
printf like functions for pretty-printing.
val fprintf : formatter -> ('a, formatter, unit) format -> '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 as with print_cut ().
  • @ : output a space, as with print_space ().
  • @\n: force a newline, as with force_newline ().
  • @;: output a 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 space.
  • @?: flush the pretty printer as with print_flush (). This is equivalent to the conversion %!.
  • @.: 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 is equivalent to print_as 0 arg. 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.
  • @@: print a plain @ 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.

val printf : ('a, formatter, unit) format -> 'a
val eprintf : ('a, formatter, unit) format -> 'a
val sprintf : ('a, unit, string) format -> 'a
val asprintf : ('a, formatter, unit, string) format4 -> 'a
val ifprintf : formatter -> ('a, formatter, unit) format -> 'a

Formatted output functions with continuations.

val kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit, 'a) format4 -> 'b
val ikfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit, 'a) format4 -> 'b
val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b
Deprecated
val bprintf : Buffer.t -> ('a, formatter, unit) format -> 'a
val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b
Basic functions to use with formatters
val pp_set_formatter_output : formatter -> _ BatIO.output -> unit
Deprecated
val set_formatter_out_channel : _ BatIO.output -> unit
val formatter_of_out_channel : _ BatIO.output -> formatter
val pp_set_formatter_out_channel : formatter -> _ BatIO.output -> unit