1Format(3)                        OCaml library                       Format(3)
2
3
4

NAME

6       Format - Pretty-printing.
7

Module

9       Module   Format
10

Documentation

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 &nbsp; 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)
Impressum