1Format(3) OCaml library Format(3)
2
6 Format - Pretty-printing.
7
9 Module Format
10
12 Module Format
13 : sig end
14 Pretty-printing.
17 This module implements a pretty-printing facility to format values
19 within Format.boxes and Format.tags combined with a set of Format.fpp .
20 The pretty-printer splits lines at specified Format.breaks , and
21 indents lines according to the box structure. Similarly, Format.tags
22 can be used to decouple text presentation from its contents.
23 This pretty-printing facility is implemented as an overlay on top of
25 abstract Format.formatter which provide basic output functions. Some
26 formatters are predefined, notably:
27 - Format.std_formatter outputs to Pervasives.stdout
29 - Format.err_formatter outputs to Pervasives.stderr
32 Most functions in the Format module come in two variants: a short ver‐
34 sion that operates on Format.std_formatter and the generic version pre‐
35 fixed by pp_ that takes a formatter as its first argument.
36 More formatters can be created with Format.formatter_of_out_channel ,
38 Format.formatter_of_buffer , Format.formatter_of_symbolic_output_buffer
39 or using Format.formatter .
40 === Introduction For a gentle introduction to the basics of
48 pretty-printing using Format, read
49 [http://caml.inria.fr/resources/doc/guides/format.en.html]
50 http://caml.inria.fr/resources/doc/guides/format.en.html. You may con‐
51 sider this module as providing an extension to the printf facility to
52 provide automatic line splitting. The addition of pretty-printing anno‐
53 tations to your regular printf format strings gives you fancy indenta‐
54 tion and line breaks. Pretty-printing annotations are described below
55 in the documentation of the function Format.fprintf. You may also use
56 the explicit pretty-printing box management and printing functions pro‐
57 vided by this module. This style is more basic but more verbose than
58 the concise fprintf format strings. For instance, the sequence
59 open_box 0; print_string x = ; print_space (); print_int 1; close_box
60 (); print_newline () that prints x = 1 within a pretty-printing box,
61 can be abbreviated as printf @[%s@ %i@]@. x = 1, or even shorter printf
62 @[x =@ %i@]@. 1. Rule of thumb for casual users of this library: - use
63 simple pretty-printing boxes (as obtained by open_box 0); - use simple
64 break hints as obtained by print_cut () that outputs a simple break
65 hint, or by print_space () that outputs a space indicating a break
66 hint; - once a pretty-printing box is open, display its material with
67 basic printing functions (e. g. print_int and print_string); - when the
68 material for a pretty-printing box has been printed, call close_box ()
69 to close the box; - at the end of pretty-printing, flush the
70 pretty-printer to display all the remaining material, e.g. evaluate
71 print_newline (). The behavior of pretty-printing commands is unspeci‐
72 fied if there is no open pretty-printing box. Each box opened by one of
73 the open_ functions below must be closed using close_box for proper
74 formatting. Otherwise, some of the material printed in the boxes may
75 not be output, or may be formatted incorrectly. In case of interactive
76 use, each phrase is executed in the initial state of the standard
77 pretty-printer: after each phrase execution, the interactive system
78 closes all open pretty-printing boxes, flushes all pending text, and
79 resets the standard pretty-printer. Warning: mixing calls to
80 pretty-printing functions of this module with calls to Pervasives low
81 level output functions is error prone. The pretty-printing functions
82 output material that is delayed in the pretty-printer queue and stacks
83 in order to compute proper line splitting. In contrast, basic I/O out‐
84 put functions write directly in their output device. As a consequence,
85 the output of a basic I/O function may appear before the output of a
86 pretty-printing function that has been called before. For instance,
87 Pervasives.print_string < ; Format.print_string PRETTY ; Perva‐
88 sives.print_string > ; Format.print_string TEXT ; leads to output
89 <>PRETTYTEXT. ===
90 type formatter
93 Abstract data corresponding to a pretty-printer (also called a format‐
96 ter) and all its machinery. See also Format.formatter .
97 === Pretty-printing boxes ===
102 === The pretty-printing engine uses the concepts of pretty-printing box
105 and break hint to drive indentation and line splitting behavior of the
106 pretty-printer. Each different pretty-printing box kind introduces a
107 specific line splitting policy: - within an horizontal box, break hints
108 never split the line (but the line may be split in a box nested
109 deeper), - within a vertical box, break hints always split the line, -
110 within an horizontal/vertical box, if the box fits on the current line
111 then break hints never split the line, otherwise break hint always
112 split the line, - within a compacting box, a break hint never splits
113 the line, unless there is no more room on the current line. Note that
114 line splitting policy is box specific: the policy of a box does not
115 rule the policy of inner boxes. For instance, if a vertical box is
116 nested in an horizontal box, all break hints within the vertical box
117 will split the line. ===
118 val pp_open_box : formatter -> int -> unit
121 val open_box : int -> unit
126 pp_open_box ppf d opens a new compacting pretty-printing box with off‐
129 set d in the formatter ppf .
130 Within this box, the pretty-printer prints as much as possible material
132 on every line.
133 A break hint splits the line if there is no more room on the line to
135 print the remainder of the box.
136 Within this box, the pretty-printer emphasizes the box structure: a
138 break hint also splits the line if the splitting ``moves to the left''
139 (i.e. the new line gets an indentation smaller than the one of the cur‐
140 rent line).
141 This box is the general purpose pretty-printing box.
143 If the pretty-printer splits the line in the box, offset d is added to
145 the current indentation.
146 val pp_close_box : formatter -> unit -> unit
150 val close_box : unit -> unit
155 Closes the most recently open pretty-printing box.
157 val pp_open_hbox : formatter -> unit -> unit
161 val open_hbox : unit -> unit
166 pp_open_hbox ppf () opens a new 'horizontal' pretty-printing box.
169 This box prints material on a single line.
171 Break hints in a horizontal box never split the line. (Line splitting
173 may still occur inside boxes nested deeper).
174 val pp_open_vbox : formatter -> int -> unit
178 val open_vbox : int -> unit
183 pp_open_vbox ppf d opens a new 'vertical' pretty-printing box with off‐
186 set d .
187 This box prints material on as many lines as break hints in the box.
189 Every break hint in a vertical box splits the line.
191 If the pretty-printer splits the line in the box, d is added to the
193 current indentation.
194 val pp_open_hvbox : formatter -> int -> unit
198 val open_hvbox : int -> unit
203 pp_open_hvbox ppf d opens a new 'horizontal/vertical' pretty-printing
206 box with offset d .
207 This box behaves as an horizontal box if it fits on a single line, oth‐
209 erwise it behaves as a vertical box.
210 If the pretty-printer splits the line in the box, d is added to the
212 current indentation.
213 val pp_open_hovbox : formatter -> int -> unit
217 val open_hovbox : int -> unit
222 pp_open_hovbox ppf d opens a new 'horizontal-or-vertical' pretty-print‐
225 ing box with offset d .
226 This box prints material as much as possible on every line.
228 A break hint splits the line if there is no more room on the line to
230 print the remainder of the box.
231 If the pretty-printer splits the line in the box, d is added to the
233 current indentation.
234 === Formatting functions ===
239 val pp_print_string : formatter -> string -> unit
242 val print_string : string -> unit
247 pp_print_string ppf s prints s in the current pretty-printing box.
250 val pp_print_as : formatter -> int -> string -> unit
254 val print_as : int -> string -> unit
259 pp_print_as ppf len s prints s in the current pretty-printing box. The
262 pretty-printer formats s as if it were of length len .
263 val pp_print_int : formatter -> int -> unit
267 val print_int : int -> unit
272 Print an integer in the current pretty-printing box.
274 val pp_print_float : formatter -> float -> unit
278 val print_float : float -> unit
283 Print a floating point number in the current pretty-printing box.
285 val pp_print_char : formatter -> char -> unit
289 val print_char : char -> unit
294 Print a character in the current pretty-printing box.
296 val pp_print_bool : formatter -> bool -> unit
300 val print_bool : bool -> unit
305 Print a boolean in the current pretty-printing box.
307 === Break hints ===
312 === A 'break hint' tells the pretty-printer to output some space or
315 split the line whichever way is more appropriate to the current
316 pretty-printing box splitting rules. Break hints are used to separate
317 printing items and are mandatory to let the pretty-printer correctly
318 split lines and indent items. Simple break hints are: - the 'space':
319 output a space or split the line if appropriate, - the 'cut': split the
320 line if appropriate. Note: the notions of space and line splitting are
321 abstract for the pretty-printing engine, since those notions can be
322 completely redefined by the programmer. However, in the pretty-printer
323 default setting, ``output a space'' simply means printing a space char‐
324 acter (ASCII code 32) and ``split the line'' means printing a newline
325 character (ASCII code 10). ===
326 val pp_print_space : formatter -> unit -> unit
329 val print_space : unit -> unit
334 pp_print_space ppf () emits a 'space' break hint: the pretty-printer
337 may split the line at this point, otherwise it prints one space.
338 pp_print_space ppf () is equivalent to pp_print_break ppf 1 0 .
341 val pp_print_cut : formatter -> unit -> unit
345 val print_cut : unit -> unit
350 pp_print_cut ppf () emits a 'cut' break hint: the pretty-printer may
353 split the line at this point, otherwise it prints nothing.
354 pp_print_cut ppf () is equivalent to pp_print_break ppf 0 0 .
357 val pp_print_break : formatter -> int -> int -> unit
361 val print_break : int -> int -> unit
366 pp_print_break ppf nspaces offset emits a 'full' break hint: the
369 pretty-printer may split the line at this point, otherwise it prints
370 nspaces spaces.
371 If the pretty-printer splits the line, offset is added to the current
373 indentation.
374 val pp_force_newline : formatter -> unit -> unit
378 val force_newline : unit -> unit
383 Force a new line in the current pretty-printing box.
385 The pretty-printer must split the line at this point,
387 Not the normal way of pretty-printing, since imperative line splitting
389 may interfere with current line counters and box size calculation.
390 Using break hints within an enclosing vertical box is a better alterna‐
391 tive.
392 val pp_print_if_newline : formatter -> unit -> unit
396 val print_if_newline : unit -> unit
401 Execute the next formatting command if the preceding line has just been
403 split. Otherwise, ignore the next formatting command.
404 === Pretty-printing termination ===
409 val pp_print_flush : formatter -> unit -> unit
412 val print_flush : unit -> unit
417 End of pretty-printing: resets the pretty-printer to initial state.
419 All open pretty-printing boxes are closed, all pending text is printed.
421 In addition, the pretty-printer low level output device is flushed to
422 ensure that all pending text is really displayed.
423 Note: never use print_flush in the normal course of a pretty-printing
425 routine, since the pretty-printer uses a complex buffering machinery to
426 properly indent the output; manually flushing those buffers at random
427 would conflict with the pretty-printer strategy and result to poor ren‐
428 dering.
429 Only consider using print_flush when displaying all pending material is
431 mandatory (for instance in case of interactive use when you want the
432 user to read some text) and when resetting the pretty-printer state
433 will not disturb further pretty-printing.
434 Warning: If the output device of the pretty-printer is an output chan‐
436 nel, repeated calls to print_flush means repeated calls to Perva‐
437 sives.flush to flush the out channel; these explicit flush calls could
438 foil the buffering strategy of output channels and could dramatically
439 impact efficiency.
440 val pp_print_newline : formatter -> unit -> unit
444 val print_newline : unit -> unit
449 End of pretty-printing: resets the pretty-printer to initial state.
451 All open pretty-printing boxes are closed, all pending text is printed.
453 Equivalent to Format.print_flush followed by a new line. See corre‐
455 sponding words of caution for Format.print_flush .
456 Note: this is not the normal way to output a new line; the preferred
458 method is using break hints within a vertical pretty-printing box.
459 === Margin ===
464 val pp_set_margin : formatter -> int -> unit
467 val set_margin : int -> unit
472 pp_set_margin ppf d sets the right margin to d (in characters): the
475 pretty-printer splits lines that overflow the right margin according to
476 the break hints given. Nothing happens if d is smaller than 2. If d
477 is too large, the right margin is set to the maximum admissible value
478 (which is greater than 10 ^ 9 ). If d is less than the current maximum
479 indentation limit, the maximum indentation limit is decreased while
480 trying to preserve a minimal ratio max_indent/margin>=50% and if possi‐
481 ble the current difference margin - max_indent .
482 val pp_get_margin : formatter -> unit -> int
486 val get_margin : unit -> int
491 Returns the position of the right margin.
493 === Maximum indentation limit ===
498 val pp_set_max_indent : formatter -> int -> unit
501 val set_max_indent : int -> unit
506 pp_set_max_indent ppf d sets the maximum indentation limit of lines to
509 d (in characters): once this limit is reached, new pretty-printing
510 boxes are rejected to the left, if they do not fit on the current line.
511 Nothing happens if d is smaller than 2. If d is too large, the limit
513 is set to the maximum admissible value (which is greater than 10 ^ 9 ).
514 If d is greater or equal than the current margin, it is ignored, and
516 the current maximum indentation limit is kept.
517 val pp_get_max_indent : formatter -> unit -> int
521 val get_max_indent : unit -> int
526 Return the maximum indentation limit (in characters).
528 === Maximum formatting depth ===
533 === The maximum formatting depth is the maximum number of pretty-print‐
536 ing boxes simultaneously open. Material inside boxes nested deeper is
537 printed as an ellipsis (more precisely as the text returned by For‐
538 mat.get_ellipsis_text ()). ===
539 val pp_set_max_boxes : formatter -> int -> unit
542 val set_max_boxes : int -> unit
547 pp_set_max_boxes ppf max sets the maximum number of pretty-printing
550 boxes simultaneously open.
551 Material inside boxes nested deeper is printed as an ellipsis (more
553 precisely as the text returned by Format.get_ellipsis_text () ).
554 Nothing happens if max is smaller than 2.
556 val pp_get_max_boxes : formatter -> unit -> int
560 val get_max_boxes : unit -> int
565 Returns the maximum number of pretty-printing boxes allowed before
567 ellipsis.
568 val pp_over_max_boxes : formatter -> unit -> bool
572 val over_max_boxes : unit -> bool
577 Tests if the maximum number of pretty-printing boxes allowed have
579 already been opened.
580 === Tabulation boxes ===
585 === A tabulation box prints material on lines divided into cells of
588 fixed length. A tabulation box provides a simple way to display verti‐
589 cal columns of left adjusted text. This box features command set_tab
590 to define cell boundaries, and command print_tab to move from cell to
591 cell and split the line when there is no more cells to print on the
592 line. Note: printing within tabulation box is line directed, so arbi‐
593 trary line splitting inside a tabulation box leads to poor rendering.
594 Yet, controlled use of tabulation boxes allows simple printing of col‐
595 umns within module Format. ===
596 val pp_open_tbox : formatter -> unit -> unit
599 val open_tbox : unit -> unit
604 open_tbox () opens a new tabulation box.
607 This box prints lines separated into cells of fixed width.
609 Inside a tabulation box, special tabulation markers defines points of
611 interest on the line (for instance to delimit cell boundaries). Func‐
612 tion Format.set_tab sets a tabulation marker at insertion point.
613 A tabulation box features specific tabulation breaks to move to next
615 tabulation marker or split the line. Function Format.print_tbreak
616 prints a tabulation break.
617 val pp_close_tbox : formatter -> unit -> unit
621 val close_tbox : unit -> unit
626 Closes the most recently opened tabulation box.
628 val pp_set_tab : formatter -> unit -> unit
632 val set_tab : unit -> unit
637 Sets a tabulation marker at current insertion point.
639 val pp_print_tab : formatter -> unit -> unit
643 val print_tab : unit -> unit
648 print_tab () emits a 'next' tabulation break hint: if not already set
651 on a tabulation marker, the insertion point moves to the first tabula‐
652 tion marker on the right, or the pretty-printer splits the line and
653 insertion point moves to the leftmost tabulation marker.
654 It is equivalent to print_tbreak 0 0 .
656 val pp_print_tbreak : formatter -> int -> int -> unit
660 val print_tbreak : int -> int -> unit
665 print_tbreak nspaces offset emits a 'full' tabulation break hint.
668 If not already set on a tabulation marker, the insertion point moves to
670 the first tabulation marker on the right and the pretty-printer prints
671 nspaces spaces.
672 If there is no next tabulation marker on the right, the pretty-printer
674 splits the line at this point, then insertion point moves to the left‐
675 most tabulation marker of the box.
676 If the pretty-printer splits the line, offset is added to the current
678 indentation.
679 === Ellipsis ===
684 val pp_set_ellipsis_text : formatter -> string -> unit
687 val set_ellipsis_text : string -> unit
692 Set the text of the ellipsis printed when too many pretty-printing
694 boxes are open (a single dot, . , by default).
695 val pp_get_ellipsis_text : formatter -> unit -> string
699 val get_ellipsis_text : unit -> string
704 Return the text of the ellipsis.
706 === Semantic tags ===
711 type tag = string
714 === Semantic tags (or simply tags) are user's defined delimiters to as‐
721 sociate user's specific operations to printed entities. Common usage
722 of semantic tags is text decoration to get specific font or text size
723 rendering for a display device, or marking delimitation of entities
724 (e.g. HTML or TeX elements or terminal escape sequences). More sophis‐
725 ticated usage of semantic tags could handle dynamic modification of the
726 pretty-printer behavior to properly print the material within some spe‐
727 cific tags. In order to properly delimit printed entities, a semantic
728 tag must be opened before and closed after the entity. Semantic tags
729 must be properly nested like parentheses. Tag specific operations
730 occur any time a tag is opened or closed, At each occurrence, two kinds
731 of operations are performed tag-marking and tag-printing: - The
732 tag-marking operation is the simpler tag specific operation: it simply
733 writes a tag specific string into the output device of the formatter.
734 Tag-marking does not interfere with line-splitting computation. - The
735 tag-printing operation is the more involved tag specific operation: it
736 can print arbitrary material to the formatter. Tag-printing is tightly
737 linked to the current pretty-printer operations. Roughly speaking,
738 tag-marking is commonly used to get a better rendering of texts in the
739 rendering device, while tag-printing allows fine tuning of printing
740 routines to print the same entity differently according to the semantic
741 tags (i.e. print additional material or even omit parts of the output).
742 More precisely: when a semantic tag is opened or closed then both and
743 successive 'tag-printing' and 'tag-marking' operations occur: -
744 Tag-printing a semantic tag means calling the formatter specific func‐
745 tion print_open_tag (resp. print_close_tag) with the name of the tag as
746 argument: that tag-printing function can then print any regular mate‐
747 rial to the formatter (so that this material is enqueued as usual in
748 the formatter queue for further line splitting computation). -
749 Tag-marking a semantic tag means calling the formatter specific func‐
750 tion mark_open_tag (resp. mark_close_tag) with the name of the tag as
751 argument: that tag-marking function can then return the 'tag-opening
752 marker' (resp. `tag-closing marker') for direct output into the output
753 device of the formatter. Being written directly into the output device
754 of the formatter, semantic tag marker strings are not considered as
755 part of the printing material that drives line splitting (in other
756 words, the length of the strings corresponding to tag markers is con‐
757 sidered as zero for line splitting). Thus, semantic tag handling is in
758 some sense transparent to pretty-printing and does not interfere with
759 usual indentation. Hence, a single pretty-printing routine can output
760 both simple 'verbatim' material or richer decorated output depending on
761 the treatment of tags. By default, tags are not active, hence the out‐
762 put is not decorated with tag information. Once set_tags is set to
763 true, the pretty-printer engine honors tags and decorates the output
764 accordingly. Default tag-marking functions behave the HTML way: tags
765 are enclosed in < and > ; hence, opening marker for tag t is <t> and
766 closing marker is </t> . Default tag-printing functions just do noth‐
767 ing. Tag-marking and tag-printing functions are user definable and can
768 be set by calling Format.set_formatter_tag_functions. Semantic tag
769 operations may be set on or off with Format.set_tags. Tag-marking
770 operations may be set on or off with Format.set_mark_tags. Tag-print‐
771 ing operations may be set on or off with Format.set_print_tags. ===
772 val pp_open_tag : formatter -> string -> unit
775 val open_tag : tag -> unit
780 pp_open_tag ppf t opens the semantic tag named t .
783 The print_open_tag tag-printing function of the formatter is called
785 with t as argument; then the opening tag marker for t , as given by
786 mark_open_tag t , is written into the output device of the formatter.
787 val pp_close_tag : formatter -> unit -> unit
791 val close_tag : unit -> unit
796 pp_close_tag ppf () closes the most recently opened semantic tag t .
799 The closing tag marker, as given by mark_close_tag t , is written into
801 the output device of the formatter; then the print_close_tag tag-print‐
802 ing function of the formatter is called with t as argument.
803 val pp_set_tags : formatter -> bool -> unit
807 val set_tags : bool -> unit
812 pp_set_tags ppf b turns on or off the treatment of semantic tags
815 (default is off).
816 val pp_set_print_tags : formatter -> bool -> unit
820 val set_print_tags : bool -> unit
825 pp_set_print_tags ppf b turns on or off the tag-printing operations.
828 val pp_set_mark_tags : formatter -> bool -> unit
832 val set_mark_tags : bool -> unit
837 pp_set_mark_tags ppf b turns on or off the tag-marking operations.
840 val pp_get_print_tags : formatter -> unit -> bool
844 val get_print_tags : unit -> bool
849 Return the current status of tag-printing operations.
851 val pp_get_mark_tags : formatter -> unit -> bool
855 val get_mark_tags : unit -> bool
860 Return the current status of tag-marking operations.
862 val pp_set_formatter_out_channel : formatter -> Pervasives.out_channel
866 -> unit
867 Redirecting the standard formatter output
870 val set_formatter_out_channel : Pervasives.out_channel -> unit
875 Redirect the standard pretty-printer output to the given channel. (All
877 the output functions of the standard formatter are set to the default
878 output functions printing to the given channel.)
879 set_formatter_out_channel is equivalent to Format.pp_set_format‐
882 ter_out_channel std_formatter .
883 val pp_set_formatter_output_functions : formatter -> (string -> int ->
887 int -> unit) -> (unit -> unit) -> unit
888 val set_formatter_output_functions : (string -> int -> int -> unit) ->
893 (unit -> unit) -> unit
894 pp_set_formatter_output_functions ppf out flush redirects the standard
897 pretty-printer output functions to the functions out and flush .
898 The out function performs all the pretty-printer string output. It is
900 called with a string s , a start position p , and a number of charac‐
901 ters n ; it is supposed to output characters p to p + n - 1 of s .
902 The flush function is called whenever the pretty-printer is flushed
904 (via conversion %! , or pretty-printing indications @? or @. , or
905 using low level functions print_flush or print_newline ).
906 val pp_get_formatter_output_functions : formatter -> unit -> (string ->
910 int -> int -> unit) * (unit -> unit)
911 val get_formatter_output_functions : unit -> (string -> int -> int ->
916 unit) * (unit -> unit)
917 Return the current output functions of the standard pretty-printer.
919 === Redefining formatter output ===
924 === The Format module is versatile enough to let you completely rede‐
927 fine the meaning of pretty-printing output: you may provide your own
928 functions to define how to handle indentation, line splitting, and even
929 printing of all the characters that have to be printed! ===
930 === Redefining output functions ===
933 type formatter_out_functions = {
936 out_string : string -> int -> int -> unit ;
937 out_flush : unit -> unit ;
938 out_newline : unit -> unit ;
939 out_spaces : int -> unit ;
940 out_indent : int -> unit ;
941 }
942 The set of output functions specific to a formatter:
945 -the out_string function performs all the pretty-printer string output.
947 It is called with a string s , a start position p , and a number of
948 characters n ; it is supposed to output characters p to p + n - 1 of s
949 .
950 -the out_flush function flushes the pretty-printer output device.
952 - out_newline is called to open a new line when the pretty-printer
954 splits the line.
955 -the out_spaces function outputs spaces when a break hint leads to spa‐
957 ces instead of a line split. It is called with the number of spaces to
958 output.
959 -the out_indent function performs new line indentation when the
961 pretty-printer splits the line. It is called with the indentation value
962 of the new line.
963 By default:
965 -fields out_string and out_flush are output device specific; (e.g.
967 Pervasives.output_string and Pervasives.flush for a Perva‐
968 sives.out_channel device, or Buffer.add_substring and Pervasives.ignore
969 for a Buffer.t output device),
970 -field out_newline is equivalent to out_string \n 0 1 ;
972 -fields out_spaces and out_indent are equivalent to out_string
974 (String.make n ' ') 0 n .
975 Since 4.01.0
979 val pp_set_formatter_out_functions : formatter -> formatter_out_func‐
983 tions -> unit
984 val set_formatter_out_functions : formatter_out_functions -> unit
989 pp_set_formatter_out_functions ppf out_funs Set all the pretty-printer
992 output functions of ppf to those of argument out_funs ,
993 This way, you can change the meaning of indentation (which can be some‐
995 thing else than just printing space characters) and the meaning of new
996 lines opening (which can be connected to any other action needed by the
997 application at hand).
998 Reasonable defaults for functions out_spaces and out_newline are
1000 respectively out_funs.out_string (String.make n ' ') 0 n and
1001 out_funs.out_string \n 0 1 .
1002 Since 4.01.0
1005 val pp_get_formatter_out_functions : formatter -> unit -> format‐
1009 ter_out_functions
1010 val get_formatter_out_functions : unit -> formatter_out_functions
1015 Return the current output functions of the pretty-printer, including
1017 line splitting and indentation functions. Useful to record the current
1018 setting and restore it afterwards.
1019 Since 4.01.0
1022 === Redefining semantic tag operations ===
1027 type formatter_tag_functions = {
1030 mark_open_tag : tag -> string ;
1031 mark_close_tag : tag -> string ;
1032 print_open_tag : tag -> unit ;
1033 print_close_tag : tag -> unit ;
1034 }
1035 The semantic tag handling functions specific to a formatter: mark ver‐
1038 sions are the 'tag-marking' functions that associate a string marker to
1039 a tag in order for the pretty-printing engine to write those markers as
1040 0 length tokens in the output device of the formatter. print versions
1041 are the 'tag-printing' functions that can perform regular printing when
1042 a tag is closed or opened.
1043 val pp_set_formatter_tag_functions : formatter -> formatter_tag_func‐
1047 tions -> unit
1048 val set_formatter_tag_functions : formatter_tag_functions -> unit
1053 pp_set_formatter_tag_functions ppf tag_funs changes the meaning of
1056 opening and closing semantic tag operations to use the functions in
1057 tag_funs when printing on ppf .
1058 When opening a semantic tag with name t , the string t is passed to the
1060 opening tag-marking function (the mark_open_tag field of the record
1061 tag_funs ), that must return the opening tag marker for that name. When
1062 the next call to close_tag () happens, the semantic tag name t is sent
1063 back to the closing tag-marking function (the mark_close_tag field of
1064 record tag_funs ), that must return a closing tag marker for that name.
1065 The print_ field of the record contains the tag-printing functions that
1067 are called at tag opening and tag closing time, to output regular mate‐
1068 rial in the pretty-printer queue.
1069 val pp_get_formatter_tag_functions : formatter -> unit -> format‐
1073 ter_tag_functions
1074 val get_formatter_tag_functions : unit -> formatter_tag_functions
1079 Return the current semantic tag operation functions of the standard
1081 pretty-printer.
1082 === Defining formatters Defining new formatters permits unrelated out‐
1087 put of material in parallel on several output devices. All the parame‐
1088 ters of a formatter are local to the formatter: right margin, maximum
1089 indentation limit, maximum number of pretty-printing boxes simultane‐
1090 ously open, ellipsis, and so on, are specific to each formatter and may
1091 be fixed independently. For instance, given a Buffer.t buffer b, For‐
1092 mat.formatter_of_buffer b returns a new formatter using buffer b as its
1093 output device. Similarly, given a Pervasives.out_channel output chan‐
1094 nel oc, Format.formatter_of_out_channel oc returns a new formatter
1095 using channel oc as its output device. Alternatively, given out_funs,
1096 a complete set of output functions for a formatter, then Format.format‐
1097 ter_of_out_functions out_funs computes a new formatter using those
1098 functions for output. ===
1099 val formatter_of_out_channel : Pervasives.out_channel -> formatter
1102 formatter_of_out_channel oc returns a new formatter writing to the cor‐
1105 responding output channel oc .
1106 val std_formatter : formatter
1110 The standard formatter to write to standard output.
1112 It is defined as Format.formatter_of_out_channel Pervasives.stdout .
1114 val err_formatter : formatter
1118 A formatter to write to standard error.
1120 It is defined as Format.formatter_of_out_channel Pervasives.stderr .
1122 val formatter_of_buffer : Buffer.t -> formatter
1126 formatter_of_buffer b returns a new formatter writing to buffer b . At
1129 the end of pretty-printing, the formatter must be flushed using For‐
1130 mat.pp_print_flush or Format.pp_print_newline , to print all the pend‐
1131 ing material into the buffer.
1132 val stdbuf : Buffer.t
1136 The string buffer in which str_formatter writes.
1138 val str_formatter : formatter
1142 A formatter to output to the Format.stdbuf string buffer.
1144 str_formatter is defined as Format.formatter_of_buffer Format.stdbuf .
1147 val flush_str_formatter : unit -> string
1151 Returns the material printed with str_formatter , flushes the formatter
1153 and resets the corresponding buffer.
1154 val make_formatter : (string -> int -> int -> unit) -> (unit -> unit)
1158 -> formatter
1159 make_formatter out flush returns a new formatter that outputs with
1162 function out , and flushes with function flush .
1163 For instance, make_formatter (Pervasives.output oc) (fun () -> Perva‐
1165 sives.flush oc) returns a formatter to the Pervasives.out_channel oc .
1166 val formatter_of_out_functions : formatter_out_functions -> formatter
1170 formatter_of_out_functions out_funs returns a new formatter that writes
1173 with the set of output functions out_funs .
1174 See definition of type Format.formatter_out_functions for the meaning
1176 of argument out_funs .
1177 Since 4.06.0
1180 === Symbolic pretty-printing ===
1185 === Symbolic pretty-printing is pretty-printing using a symbolic for‐
1188 matter, i.e. a formatter that outputs symbolic pretty-printing items.
1189 When using a symbolic formatter, all regular pretty-printing activities
1190 occur but output material is symbolic and stored in a buffer of output
1191 items. At the end of pretty-printing, flushing the output buffer
1192 allows post-processing of symbolic output before performing low level
1193 output operations. In practice, first define a symbolic output buffer
1194 b using: - let sob = make_symbolic_output_buffer (). Then define a
1195 symbolic formatter with: - let ppf = formatter_of_symbolic_output_buf‐
1196 fer sob Use symbolic formatter ppf as usual, and retrieve symbolic
1197 items at end of pretty-printing by flushing symbolic output buffer sob
1198 with: - flush_symbolic_output_buffer sob. ===
1199 type symbolic_output_item =
1202 | Output_flush (* symbolic flush command
1203 *)
1204 | Output_newline (* symbolic newline command
1205 *)
1206 | Output_string of string
1207 (* Output_string s : symbolic output for string s
1208 *)
1210 | Output_spaces of int
1211 (* Output_spaces n : symbolic command to output n spaces
1212 *)
1213 | Output_indent of int
1214 (* Output_indent i : symbolic indentation of size i
1215 *)
1217 Items produced by symbolic pretty-printers
1220 Since 4.06.0
1223 type symbolic_output_buffer
1226 The output buffer of a symbolic pretty-printer.
1229 Since 4.06.0
1232 val make_symbolic_output_buffer : unit -> symbolic_output_buffer
1236 make_symbolic_output_buffer () returns a fresh buffer for symbolic out‐
1239 put.
1240 Since 4.06.0
1243 val clear_symbolic_output_buffer : symbolic_output_buffer -> unit
1247 clear_symbolic_output_buffer sob resets buffer sob .
1250 Since 4.06.0
1253 val get_symbolic_output_buffer : symbolic_output_buffer -> sym‐
1257 bolic_output_item list
1258 get_symbolic_output_buffer sob returns the contents of buffer sob .
1261 Since 4.06.0
1264 val flush_symbolic_output_buffer : symbolic_output_buffer -> sym‐
1268 bolic_output_item list
1269 flush_symbolic_output_buffer sob returns the contents of buffer sob and
1272 resets buffer sob . flush_symbolic_output_buffer sob is equivalent to
1273 let items = get_symbolic_output_buffer sob in clear_symbolic_out‐
1274 put_buffer sob; items
1275 Since 4.06.0
1279 val add_symbolic_output_item : symbolic_output_buffer -> symbolic_out‐
1283 put_item -> unit
1284 add_symbolic_output_item sob itm adds item itm to buffer sob .
1287 Since 4.06.0
1290 val formatter_of_symbolic_output_buffer : symbolic_output_buffer ->
1294 formatter
1295 formatter_of_symbolic_output_buffer sob returns a symbolic formatter
1298 that outputs to symbolic_output_buffer sob .
1299 Since 4.06.0
1302 === Convenience formatting functions. ===
1307 val pp_print_list : ?pp_sep:(formatter -> unit -> unit) -> (formatter
1310 -> 'a -> unit) -> formatter -> 'a list -> unit
1311 pp_print_list ?pp_sep pp_v ppf l prints items of list l , using pp_v to
1314 print each item, and calling pp_sep between items ( pp_sep defaults to
1315 Format.pp_print_cut . Does nothing on empty lists.
1316 Since 4.02.0
1319 val pp_print_text : formatter -> string -> unit
1323 pp_print_text ppf s prints s with spaces and newlines respectively
1326 printed using Format.pp_print_space and Format.pp_force_newline .
1327 Since 4.02.0
1330 === Formatted pretty-printing ===
1335 === Module Format provides a complete set of printf like functions for
1338 pretty-printing using format string specifications. Specific annota‐
1339 tions may be added in the format strings to give pretty-printing com‐
1340 mands to the pretty-printing engine. Those annotations are introduced
1341 in the format strings using the @ character. For instance, @ means a
1342 space break, @, means a cut, @[ opens a new box, and @] closes the last
1343 open box. ===
1344 val fprintf : formatter -> ('a, formatter, unit) Pervasives.format ->
1347 'a
1348 === fprintf ff fmt arg1 ... argN formats the arguments arg1 to argN
1354 according to the format string fmt, and outputs the resulting string on
1355 the formatter ff. The format string fmt is a character string which
1356 contains three types of objects: plain characters and conversion speci‐
1357 fications as specified in the Printf module, and pretty-printing indi‐
1358 cations specific to the Format module. The pretty-printing indication
1359 characters are introduced by a @ character, and their meanings are: -
1360 @[: open a pretty-printing box. The type and offset of the box may be
1361 optionally specified with the following syntax: the < character, fol‐
1362 lowed by an optional box type indication, then an optional integer off‐
1363 set, and the closing > character. Pretty-printing box type is one of
1364 h, v, hv, b, or hov. 'h' stands for an 'horizontal' pretty-printing
1365 box, 'v' stands for a 'vertical' pretty-printing box, 'hv' stands for
1366 an 'horizontal/vertical' pretty-printing box, 'b' stands for an 'hori‐
1367 zontal-or-vertical' pretty-printing box demonstrating indentation,
1368 'hov' stands a simple 'horizontal-or-vertical' pretty-printing box.
1369 For instance, @[<hov 2> opens an 'horizontal-or-vertical' pretty-print‐
1370 ing box with indentation 2 as obtained with open_hovbox 2. For more
1371 details about pretty-printing boxes, see the various box opening func‐
1372 tions open_*box. - @]: close the most recently opened pretty-printing
1373 box. - @,: output a 'cut' break hint, as with print_cut (). - @ :
1374 output a 'space' break hint, as with print_space (). - @;: output a
1375 'full' break hint as with print_break. The nspaces and offset parame‐
1376 ters of the break hint may be optionally specified with the following
1377 syntax: the < character, followed by an integer nspaces value, then an
1378 integer offset, and a closing > character. If no parameters are pro‐
1379 vided, the good break defaults to a 'space' break hint. - @.: flush
1380 the pretty-printer and split the line, as with print_newline (). -
1381 @<n>: print the following item as if it were of length n. Hence,
1382 printf @<0>%s arg prints arg as a zero length string. If @<n> is not
1383 followed by a conversion specification, then the following character of
1384 the format is printed as if it were of length n. - @{: open a semantic
1385 tag. The name of the tag may be optionally specified with the following
1386 syntax: the < character, followed by an optional string specification,
1387 and the closing > character. The string specification is any character
1388 string that does not contain the closing character '>'. If omitted, the
1389 tag name defaults to the empty string. For more details about semantic
1390 tags, see the functions Format.open_tag and Format.close_tag. - @}:
1391 close the most recently opened semantic tag. - @?: flush the
1392 pretty-printer as with print_flush (). This is equivalent to the con‐
1393 version %!. - @\n: force a newline, as with force_newline (), not the
1394 normal way of pretty-printing, you should prefer using break hints
1395 inside a vertical pretty-printing box. Note: To prevent the interpre‐
1396 tation of a @ character as a pretty-printing indication, escape it with
1397 a % character. Old quotation mode @@ is deprecated since it is not
1398 compatible with formatted input interpretation of character '@'. Exam‐
1399 ple: printf @[%s@ %d@]@. x = 1 is equivalent to open_box ();
1400 print_string x = ; print_space (); print_int 1; close_box ();
1401 print_newline (). It prints x = 1 within a pretty-printing 'horizon‐
1402 tal-or-vertical' box. ===
1403 val printf : ('a, formatter, unit) Pervasives.format -> 'a
1406 Same as fprintf above, but output on std_formatter .
1408 val eprintf : ('a, formatter, unit) Pervasives.format -> 'a
1412 Same as fprintf above, but output on err_formatter .
1414 val sprintf : ('a, unit, string) Pervasives.format -> 'a
1418 Same as printf above, but instead of printing on a formatter, returns a
1420 string containing the result of formatting the arguments. Note that
1421 the pretty-printer queue is flushed at the end of each call to sprintf
1422 .
1423 In case of multiple and related calls to sprintf to output material on
1425 a single string, you should consider using fprintf with the predefined
1426 formatter str_formatter and call flush_str_formatter () to get the
1427 final result.
1428 Alternatively, you can use Format.fprintf with a formatter writing to a
1430 buffer of your own: flushing the formatter and the buffer at the end of
1431 pretty-printing returns the desired string.
1432 val asprintf : ('a, formatter, unit, string) Pervasives.format4 -> 'a
1436 Same as printf above, but instead of printing on a formatter, returns a
1438 string containing the result of formatting the arguments. The type of
1439 asprintf is general enough to interact nicely with %a conversions.
1440 Since 4.01.0
1443 val ifprintf : formatter -> ('a, formatter, unit) Pervasives.format ->
1447 'a
1448 Same as fprintf above, but does not print anything. Useful to ignore
1450 some material when conditionally printing.
1451 Since 3.10.0
1454 === Formatted Pretty-Printing with continuations. ===
1459 val kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1462 'a) Pervasives.format4 -> 'b
1463 Same as fprintf above, but instead of returning immediately, passes the
1465 formatter to its first argument at the end of printing.
1466 val ikfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1470 'a) Pervasives.format4 -> 'b
1471 Same as kfprintf above, but does not print anything. Useful to ignore
1473 some material when conditionally printing.
1474 Since 3.12.0
1477 val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.for‐
1481 mat4 -> 'b
1482 Same as sprintf above, but instead of returning the string, passes it
1484 to the first argument.
1485 val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) Perva‐
1489 sives.format4 -> 'b
1490 Same as asprintf above, but instead of returning the string, passes it
1492 to the first argument.
1493 Since 4.03
1496 === Deprecated ===
1501 val bprintf : Buffer.t -> ('a, formatter, unit) Pervasives.format -> 'a
1504 Deprecated. This function is error prone. Do not use it. This func‐
1506 tion is neither compositional nor incremental, since it flushes the
1507 pretty-printer queue at each call.
1508 If you need to print to some buffer b , you must first define a format‐
1510 ter writing to b , using let to_b = formatter_of_buffer b ; then use
1511 regular calls to Format.fprintf with formatter to_b .
1512 val kprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.for‐
1516 mat4 -> 'b
1517 Deprecated. An alias for ksprintf .
1519 val set_all_formatter_output_functions : out:(string -> int -> int ->
1523 unit) -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int
1524 -> unit) -> unit
1525 Deprecated. Subsumed by set_formatter_out_functions .
1527 val get_all_formatter_output_functions : unit -> (string -> int -> int
1531 -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
1532 Deprecated. Subsumed by get_formatter_out_functions .
1534 val pp_set_all_formatter_output_functions : formatter -> out:(string ->
1538 int -> int -> unit) -> flush:(unit -> unit) -> newline:(unit -> unit)
1539 -> spaces:(int -> unit) -> unit
1540 Deprecated. Subsumed by pp_set_formatter_out_functions .
1542 val pp_get_all_formatter_output_functions : formatter -> unit ->
1546 (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int
1547 -> unit)
1548 Deprecated. Subsumed by pp_get_formatter_out_functions .
1550OCamldoc 2019-02-02 Format(3)