diff options
Diffstat (limited to 'stdlib/format.mli')
| -rw-r--r-- | stdlib/format.mli | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/stdlib/format.mli b/stdlib/format.mli new file mode 100644 index 0000000000..5d9a9ac3e2 --- /dev/null +++ b/stdlib/format.mli @@ -0,0 +1,151 @@ +(* 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. +*) + +(* The behaviour of pretty-printing commands is unspecified + if there is no opened pretty-printing box. *) + +(*** Boxes *) +val open_vbox : int -> unit + (* [open_vbox d] opens a new pretty-printing box + with offset [d]. + This box is ``vertical'': every break hint inside this + box leads to a new line. + When a new line is printed in the box, [d] is added to the + current indentation. *) +val open_hbox : unit -> unit + (* [open_hbox ()] opens a new pretty-printing box. + This box is ``horizontal'': the line is not List.split in this box + (new lines may still occur inside boxes nested deeper). *) +val open_hvbox : int -> unit + (* [open_hovbox d] opens a new pretty-printing box + with offset [d]. + This box is ``horizontal-vertical'': it behaves as an + ``horizontal'' box if it fits on a single line, + otherwise it behaves as a ``vertical'' box. + When a new line is printed in the box, [d] is added to the + current indentation. *) +val open_hovbox : int -> unit + (* [open_hovbox d] opens a new pretty-printing box + with offset [d]. + This box is ``horizontal or vertical'': break hints + inside this box may lead to a new line, if there is no more room + on the line to print the remainder of the box. + When a new line is printed in the box, [d] is added to the + current indentation. *) +val close_box : unit -> unit + (* Close the most recently opened pretty-printing box. *) + +(*** Formatting functions *) +val print_string : string -> unit + (* [print_string str] prints [str] in the current box. *) +val print_as : int -> string -> unit + (* [print_as len str] prints [str] in the + current box. The pretty-printer formats [str] as if + it were of length [len]. *) +val print_int : int -> unit + (* Print an integer in the current box. *) +val print_float : float -> unit + (* Print a floating point number in the current box. *) +val print_char : char -> unit + (* Print a character in the current box. *) +val print_bool : bool -> unit + (* Print an boolean in the current box. *) + +(*** Break hints *) +val print_break : int * int -> unit + (* Insert a break hint in a pretty-printing box. + [print_break (nspaces, offset)] indicates that the line may + be List.split (a newline character is printed) at this point, + if the contents of the current box does not fit on one line. + If the line is List.split at that point, [offset] is added to + the current indentation. If the line is not List.split, + [nspaces] spaces are printed. *) +val print_cut : unit -> unit + (* [print_cut ()] is equivalent to [print_break (0,0)]. + This allows line splitting at the current point, without printing + spaces or adding indentation. *) +val print_space : unit -> unit + (* [print_space ()] is equivalent to [print_break (1,0)]. + This either prints one space or splits the line at that point. *) +val force_newline : unit -> unit + (* Force a newline in the current box. *) + +val print_flush : unit -> unit + (* Flush the pretty printer: all opened boxes are closed, + and all pending text is displayed. *) +val print_newline : unit -> unit + (* Equivalent to [print_flush] followed by a new line. *) + +val print_if_newline : unit -> unit + (* If the preceding line has not been List.split, the next + formatting command is ignored. *) + +(*** Tabulations *) +val open_tbox : unit -> unit + (* Open a tabulation box. *) +val close_tbox : unit -> unit + (* Close the most recently opened tabulation box. *) +val print_tbreak : int * int -> unit + (* Break hint in a tabulation box. + [print_tbreak (spaces, offset)] moves the insertion point to + the next tabulation ([spaces] being added to this position). + Nothing occurs if insertion point is already on a + tabulation mark. + If there is no next tabulation on the line, then a newline + is printed and the insertion point moves to the first + tabulation of the box. + If a new line is printed, [offset] is added to the current + indentation. *) +val set_tab : unit -> unit + (* Set a tabulation mark at the current insertion point. *) +val print_tab : unit -> unit + (* [print_tab ()] is equivalent to [print_tbreak (0,0)]. *) + +(*** Margin *) +val set_margin : int -> unit + (* [set_margin d] sets the val of the right margin + to [d] (in characters): this val is used to detect line + overflows that leads to List.split lines. + Nothing happens if [d] is not greater than 1. *) +val get_margin : unit -> int + (* Return the position of the right margin. *) + +(*** Maximum indentation limit *) +val set_max_indent : int -> unit + (* [set_max_indent d] sets the val of the maximum + indentation limit to [d] (in characters): + once this limit is reached, boxes are rejected to the left, + if they do not fit on the current line. + Nothing happens if [d] is not greater than 1. *) +val get_max_indent : unit -> int + (* Return the val of the maximum indentation limit (in + characters). *) + +(*** Formatting depth: maximum number of boxes allowed before ellipsis *) +val set_max_boxes : int -> unit + (* [set_max_boxes max] sets the maximum number + of boxes simultaneously opened. + Material inside boxes nested deeper is printed as an + ellipsis (more precisely as the text returned by + [get_ellipsis_text]). + Nothing happens if [max] is not greater than 1. *) +val get_max_boxes : unit -> int + (* Return the maximum number of boxes allowed before ellipsis. *) + +(*** Ellipsis *) +val set_ellipsis_text : string -> unit + (* Set the text of the ellipsis printed when too many boxes + are opened (a single dot, [.], by default). *) +val get_ellipsis_text : unit -> string + (* Return the text of the ellipsis. *) + +(*** Redirecting formatter output *) +val set_formatter_output : out_channel -> unit + (* Redirect the pretty-printer output to the given channel. *) +val get_formatter_output : unit -> out_channel + (* Return the channel connected to the pretty-printer. *) + |