1Format(3) OCaml library Format(3)
2
3
4
6 Format - Pretty-printing.
7
9 Module Format
10
12 Module Format
13 : sig end
14
15
16 Pretty-printing.
17
18 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 in‐
21 dents lines according to the box structure. Similarly, Format.tags can
22 be used to decouple text presentation from its contents.
23
24 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
28 - Format.std_formatter outputs to stdout
29
30
31 - Format.err_formatter outputs to stderr
32
33 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
37 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
41
42
43
44
45
46
47 Introduction
48 For a gentle introduction to the basics of pretty-printing using Format
49 , read http://caml.inria.fr/resources/doc/guides/format.en.html.
50
51 You may consider this module as providing an extension to the printf
52 facility to provide automatic line splitting. The addition of
53 pretty-printing annotations to your regular printf format strings gives
54 you fancy indentation and line breaks. Pretty-printing annotations are
55 described below in the documentation of the function Format.fprintf .
56
57 You may also use the explicit pretty-printing box management and print‐
58 ing functions provided by this module. This style is more basic but
59 more verbose than the concise fprintf format strings.
60
61 For instance, the sequence open_box 0; print_string "x ="; print_space
62 ();
63 print_int 1; close_box (); print_newline () that prints x = 1
64 within a pretty-printing box, can be abbreviated as printf "@[%s@
65 %i@]@." "x =" 1 , or even shorter printf "@[x =@ %i@]@." 1 .
66
67 Rule of thumb for casual users of this library:
68
69 -use simple pretty-printing boxes (as obtained by open_box 0 );
70
71 -use simple break hints as obtained by print_cut () that outputs a sim‐
72 ple break hint, or by print_space () that outputs a space indicating a
73 break hint;
74
75 -once a pretty-printing box is open, display its material with basic
76 printing functions (e. g. print_int and print_string );
77
78 -when the material for a pretty-printing box has been printed, call
79 close_box () to close the box;
80
81 -at the end of pretty-printing, flush the pretty-printer to display all
82 the remaining material, e.g. evaluate print_newline () .
83
84 The behavior of pretty-printing commands is unspecified if there is no
85 open pretty-printing box. Each box opened by one of the open_ functions
86 below must be closed using close_box for proper formatting. Otherwise,
87 some of the material printed in the boxes may not be output, or may be
88 formatted incorrectly.
89
90 In case of interactive use, each phrase is executed in the initial
91 state of the standard pretty-printer: after each phrase execution, the
92 interactive system closes all open pretty-printing boxes, flushes all
93 pending text, and resets the standard pretty-printer.
94
95 Warning: mixing calls to pretty-printing functions of this module with
96 calls to Stdlib low level output functions is error prone.
97
98 The pretty-printing functions output material that is delayed in the
99 pretty-printer queue and stacks in order to compute proper line split‐
100 ting. In contrast, basic I/O output functions write directly in their
101 output device. As a consequence, the output of a basic I/O function may
102 appear before the output of a pretty-printing function that has been
103 called before. For instance,
104 Stdlib.print_string "<";
105 Format.print_string "PRETTY";
106 Stdlib.print_string ">";
107 Format.print_string "TEXT";
108 leads to output <>PRETTYTEXT .
109
110 type formatter
111
112
113 Abstract data corresponding to a pretty-printer (also called a format‐
114 ter) and all its machinery. See also Format.formatter .
115
116
117
118
119 Pretty-printing boxes
120 The pretty-printing engine uses the concepts of pretty-printing box and
121 break hint to drive indentation and line splitting behavior of the
122 pretty-printer.
123
124 Each different pretty-printing box kind introduces a specific line
125 splitting policy:
126
127
128 -within an horizontal box, break hints never split the line (but the
129 line may be split in a box nested deeper),
130
131 -within a vertical box, break hints always split the line,
132
133 -within an horizontal/vertical box, if the box fits on the current line
134 then break hints never split the line, otherwise break hint always
135 split the line,
136
137 -within a compacting box, a break hint never splits the line, unless
138 there is no more room on the current line.
139
140 Note that line splitting policy is box specific: the policy of a box
141 does not rule the policy of inner boxes. For instance, if a vertical
142 box is nested in an horizontal box, all break hints within the vertical
143 box will split the line.
144
145 Moreover, opening a box after the Format.maxindent splits the line
146 whether or not the box would end up fitting on the line.
147
148 val pp_open_box : formatter -> int -> unit
149
150
151
152
153 val open_box : int -> unit
154
155
156 pp_open_box ppf d opens a new compacting pretty-printing box with off‐
157 set d in the formatter ppf .
158
159 Within this box, the pretty-printer prints as much as possible material
160 on every line.
161
162 A break hint splits the line if there is no more room on the line to
163 print the remainder of the box.
164
165 Within this box, the pretty-printer emphasizes the box structure: if a
166 structural box does not fit fully on a simple line, a break hint also
167 splits the line if the splitting ``moves to the left'' (i.e. the new
168 line gets an indentation smaller than the one of the current line).
169
170 This box is the general purpose pretty-printing box.
171
172 If the pretty-printer splits the line in the box, offset d is added to
173 the current indentation.
174
175
176
177 val pp_close_box : formatter -> unit -> unit
178
179
180
181
182 val close_box : unit -> unit
183
184 Closes the most recently open pretty-printing box.
185
186
187
188 val pp_open_hbox : formatter -> unit -> unit
189
190
191
192
193 val open_hbox : unit -> unit
194
195
196 pp_open_hbox ppf () opens a new 'horizontal' pretty-printing box.
197
198 This box prints material on a single line.
199
200 Break hints in a horizontal box never split the line. (Line splitting
201 may still occur inside boxes nested deeper).
202
203
204
205 val pp_open_vbox : formatter -> int -> unit
206
207
208
209
210 val open_vbox : int -> unit
211
212
213 pp_open_vbox ppf d opens a new 'vertical' pretty-printing box with off‐
214 set d .
215
216 This box prints material on as many lines as break hints in the box.
217
218 Every break hint in a vertical box splits the line.
219
220 If the pretty-printer splits the line in the box, d is added to the
221 current indentation.
222
223
224
225 val pp_open_hvbox : formatter -> int -> unit
226
227
228
229
230 val open_hvbox : int -> unit
231
232
233 pp_open_hvbox ppf d opens a new 'horizontal/vertical' pretty-printing
234 box with offset d .
235
236 This box behaves as an horizontal box if it fits on a single line, oth‐
237 erwise it behaves as a vertical box.
238
239 If the pretty-printer splits the line in the box, d is added to the
240 current indentation.
241
242
243
244 val pp_open_hovbox : formatter -> int -> unit
245
246
247
248
249 val open_hovbox : int -> unit
250
251
252 pp_open_hovbox ppf d opens a new 'horizontal-or-vertical' pretty-print‐
253 ing box with offset d .
254
255 This box prints material as much as possible on every line.
256
257 A break hint splits the line if there is no more room on the line to
258 print the remainder of the box.
259
260 If the pretty-printer splits the line in the box, d is added to the
261 current indentation.
262
263
264
265
266 Formatting functions
267 val pp_print_string : formatter -> string -> unit
268
269
270
271
272 val print_string : string -> unit
273
274
275 pp_print_string ppf s prints s in the current pretty-printing box.
276
277
278
279 val pp_print_as : formatter -> int -> string -> unit
280
281
282
283
284 val print_as : int -> string -> unit
285
286
287 pp_print_as ppf len s prints s in the current pretty-printing box. The
288 pretty-printer formats s as if it were of length len .
289
290
291
292 val pp_print_int : formatter -> int -> unit
293
294
295
296
297 val print_int : int -> unit
298
299 Print an integer in the current pretty-printing box.
300
301
302
303 val pp_print_float : formatter -> float -> unit
304
305
306
307
308 val print_float : float -> unit
309
310 Print a floating point number in the current pretty-printing box.
311
312
313
314 val pp_print_char : formatter -> char -> unit
315
316
317
318
319 val print_char : char -> unit
320
321 Print a character in the current pretty-printing box.
322
323
324
325 val pp_print_bool : formatter -> bool -> unit
326
327
328
329
330 val print_bool : bool -> unit
331
332 Print a boolean in the current pretty-printing box.
333
334
335
336
337 Break hints
338 A 'break hint' tells the pretty-printer to output some space or split
339 the line whichever way is more appropriate to the current pretty-print‐
340 ing box splitting rules.
341
342 Break hints are used to separate printing items and are mandatory to
343 let the pretty-printer correctly split lines and indent items.
344
345 Simple break hints are:
346
347 -the 'space': output a space or split the line if appropriate,
348
349 -the 'cut': split the line if appropriate.
350
351 Note: the notions of space and line splitting are abstract for the
352 pretty-printing engine, since those notions can be completely redefined
353 by the programmer. However, in the pretty-printer default setting,
354 ``output a space'' simply means printing a space character (ASCII code
355 32) and ``split the line'' means printing a newline character (ASCII
356 code 10).
357
358 val pp_print_space : formatter -> unit -> unit
359
360
361
362
363 val print_space : unit -> unit
364
365
366 pp_print_space ppf () emits a 'space' break hint: the pretty-printer
367 may split the line at this point, otherwise it prints one space.
368
369
370 pp_print_space ppf () is equivalent to pp_print_break ppf 1 0 .
371
372
373
374 val pp_print_cut : formatter -> unit -> unit
375
376
377
378
379 val print_cut : unit -> unit
380
381
382 pp_print_cut ppf () emits a 'cut' break hint: the pretty-printer may
383 split the line at this point, otherwise it prints nothing.
384
385
386 pp_print_cut ppf () is equivalent to pp_print_break ppf 0 0 .
387
388
389
390 val pp_print_break : formatter -> int -> int -> unit
391
392
393
394
395 val print_break : int -> int -> unit
396
397
398 pp_print_break ppf nspaces offset emits a 'full' break hint: the
399 pretty-printer may split the line at this point, otherwise it prints
400 nspaces spaces.
401
402 If the pretty-printer splits the line, offset is added to the current
403 indentation.
404
405
406
407 val pp_print_custom_break : formatter -> fits:string * int * string ->
408 breaks:string * int * string -> unit
409
410
411 pp_print_custom_break ppf ~fits:(s1, n, s2) ~breaks:(s3, m, s4) emits a
412 custom break hint: the pretty-printer may split the line at this point.
413
414 If it does not split the line, then the s1 is emitted, then n spaces,
415 then s2 .
416
417 If it splits the line, then it emits the s3 string, then an indent (ac‐
418 cording to the box rules), then an offset of m spaces, then the s4
419 string.
420
421 While n and m are handled by formatter_out_functions.out_indent , the
422 strings will be handled by formatter_out_functions.out_string . This
423 allows for a custom formatter that handles indentation distinctly, for
424 example, outputs <br/> tags or entities.
425
426 The custom break is useful if you want to change which visible
427 (non-whitespace) characters are printed in case of break or no break.
428 For example, when printing a list
429 [a; b; c]
430 trailing semicolon when it is printed vertically:
431
432
433 [
434 a;
435 b;
436 c;
437 ]
438
439
440 You can do this as follows:
441 printf "@[<v 0>[@;<0 2>@[<v 0>a;@,b;@,c@]%t]@]@\n"
442 (pp_print_custom_break ~fits:("", 0, "") ~breaks:(";", 0, ""))
443
444
445
446 Since 4.08.0
447
448
449
450 val pp_force_newline : formatter -> unit -> unit
451
452
453
454
455 val force_newline : unit -> unit
456
457 Force a new line in the current pretty-printing box.
458
459 The pretty-printer must split the line at this point,
460
461 Not the normal way of pretty-printing, since imperative line splitting
462 may interfere with current line counters and box size calculation. Us‐
463 ing break hints within an enclosing vertical box is a better alterna‐
464 tive.
465
466
467
468 val pp_print_if_newline : formatter -> unit -> unit
469
470
471
472
473 val print_if_newline : unit -> unit
474
475 Execute the next formatting command if the preceding line has just been
476 split. Otherwise, ignore the next formatting command.
477
478
479
480
481 Pretty-printing termination
482 val pp_print_flush : formatter -> unit -> unit
483
484
485
486
487 val print_flush : unit -> unit
488
489 End of pretty-printing: resets the pretty-printer to initial state.
490
491 All open pretty-printing boxes are closed, all pending text is printed.
492 In addition, the pretty-printer low level output device is flushed to
493 ensure that all pending text is really displayed.
494
495 Note: never use print_flush in the normal course of a pretty-printing
496 routine, since the pretty-printer uses a complex buffering machinery to
497 properly indent the output; manually flushing those buffers at random
498 would conflict with the pretty-printer strategy and result to poor ren‐
499 dering.
500
501 Only consider using print_flush when displaying all pending material is
502 mandatory (for instance in case of interactive use when you want the
503 user to read some text) and when resetting the pretty-printer state
504 will not disturb further pretty-printing.
505
506 Warning: If the output device of the pretty-printer is an output chan‐
507 nel, repeated calls to print_flush means repeated calls to flush to
508 flush the out channel; these explicit flush calls could foil the
509 buffering strategy of output channels and could dramatically impact ef‐
510 ficiency.
511
512
513
514 val pp_print_newline : formatter -> unit -> unit
515
516
517
518
519 val print_newline : unit -> unit
520
521 End of pretty-printing: resets the pretty-printer to initial state.
522
523 All open pretty-printing boxes are closed, all pending text is printed.
524
525 Equivalent to Format.print_flush followed by a new line. See corre‐
526 sponding words of caution for Format.print_flush .
527
528 Note: this is not the normal way to output a new line; the preferred
529 method is using break hints within a vertical pretty-printing box.
530
531
532
533
534 Margin
535 val pp_set_margin : formatter -> int -> unit
536
537
538
539
540 val set_margin : int -> unit
541
542
543 pp_set_margin ppf d sets the right margin to d (in characters): the
544 pretty-printer splits lines that overflow the right margin according to
545 the break hints given. Setting the margin to d means that the format‐
546 ting engine aims at printing at most d-1 characters per line. Nothing
547 happens if d is smaller than 2. If d is too large, the right margin is
548 set to the maximum admissible value (which is greater than 10 ^ 9 ).
549 If d is less than the current maximum indentation limit, the maximum
550 indentation limit is decreased while trying to preserve a minimal ratio
551 max_indent/margin>=50% and if possible the current difference margin -
552 max_indent .
553
554 See also Format.pp_set_geometry .
555
556
557
558 val pp_get_margin : formatter -> unit -> int
559
560
561
562
563 val get_margin : unit -> int
564
565 Returns the position of the right margin.
566
567
568
569
570 Maximum indentation limit
571 val pp_set_max_indent : formatter -> int -> unit
572
573
574
575
576 val set_max_indent : int -> unit
577
578
579 pp_set_max_indent ppf d sets the maximum indentation limit of lines to
580 d (in characters): once this limit is reached, new pretty-printing
581 boxes are rejected to the left, unless the enclosing box fully fits on
582 the current line. As an illustration,
583 set_margin 10; set_max_indent 5; printf "@[123456@[7@]89A@]@."
584 yields
585 123456
586 789A
587
588 because the nested box "@[7@]" is opened after the maximum indentation
589 limit ( 7>5 ) and its parent box does not fit on the current line. Ei‐
590 ther decreasing the length of the parent box to make it fit on a line:
591 printf "@[123456@[7@]89@]@."
592 or opening an intermediary box before the maximum indentation limit
593 which fits on the current line
594 printf "@[123@[456@[7@]89@]A@]@."
595 avoids the rejection to the left of the inner boxes and print respec‐
596 tively "123456789" and "123456789A" . Note also that vertical boxes
597 never fit on a line whereas horizontal boxes always fully fit on the
598 current line. Opening a box may split a line whereas the contents may
599 have fit. If this behavior is problematic, it can be curtailed by set‐
600 ting the maximum indentation limit to margin - 1 . Note that setting
601 the maximum indentation limit to margin is invalid.
602
603 Nothing happens if d is smaller than 2.
604
605 If d is too large, the limit is set to the maximum admissible value
606 (which is greater than 10 ^ 9 ).
607
608 If d is greater or equal than the current margin, it is ignored, and
609 the current maximum indentation limit is kept.
610
611 See also Format.pp_set_geometry .
612
613
614
615 val pp_get_max_indent : formatter -> unit -> int
616
617
618
619
620 val get_max_indent : unit -> int
621
622 Return the maximum indentation limit (in characters).
623
624
625
626
627 Geometry
628 Geometric functions can be used to manipulate simultaneously the cou‐
629 pled variables, margin and maxixum indentation limit.
630
631 type geometry = {
632 max_indent : int ;
633 margin : int ;
634 }
635
636
637
638
639
640 val check_geometry : geometry -> bool
641
642 Check if the formatter geometry is valid: 1 < max_indent < margin
643
644
645
646
647 val pp_set_geometry : formatter -> max_indent:int -> margin:int -> unit
648
649
650
651
652 val set_geometry : max_indent:int -> margin:int -> unit
653
654
655
656
657 val pp_safe_set_geometry : formatter -> max_indent:int -> margin:int ->
658 unit
659
660
661
662
663 val safe_set_geometry : max_indent:int -> margin:int -> unit
664
665
666 pp_set_geometry ppf ~max_indent ~margin sets both the margin and maxi‐
667 mum indentation limit for ppf .
668
669 When 1 < max_indent < margin , pp_set_geometry ppf ~max_indent ~margin
670 is equivalent to pp_set_margin ppf margin; pp_set_max_indent ppf
671 max_indent ; and avoids the subtly incorrect pp_set_max_indent ppf
672 max_indent; pp_set_margin ppf margin ;
673
674 Outside of this domain, pp_set_geometry raises an invalid argument ex‐
675 ception whereas pp_safe_set_geometry does nothing.
676
677
678 Since 4.08.0
679
680
681
682 val pp_update_geometry : formatter -> (geometry -> geometry) -> unit
683
684
685 pp_update_geometry ppf (fun geo -> { geo with ... }) lets you update a
686 formatter's geometry in a way that is robust to extension of the geome‐
687 try record with new fields.
688
689 Raises an invalid argument exception if the returned geometry does not
690 satisfy Format.check_geometry .
691
692
693 Since 4.11.0
694
695
696
697 val update_geometry : (geometry -> geometry) -> unit
698
699
700
701
702 val pp_get_geometry : formatter -> unit -> geometry
703
704
705
706
707 val get_geometry : unit -> geometry
708
709 Return the current geometry of the formatter
710
711
712 Since 4.08.0
713
714
715
716
717 Maximum formatting depth
718 The maximum formatting depth is the maximum number of pretty-printing
719 boxes simultaneously open.
720
721 Material inside boxes nested deeper is printed as an ellipsis (more
722 precisely as the text returned by Format.get_ellipsis_text () ).
723
724 val pp_set_max_boxes : formatter -> int -> unit
725
726
727
728
729 val set_max_boxes : int -> unit
730
731
732 pp_set_max_boxes ppf max sets the maximum number of pretty-printing
733 boxes simultaneously open.
734
735 Material inside boxes nested deeper is printed as an ellipsis (more
736 precisely as the text returned by Format.get_ellipsis_text () ).
737
738 Nothing happens if max is smaller than 2.
739
740
741
742 val pp_get_max_boxes : formatter -> unit -> int
743
744
745
746
747 val get_max_boxes : unit -> int
748
749 Returns the maximum number of pretty-printing boxes allowed before el‐
750 lipsis.
751
752
753
754 val pp_over_max_boxes : formatter -> unit -> bool
755
756
757
758
759 val over_max_boxes : unit -> bool
760
761 Tests if the maximum number of pretty-printing boxes allowed have al‐
762 ready been opened.
763
764
765
766
767 Tabulation boxes
768 A tabulation box prints material on lines divided into cells of fixed
769 length. A tabulation box provides a simple way to display vertical col‐
770 umns of left adjusted text.
771
772 This box features command set_tab to define cell boundaries, and com‐
773 mand print_tab to move from cell to cell and split the line when there
774 is no more cells to print on the line.
775
776 Note: printing within tabulation box is line directed, so arbitrary
777 line splitting inside a tabulation box leads to poor rendering. Yet,
778 controlled use of tabulation boxes allows simple printing of columns
779 within module Format .
780
781 val pp_open_tbox : formatter -> unit -> unit
782
783
784
785
786 val open_tbox : unit -> unit
787
788
789 open_tbox () opens a new tabulation box.
790
791 This box prints lines separated into cells of fixed width.
792
793 Inside a tabulation box, special tabulation markers defines points of
794 interest on the line (for instance to delimit cell boundaries). Func‐
795 tion Format.set_tab sets a tabulation marker at insertion point.
796
797 A tabulation box features specific tabulation breaks to move to next
798 tabulation marker or split the line. Function Format.print_tbreak
799 prints a tabulation break.
800
801
802
803 val pp_close_tbox : formatter -> unit -> unit
804
805
806
807
808 val close_tbox : unit -> unit
809
810 Closes the most recently opened tabulation box.
811
812
813
814 val pp_set_tab : formatter -> unit -> unit
815
816
817
818
819 val set_tab : unit -> unit
820
821 Sets a tabulation marker at current insertion point.
822
823
824
825 val pp_print_tab : formatter -> unit -> unit
826
827
828
829
830 val print_tab : unit -> unit
831
832
833 print_tab () emits a 'next' tabulation break hint: if not already set
834 on a tabulation marker, the insertion point moves to the first tabula‐
835 tion marker on the right, or the pretty-printer splits the line and in‐
836 sertion point moves to the leftmost tabulation marker.
837
838 It is equivalent to print_tbreak 0 0 .
839
840
841
842 val pp_print_tbreak : formatter -> int -> int -> unit
843
844
845
846
847 val print_tbreak : int -> int -> unit
848
849
850 print_tbreak nspaces offset emits a 'full' tabulation break hint.
851
852 If not already set on a tabulation marker, the insertion point moves to
853 the first tabulation marker on the right and the pretty-printer prints
854 nspaces spaces.
855
856 If there is no next tabulation marker on the right, the pretty-printer
857 splits the line at this point, then insertion point moves to the left‐
858 most tabulation marker of the box.
859
860 If the pretty-printer splits the line, offset is added to the current
861 indentation.
862
863
864
865
866 Ellipsis
867 val pp_set_ellipsis_text : formatter -> string -> unit
868
869
870
871
872 val set_ellipsis_text : string -> unit
873
874 Set the text of the ellipsis printed when too many pretty-printing
875 boxes are open (a single dot, . , by default).
876
877
878
879 val pp_get_ellipsis_text : formatter -> unit -> string
880
881
882
883
884 val get_ellipsis_text : unit -> string
885
886 Return the text of the ellipsis.
887
888
889
890
891 Semantic tags
892 type stag = ..
893
894
895 Semantic tags (or simply tags) are user's defined annotations to asso‐
896 ciate user's specific operations to printed entities.
897
898 Common usage of semantic tags is text decoration to get specific font
899 or text size rendering for a display device, or marking delimitation of
900 entities (e.g. HTML or TeX elements or terminal escape sequences).
901 More sophisticated usage of semantic tags could handle dynamic modifi‐
902 cation of the pretty-printer behavior to properly print the material
903 within some specific tags. For instance, we can define an RGB tag like
904 so:
905 type stag += RGB of {r:int;g:int;b:int}
906
907
908 In order to properly delimit printed entities, a semantic tag must be
909 opened before and closed after the entity. Semantic tags must be prop‐
910 erly nested like parentheses using Format.pp_open_stag and For‐
911 mat.pp_close_stag .
912
913 Tag specific operations occur any time a tag is opened or closed, At
914 each occurrence, two kinds of operations are performed tag-marking and
915 tag-printing:
916
917 -The tag-marking operation is the simpler tag specific operation: it
918 simply writes a tag specific string into the output device of the for‐
919 matter. Tag-marking does not interfere with line-splitting computation.
920
921 -The tag-printing operation is the more involved tag specific opera‐
922 tion: it can print arbitrary material to the formatter. Tag-printing is
923 tightly linked to the current pretty-printer operations.
924
925 Roughly speaking, tag-marking is commonly used to get a better render‐
926 ing of texts in the rendering device, while tag-printing allows fine
927 tuning of printing routines to print the same entity differently ac‐
928 cording to the semantic tags (i.e. print additional material or even
929 omit parts of the output).
930
931 More precisely: when a semantic tag is opened or closed then both and
932 successive 'tag-printing' and 'tag-marking' operations occur:
933
934 -Tag-printing a semantic tag means calling the formatter specific func‐
935 tion print_open_stag (resp. print_close_stag ) with the name of the
936 tag as argument: that tag-printing function can then print any regular
937 material to the formatter (so that this material is enqueued as usual
938 in the formatter queue for further line splitting computation).
939
940 -Tag-marking a semantic tag means calling the formatter specific func‐
941 tion mark_open_stag (resp. mark_close_stag ) with the name of the tag
942 as argument: that tag-marking function can then return the 'tag-opening
943 marker' (resp. `tag-closing marker') for direct output into the output
944 device of the formatter.
945
946 Being written directly into the output device of the formatter, seman‐
947 tic tag marker strings are not considered as part of the printing mate‐
948 rial that drives line splitting (in other words, the length of the
949 strings corresponding to tag markers is considered as zero for line
950 splitting).
951
952 Thus, semantic tag handling is in some sense transparent to
953 pretty-printing and does not interfere with usual indentation. Hence, a
954 single pretty-printing routine can output both simple 'verbatim' mate‐
955 rial or richer decorated output depending on the treatment of tags. By
956 default, tags are not active, hence the output is not decorated with
957 tag information. Once set_tags is set to true , the pretty-printer en‐
958 gine honors tags and decorates the output accordingly.
959
960 Default tag-marking functions behave the HTML way: Format.tag are en‐
961 closed in "<" and ">" while other tags are ignored; hence, opening
962 marker for tag string "t" is "<t>" and closing marker is "</t>" .
963
964 Default tag-printing functions just do nothing.
965
966 Tag-marking and tag-printing functions are user definable and can be
967 set by calling Format.set_formatter_stag_functions .
968
969 Semantic tag operations may be set on or off with Format.set_tags .
970 Tag-marking operations may be set on or off with Format.set_mark_tags .
971 Tag-printing operations may be set on or off with Format.set_print_tags
972 .
973
974
975 type tag = string
976
977
978
979
980 type stag +=
981 | String_tag of tag (* String_tag s is a string tag s . String tags
982 can be inserted either by explicitly using the constructor String_tag
983 or by using the dedicated format syntax "@{<s> ... @}" .
984 *)
985
986
987
988
989
990 val pp_open_stag : formatter -> stag -> unit
991
992
993
994
995 val open_stag : stag -> unit
996
997
998 pp_open_stag ppf t opens the semantic tag named t .
999
1000 The print_open_stag tag-printing function of the formatter is called
1001 with t as argument; then the opening tag marker for t , as given by
1002 mark_open_stag t , is written into the output device of the formatter.
1003
1004
1005
1006 val pp_close_stag : formatter -> unit -> unit
1007
1008
1009
1010
1011 val close_stag : unit -> unit
1012
1013
1014 pp_close_stag ppf () closes the most recently opened semantic tag t .
1015
1016 The closing tag marker, as given by mark_close_stag t , is written into
1017 the output device of the formatter; then the print_close_stag
1018 tag-printing function of the formatter is called with t as argument.
1019
1020
1021
1022 val pp_set_tags : formatter -> bool -> unit
1023
1024
1025
1026
1027 val set_tags : bool -> unit
1028
1029
1030 pp_set_tags ppf b turns on or off the treatment of semantic tags (de‐
1031 fault is off).
1032
1033
1034
1035 val pp_set_print_tags : formatter -> bool -> unit
1036
1037
1038
1039
1040 val set_print_tags : bool -> unit
1041
1042
1043 pp_set_print_tags ppf b turns on or off the tag-printing operations.
1044
1045
1046
1047 val pp_set_mark_tags : formatter -> bool -> unit
1048
1049
1050
1051
1052 val set_mark_tags : bool -> unit
1053
1054
1055 pp_set_mark_tags ppf b turns on or off the tag-marking operations.
1056
1057
1058
1059 val pp_get_print_tags : formatter -> unit -> bool
1060
1061
1062
1063
1064 val get_print_tags : unit -> bool
1065
1066 Return the current status of tag-printing operations.
1067
1068
1069
1070 val pp_get_mark_tags : formatter -> unit -> bool
1071
1072
1073
1074
1075 val get_mark_tags : unit -> bool
1076
1077 Return the current status of tag-marking operations.
1078
1079
1080
1081 val pp_set_formatter_out_channel : formatter -> out_channel -> unit
1082
1083
1084 Redirecting the standard formatter output
1085 val set_formatter_out_channel : out_channel -> unit
1086
1087 Redirect the standard pretty-printer output to the given channel. (All
1088 the output functions of the standard formatter are set to the default
1089 output functions printing to the given channel.)
1090
1091
1092 set_formatter_out_channel is equivalent to Format.pp_set_format‐
1093 ter_out_channel std_formatter .
1094
1095
1096
1097 val pp_set_formatter_output_functions : formatter -> (string -> int ->
1098 int -> unit) -> (unit -> unit) -> unit
1099
1100
1101
1102
1103 val set_formatter_output_functions : (string -> int -> int -> unit) ->
1104 (unit -> unit) -> unit
1105
1106
1107 pp_set_formatter_output_functions ppf out flush redirects the standard
1108 pretty-printer output functions to the functions out and flush .
1109
1110 The out function performs all the pretty-printer string output. It is
1111 called with a string s , a start position p , and a number of charac‐
1112 ters n ; it is supposed to output characters p to p + n - 1 of s .
1113
1114 The flush function is called whenever the pretty-printer is flushed
1115 (via conversion %! , or pretty-printing indications @? or @. , or
1116 using low level functions print_flush or print_newline ).
1117
1118
1119
1120 val pp_get_formatter_output_functions : formatter -> unit -> (string ->
1121 int -> int -> unit) * (unit -> unit)
1122
1123
1124
1125
1126 val get_formatter_output_functions : unit -> (string -> int -> int ->
1127 unit) * (unit -> unit)
1128
1129 Return the current output functions of the standard pretty-printer.
1130
1131
1132
1133
1134 Redefining formatter output
1135 The Format module is versatile enough to let you completely redefine
1136 the meaning of pretty-printing output: you may provide your own func‐
1137 tions to define how to handle indentation, line splitting, and even
1138 printing of all the characters that have to be printed!
1139
1140 Redefining output functions
1141 type formatter_out_functions = {
1142 out_string : string -> int -> int -> unit ;
1143 out_flush : unit -> unit ;
1144 out_newline : unit -> unit ;
1145 out_spaces : int -> unit ;
1146 out_indent : int -> unit ; (* .B "Since" 4.06.0
1147 *)
1148 }
1149
1150
1151 The set of output functions specific to a formatter:
1152
1153 -the out_string function performs all the pretty-printer string output.
1154 It is called with a string s , a start position p , and a number of
1155 characters n ; it is supposed to output characters p to p + n - 1 of s
1156 .
1157
1158 -the out_flush function flushes the pretty-printer output device.
1159
1160 - out_newline is called to open a new line when the pretty-printer
1161 splits the line.
1162
1163 -the out_spaces function outputs spaces when a break hint leads to spa‐
1164 ces instead of a line split. It is called with the number of spaces to
1165 output.
1166
1167 -the out_indent function performs new line indentation when the
1168 pretty-printer splits the line. It is called with the indentation value
1169 of the new line.
1170
1171 By default:
1172
1173 -fields out_string and out_flush are output device specific; (e.g.
1174 output_string and flush for a out_channel device, or Buffer.add_sub‐
1175 string and ignore for a Buffer.t output device),
1176
1177 -field out_newline is equivalent to out_string "\n" 0 1 ;
1178
1179 -fields out_spaces and out_indent are equivalent to out_string
1180 (String.make n ' ') 0 n .
1181
1182
1183
1184 Since 4.01.0
1185
1186
1187
1188 val pp_set_formatter_out_functions : formatter -> formatter_out_func‐
1189 tions -> unit
1190
1191
1192
1193
1194 val set_formatter_out_functions : formatter_out_functions -> unit
1195
1196
1197 pp_set_formatter_out_functions ppf out_funs Set all the pretty-printer
1198 output functions of ppf to those of argument out_funs ,
1199
1200 This way, you can change the meaning of indentation (which can be some‐
1201 thing else than just printing space characters) and the meaning of new
1202 lines opening (which can be connected to any other action needed by the
1203 application at hand).
1204
1205 Reasonable defaults for functions out_spaces and out_newline are re‐
1206 spectively out_funs.out_string (String.make n ' ') 0 n and
1207 out_funs.out_string "\n" 0 1 .
1208
1209
1210 Since 4.01.0
1211
1212
1213
1214 val pp_get_formatter_out_functions : formatter -> unit -> format‐
1215 ter_out_functions
1216
1217
1218
1219
1220 val get_formatter_out_functions : unit -> formatter_out_functions
1221
1222 Return the current output functions of the pretty-printer, including
1223 line splitting and indentation functions. Useful to record the current
1224 setting and restore it afterwards.
1225
1226
1227 Since 4.01.0
1228
1229
1230
1231
1232 Redefining semantic tag operations
1233 type formatter_stag_functions = {
1234 mark_open_stag : stag -> string ;
1235 mark_close_stag : stag -> string ;
1236 print_open_stag : stag -> unit ;
1237 print_close_stag : stag -> unit ;
1238 }
1239
1240
1241 The semantic tag handling functions specific to a formatter: mark ver‐
1242 sions are the 'tag-marking' functions that associate a string marker to
1243 a tag in order for the pretty-printing engine to write those markers as
1244 0 length tokens in the output device of the formatter. print versions
1245 are the 'tag-printing' functions that can perform regular printing when
1246 a tag is closed or opened.
1247
1248
1249
1250 val pp_set_formatter_stag_functions : formatter -> formatter_stag_func‐
1251 tions -> unit
1252
1253
1254
1255
1256 val set_formatter_stag_functions : formatter_stag_functions -> unit
1257
1258
1259 pp_set_formatter_stag_functions ppf tag_funs changes the meaning of
1260 opening and closing semantic tag operations to use the functions in
1261 tag_funs when printing on ppf .
1262
1263 When opening a semantic tag with name t , the string t is passed to the
1264 opening tag-marking function (the mark_open_stag field of the record
1265 tag_funs ), that must return the opening tag marker for that name. When
1266 the next call to close_stag () happens, the semantic tag name t is sent
1267 back to the closing tag-marking function (the mark_close_stag field of
1268 record tag_funs ), that must return a closing tag marker for that name.
1269
1270 The print_ field of the record contains the tag-printing functions that
1271 are called at tag opening and tag closing time, to output regular mate‐
1272 rial in the pretty-printer queue.
1273
1274
1275
1276 val pp_get_formatter_stag_functions : formatter -> unit -> format‐
1277 ter_stag_functions
1278
1279
1280
1281
1282 val get_formatter_stag_functions : unit -> formatter_stag_functions
1283
1284 Return the current semantic tag operation functions of the standard
1285 pretty-printer.
1286
1287
1288
1289
1290 Defining formatters
1291 Defining new formatters permits unrelated output of material in paral‐
1292 lel on several output devices. All the parameters of a formatter are
1293 local to the formatter: right margin, maximum indentation limit, maxi‐
1294 mum number of pretty-printing boxes simultaneously open, ellipsis, and
1295 so on, are specific to each formatter and may be fixed independently.
1296
1297 For instance, given a Buffer.t buffer b , Format.formatter_of_buffer b
1298 returns a new formatter using buffer b as its output device. Simi‐
1299 larly, given a out_channel output channel oc , Format.format‐
1300 ter_of_out_channel oc returns a new formatter using channel oc as its
1301 output device.
1302
1303 Alternatively, given out_funs , a complete set of output functions for
1304 a formatter, then Format.formatter_of_out_functions out_funs computes a
1305 new formatter using those functions for output.
1306
1307 val formatter_of_out_channel : out_channel -> formatter
1308
1309
1310 formatter_of_out_channel oc returns a new formatter writing to the cor‐
1311 responding output channel oc .
1312
1313
1314
1315 val std_formatter : formatter
1316
1317 The standard formatter to write to standard output.
1318
1319 It is defined as Format.formatter_of_out_channel stdout .
1320
1321
1322
1323 val err_formatter : formatter
1324
1325 A formatter to write to standard error.
1326
1327 It is defined as Format.formatter_of_out_channel stderr .
1328
1329
1330
1331 val formatter_of_buffer : Buffer.t -> formatter
1332
1333
1334 formatter_of_buffer b returns a new formatter writing to buffer b . At
1335 the end of pretty-printing, the formatter must be flushed using For‐
1336 mat.pp_print_flush or Format.pp_print_newline , to print all the pend‐
1337 ing material into the buffer.
1338
1339
1340
1341 val stdbuf : Buffer.t
1342
1343 The string buffer in which str_formatter writes.
1344
1345
1346
1347 val str_formatter : formatter
1348
1349 A formatter to output to the Format.stdbuf string buffer.
1350
1351
1352 str_formatter is defined as Format.formatter_of_buffer Format.stdbuf .
1353
1354
1355
1356 val flush_str_formatter : unit -> string
1357
1358 Returns the material printed with str_formatter , flushes the formatter
1359 and resets the corresponding buffer.
1360
1361
1362
1363 val make_formatter : (string -> int -> int -> unit) -> (unit -> unit)
1364 -> formatter
1365
1366
1367 make_formatter out flush returns a new formatter that outputs with
1368 function out , and flushes with function flush .
1369
1370 For instance,
1371 make_formatter
1372 (Stdlib.output oc)
1373 (fun () -> Stdlib.flush oc)
1374 returns a formatter to the out_channel oc .
1375
1376
1377
1378 val formatter_of_out_functions : formatter_out_functions -> formatter
1379
1380
1381 formatter_of_out_functions out_funs returns a new formatter that writes
1382 with the set of output functions out_funs .
1383
1384 See definition of type Format.formatter_out_functions for the meaning
1385 of argument out_funs .
1386
1387
1388 Since 4.06.0
1389
1390
1391
1392
1393 Symbolic pretty-printing
1394 Symbolic pretty-printing is pretty-printing using a symbolic formatter,
1395 i.e. a formatter that outputs symbolic pretty-printing items.
1396
1397 When using a symbolic formatter, all regular pretty-printing activities
1398 occur but output material is symbolic and stored in a buffer of output
1399 items. At the end of pretty-printing, flushing the output buffer al‐
1400 lows post-processing of symbolic output before performing low level
1401 output operations.
1402
1403 In practice, first define a symbolic output buffer b using:
1404
1405 - let sob = make_symbolic_output_buffer () . Then define a symbolic
1406 formatter with:
1407
1408 - let ppf = formatter_of_symbolic_output_buffer sob
1409
1410 Use symbolic formatter ppf as usual, and retrieve symbolic items at end
1411 of pretty-printing by flushing symbolic output buffer sob with:
1412
1413 - flush_symbolic_output_buffer sob .
1414
1415
1416 type symbolic_output_item =
1417 | Output_flush (* symbolic flush command
1418 *)
1419 | Output_newline (* symbolic newline command
1420 *)
1421 | Output_string of string
1422 (* Output_string s : symbolic output for string s
1423
1424 *)
1425 | Output_spaces of int
1426 (* Output_spaces n : symbolic command to output n spaces
1427 *)
1428 | Output_indent of int
1429 (* Output_indent i : symbolic indentation of size i
1430
1431 *)
1432
1433
1434 Items produced by symbolic pretty-printers
1435
1436
1437 Since 4.06.0
1438
1439
1440 type symbolic_output_buffer
1441
1442
1443 The output buffer of a symbolic pretty-printer.
1444
1445
1446 Since 4.06.0
1447
1448
1449
1450 val make_symbolic_output_buffer : unit -> symbolic_output_buffer
1451
1452
1453 make_symbolic_output_buffer () returns a fresh buffer for symbolic out‐
1454 put.
1455
1456
1457 Since 4.06.0
1458
1459
1460
1461 val clear_symbolic_output_buffer : symbolic_output_buffer -> unit
1462
1463
1464 clear_symbolic_output_buffer sob resets buffer sob .
1465
1466
1467 Since 4.06.0
1468
1469
1470
1471 val get_symbolic_output_buffer : symbolic_output_buffer -> sym‐
1472 bolic_output_item list
1473
1474
1475 get_symbolic_output_buffer sob returns the contents of buffer sob .
1476
1477
1478 Since 4.06.0
1479
1480
1481
1482 val flush_symbolic_output_buffer : symbolic_output_buffer -> sym‐
1483 bolic_output_item list
1484
1485
1486 flush_symbolic_output_buffer sob returns the contents of buffer sob and
1487 resets buffer sob . flush_symbolic_output_buffer sob is equivalent to
1488 let items = get_symbolic_output_buffer sob in
1489 clear_symbolic_output_buffer sob; items
1490
1491
1492
1493 Since 4.06.0
1494
1495
1496
1497 val add_symbolic_output_item : symbolic_output_buffer -> symbolic_out‐
1498 put_item -> unit
1499
1500
1501 add_symbolic_output_item sob itm adds item itm to buffer sob .
1502
1503
1504 Since 4.06.0
1505
1506
1507
1508 val formatter_of_symbolic_output_buffer : symbolic_output_buffer ->
1509 formatter
1510
1511
1512 formatter_of_symbolic_output_buffer sob returns a symbolic formatter
1513 that outputs to symbolic_output_buffer sob .
1514
1515
1516 Since 4.06.0
1517
1518
1519
1520
1521 Convenience formatting functions.
1522 val pp_print_list : ?pp_sep:(formatter -> unit -> unit) -> (formatter
1523 -> 'a -> unit) -> formatter -> 'a list -> unit
1524
1525
1526 pp_print_list ?pp_sep pp_v ppf l prints items of list l , using pp_v to
1527 print each item, and calling pp_sep between items ( pp_sep defaults to
1528 Format.pp_print_cut . Does nothing on empty lists.
1529
1530
1531 Since 4.02.0
1532
1533
1534
1535 val pp_print_seq : ?pp_sep:(formatter -> unit -> unit) -> (formatter ->
1536 'a -> unit) -> formatter -> 'a Seq.t -> unit
1537
1538
1539 pp_print_seq ?pp_sep pp_v ppf s prints items of sequence s , using pp_v
1540 to print each item, and calling pp_sep between items ( pp_sep defaults
1541 to Format.pp_print_cut . Does nothing on empty sequences.
1542
1543 This function does not terminate on infinite sequences.
1544
1545
1546 Since 4.12
1547
1548
1549
1550 val pp_print_text : formatter -> string -> unit
1551
1552
1553 pp_print_text ppf s prints s with spaces and newlines respectively
1554 printed using Format.pp_print_space and Format.pp_force_newline .
1555
1556
1557 Since 4.02.0
1558
1559
1560
1561 val pp_print_option : ?none:(formatter -> unit -> unit) -> (formatter
1562 -> 'a -> unit) -> formatter -> 'a option -> unit
1563
1564
1565 pp_print_option ?none pp_v ppf o prints o on ppf using pp_v if o is
1566 Some v and none if it is None . none prints nothing by default.
1567
1568
1569 Since 4.08
1570
1571
1572
1573 val pp_print_result : ok:(formatter -> 'a -> unit) -> error:(formatter
1574 -> 'e -> unit) -> formatter -> ('a, 'e) result -> unit
1575
1576
1577 pp_print_result ~ok ~error ppf r prints r on ppf using ok if r is Ok _
1578 and error if r is Error _ .
1579
1580
1581 Since 4.08
1582
1583
1584
1585
1586 Formatted pretty-printing
1587 Module Format provides a complete set of printf like functions for
1588 pretty-printing using format string specifications.
1589
1590 Specific annotations may be added in the format strings to give
1591 pretty-printing commands to the pretty-printing engine.
1592
1593 Those annotations are introduced in the format strings using the @
1594 character. For instance, @ means a space break, @, means a cut, @[
1595 opens a new box, and @] closes the last open box.
1596
1597 val fprintf : formatter -> ('a, formatter, unit) format -> 'a
1598
1599
1600
1601
1602
1603 fprintf ff fmt arg1 ... argN formats the arguments arg1 to argN accord‐
1604 ing to the format string fmt , and outputs the resulting string on the
1605 formatter ff .
1606
1607 The format string fmt is a character string which contains three types
1608 of objects: plain characters and conversion specifications as specified
1609 in the Printf module, and pretty-printing indications specific to the
1610 Format module.
1611
1612 The pretty-printing indication characters are introduced by a @ charac‐
1613 ter, and their meanings are:
1614
1615 - @[ : open a pretty-printing box. The type and offset of the box may
1616 be optionally specified with the following syntax: the < character,
1617 followed by an optional box type indication, then an optional integer
1618 offset, and the closing > character. Pretty-printing box type is one
1619 of h , v , hv , b , or hov . ' h ' stands for an 'horizontal'
1620 pretty-printing box, ' v ' stands for a 'vertical' pretty-printing box,
1621 ' hv ' stands for an 'horizontal/vertical' pretty-printing box, ' b '
1622 stands for an 'horizontal-or-vertical' pretty-printing box demonstrat‐
1623 ing indentation, ' hov ' stands a simple 'horizontal-or-vertical'
1624 pretty-printing box. For instance, @[<hov 2> opens an 'horizon‐
1625 tal-or-vertical' pretty-printing box with indentation 2 as obtained
1626 with open_hovbox 2 . For more details about pretty-printing boxes, see
1627 the various box opening functions open_*box .
1628
1629 - @] : close the most recently opened pretty-printing box.
1630
1631 - @, : output a 'cut' break hint, as with print_cut () .
1632
1633 - @ : output a 'space' break hint, as with print_space () .
1634
1635 - @; : output a 'full' break hint as with print_break . The nspaces and
1636 offset parameters of the break hint may be optionally specified with
1637 the following syntax: the < character, followed by an integer nspaces
1638 value, then an integer offset , and a closing > character. If no pa‐
1639 rameters are provided, the good break defaults to a 'space' break hint.
1640
1641 - @. : flush the pretty-printer and split the line, as with print_new‐
1642 line () .
1643
1644 - @<n> : print the following item as if it were of length n . Hence,
1645 printf "@<0>%s" arg prints arg as a zero length string. If @<n> is not
1646 followed by a conversion specification, then the following character of
1647 the format is printed as if it were of length n .
1648
1649 - @{ : open a semantic tag. The name of the tag may be optionally spec‐
1650 ified with the following syntax: the < character, followed by an op‐
1651 tional string specification, and the closing > character. The string
1652 specification is any character string that does not contain the closing
1653 character '>' . If omitted, the tag name defaults to the empty string.
1654 For more details about semantic tags, see the functions For‐
1655 mat.open_stag and Format.close_stag .
1656
1657 - @} : close the most recently opened semantic tag.
1658
1659 - @? : flush the pretty-printer as with print_flush () . This is
1660 equivalent to the conversion %! .
1661
1662 - @\n : force a newline, as with force_newline () , not the normal way
1663 of pretty-printing, you should prefer using break hints inside a verti‐
1664 cal pretty-printing box.
1665
1666 Note: To prevent the interpretation of a @ character as a pretty-print‐
1667 ing indication, escape it with a % character. Old quotation mode @@ is
1668 deprecated since it is not compatible with formatted input interpreta‐
1669 tion of character '@' .
1670
1671 Example: printf "@[%s@ %d@]@." "x =" 1 is equivalent to open_box ();
1672 print_string "x ="; print_space ();
1673 print_int 1; close_box (); print_newline () . It prints x = 1
1674 within a pretty-printing 'horizontal-or-vertical' box.
1675
1676 val printf : ('a, formatter, unit) format -> 'a
1677
1678 Same as fprintf above, but output on std_formatter .
1679
1680
1681
1682 val eprintf : ('a, formatter, unit) format -> 'a
1683
1684 Same as fprintf above, but output on err_formatter .
1685
1686
1687
1688 val sprintf : ('a, unit, string) format -> 'a
1689
1690 Same as printf above, but instead of printing on a formatter, returns a
1691 string containing the result of formatting the arguments. Note that
1692 the pretty-printer queue is flushed at the end of each call to sprintf
1693 .
1694
1695 In case of multiple and related calls to sprintf to output material on
1696 a single string, you should consider using fprintf with the predefined
1697 formatter str_formatter and call flush_str_formatter () to get the fi‐
1698 nal result.
1699
1700 Alternatively, you can use Format.fprintf with a formatter writing to a
1701 buffer of your own: flushing the formatter and the buffer at the end of
1702 pretty-printing returns the desired string.
1703
1704
1705
1706 val asprintf : ('a, formatter, unit, string) format4 -> 'a
1707
1708 Same as printf above, but instead of printing on a formatter, returns a
1709 string containing the result of formatting the arguments. The type of
1710 asprintf is general enough to interact nicely with %a conversions.
1711
1712
1713 Since 4.01.0
1714
1715
1716
1717 val dprintf : ('a, formatter, unit, formatter -> unit) format4 -> 'a
1718
1719 Same as Format.fprintf , except the formatter is the last argument.
1720 dprintf "..." a b c is a function of type formatter -> unit which can
1721 be given to a format specifier %t .
1722
1723 This can be used as a replacement for Format.asprintf to delay format‐
1724 ting decisions. Using the string returned by Format.asprintf in a for‐
1725 matting context forces formatting decisions to be taken in isolation,
1726 and the final string may be created prematurely. Format.dprintf allows
1727 delay of formatting decisions until the final formatting context is
1728 known. For example:
1729 let t = Format.dprintf "%i@ %i@ %i" 1 2 3 in
1730 ...
1731 Format.printf "@[<v>%t@]" t
1732
1733
1734
1735 Since 4.08.0
1736
1737
1738
1739 val ifprintf : formatter -> ('a, formatter, unit) format -> 'a
1740
1741 Same as fprintf above, but does not print anything. Useful to ignore
1742 some material when conditionally printing.
1743
1744
1745 Since 3.10.0
1746
1747
1748
1749
1750 Formatted Pretty-Printing with continuations.
1751
1752 val kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1753 'a) format4 -> 'b
1754
1755 Same as fprintf above, but instead of returning immediately, passes the
1756 formatter to its first argument at the end of printing.
1757
1758
1759
1760 val kdprintf : ((formatter -> unit) -> 'a) -> ('b, formatter, unit, 'a)
1761 format4 -> 'b
1762
1763 Same as Format.dprintf above, but instead of returning immediately,
1764 passes the suspended printer to its first argument at the end of print‐
1765 ing.
1766
1767
1768 Since 4.08.0
1769
1770
1771
1772 val ikfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1773 'a) format4 -> 'b
1774
1775 Same as kfprintf above, but does not print anything. Useful to ignore
1776 some material when conditionally printing.
1777
1778
1779 Since 3.12.0
1780
1781
1782
1783 val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b
1784
1785 Same as sprintf above, but instead of returning the string, passes it
1786 to the first argument.
1787
1788
1789
1790 val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) format4 ->
1791 'b
1792
1793 Same as asprintf above, but instead of returning the string, passes it
1794 to the first argument.
1795
1796
1797 Since 4.03
1798
1799
1800
1801
1802 Deprecated
1803 val bprintf : Buffer.t -> ('a, formatter, unit) format -> 'a
1804
1805 Deprecated. This function is error prone. Do not use it. This func‐
1806 tion is neither compositional nor incremental, since it flushes the
1807 pretty-printer queue at each call.
1808
1809 If you need to print to some buffer b , you must first define a format‐
1810 ter writing to b , using let to_b = formatter_of_buffer b ; then use
1811 regular calls to Format.fprintf with formatter to_b .
1812
1813
1814
1815 val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b
1816
1817 Deprecated. An alias for ksprintf .
1818
1819
1820
1821 val set_all_formatter_output_functions : out:(string -> int -> int ->
1822 unit) -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int
1823 -> unit) -> unit
1824
1825 Deprecated. Subsumed by set_formatter_out_functions .
1826
1827
1828
1829 val get_all_formatter_output_functions : unit -> (string -> int -> int
1830 -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
1831
1832 Deprecated. Subsumed by get_formatter_out_functions .
1833
1834
1835
1836 val pp_set_all_formatter_output_functions : formatter -> out:(string ->
1837 int -> int -> unit) -> flush:(unit -> unit) -> newline:(unit -> unit)
1838 -> spaces:(int -> unit) -> unit
1839
1840 Deprecated. Subsumed by pp_set_formatter_out_functions .
1841
1842
1843
1844 val pp_get_all_formatter_output_functions : formatter -> unit ->
1845 (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int
1846 -> unit)
1847
1848 Deprecated. Subsumed by pp_get_formatter_out_functions .
1849
1850
1851
1852
1853 String tags
1854 val pp_open_tag : formatter -> tag -> unit
1855
1856 Deprecated. Subsumed by Format.pp_open_stag .
1857
1858
1859
1860 val open_tag : tag -> unit
1861
1862 Deprecated. Subsumed by Format.open_stag .
1863
1864
1865
1866 val pp_close_tag : formatter -> unit -> unit
1867
1868 Deprecated. Subsumed by Format.pp_close_stag .
1869
1870
1871
1872 val close_tag : unit -> unit
1873
1874 Deprecated. Subsumed by Format.close_stag .
1875
1876
1877 type formatter_tag_functions = {
1878 mark_open_tag : tag -> string ;
1879 mark_close_tag : tag -> string ;
1880 print_open_tag : tag -> unit ;
1881 print_close_tag : tag -> unit ;
1882 }
1883
1884
1885 Deprecated. Subsumed by Format.formatter_stag_functions .
1886
1887
1888
1889 val pp_set_formatter_tag_functions : formatter -> formatter_tag_func‐
1890 tions -> unit
1891
1892 Deprecated. Subsumed by Format.pp_set_formatter_stag_functions .
1893
1894
1895 This function will erase non-string tag formatting functions.
1896
1897
1898
1899 val set_formatter_tag_functions : formatter_tag_functions -> unit
1900
1901 Deprecated. Subsumed by Format.set_formatter_stag_functions .
1902
1903
1904
1905 val pp_get_formatter_tag_functions : formatter -> unit -> format‐
1906 ter_tag_functions
1907
1908 Deprecated. Subsumed by Format.pp_get_formatter_stag_functions .
1909
1910
1911
1912 val get_formatter_tag_functions : unit -> formatter_tag_functions
1913
1914 Deprecated. Subsumed by Format.get_formatter_stag_functions .
1915
1916
1917
1918
1919
1920OCamldoc 2021-07-22 Format(3)