4154 lines
62 KiB
HTML
4154 lines
62 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Format</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Format</H1>
|
|
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Format - Pretty-printing.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>Module</H2>
|
|
|
|
Module Format
|
|
<A NAME="lbAD"> </A>
|
|
<H2>Documentation</H2>
|
|
|
|
<P>
|
|
Module
|
|
<B>Format</B>
|
|
|
|
<BR> :
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
Pretty-printing.
|
|
<P>
|
|
This module implements a pretty-printing facility to format values
|
|
within
|
|
<B>Format.boxes</B>
|
|
|
|
and
|
|
<B>Format.tags</B>
|
|
|
|
combined with a set of
|
|
<B>Format.fpp</B>
|
|
|
|
.
|
|
The pretty-printer splits lines at specified
|
|
<B>Format.breaks</B>
|
|
|
|
,
|
|
and indents lines according to the box structure.
|
|
Similarly,
|
|
<B>Format.tags</B>
|
|
|
|
can be used to decouple text
|
|
presentation from its contents.
|
|
<P>
|
|
This pretty-printing facility is implemented as an overlay on top of
|
|
abstract
|
|
<B>Format.formatter</B>
|
|
|
|
which provide basic output
|
|
functions.
|
|
Some formatters are predefined, notably:
|
|
<P>
|
|
-
|
|
<B>Format.std_formatter</B>
|
|
|
|
outputs to
|
|
<B>stdout</B>
|
|
|
|
<P>
|
|
<P>
|
|
-
|
|
<B>Format.err_formatter</B>
|
|
|
|
outputs to
|
|
<B>stderr</B>
|
|
|
|
<P>
|
|
Most functions in the
|
|
<B>Format</B>
|
|
|
|
module come in two variants:
|
|
a short version that operates on
|
|
<B>Format.std_formatter</B>
|
|
|
|
and the
|
|
generic version prefixed by
|
|
<B>pp_</B>
|
|
|
|
that takes a formatter
|
|
as its first argument.
|
|
<P>
|
|
More formatters can be created with
|
|
<B>Format.formatter_of_out_channel</B>
|
|
|
|
,
|
|
<B>Format.formatter_of_buffer</B>
|
|
|
|
,
|
|
<B>Format.formatter_of_symbolic_output_buffer</B>
|
|
|
|
or using
|
|
<B>Format.formatter</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Introduction</H3>
|
|
|
|
For a gentle introduction to the basics of pretty-printing using
|
|
<B>Format</B>
|
|
|
|
, read
|
|
<A HREF="http://caml.inria.fr/resources/doc/guides/format.en.html.">http://caml.inria.fr/resources/doc/guides/format.en.html.</A>
|
|
<P>
|
|
You may consider this module as providing an extension to the
|
|
<B>printf</B>
|
|
|
|
facility to provide automatic line splitting. The addition of
|
|
pretty-printing annotations to your regular
|
|
<B>printf</B>
|
|
|
|
format strings gives
|
|
you fancy indentation and line breaks.
|
|
Pretty-printing annotations are described below in the documentation of
|
|
the function
|
|
<B>Format.fprintf</B>
|
|
|
|
.
|
|
<P>
|
|
You may also use the explicit pretty-printing box management and printing
|
|
functions provided by this module. This style is more basic but more
|
|
verbose than the concise
|
|
<B>fprintf</B>
|
|
|
|
format strings.
|
|
<P>
|
|
For instance, the sequence
|
|
<B>open_box 0; print_string x =; print_space ();</B>
|
|
|
|
<B>print_int 1; close_box (); print_newline ()</B>
|
|
|
|
that prints
|
|
<B>x = 1</B>
|
|
|
|
within a pretty-printing box, can be
|
|
abbreviated as
|
|
<B>printf @[%s@ %i@]@. x = 1</B>
|
|
|
|
, or even shorter
|
|
<B>printf @[x =@ %i@]@. 1</B>
|
|
|
|
.
|
|
<P>
|
|
Rule of thumb for casual users of this library:
|
|
<P>
|
|
-use simple pretty-printing boxes (as obtained by
|
|
<B>open_box 0</B>
|
|
|
|
);
|
|
<P>
|
|
-use simple break hints as obtained by
|
|
<B>print_cut ()</B>
|
|
|
|
that outputs a
|
|
simple break hint, or by
|
|
<B>print_space ()</B>
|
|
|
|
that outputs a space
|
|
indicating a break hint;
|
|
<P>
|
|
-once a pretty-printing box is open, display its material with basic
|
|
printing functions (e. g.
|
|
<B>print_int</B>
|
|
|
|
and
|
|
<B>print_string</B>
|
|
|
|
);
|
|
<P>
|
|
-when the material for a pretty-printing box has been printed, call
|
|
<B>close_box ()</B>
|
|
|
|
to close the box;
|
|
<P>
|
|
-at the end of pretty-printing, flush the pretty-printer to display all
|
|
the remaining material, e.g. evaluate
|
|
<B>print_newline ()</B>
|
|
|
|
.
|
|
<P>
|
|
The behavior of pretty-printing commands is unspecified
|
|
if there is no open pretty-printing box. Each box opened by
|
|
one of the
|
|
<B>open_</B>
|
|
|
|
functions below must be closed using
|
|
<B>close_box</B>
|
|
|
|
for proper formatting. Otherwise, some of the material printed in the
|
|
boxes may not be output, or may be formatted incorrectly.
|
|
<P>
|
|
In case of interactive use, each phrase is executed in the initial state
|
|
of the standard pretty-printer: after each phrase execution, the
|
|
interactive system closes all open pretty-printing boxes, flushes all
|
|
pending text, and resets the standard pretty-printer.
|
|
<P>
|
|
Warning: mixing calls to pretty-printing functions of this module with
|
|
calls to
|
|
<B>Stdlib</B>
|
|
|
|
low level output functions is error prone.
|
|
<P>
|
|
The pretty-printing functions output material that is delayed in the
|
|
pretty-printer queue and stacks in order to compute proper line
|
|
splitting. In contrast, basic I/O output functions write directly in
|
|
their output device. As a consequence, the output of a basic I/O function
|
|
may appear before the output of a pretty-printing function that has been
|
|
called before. For instance,
|
|
<B>Stdlib.print_string <;</B>
|
|
|
|
|
|
|
|
<B>Format.print_string PRETTY;</B>
|
|
|
|
<B>Stdlib.print_string >;</B>
|
|
|
|
<B>Format.print_string TEXT;</B>
|
|
|
|
<B>leads to output </B>
|
|
|
|
<B><>PRETTYTEXT</B>
|
|
|
|
.
|
|
<P>
|
|
|
|
<I>type formatter </I>
|
|
|
|
<P>
|
|
<P>
|
|
Abstract data corresponding to a pretty-printer (also called a
|
|
formatter) and all its machinery. See also
|
|
<B>Format.formatter</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Pretty-printing boxes</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
The pretty-printing engine uses the concepts of pretty-printing box and
|
|
break hint to drive indentation and line splitting behavior of the
|
|
pretty-printer.
|
|
<P>
|
|
Each different pretty-printing box kind introduces a specific line splitting
|
|
policy:
|
|
<P>
|
|
<P>
|
|
-within an horizontal box, break hints never split the line (but the
|
|
line may be split in a box nested deeper),
|
|
<P>
|
|
-within a vertical box, break hints always split the line,
|
|
<P>
|
|
-within an horizontal/vertical box, if the box fits on the current line
|
|
then break hints never split the line, otherwise break hint always split
|
|
the line,
|
|
<P>
|
|
-within a compacting box, a break hint never splits the line,
|
|
unless there is no more room on the current line.
|
|
<P>
|
|
Note that line splitting policy is box specific: the policy of a box does
|
|
not rule the policy of inner boxes. For instance, if a vertical box is
|
|
nested in an horizontal box, all break hints within the vertical box will
|
|
split the line.
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_open_box </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_box </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_open_box ppf d</B>
|
|
|
|
opens a new compacting pretty-printing box with
|
|
offset
|
|
<B>d</B>
|
|
|
|
in the formatter
|
|
<B>ppf</B>
|
|
|
|
.
|
|
<P>
|
|
Within this box, the pretty-printer prints as much as possible material on
|
|
every line.
|
|
<P>
|
|
A break hint splits the line if there is no more room on the line to
|
|
print the remainder of the box.
|
|
<P>
|
|
Within this box, the pretty-printer emphasizes the box structure: a break
|
|
hint also splits the line if the splitting ``moves to the left''
|
|
(i.e. the new line gets an indentation smaller than the one of the current
|
|
line).
|
|
<P>
|
|
This box is the general purpose pretty-printing box.
|
|
<P>
|
|
If the pretty-printer splits the line in the box, offset
|
|
<B>d</B>
|
|
|
|
is added to
|
|
the current indentation.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_close_box </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val close_box </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
Closes the most recently open pretty-printing box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_open_hbox </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_hbox </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_open_hbox ppf ()</B>
|
|
|
|
opens a new 'horizontal' pretty-printing box.
|
|
<P>
|
|
This box prints material on a single line.
|
|
<P>
|
|
Break hints in a horizontal box never split the line.
|
|
(Line splitting may still occur inside boxes nested deeper).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_open_vbox </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_vbox </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_open_vbox ppf d</B>
|
|
|
|
opens a new 'vertical' pretty-printing box
|
|
with offset
|
|
<B>d</B>
|
|
|
|
.
|
|
<P>
|
|
This box prints material on as many lines as break hints in the box.
|
|
<P>
|
|
Every break hint in a vertical box splits the line.
|
|
<P>
|
|
If the pretty-printer splits the line in the box,
|
|
<B>d</B>
|
|
|
|
is added to the
|
|
current indentation.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_open_hvbox </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_hvbox </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_open_hvbox ppf d</B>
|
|
|
|
opens a new 'horizontal/vertical' pretty-printing box
|
|
with offset
|
|
<B>d</B>
|
|
|
|
.
|
|
<P>
|
|
This box behaves as an horizontal box if it fits on a single line,
|
|
otherwise it behaves as a vertical box.
|
|
<P>
|
|
If the pretty-printer splits the line in the box,
|
|
<B>d</B>
|
|
|
|
is added to the
|
|
current indentation.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_open_hovbox </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_hovbox </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_open_hovbox ppf d</B>
|
|
|
|
opens a new 'horizontal-or-vertical'
|
|
pretty-printing box with offset
|
|
<B>d</B>
|
|
|
|
.
|
|
<P>
|
|
This box prints material as much as possible on every line.
|
|
<P>
|
|
A break hint splits the line if there is no more room on the line to
|
|
print the remainder of the box.
|
|
<P>
|
|
If the pretty-printer splits the line in the box,
|
|
<B>d</B>
|
|
|
|
is added to the
|
|
current indentation.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Formatting functions</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_print_string </I>
|
|
|
|
:
|
|
<B>formatter -> string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_string </I>
|
|
|
|
:
|
|
<B>string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_string ppf s</B>
|
|
|
|
prints
|
|
<B>s</B>
|
|
|
|
in the current pretty-printing box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_as </I>
|
|
|
|
:
|
|
<B>formatter -> int -> string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_as </I>
|
|
|
|
:
|
|
<B>int -> string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_as ppf len s</B>
|
|
|
|
prints
|
|
<B>s</B>
|
|
|
|
in the current pretty-printing box.
|
|
The pretty-printer formats
|
|
<B>s</B>
|
|
|
|
as if it were of length
|
|
<B>len</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_int </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_int </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
Print an integer in the current pretty-printing box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_float </I>
|
|
|
|
:
|
|
<B>formatter -> float -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_float </I>
|
|
|
|
:
|
|
<B>float -> unit</B>
|
|
|
|
<P>
|
|
Print a floating point number in the current pretty-printing box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_char </I>
|
|
|
|
:
|
|
<B>formatter -> char -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_char </I>
|
|
|
|
:
|
|
<B>char -> unit</B>
|
|
|
|
<P>
|
|
Print a character in the current pretty-printing box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_bool </I>
|
|
|
|
:
|
|
<B>formatter -> bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_bool </I>
|
|
|
|
:
|
|
<B>bool -> unit</B>
|
|
|
|
<P>
|
|
Print a boolean in the current pretty-printing box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Break hints</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
A 'break hint' tells the pretty-printer to output some space or split the
|
|
line whichever way is more appropriate to the current pretty-printing box
|
|
splitting rules.
|
|
<P>
|
|
Break hints are used to separate printing items and are mandatory to let
|
|
the pretty-printer correctly split lines and indent items.
|
|
<P>
|
|
Simple break hints are:
|
|
<P>
|
|
-the 'space': output a space or split the line if appropriate,
|
|
<P>
|
|
-the 'cut': split the line if appropriate.
|
|
<P>
|
|
Note: the notions of space and line splitting are abstract for the
|
|
pretty-printing engine, since those notions can be completely redefined
|
|
by the programmer.
|
|
However, in the pretty-printer default setting, ``output a space'' simply
|
|
means printing a space character (ASCII code 32) and ``split the line''
|
|
means printing a newline character (ASCII code 10).
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_print_space </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_space </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_space ppf ()</B>
|
|
|
|
emits a 'space' break hint:
|
|
the pretty-printer may split the line at this point,
|
|
otherwise it prints one space.
|
|
<P>
|
|
<P>
|
|
<B>pp_print_space ppf ()</B>
|
|
|
|
is equivalent to
|
|
<B>pp_print_break ppf 1 0</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_cut </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_cut </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_cut ppf ()</B>
|
|
|
|
emits a 'cut' break hint:
|
|
the pretty-printer may split the line at this point,
|
|
otherwise it prints nothing.
|
|
<P>
|
|
<P>
|
|
<B>pp_print_cut ppf ()</B>
|
|
|
|
is equivalent to
|
|
<B>pp_print_break ppf 0 0</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_break </I>
|
|
|
|
:
|
|
<B>formatter -> int -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_break </I>
|
|
|
|
:
|
|
<B>int -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_break ppf nspaces offset</B>
|
|
|
|
emits a 'full' break hint:
|
|
the pretty-printer may split the line at this point,
|
|
otherwise it prints
|
|
<B>nspaces</B>
|
|
|
|
spaces.
|
|
<P>
|
|
If the pretty-printer splits the line,
|
|
<B>offset</B>
|
|
|
|
is added to
|
|
the current indentation.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_custom_break </I>
|
|
|
|
:
|
|
<B>formatter -></B>
|
|
|
|
<B>fits:string * int * string -> breaks:string * int * string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_custom_break ppf ~fits:(s1, n, s2) ~breaks:(s3, m, s4)</B>
|
|
|
|
emits a
|
|
custom break hint: the pretty-printer may split the line at this point.
|
|
<P>
|
|
If it does not split the line, then the
|
|
<B>s1</B>
|
|
|
|
is emitted, then
|
|
<B>n</B>
|
|
|
|
spaces,
|
|
then
|
|
<B>s2</B>
|
|
|
|
.
|
|
<P>
|
|
If it splits the line, then it emits the
|
|
<B>s3</B>
|
|
|
|
string, then an indent
|
|
(according to the box rules), then an offset of
|
|
<B>m</B>
|
|
|
|
spaces, then the
|
|
<B>s4</B>
|
|
|
|
string.
|
|
<P>
|
|
While
|
|
<B>n</B>
|
|
|
|
and
|
|
<B>m</B>
|
|
|
|
are handled by
|
|
<B>formatter_out_functions.out_indent</B>
|
|
|
|
, the
|
|
strings will be handled by
|
|
<B>formatter_out_functions.out_string</B>
|
|
|
|
. This allows
|
|
for a custom formatter that handles indentation distinctly, for example,
|
|
outputs
|
|
<B><br/></B>
|
|
|
|
tags or
|
|
<B>&nbsp;</B>
|
|
|
|
entities.
|
|
<P>
|
|
The custom break is useful if you want to change which visible
|
|
(non-whitespace) characters are printed in case of break or no break. For
|
|
example, when printing a list
|
|
<B>[a; b; c] </B>
|
|
|
|
, you might want to add a
|
|
trailing semicolon when it is printed vertically:
|
|
<P>
|
|
<P>
|
|
<B>[</B>
|
|
|
|
|
|
|
|
<B>a;</B>
|
|
|
|
<B>b;</B>
|
|
|
|
<B>c;</B>
|
|
|
|
<B>]</B>
|
|
|
|
<B><P>
|
|
</B>
|
|
|
|
You can do this as follows:
|
|
<B>printf @[<v 0>[@;<0 2>@[<v 0>a;@,b;@,c@]%t]@]@\n</B>
|
|
|
|
|
|
|
|
<B>(pp_print_custom_break ~fits:(, 0, ) ~breaks:(;, 0, ))</B>
|
|
|
|
<B></B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_force_newline </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val force_newline </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
Force a new line in the current pretty-printing box.
|
|
<P>
|
|
The pretty-printer must split the line at this point,
|
|
<P>
|
|
Not the normal way of pretty-printing, since imperative line splitting may
|
|
interfere with current line counters and box size calculation.
|
|
Using break hints within an enclosing vertical box is a better
|
|
alternative.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_if_newline </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_if_newline </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
Execute the next formatting command if the preceding line
|
|
has just been split. Otherwise, ignore the next formatting
|
|
command.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H3>Pretty-printing termination</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_print_flush </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_flush </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
End of pretty-printing: resets the pretty-printer to initial state.
|
|
<P>
|
|
All open pretty-printing boxes are closed, all pending text is printed.
|
|
In addition, the pretty-printer low level output device is flushed to
|
|
ensure that all pending text is really displayed.
|
|
<P>
|
|
Note: never use
|
|
<B>print_flush</B>
|
|
|
|
in the normal course of a pretty-printing
|
|
routine, since the pretty-printer uses a complex buffering machinery to
|
|
properly indent the output; manually flushing those buffers at random
|
|
would conflict with the pretty-printer strategy and result to poor
|
|
rendering.
|
|
<P>
|
|
Only consider using
|
|
<B>print_flush</B>
|
|
|
|
when displaying all pending material is
|
|
mandatory (for instance in case of interactive use when you want the user
|
|
to read some text) and when resetting the pretty-printer state will not
|
|
disturb further pretty-printing.
|
|
<P>
|
|
Warning: If the output device of the pretty-printer is an output channel,
|
|
repeated calls to
|
|
<B>print_flush</B>
|
|
|
|
means repeated calls to
|
|
<B>flush</B>
|
|
|
|
to flush the out channel; these explicit flush calls could foil the
|
|
buffering strategy of output channels and could dramatically impact
|
|
efficiency.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_newline </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_newline </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
End of pretty-printing: resets the pretty-printer to initial state.
|
|
<P>
|
|
All open pretty-printing boxes are closed, all pending text is printed.
|
|
<P>
|
|
Equivalent to
|
|
<B>Format.print_flush</B>
|
|
|
|
followed by a new line.
|
|
See corresponding words of caution for
|
|
<B>Format.print_flush</B>
|
|
|
|
.
|
|
<P>
|
|
Note: this is not the normal way to output a new line;
|
|
the preferred method is using break hints within a vertical pretty-printing
|
|
box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H3>Margin</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_set_margin </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_margin </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_margin ppf d</B>
|
|
|
|
sets the right margin to
|
|
<B>d</B>
|
|
|
|
(in characters):
|
|
the pretty-printer splits lines that overflow the right margin according to
|
|
the break hints given.
|
|
Nothing happens if
|
|
<B>d</B>
|
|
|
|
is smaller than 2.
|
|
If
|
|
<B>d</B>
|
|
|
|
is too large, the right margin is set to the maximum
|
|
admissible value (which is greater than
|
|
<B>10 ^ 9</B>
|
|
|
|
).
|
|
If
|
|
<B>d</B>
|
|
|
|
is less than the current maximum indentation limit, the
|
|
maximum indentation limit is decreased while trying to preserve
|
|
a minimal ratio
|
|
<B>max_indent/margin>=50%</B>
|
|
|
|
and if possible
|
|
the current difference
|
|
<B>margin - max_indent</B>
|
|
|
|
.
|
|
<P>
|
|
See also
|
|
<B>Format.pp_set_geometry</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_margin </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> int</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_margin </I>
|
|
|
|
:
|
|
<B>unit -> int</B>
|
|
|
|
<P>
|
|
Returns the position of the right margin.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>Maximum indentation limit</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_set_max_indent </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_max_indent </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_max_indent ppf d</B>
|
|
|
|
sets the maximum indentation limit of lines
|
|
to
|
|
<B>d</B>
|
|
|
|
(in characters):
|
|
once this limit is reached, new pretty-printing boxes are rejected to the
|
|
left, unless the enclosing box fully fits on the current line.
|
|
As an illustration,
|
|
<B>set_margin 10; set_max_indent 5; printf @[123456@[7@]89A@]@. </B>
|
|
|
|
yields
|
|
<B>123456</B>
|
|
|
|
|
|
|
|
<B>789A</B>
|
|
|
|
<B>because the nested box </B>
|
|
|
|
<B>@[7@]</B>
|
|
|
|
is opened after the maximum indentation
|
|
limit (
|
|
<B>7>5</B>
|
|
|
|
) and its parent box does not fit on the current line.
|
|
Either decreasing the length of the parent box to make it fit on a line:
|
|
<B>printf @[123456@[7@]89@]@. </B>
|
|
|
|
or opening an intermediary box before the maximum indentation limit which
|
|
fits on the current line
|
|
<B>printf @[123@[456@[7@]89@]A@]@. </B>
|
|
|
|
avoids the rejection to the left of the inner boxes and print respectively
|
|
<B>123456789</B>
|
|
|
|
and
|
|
<B>123456789A</B>
|
|
|
|
.
|
|
Note also that vertical boxes never fit on a line whereas horizontal boxes
|
|
always fully fit on the current line.
|
|
<P>
|
|
Nothing happens if
|
|
<B>d</B>
|
|
|
|
is smaller than 2.
|
|
<P>
|
|
If
|
|
<B>d</B>
|
|
|
|
is too large, the limit is set to the maximum
|
|
admissible value (which is greater than
|
|
<B>10 ^ 9</B>
|
|
|
|
).
|
|
<P>
|
|
If
|
|
<B>d</B>
|
|
|
|
is greater or equal than the current margin, it is ignored,
|
|
and the current maximum indentation limit is kept.
|
|
<P>
|
|
See also
|
|
<B>Format.pp_set_geometry</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_max_indent </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> int</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_max_indent </I>
|
|
|
|
:
|
|
<B>unit -> int</B>
|
|
|
|
<P>
|
|
Return the maximum indentation limit (in characters).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H3>Geometry </H3>
|
|
|
|
<P>
|
|
Geometric functions can be used to manipulate simultaneously the
|
|
coupled variables, margin and maxixum indentation limit.
|
|
<P>
|
|
|
|
<I>type geometry </I>
|
|
|
|
= {
|
|
<BR> max_indent :
|
|
<B>int</B>
|
|
|
|
;
|
|
<BR> margin :
|
|
<B>int</B>
|
|
|
|
;
|
|
<BR> }
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val check_geometry </I>
|
|
|
|
:
|
|
<B>geometry -> bool</B>
|
|
|
|
<P>
|
|
Check if the formatter geometry is valid:
|
|
<B>1 < max_indent < margin</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_geometry </I>
|
|
|
|
:
|
|
<B>formatter -> max_indent:int -> margin:int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_geometry </I>
|
|
|
|
:
|
|
<B>max_indent:int -> margin:int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_safe_set_geometry </I>
|
|
|
|
:
|
|
<B>formatter -> max_indent:int -> margin:int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val safe_set_geometry </I>
|
|
|
|
:
|
|
<B>max_indent:int -> margin:int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_geometry ppf ~max_indent ~margin</B>
|
|
|
|
sets both the margin
|
|
and maximum indentation limit for
|
|
<B>ppf</B>
|
|
|
|
.
|
|
<P>
|
|
When
|
|
<B>1 < max_indent < margin</B>
|
|
|
|
,
|
|
<B>pp_set_geometry ppf ~max_indent ~margin</B>
|
|
|
|
is equivalent to
|
|
<B>pp_set_margin ppf margin; pp_set_max_indent ppf max_indent</B>
|
|
|
|
;
|
|
and avoids the subtly incorrect
|
|
<B>pp_set_max_indent ppf max_indent; pp_set_margin ppf margin</B>
|
|
|
|
;
|
|
<P>
|
|
Outside of this domain,
|
|
<B>pp_set_geometry</B>
|
|
|
|
raises an invalid argument
|
|
exception whereas
|
|
<B>pp_safe_set_geometry</B>
|
|
|
|
does nothing.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_geometry </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> geometry</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_geometry </I>
|
|
|
|
:
|
|
<B>unit -> geometry</B>
|
|
|
|
<P>
|
|
Return the current geometry of the formatter
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H3>Maximum formatting depth</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
The maximum formatting depth is the maximum number of pretty-printing
|
|
boxes simultaneously open.
|
|
<P>
|
|
Material inside boxes nested deeper is printed as an ellipsis (more
|
|
precisely as the text returned by
|
|
<B>Format.get_ellipsis_text</B>
|
|
|
|
<B>()</B>
|
|
|
|
).
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_set_max_boxes </I>
|
|
|
|
:
|
|
<B>formatter -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_max_boxes </I>
|
|
|
|
:
|
|
<B>int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_max_boxes ppf max</B>
|
|
|
|
sets the maximum number of pretty-printing
|
|
boxes simultaneously open.
|
|
<P>
|
|
Material inside boxes nested deeper is printed as an ellipsis (more
|
|
precisely as the text returned by
|
|
<B>Format.get_ellipsis_text</B>
|
|
|
|
<B>()</B>
|
|
|
|
).
|
|
<P>
|
|
Nothing happens if
|
|
<B>max</B>
|
|
|
|
is smaller than 2.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_max_boxes </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> int</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_max_boxes </I>
|
|
|
|
:
|
|
<B>unit -> int</B>
|
|
|
|
<P>
|
|
Returns the maximum number of pretty-printing boxes allowed before
|
|
ellipsis.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_over_max_boxes </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> bool</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val over_max_boxes </I>
|
|
|
|
:
|
|
<B>unit -> bool</B>
|
|
|
|
<P>
|
|
Tests if the maximum number of pretty-printing boxes allowed have already
|
|
been opened.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H3>Tabulation boxes</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
A tabulation box prints material on lines divided into cells of fixed
|
|
length. A tabulation box provides a simple way to display vertical columns
|
|
of left adjusted text.
|
|
<P>
|
|
This box features command
|
|
<B>set_tab</B>
|
|
|
|
to define cell boundaries, and command
|
|
<B>print_tab</B>
|
|
|
|
to move from cell to cell and split the line when there is no
|
|
more cells to print on the line.
|
|
<P>
|
|
Note: printing within tabulation box is line directed, so arbitrary line
|
|
splitting inside a tabulation box leads to poor rendering. Yet, controlled
|
|
use of tabulation boxes allows simple printing of columns within
|
|
module
|
|
<B>Format</B>
|
|
|
|
.
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_open_tbox </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_tbox </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>open_tbox ()</B>
|
|
|
|
opens a new tabulation box.
|
|
<P>
|
|
This box prints lines separated into cells of fixed width.
|
|
<P>
|
|
Inside a tabulation box, special tabulation markers defines points of
|
|
interest on the line (for instance to delimit cell boundaries).
|
|
Function
|
|
<B>Format.set_tab</B>
|
|
|
|
sets a tabulation marker at insertion point.
|
|
<P>
|
|
A tabulation box features specific tabulation breaks to move to next
|
|
tabulation marker or split the line. Function
|
|
<B>Format.print_tbreak</B>
|
|
|
|
prints
|
|
a tabulation break.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_close_tbox </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val close_tbox </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
Closes the most recently opened tabulation box.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_tab </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_tab </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
Sets a tabulation marker at current insertion point.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_tab </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_tab </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>print_tab ()</B>
|
|
|
|
emits a 'next' tabulation break hint: if not already set on
|
|
a tabulation marker, the insertion point moves to the first tabulation
|
|
marker on the right, or the pretty-printer splits the line and insertion
|
|
point moves to the leftmost tabulation marker.
|
|
<P>
|
|
It is equivalent to
|
|
<B>print_tbreak 0 0</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_tbreak </I>
|
|
|
|
:
|
|
<B>formatter -> int -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val print_tbreak </I>
|
|
|
|
:
|
|
<B>int -> int -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>print_tbreak nspaces offset</B>
|
|
|
|
emits a 'full' tabulation break hint.
|
|
<P>
|
|
If not already set on a tabulation marker, the insertion point moves to the
|
|
first tabulation marker on the right and the pretty-printer prints
|
|
<B>nspaces</B>
|
|
|
|
spaces.
|
|
<P>
|
|
If there is no next tabulation marker on the right, the pretty-printer
|
|
splits the line at this point, then insertion point moves to the leftmost
|
|
tabulation marker of the box.
|
|
<P>
|
|
If the pretty-printer splits the line,
|
|
<B>offset</B>
|
|
|
|
is added to
|
|
the current indentation.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAO"> </A>
|
|
<H3>Ellipsis</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_set_ellipsis_text </I>
|
|
|
|
:
|
|
<B>formatter -> string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_ellipsis_text </I>
|
|
|
|
:
|
|
<B>string -> unit</B>
|
|
|
|
<P>
|
|
Set the text of the ellipsis printed when too many pretty-printing boxes
|
|
are open (a single dot,
|
|
<B>.</B>
|
|
|
|
, by default).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_ellipsis_text </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_ellipsis_text </I>
|
|
|
|
:
|
|
<B>unit -> string</B>
|
|
|
|
<P>
|
|
Return the text of the ellipsis.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAP"> </A>
|
|
<H3>Semantic tags</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type stag </I>
|
|
|
|
= ..
|
|
<P>
|
|
<P>
|
|
Semantic tags (or simply tags) are user's defined annotations
|
|
to associate user's specific operations to printed entities.
|
|
<P>
|
|
Common usage of semantic tags is text decoration to get specific font or
|
|
text size rendering for a display device, or marking delimitation of
|
|
entities (e.g. HTML or TeX elements or terminal escape sequences).
|
|
More sophisticated usage of semantic tags could handle dynamic
|
|
modification of the pretty-printer behavior to properly print the material
|
|
within some specific tags.
|
|
For instance, we can define an RGB tag like so:
|
|
<B>type stag += RGB of {r:int;g:int;b:int}</B>
|
|
|
|
|
|
|
|
<B><P>
|
|
</B>
|
|
|
|
In order to properly delimit printed entities, a semantic tag must be
|
|
opened before and closed after the entity. Semantic tags must be properly
|
|
nested like parentheses using
|
|
<B>Format.pp_open_stag</B>
|
|
|
|
and
|
|
<B>Format.pp_close_stag</B>
|
|
|
|
.
|
|
<P>
|
|
Tag specific operations occur any time a tag is opened or closed, At each
|
|
occurrence, two kinds of operations are performed tag-marking and
|
|
tag-printing:
|
|
<P>
|
|
-The tag-marking operation is the simpler tag specific operation: it simply
|
|
writes a tag specific string into the output device of the
|
|
formatter. Tag-marking does not interfere with line-splitting computation.
|
|
<P>
|
|
-The tag-printing operation is the more involved tag specific operation: it
|
|
can print arbitrary material to the formatter. Tag-printing is tightly
|
|
linked to the current pretty-printer operations.
|
|
<P>
|
|
Roughly speaking, tag-marking is commonly used to get a better rendering of
|
|
texts in the rendering device, while tag-printing allows fine tuning of
|
|
printing routines to print the same entity differently according to the
|
|
semantic tags (i.e. print additional material or even omit parts of the
|
|
output).
|
|
<P>
|
|
More precisely: when a semantic tag is opened or closed then both and
|
|
successive 'tag-printing' and 'tag-marking' operations occur:
|
|
<P>
|
|
-Tag-printing a semantic tag means calling the formatter specific function
|
|
<B>print_open_stag</B>
|
|
|
|
(resp.
|
|
<B>print_close_stag</B>
|
|
|
|
) 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 splitting computation).
|
|
<P>
|
|
-Tag-marking a semantic tag means calling the formatter specific function
|
|
<B>mark_open_stag</B>
|
|
|
|
(resp.
|
|
<B>mark_close_stag</B>
|
|
|
|
) with the name of the tag as
|
|
argument: that tag-marking function can then return the 'tag-opening
|
|
marker' (resp. `tag-closing marker') for direct output into the output
|
|
device of the formatter.
|
|
<P>
|
|
Being written directly into the output device of the formatter, semantic
|
|
tag marker strings are not considered as part of the printing material that
|
|
drives line splitting (in other words, the length of the strings
|
|
corresponding to tag markers is considered as zero for line splitting).
|
|
<P>
|
|
Thus, semantic 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
|
|
<B>set_tags</B>
|
|
|
|
is set to
|
|
<B>true</B>
|
|
|
|
, the pretty-printer engine
|
|
honors tags and decorates the output accordingly.
|
|
<P>
|
|
Default tag-marking functions behave the HTML way:
|
|
<B>Format.tag</B>
|
|
|
|
are
|
|
enclosed in "<" and ">" while other tags are ignored;
|
|
hence, opening marker for tag string
|
|
<B>t</B>
|
|
|
|
is
|
|
<B><t></B>
|
|
|
|
and closing marker
|
|
is
|
|
<B></t></B>
|
|
|
|
.
|
|
<P>
|
|
Default tag-printing functions just do nothing.
|
|
<P>
|
|
Tag-marking and tag-printing functions are user definable and can
|
|
be set by calling
|
|
<B>Format.set_formatter_stag_functions</B>
|
|
|
|
.
|
|
<P>
|
|
Semantic tag operations may be set on or off with
|
|
<B>Format.set_tags</B>
|
|
|
|
.
|
|
Tag-marking operations may be set on or off with
|
|
<B>Format.set_mark_tags</B>
|
|
|
|
.
|
|
Tag-printing operations may be set on or off with
|
|
<B>Format.set_print_tags</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<I>type tag </I>
|
|
|
|
=
|
|
<B>string</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type stag </I>
|
|
|
|
+=
|
|
<BR> | String_tag
|
|
<B>of </B>
|
|
|
|
<B>tag</B>
|
|
|
|
<I> </I>
|
|
|
|
(*
|
|
<B>String_tag s</B>
|
|
|
|
is a string tag
|
|
<B>s</B>
|
|
|
|
. String tags can be inserted either
|
|
by explicitly using the constructor
|
|
<B>String_tag</B>
|
|
|
|
or by using the dedicated
|
|
format syntax
|
|
<B>@{<s> ... @}</B>
|
|
|
|
.
|
|
<BR> *)
|
|
<BR>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_open_stag </I>
|
|
|
|
:
|
|
<B>formatter -> stag -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_stag </I>
|
|
|
|
:
|
|
<B>stag -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_open_stag ppf t</B>
|
|
|
|
opens the semantic tag named
|
|
<B>t</B>
|
|
|
|
.
|
|
<P>
|
|
The
|
|
<B>print_open_stag</B>
|
|
|
|
tag-printing function of the formatter is called with
|
|
<B>t</B>
|
|
|
|
as argument; then the opening tag marker for
|
|
<B>t</B>
|
|
|
|
, as given by
|
|
<B>mark_open_stag t</B>
|
|
|
|
, is written into the output device of the formatter.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_close_stag </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val close_stag </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_close_stag ppf ()</B>
|
|
|
|
closes the most recently opened semantic tag
|
|
<B>t</B>
|
|
|
|
.
|
|
<P>
|
|
The closing tag marker, as given by
|
|
<B>mark_close_stag t</B>
|
|
|
|
, is written into the
|
|
output device of the formatter; then the
|
|
<B>print_close_stag</B>
|
|
|
|
tag-printing
|
|
function of the formatter is called with
|
|
<B>t</B>
|
|
|
|
as argument.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_tags </I>
|
|
|
|
:
|
|
<B>formatter -> bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_tags </I>
|
|
|
|
:
|
|
<B>bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_tags ppf b</B>
|
|
|
|
turns on or off the treatment of semantic tags
|
|
(default is off).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_print_tags </I>
|
|
|
|
:
|
|
<B>formatter -> bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_print_tags </I>
|
|
|
|
:
|
|
<B>bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_print_tags ppf b</B>
|
|
|
|
turns on or off the tag-printing operations.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_mark_tags </I>
|
|
|
|
:
|
|
<B>formatter -> bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_mark_tags </I>
|
|
|
|
:
|
|
<B>bool -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_mark_tags ppf b</B>
|
|
|
|
turns on or off the tag-marking operations.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_print_tags </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> bool</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_print_tags </I>
|
|
|
|
:
|
|
<B>unit -> bool</B>
|
|
|
|
<P>
|
|
Return the current status of tag-printing operations.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_mark_tags </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> bool</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_mark_tags </I>
|
|
|
|
:
|
|
<B>unit -> bool</B>
|
|
|
|
<P>
|
|
Return the current status of tag-marking operations.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_formatter_out_channel </I>
|
|
|
|
:
|
|
<B>formatter -> out_channel -> unit</B>
|
|
|
|
<P>
|
|
<A NAME="lbAQ"> </A>
|
|
<H3>Redirecting the standard formatter output</H3>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_formatter_out_channel </I>
|
|
|
|
:
|
|
<B>out_channel -> unit</B>
|
|
|
|
<P>
|
|
Redirect the standard pretty-printer output to the given channel.
|
|
(All the output functions of the standard formatter are set to the
|
|
default output functions printing to the given channel.)
|
|
<P>
|
|
<P>
|
|
<B>set_formatter_out_channel</B>
|
|
|
|
is equivalent to
|
|
<B>Format.pp_set_formatter_out_channel</B>
|
|
|
|
<B>std_formatter</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>formatter -> (string -> int -> int -> unit) -> (unit -> unit) -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>(string -> int -> int -> unit) -> (unit -> unit) -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_formatter_output_functions ppf out flush</B>
|
|
|
|
redirects the
|
|
standard pretty-printer output functions to the functions
|
|
<B>out</B>
|
|
|
|
and
|
|
<B>flush</B>
|
|
|
|
.
|
|
<P>
|
|
The
|
|
<B>out</B>
|
|
|
|
function performs all the pretty-printer string output.
|
|
It is called with a string
|
|
<B>s</B>
|
|
|
|
, a start position
|
|
<B>p</B>
|
|
|
|
, and a number of
|
|
characters
|
|
<B>n</B>
|
|
|
|
; it is supposed to output characters
|
|
<B>p</B>
|
|
|
|
to
|
|
<B>p + n - 1</B>
|
|
|
|
of
|
|
<B>s</B>
|
|
|
|
.
|
|
<P>
|
|
The
|
|
<B>flush</B>
|
|
|
|
function is called whenever the pretty-printer is flushed
|
|
(via conversion
|
|
<B>%!</B>
|
|
|
|
, or pretty-printing indications
|
|
<B>@?</B>
|
|
|
|
or
|
|
<B>@.</B>
|
|
|
|
, or
|
|
using low level functions
|
|
<B>print_flush</B>
|
|
|
|
or
|
|
<B>print_newline</B>
|
|
|
|
).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> (string -> int -> int -> unit) * (unit -> unit)</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>unit -> (string -> int -> int -> unit) * (unit -> unit)</B>
|
|
|
|
<P>
|
|
Return the current output functions of the standard pretty-printer.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAR"> </A>
|
|
<H3>Redefining formatter output</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
The
|
|
<B>Format</B>
|
|
|
|
module is versatile enough to let you completely redefine
|
|
the meaning of pretty-printing output: you may provide your own functions
|
|
to define how to handle indentation, line splitting, and even printing of
|
|
all the characters that have to be printed!
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAS"> </A>
|
|
<H3>Redefining output functions</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type formatter_out_functions </I>
|
|
|
|
= {
|
|
<BR> out_string :
|
|
<B>string -> int -> int -> unit</B>
|
|
|
|
;
|
|
<BR> out_flush :
|
|
<B>unit -> unit</B>
|
|
|
|
;
|
|
<BR> out_newline :
|
|
<B>unit -> unit</B>
|
|
|
|
;
|
|
<BR> out_spaces :
|
|
<B>int -> unit</B>
|
|
|
|
;
|
|
<BR> out_indent :
|
|
<B>int -> unit</B>
|
|
|
|
;
|
|
<BR> }
|
|
<P>
|
|
<P>
|
|
The set of output functions specific to a formatter:
|
|
<P>
|
|
-the
|
|
<B>out_string</B>
|
|
|
|
function performs all the pretty-printer string output.
|
|
It is called with a string
|
|
<B>s</B>
|
|
|
|
, a start position
|
|
<B>p</B>
|
|
|
|
, and a number of
|
|
characters
|
|
<B>n</B>
|
|
|
|
; it is supposed to output characters
|
|
<B>p</B>
|
|
|
|
to
|
|
<B>p + n - 1</B>
|
|
|
|
of
|
|
<B>s</B>
|
|
|
|
.
|
|
<P>
|
|
-the
|
|
<B>out_flush</B>
|
|
|
|
function flushes the pretty-printer output device.
|
|
<P>
|
|
-
|
|
<B>out_newline</B>
|
|
|
|
is called to open a new line when the pretty-printer splits
|
|
the line.
|
|
<P>
|
|
-the
|
|
<B>out_spaces</B>
|
|
|
|
function outputs spaces when a break hint leads to spaces
|
|
instead of a line split. It is called with the number of spaces to output.
|
|
<P>
|
|
-the
|
|
<B>out_indent</B>
|
|
|
|
function performs new line indentation when the
|
|
pretty-printer splits the line. It is called with the indentation value of
|
|
the new line.
|
|
<P>
|
|
By default:
|
|
<P>
|
|
-fields
|
|
<B>out_string</B>
|
|
|
|
and
|
|
<B>out_flush</B>
|
|
|
|
are output device specific;
|
|
(e.g.
|
|
<B>output_string</B>
|
|
|
|
and
|
|
<B>flush</B>
|
|
|
|
for a
|
|
<B>out_channel</B>
|
|
|
|
device, or
|
|
<B>Buffer.add_substring</B>
|
|
|
|
and
|
|
<B>ignore</B>
|
|
|
|
for a
|
|
<B>Buffer.t</B>
|
|
|
|
output device),
|
|
<P>
|
|
-field
|
|
<B>out_newline</B>
|
|
|
|
is equivalent to
|
|
<B>out_string \n 0 1</B>
|
|
|
|
;
|
|
<P>
|
|
-fields
|
|
<B>out_spaces</B>
|
|
|
|
and
|
|
<B>out_indent</B>
|
|
|
|
are equivalent to
|
|
<B>out_string (String.make n ' ') 0 n</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_formatter_out_functions </I>
|
|
|
|
:
|
|
<B>formatter -> formatter_out_functions -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_formatter_out_functions </I>
|
|
|
|
:
|
|
<B>formatter_out_functions -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_formatter_out_functions ppf out_funs</B>
|
|
|
|
Set all the pretty-printer output functions of
|
|
<B>ppf</B>
|
|
|
|
to those of
|
|
argument
|
|
<B>out_funs</B>
|
|
|
|
,
|
|
<P>
|
|
This way, you can change the meaning of indentation (which can be
|
|
something else than just printing space characters) and the meaning of new
|
|
lines opening (which can be connected to any other action needed by the
|
|
application at hand).
|
|
<P>
|
|
Reasonable defaults for functions
|
|
<B>out_spaces</B>
|
|
|
|
and
|
|
<B>out_newline</B>
|
|
|
|
are
|
|
respectively
|
|
<B>out_funs.out_string (String.make n ' ') 0 n</B>
|
|
|
|
and
|
|
<B>out_funs.out_string \n 0 1</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_formatter_out_functions </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> formatter_out_functions</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_formatter_out_functions </I>
|
|
|
|
:
|
|
<B>unit -> formatter_out_functions</B>
|
|
|
|
<P>
|
|
Return the current output functions of the pretty-printer,
|
|
including line splitting and indentation functions. Useful to record the
|
|
current setting and restore it afterwards.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAT"> </A>
|
|
<H3>Redefining semantic tag operations</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type formatter_stag_functions </I>
|
|
|
|
= {
|
|
<BR> mark_open_stag :
|
|
<B>stag -> string</B>
|
|
|
|
;
|
|
<BR> mark_close_stag :
|
|
<B>stag -> string</B>
|
|
|
|
;
|
|
<BR> print_open_stag :
|
|
<B>stag -> unit</B>
|
|
|
|
;
|
|
<BR> print_close_stag :
|
|
<B>stag -> unit</B>
|
|
|
|
;
|
|
<BR> }
|
|
<P>
|
|
<P>
|
|
The semantic tag handling functions specific to a formatter:
|
|
<B>mark</B>
|
|
|
|
versions are the 'tag-marking' functions that associate a string
|
|
marker to a tag in order for the pretty-printing engine to write
|
|
those markers as 0 length tokens in the output device of the formatter.
|
|
<B>print</B>
|
|
|
|
versions are the 'tag-printing' functions that can perform
|
|
regular printing when a tag is closed or opened.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_formatter_stag_functions </I>
|
|
|
|
:
|
|
<B>formatter -> formatter_stag_functions -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_formatter_stag_functions </I>
|
|
|
|
:
|
|
<B>formatter_stag_functions -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_set_formatter_stag_functions ppf tag_funs</B>
|
|
|
|
changes the meaning of
|
|
opening and closing semantic tag operations to use the functions in
|
|
<B>tag_funs</B>
|
|
|
|
when printing on
|
|
<B>ppf</B>
|
|
|
|
.
|
|
<P>
|
|
When opening a semantic tag with name
|
|
<B>t</B>
|
|
|
|
, the string
|
|
<B>t</B>
|
|
|
|
is passed to the
|
|
opening tag-marking function (the
|
|
<B>mark_open_stag</B>
|
|
|
|
field of the
|
|
record
|
|
<B>tag_funs</B>
|
|
|
|
), that must return the opening tag marker for
|
|
that name. When the next call to
|
|
<B>close_stag ()</B>
|
|
|
|
happens, the semantic tag
|
|
name
|
|
<B>t</B>
|
|
|
|
is sent back to the closing tag-marking function (the
|
|
<B>mark_close_stag</B>
|
|
|
|
field of record
|
|
<B>tag_funs</B>
|
|
|
|
), that must return a
|
|
closing tag marker for that name.
|
|
<P>
|
|
The
|
|
<B>print_</B>
|
|
|
|
field of the record contains the tag-printing functions that
|
|
are called at tag opening and tag closing time, to output regular material
|
|
in the pretty-printer queue.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_formatter_stag_functions </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> formatter_stag_functions</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_formatter_stag_functions </I>
|
|
|
|
:
|
|
<B>unit -> formatter_stag_functions</B>
|
|
|
|
<P>
|
|
Return the current semantic tag operation functions of the standard
|
|
pretty-printer.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAU"> </A>
|
|
<H3>Defining formatters</H3>
|
|
|
|
<P>
|
|
Defining new formatters permits unrelated output of material in
|
|
parallel on several output devices.
|
|
All the parameters of a formatter are local to the formatter:
|
|
right margin, maximum indentation limit, maximum number of pretty-printing
|
|
boxes simultaneously open, ellipsis, and so on, are specific to
|
|
each formatter and may be fixed independently.
|
|
<P>
|
|
For instance, given a
|
|
<B>Buffer.t</B>
|
|
|
|
buffer
|
|
<B>b</B>
|
|
|
|
,
|
|
<B>Format.formatter_of_buffer</B>
|
|
|
|
<B>b</B>
|
|
|
|
returns a new formatter using buffer
|
|
<B>b</B>
|
|
|
|
as its output device.
|
|
Similarly, given a
|
|
<B>out_channel</B>
|
|
|
|
output channel
|
|
<B>oc</B>
|
|
|
|
,
|
|
<B>Format.formatter_of_out_channel</B>
|
|
|
|
<B>oc</B>
|
|
|
|
returns a new formatter using
|
|
channel
|
|
<B>oc</B>
|
|
|
|
as its output device.
|
|
<P>
|
|
Alternatively, given
|
|
<B>out_funs</B>
|
|
|
|
, a complete set of output functions for a
|
|
formatter, then
|
|
<B>Format.formatter_of_out_functions</B>
|
|
|
|
<B>out_funs</B>
|
|
|
|
computes a new
|
|
formatter using those functions for output.
|
|
<P>
|
|
|
|
<P>
|
|
<I>val formatter_of_out_channel </I>
|
|
|
|
:
|
|
<B>out_channel -> formatter</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>formatter_of_out_channel oc</B>
|
|
|
|
returns a new formatter writing
|
|
to the corresponding output channel
|
|
<B>oc</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val std_formatter </I>
|
|
|
|
:
|
|
<B>formatter</B>
|
|
|
|
<P>
|
|
The standard formatter to write to standard output.
|
|
<P>
|
|
It is defined as
|
|
<B>Format.formatter_of_out_channel</B>
|
|
|
|
<B>stdout</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val err_formatter </I>
|
|
|
|
:
|
|
<B>formatter</B>
|
|
|
|
<P>
|
|
A formatter to write to standard error.
|
|
<P>
|
|
It is defined as
|
|
<B>Format.formatter_of_out_channel</B>
|
|
|
|
<B>stderr</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val formatter_of_buffer </I>
|
|
|
|
:
|
|
<B>Buffer.t -> formatter</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>formatter_of_buffer b</B>
|
|
|
|
returns a new formatter writing to
|
|
buffer
|
|
<B>b</B>
|
|
|
|
. At the end of pretty-printing, the formatter must be flushed
|
|
using
|
|
<B>Format.pp_print_flush</B>
|
|
|
|
or
|
|
<B>Format.pp_print_newline</B>
|
|
|
|
, to print all the
|
|
pending material into the buffer.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val stdbuf </I>
|
|
|
|
:
|
|
<B>Buffer.t</B>
|
|
|
|
<P>
|
|
The string buffer in which
|
|
<B>str_formatter</B>
|
|
|
|
writes.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val str_formatter </I>
|
|
|
|
:
|
|
<B>formatter</B>
|
|
|
|
<P>
|
|
A formatter to output to the
|
|
<B>Format.stdbuf</B>
|
|
|
|
string buffer.
|
|
<P>
|
|
<P>
|
|
<B>str_formatter</B>
|
|
|
|
is defined as
|
|
<B>Format.formatter_of_buffer</B>
|
|
|
|
<B>Format.stdbuf</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val flush_str_formatter </I>
|
|
|
|
:
|
|
<B>unit -> string</B>
|
|
|
|
<P>
|
|
Returns the material printed with
|
|
<B>str_formatter</B>
|
|
|
|
, flushes
|
|
the formatter and resets the corresponding buffer.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val make_formatter </I>
|
|
|
|
:
|
|
<B>(string -> int -> int -> unit) -> (unit -> unit) -> formatter</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>make_formatter out flush</B>
|
|
|
|
returns a new formatter that outputs with
|
|
function
|
|
<B>out</B>
|
|
|
|
, and flushes with function
|
|
<B>flush</B>
|
|
|
|
.
|
|
<P>
|
|
For instance,
|
|
<B>make_formatter</B>
|
|
|
|
|
|
|
|
<B>(Stdlib.output oc)</B>
|
|
|
|
<B>(fun () -> Stdlib.flush oc) </B>
|
|
|
|
returns a formatter to the
|
|
<B>out_channel</B>
|
|
|
|
<B>oc</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val formatter_of_out_functions </I>
|
|
|
|
:
|
|
<B>formatter_out_functions -> formatter</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>formatter_of_out_functions out_funs</B>
|
|
|
|
returns a new formatter that writes
|
|
with the set of output functions
|
|
<B>out_funs</B>
|
|
|
|
.
|
|
<P>
|
|
See definition of type
|
|
<B>Format.formatter_out_functions</B>
|
|
|
|
for the meaning of argument
|
|
<B>out_funs</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAV"> </A>
|
|
<H3>Symbolic pretty-printing</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
Symbolic pretty-printing is pretty-printing using a symbolic formatter,
|
|
i.e. a formatter that outputs symbolic pretty-printing items.
|
|
<P>
|
|
When using a symbolic formatter, all regular pretty-printing activities
|
|
occur but output material is symbolic and stored in a buffer of output items.
|
|
At the end of pretty-printing, flushing the output buffer allows
|
|
post-processing of symbolic output before performing low level output
|
|
operations.
|
|
<P>
|
|
In practice, first define a symbolic output buffer
|
|
<B>b</B>
|
|
|
|
using:
|
|
<P>
|
|
-
|
|
<B>let sob = make_symbolic_output_buffer ()</B>
|
|
|
|
.
|
|
Then define a symbolic formatter with:
|
|
<P>
|
|
-
|
|
<B>let ppf = formatter_of_symbolic_output_buffer sob</B>
|
|
|
|
<P>
|
|
Use symbolic formatter
|
|
<B>ppf</B>
|
|
|
|
as usual, and retrieve symbolic items at end
|
|
of pretty-printing by flushing symbolic output buffer
|
|
<B>sob</B>
|
|
|
|
with:
|
|
<P>
|
|
-
|
|
<B>flush_symbolic_output_buffer sob</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
|
|
<I>type symbolic_output_item </I>
|
|
|
|
=
|
|
<BR> | Output_flush (* symbolic flush command
|
|
<BR> *)
|
|
<BR> | Output_newline (* symbolic newline command
|
|
<BR> *)
|
|
<BR> | Output_string
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (*
|
|
<B>Output_string s</B>
|
|
|
|
: symbolic output for string
|
|
<B>s</B>
|
|
|
|
<P>
|
|
<BR> *)
|
|
<BR> | Output_spaces
|
|
<B>of </B>
|
|
|
|
<B>int</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (*
|
|
<B>Output_spaces n</B>
|
|
|
|
: symbolic command to output
|
|
<B>n</B>
|
|
|
|
spaces
|
|
<BR> *)
|
|
<BR> | Output_indent
|
|
<B>of </B>
|
|
|
|
<B>int</B>
|
|
|
|
<I> </I>
|
|
|
|
<BR> (*
|
|
<B>Output_indent i</B>
|
|
|
|
: symbolic indentation of size
|
|
<B>i</B>
|
|
|
|
<P>
|
|
<BR> *)
|
|
<BR>
|
|
<P>
|
|
Items produced by symbolic pretty-printers
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<I>type symbolic_output_buffer </I>
|
|
|
|
<P>
|
|
<P>
|
|
The output buffer of a symbolic pretty-printer.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val make_symbolic_output_buffer </I>
|
|
|
|
:
|
|
<B>unit -> symbolic_output_buffer</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>make_symbolic_output_buffer ()</B>
|
|
|
|
returns a fresh buffer for
|
|
symbolic output.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val clear_symbolic_output_buffer </I>
|
|
|
|
:
|
|
<B>symbolic_output_buffer -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>clear_symbolic_output_buffer sob</B>
|
|
|
|
resets buffer
|
|
<B>sob</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_symbolic_output_buffer </I>
|
|
|
|
:
|
|
<B>symbolic_output_buffer -> symbolic_output_item list</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>get_symbolic_output_buffer sob</B>
|
|
|
|
returns the contents of buffer
|
|
<B>sob</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val flush_symbolic_output_buffer </I>
|
|
|
|
:
|
|
<B>symbolic_output_buffer -> symbolic_output_item list</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>flush_symbolic_output_buffer sob</B>
|
|
|
|
returns the contents of buffer
|
|
<B>sob</B>
|
|
|
|
and resets buffer
|
|
<B>sob</B>
|
|
|
|
.
|
|
<B>flush_symbolic_output_buffer sob</B>
|
|
|
|
is equivalent to
|
|
<B>let items = get_symbolic_output_buffer sob in</B>
|
|
|
|
<B>clear_symbolic_output_buffer sob; items</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val add_symbolic_output_item </I>
|
|
|
|
:
|
|
<B>symbolic_output_buffer -> symbolic_output_item -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>add_symbolic_output_item sob itm</B>
|
|
|
|
adds item
|
|
<B>itm</B>
|
|
|
|
to buffer
|
|
<B>sob</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val formatter_of_symbolic_output_buffer </I>
|
|
|
|
:
|
|
<B>symbolic_output_buffer -> formatter</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>formatter_of_symbolic_output_buffer sob</B>
|
|
|
|
returns a symbolic formatter
|
|
that outputs to
|
|
<B>symbolic_output_buffer</B>
|
|
|
|
<B>sob</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.06.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAW"> </A>
|
|
<H3>Convenience formatting functions.</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_print_list </I>
|
|
|
|
:
|
|
<B>?pp_sep:(formatter -> unit -> unit) -></B>
|
|
|
|
<B>(formatter -> 'a -> unit) -> formatter -> 'a list -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_list ?pp_sep pp_v ppf l</B>
|
|
|
|
prints items of list
|
|
<B>l</B>
|
|
|
|
,
|
|
using
|
|
<B>pp_v</B>
|
|
|
|
to print each item, and calling
|
|
<B>pp_sep</B>
|
|
|
|
between items (
|
|
<B>pp_sep</B>
|
|
|
|
defaults to
|
|
<B>Format.pp_print_cut</B>
|
|
|
|
.
|
|
Does nothing on empty lists.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_text </I>
|
|
|
|
:
|
|
<B>formatter -> string -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_text ppf s</B>
|
|
|
|
prints
|
|
<B>s</B>
|
|
|
|
with spaces and newlines respectively
|
|
printed using
|
|
<B>Format.pp_print_space</B>
|
|
|
|
and
|
|
<B>Format.pp_force_newline</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.02.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_option </I>
|
|
|
|
:
|
|
<B>?none:(formatter -> unit -> unit) -></B>
|
|
|
|
<B>(formatter -> 'a -> unit) -> formatter -> 'a option -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_option ?none pp_v ppf o</B>
|
|
|
|
prints
|
|
<B>o</B>
|
|
|
|
on
|
|
<B>ppf</B>
|
|
|
|
using
|
|
<B>pp_v</B>
|
|
|
|
if
|
|
<B>o</B>
|
|
|
|
is
|
|
<B>Some v</B>
|
|
|
|
and
|
|
<B>none</B>
|
|
|
|
if it is
|
|
<B>None</B>
|
|
|
|
.
|
|
<B>none</B>
|
|
|
|
prints nothing by default.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_print_result </I>
|
|
|
|
:
|
|
<B>ok:(formatter -> 'a -> unit) -></B>
|
|
|
|
<B>error:(formatter -> 'e -> unit) -></B>
|
|
|
|
<B>formatter -> ('a, 'e) result -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>pp_print_result ~ok ~error ppf r</B>
|
|
|
|
prints
|
|
<B>r</B>
|
|
|
|
on
|
|
<B>ppf</B>
|
|
|
|
using
|
|
<B>ok</B>
|
|
|
|
if
|
|
<B>r</B>
|
|
|
|
is
|
|
<B>Ok _</B>
|
|
|
|
and
|
|
<B>error</B>
|
|
|
|
if
|
|
<B>r</B>
|
|
|
|
is
|
|
<B>Error _</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAX"> </A>
|
|
<H3>Formatted pretty-printing</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
Module
|
|
<B>Format</B>
|
|
|
|
provides a complete set of
|
|
<B>printf</B>
|
|
|
|
like functions for
|
|
pretty-printing using format string specifications.
|
|
<P>
|
|
Specific annotations may be added in the format strings to give
|
|
pretty-printing commands to the pretty-printing engine.
|
|
<P>
|
|
Those annotations are introduced in the format strings using the
|
|
<B>@</B>
|
|
|
|
character. For instance,
|
|
<B>@ </B>
|
|
|
|
means a space break,
|
|
<B>@,</B>
|
|
|
|
means a cut,
|
|
<B>@[</B>
|
|
|
|
opens a new box, and
|
|
<B>@]</B>
|
|
|
|
closes the last open box.
|
|
<P>
|
|
|
|
<P>
|
|
<I>val fprintf </I>
|
|
|
|
:
|
|
<B>formatter -> ('a, formatter, unit) format -> 'a</B>
|
|
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<B>fprintf ff fmt arg1 ... argN</B>
|
|
|
|
formats the arguments
|
|
<B>arg1</B>
|
|
|
|
to
|
|
<B>argN</B>
|
|
|
|
according to the format string
|
|
<B>fmt</B>
|
|
|
|
, and outputs the resulting string on
|
|
the formatter
|
|
<B>ff</B>
|
|
|
|
.
|
|
<P>
|
|
The format string
|
|
<B>fmt</B>
|
|
|
|
is a character string which contains three types of
|
|
objects: plain characters and conversion specifications as specified in
|
|
the
|
|
<B>Printf</B>
|
|
|
|
module, and pretty-printing indications specific to the
|
|
<B>Format</B>
|
|
|
|
module.
|
|
<P>
|
|
The pretty-printing indication characters are introduced by
|
|
a
|
|
<B>@</B>
|
|
|
|
character, and their meanings are:
|
|
<P>
|
|
-
|
|
<B>@[</B>
|
|
|
|
: open a pretty-printing box. The type and offset of the
|
|
box may be optionally specified with the following syntax:
|
|
the
|
|
<B><</B>
|
|
|
|
character, followed by an optional box type indication,
|
|
then an optional integer offset, and the closing
|
|
<B>></B>
|
|
|
|
character.
|
|
Pretty-printing box type is one of
|
|
<B>h</B>
|
|
|
|
,
|
|
<B>v</B>
|
|
|
|
,
|
|
<B>hv</B>
|
|
|
|
,
|
|
<B>b</B>
|
|
|
|
, or
|
|
<B>hov</B>
|
|
|
|
.
|
|
'
|
|
<B>h</B>
|
|
|
|
' stands for an 'horizontal' pretty-printing box,
|
|
'
|
|
<B>v</B>
|
|
|
|
' stands for a 'vertical' pretty-printing box,
|
|
'
|
|
<B>hv</B>
|
|
|
|
' stands for an 'horizontal/vertical' pretty-printing box,
|
|
'
|
|
<B>b</B>
|
|
|
|
' stands for an 'horizontal-or-vertical' pretty-printing box
|
|
demonstrating indentation,
|
|
'
|
|
<B>hov</B>
|
|
|
|
' stands a simple 'horizontal-or-vertical' pretty-printing box.
|
|
For instance,
|
|
<B>@[<hov 2></B>
|
|
|
|
opens an 'horizontal-or-vertical'
|
|
pretty-printing box with indentation 2 as obtained with
|
|
<B>open_hovbox 2</B>
|
|
|
|
.
|
|
For more details about pretty-printing boxes, see the various box opening
|
|
functions
|
|
<B>open_*box</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@]</B>
|
|
|
|
: close the most recently opened pretty-printing box.
|
|
<P>
|
|
-
|
|
<B>@,</B>
|
|
|
|
: output a 'cut' break hint, as with
|
|
<B>print_cut ()</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@ </B>
|
|
|
|
: output a 'space' break hint, as with
|
|
<B>print_space ()</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@;</B>
|
|
|
|
: output a 'full' break hint as with
|
|
<B>print_break</B>
|
|
|
|
. The
|
|
<B>nspaces</B>
|
|
|
|
and
|
|
<B>offset</B>
|
|
|
|
parameters of the break hint may be
|
|
optionally specified with the following syntax:
|
|
the
|
|
<B><</B>
|
|
|
|
character, followed by an integer
|
|
<B>nspaces</B>
|
|
|
|
value,
|
|
then an integer
|
|
<B>offset</B>
|
|
|
|
, and a closing
|
|
<B>></B>
|
|
|
|
character.
|
|
If no parameters are provided, the good break defaults to a
|
|
'space' break hint.
|
|
<P>
|
|
-
|
|
<B>@.</B>
|
|
|
|
: flush the pretty-printer and split the line, as with
|
|
<B>print_newline ()</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@<n></B>
|
|
|
|
: print the following item as if it were of length
|
|
<B>n</B>
|
|
|
|
.
|
|
Hence,
|
|
<B>printf @<0>%s arg</B>
|
|
|
|
prints
|
|
<B>arg</B>
|
|
|
|
as a zero length string.
|
|
If
|
|
<B>@<n></B>
|
|
|
|
is not followed by a conversion specification,
|
|
then the following character of the format is printed as if
|
|
it were of length
|
|
<B>n</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@{</B>
|
|
|
|
: open a semantic tag. The name of the tag may be optionally
|
|
specified with the following syntax:
|
|
the
|
|
<B><</B>
|
|
|
|
character, followed by an optional string
|
|
specification, and the closing
|
|
<B>></B>
|
|
|
|
character. The string
|
|
specification is any character string that does not contain the
|
|
closing character
|
|
<B>'>'</B>
|
|
|
|
. If omitted, the tag name defaults to the
|
|
empty string.
|
|
For more details about semantic tags, see the functions
|
|
<B>Format.open_stag</B>
|
|
|
|
and
|
|
<B>Format.close_stag</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@}</B>
|
|
|
|
: close the most recently opened semantic tag.
|
|
<P>
|
|
-
|
|
<B>@?</B>
|
|
|
|
: flush the pretty-printer as with
|
|
<B>print_flush ()</B>
|
|
|
|
.
|
|
This is equivalent to the conversion
|
|
<B>%!</B>
|
|
|
|
.
|
|
<P>
|
|
-
|
|
<B>@\n</B>
|
|
|
|
: force a newline, as with
|
|
<B>force_newline ()</B>
|
|
|
|
, not the normal way
|
|
of pretty-printing, you should prefer using break hints inside a vertical
|
|
pretty-printing box.
|
|
<P>
|
|
Note: To prevent the interpretation of a
|
|
<B>@</B>
|
|
|
|
character as a
|
|
pretty-printing indication, escape it with a
|
|
<B>%</B>
|
|
|
|
character.
|
|
Old quotation mode
|
|
<B>@@</B>
|
|
|
|
is deprecated since it is not compatible with
|
|
formatted input interpretation of character
|
|
<B>'@'</B>
|
|
|
|
.
|
|
<P>
|
|
Example:
|
|
<B>printf @[%s@ %d@]@. x = 1</B>
|
|
|
|
is equivalent to
|
|
<B>open_box (); print_string x =; print_space ();</B>
|
|
|
|
<B>print_int 1; close_box (); print_newline ()</B>
|
|
|
|
.
|
|
It prints
|
|
<B>x = 1</B>
|
|
|
|
within a pretty-printing 'horizontal-or-vertical' box.
|
|
<P>
|
|
|
|
<P>
|
|
<I>val printf </I>
|
|
|
|
:
|
|
<B>('a, formatter, unit) format -> 'a</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>fprintf</B>
|
|
|
|
above, but output on
|
|
<B>std_formatter</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val eprintf </I>
|
|
|
|
:
|
|
<B>('a, formatter, unit) format -> 'a</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>fprintf</B>
|
|
|
|
above, but output on
|
|
<B>err_formatter</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val sprintf </I>
|
|
|
|
:
|
|
<B>('a, unit, string) format -> 'a</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>printf</B>
|
|
|
|
above, but instead of printing on a formatter,
|
|
returns a string containing the result of formatting the arguments.
|
|
Note that the pretty-printer queue is flushed at the end of each
|
|
call to
|
|
<B>sprintf</B>
|
|
|
|
.
|
|
<P>
|
|
In case of multiple and related calls to
|
|
<B>sprintf</B>
|
|
|
|
to output
|
|
material on a single string, you should consider using
|
|
<B>fprintf</B>
|
|
|
|
with the predefined formatter
|
|
<B>str_formatter</B>
|
|
|
|
and call
|
|
<B>flush_str_formatter ()</B>
|
|
|
|
to get the final result.
|
|
<P>
|
|
Alternatively, you can use
|
|
<B>Format.fprintf</B>
|
|
|
|
with a formatter writing to a
|
|
buffer of your own: flushing the formatter and the buffer at the end of
|
|
pretty-printing returns the desired string.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val asprintf </I>
|
|
|
|
:
|
|
<B>('a, formatter, unit, string) format4 -> 'a</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>printf</B>
|
|
|
|
above, but instead of printing on a formatter,
|
|
returns a string containing the result of formatting the arguments.
|
|
The type of
|
|
<B>asprintf</B>
|
|
|
|
is general enough to interact nicely with
|
|
<B>%a</B>
|
|
|
|
conversions.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.01.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val dprintf </I>
|
|
|
|
:
|
|
<B>('a, formatter, unit, formatter -> unit) format4 -> 'a</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Format.fprintf</B>
|
|
|
|
, except the formatter is the last argument.
|
|
<B>dprintf ... a b c</B>
|
|
|
|
is a function of type
|
|
<B>formatter -> unit</B>
|
|
|
|
which can be given to a format specifier
|
|
<B>%t</B>
|
|
|
|
.
|
|
<P>
|
|
This can be used as a replacement for
|
|
<B>Format.asprintf</B>
|
|
|
|
to delay
|
|
formatting decisions. Using the string returned by
|
|
<B>Format.asprintf</B>
|
|
|
|
in a
|
|
formatting context forces formatting decisions to be taken in
|
|
isolation, and the final string may be created
|
|
prematurely.
|
|
<B>Format.dprintf</B>
|
|
|
|
allows delay of formatting decisions until
|
|
the final formatting context is known.
|
|
For example:
|
|
<B>let t = Format.dprintf %i@ %i@ %i 1 2 3 in</B>
|
|
|
|
|
|
|
|
<B>...</B>
|
|
|
|
<B>Format.printf @[<v>%t@] t</B>
|
|
|
|
<B></B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val ifprintf </I>
|
|
|
|
:
|
|
<B>formatter -> ('a, formatter, unit) format -> 'a</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>fprintf</B>
|
|
|
|
above, but does not print anything.
|
|
Useful to ignore some material when conditionally printing.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.10.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
Formatted Pretty-Printing with continuations.
|
|
<P>
|
|
|
|
<P>
|
|
<I>val kfprintf </I>
|
|
|
|
:
|
|
<B>(formatter -> 'a) -></B>
|
|
|
|
<B>formatter -> ('b, formatter, unit, 'a) format4 -> 'b</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>fprintf</B>
|
|
|
|
above, but instead of returning immediately,
|
|
passes the formatter to its first argument at the end of printing.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val kdprintf </I>
|
|
|
|
:
|
|
<B>((formatter -> unit) -> 'a) -></B>
|
|
|
|
<B>('b, formatter, unit, 'a) format4 -> 'b</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>Format.dprintf</B>
|
|
|
|
above, but instead of returning immediately,
|
|
passes the suspended printer to its first argument at the end of printing.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.08.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val ikfprintf </I>
|
|
|
|
:
|
|
<B>(formatter -> 'a) -></B>
|
|
|
|
<B>formatter -> ('b, formatter, unit, 'a) format4 -> 'b</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>kfprintf</B>
|
|
|
|
above, but does not print anything.
|
|
Useful to ignore some material when conditionally printing.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
3.12.0
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val ksprintf </I>
|
|
|
|
:
|
|
<B>(string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>sprintf</B>
|
|
|
|
above, but instead of returning the string,
|
|
passes it to the first argument.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val kasprintf </I>
|
|
|
|
:
|
|
<B>(string -> 'a) -> ('b, formatter, unit, 'a) format4 -> 'b</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>asprintf</B>
|
|
|
|
above, but instead of returning the string,
|
|
passes it to the first argument.
|
|
<P>
|
|
<P>
|
|
<B>Since</B>
|
|
|
|
4.03
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAY"> </A>
|
|
<H3>Deprecated</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val bprintf </I>
|
|
|
|
:
|
|
<B>Buffer.t -> ('a, formatter, unit) format -> 'a</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
This function is error prone. Do not use it.
|
|
This function is neither compositional nor incremental, since it flushes
|
|
the pretty-printer queue at each call.
|
|
<P>
|
|
If you need to print to some buffer
|
|
<B>b</B>
|
|
|
|
, you must first define a
|
|
formatter writing to
|
|
<B>b</B>
|
|
|
|
, using
|
|
<B>let to_b = formatter_of_buffer b</B>
|
|
|
|
; then
|
|
use regular calls to
|
|
<B>Format.fprintf</B>
|
|
|
|
with formatter
|
|
<B>to_b</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val kprintf </I>
|
|
|
|
:
|
|
<B>(string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
An alias for
|
|
<B>ksprintf</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_all_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>out:(string -> int -> int -> unit) -></B>
|
|
|
|
<B>flush:(unit -> unit) -></B>
|
|
|
|
<B>newline:(unit -> unit) -> spaces:(int -> unit) -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>set_formatter_out_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_all_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>unit -></B>
|
|
|
|
<B>(string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) *</B>
|
|
|
|
<B>(int -> unit)</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>get_formatter_out_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_all_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>formatter -></B>
|
|
|
|
<B>out:(string -> int -> int -> unit) -></B>
|
|
|
|
<B>flush:(unit -> unit) -></B>
|
|
|
|
<B>newline:(unit -> unit) -> spaces:(int -> unit) -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>pp_set_formatter_out_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_all_formatter_output_functions </I>
|
|
|
|
:
|
|
<B>formatter -></B>
|
|
|
|
<B>unit -></B>
|
|
|
|
<B>(string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) *</B>
|
|
|
|
<B>(int -> unit)</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>pp_get_formatter_out_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAZ"> </A>
|
|
<H3>String tags</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val pp_open_tag </I>
|
|
|
|
:
|
|
<B>formatter -> tag -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.pp_open_stag</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val open_tag </I>
|
|
|
|
:
|
|
<B>tag -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.open_stag</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_close_tag </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.pp_close_stag</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val close_tag </I>
|
|
|
|
:
|
|
<B>unit -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.close_stag</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<I>type formatter_tag_functions </I>
|
|
|
|
= {
|
|
<BR> mark_open_tag :
|
|
<B>tag -> string</B>
|
|
|
|
;
|
|
<BR> mark_close_tag :
|
|
<B>tag -> string</B>
|
|
|
|
;
|
|
<BR> print_open_tag :
|
|
<B>tag -> unit</B>
|
|
|
|
;
|
|
<BR> print_close_tag :
|
|
<B>tag -> unit</B>
|
|
|
|
;
|
|
<BR> }
|
|
<P>
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.formatter_stag_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_set_formatter_tag_functions </I>
|
|
|
|
:
|
|
<B>formatter -> formatter_tag_functions -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.pp_set_formatter_stag_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
This function will erase non-string tag formatting functions.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val set_formatter_tag_functions </I>
|
|
|
|
:
|
|
<B>formatter_tag_functions -> unit</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.set_formatter_stag_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val pp_get_formatter_tag_functions </I>
|
|
|
|
:
|
|
<B>formatter -> unit -> formatter_tag_functions</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.pp_get_formatter_stag_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val get_formatter_tag_functions </I>
|
|
|
|
:
|
|
<B>unit -> formatter_tag_functions</B>
|
|
|
|
<P>
|
|
<B>Deprecated.</B>
|
|
|
|
Subsumed by
|
|
<B>Format.get_formatter_stag_functions</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">Module</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
|
|
<DL>
|
|
<DT id="4"><A HREF="#lbAE">Introduction</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">Pretty-printing boxes</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">Formatting functions</A><DD>
|
|
<DT id="7"><A HREF="#lbAH">Break hints</A><DD>
|
|
<DT id="8"><A HREF="#lbAI">Pretty-printing termination</A><DD>
|
|
<DT id="9"><A HREF="#lbAJ">Margin</A><DD>
|
|
<DT id="10"><A HREF="#lbAK">Maximum indentation limit</A><DD>
|
|
<DT id="11"><A HREF="#lbAL">Geometry </A><DD>
|
|
<DT id="12"><A HREF="#lbAM">Maximum formatting depth</A><DD>
|
|
<DT id="13"><A HREF="#lbAN">Tabulation boxes</A><DD>
|
|
<DT id="14"><A HREF="#lbAO">Ellipsis</A><DD>
|
|
<DT id="15"><A HREF="#lbAP">Semantic tags</A><DD>
|
|
<DT id="16"><A HREF="#lbAQ">Redirecting the standard formatter output</A><DD>
|
|
<DT id="17"><A HREF="#lbAR">Redefining formatter output</A><DD>
|
|
<DT id="18"><A HREF="#lbAS">Redefining output functions</A><DD>
|
|
<DT id="19"><A HREF="#lbAT">Redefining semantic tag operations</A><DD>
|
|
<DT id="20"><A HREF="#lbAU">Defining formatters</A><DD>
|
|
<DT id="21"><A HREF="#lbAV">Symbolic pretty-printing</A><DD>
|
|
<DT id="22"><A HREF="#lbAW">Convenience formatting functions.</A><DD>
|
|
<DT id="23"><A HREF="#lbAX">Formatted pretty-printing</A><DD>
|
|
<DT id="24"><A HREF="#lbAY">Deprecated</A><DD>
|
|
<DT id="25"><A HREF="#lbAZ">String tags</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:43 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|