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 ;
1147        }
1148
1149
1150       The set of output functions specific to a formatter:
1151
1152       -the out_string function performs all the pretty-printer string output.
1153       It  is  called  with  a string s , a start position p , and a number of
1154       characters n ; it is supposed to output characters p to p + n - 1 of  s
1155       .
1156
1157       -the out_flush function flushes the pretty-printer output device.
1158
1159       -  out_newline  is  called  to  open a new line when the pretty-printer
1160       splits the line.
1161
1162       -the out_spaces function outputs spaces when a break hint leads to spa‐
1163       ces  instead of a line split. It is called with the number of spaces to
1164       output.
1165
1166       -the  out_indent  function  performs  new  line  indentation  when  the
1167       pretty-printer splits the line. It is called with the indentation value
1168       of the new line.
1169
1170       By default:
1171
1172       -fields out_string and out_flush  are  output  device  specific;  (e.g.
1173       output_string  and  flush  for a out_channel device, or Buffer.add_sub‐
1174       string and ignore for a Buffer.t output device),
1175
1176       -field out_newline is equivalent to out_string "\n" 0 1 ;
1177
1178       -fields  out_spaces  and  out_indent  are  equivalent   to   out_string
1179       (String.make n ' ') 0 n .
1180
1181
1182
1183       Since 4.01.0
1184
1185
1186
1187       val  pp_set_formatter_out_functions  : formatter -> formatter_out_func‐
1188       tions -> unit
1189
1190
1191
1192
1193       val set_formatter_out_functions : formatter_out_functions -> unit
1194
1195
1196       pp_set_formatter_out_functions ppf out_funs Set all the  pretty-printer
1197       output functions of ppf to those of argument out_funs ,
1198
1199       This way, you can change the meaning of indentation (which can be some‐
1200       thing else than just printing space characters) and the meaning of  new
1201       lines opening (which can be connected to any other action needed by the
1202       application at hand).
1203
1204       Reasonable defaults for functions out_spaces and  out_newline  are  re‐
1205       spectively   out_funs.out_string   (String.make   n   '   ')  0  n  and
1206       out_funs.out_string "\n" 0 1 .
1207
1208
1209       Since 4.01.0
1210
1211
1212
1213       val pp_get_formatter_out_functions  :  formatter  ->  unit  ->  format‐
1214       ter_out_functions
1215
1216
1217
1218
1219       val get_formatter_out_functions : unit -> formatter_out_functions
1220
1221       Return  the  current  output functions of the pretty-printer, including
1222       line splitting and indentation functions. Useful to record the  current
1223       setting and restore it afterwards.
1224
1225
1226       Since 4.01.0
1227
1228
1229
1230
1231   Redefining semantic tag operations
1232       type formatter_stag_functions = {
1233        mark_open_stag : stag -> string ;
1234        mark_close_stag : stag -> string ;
1235        print_open_stag : stag -> unit ;
1236        print_close_stag : stag -> unit ;
1237        }
1238
1239
1240       The  semantic tag handling functions specific to a formatter: mark ver‐
1241       sions are the 'tag-marking' functions that associate a string marker to
1242       a tag in order for the pretty-printing engine to write those markers as
1243       0 length tokens in the output device of the formatter.  print  versions
1244       are the 'tag-printing' functions that can perform regular printing when
1245       a tag is closed or opened.
1246
1247
1248
1249       val pp_set_formatter_stag_functions : formatter -> formatter_stag_func‐
1250       tions -> unit
1251
1252
1253
1254
1255       val set_formatter_stag_functions : formatter_stag_functions -> unit
1256
1257
1258       pp_set_formatter_stag_functions  ppf  tag_funs  changes  the meaning of
1259       opening and closing semantic tag operations to  use  the  functions  in
1260       tag_funs when printing on ppf .
1261
1262       When opening a semantic tag with name t , the string t is passed to the
1263       opening tag-marking function (the mark_open_stag field  of  the  record
1264       tag_funs ), that must return the opening tag marker for that name. When
1265       the next call to close_stag () happens, the semantic tag name t is sent
1266       back  to the closing tag-marking function (the mark_close_stag field of
1267       record tag_funs ), that must return a closing tag marker for that name.
1268
1269       The print_ field of the record contains the tag-printing functions that
1270       are called at tag opening and tag closing time, to output regular mate‐
1271       rial in the pretty-printer queue.
1272
1273
1274
1275       val pp_get_formatter_stag_functions :  formatter  ->  unit  ->  format‐
1276       ter_stag_functions
1277
1278
1279
1280
1281       val get_formatter_stag_functions : unit -> formatter_stag_functions
1282
1283       Return  the  current  semantic  tag operation functions of the standard
1284       pretty-printer.
1285
1286
1287
1288
1289   Defining formatters
1290       Defining new formatters permits unrelated output of material in  paral‐
1291       lel  on  several output devices.  All the parameters of a formatter are
1292       local to the formatter: right margin, maximum indentation limit,  maxi‐
1293       mum  number of pretty-printing boxes simultaneously open, ellipsis, and
1294       so on, are specific to each formatter and may be fixed independently.
1295
1296       For instance, given a Buffer.t buffer b , Format.formatter_of_buffer  b
1297       returns  a  new  formatter  using buffer b as its output device.  Simi‐
1298       larly,  given  a  out_channel  output  channel  oc   ,   Format.format‐
1299       ter_of_out_channel  oc  returns a new formatter using channel oc as its
1300       output device.
1301
1302       Alternatively, given out_funs , a complete set of output functions  for
1303       a formatter, then Format.formatter_of_out_functions out_funs computes a
1304       new formatter using those functions for output.
1305
1306       val formatter_of_out_channel : out_channel -> formatter
1307
1308
1309       formatter_of_out_channel oc returns a new formatter writing to the cor‐
1310       responding output channel oc .
1311
1312
1313
1314       val std_formatter : formatter
1315
1316       The standard formatter to write to standard output.
1317
1318       It is defined as Format.formatter_of_out_channel stdout .
1319
1320
1321
1322       val err_formatter : formatter
1323
1324       A formatter to write to standard error.
1325
1326       It is defined as Format.formatter_of_out_channel stderr .
1327
1328
1329
1330       val formatter_of_buffer : Buffer.t -> formatter
1331
1332
1333       formatter_of_buffer  b returns a new formatter writing to buffer b . At
1334       the end of pretty-printing, the formatter must be  flushed  using  For‐
1335       mat.pp_print_flush  or Format.pp_print_newline , to print all the pend‐
1336       ing material into the buffer.
1337
1338
1339
1340       val stdbuf : Buffer.t
1341
1342       The string buffer in which str_formatter writes.
1343
1344
1345
1346       val str_formatter : formatter
1347
1348       A formatter to output to the Format.stdbuf string buffer.
1349
1350
1351       str_formatter is defined as Format.formatter_of_buffer Format.stdbuf .
1352
1353
1354
1355       val flush_str_formatter : unit -> string
1356
1357       Returns the material printed with str_formatter , flushes the formatter
1358       and resets the corresponding buffer.
1359
1360
1361
1362       val  make_formatter  : (string -> int -> int -> unit) -> (unit -> unit)
1363       -> formatter
1364
1365
1366       make_formatter out flush returns a  new  formatter  that  outputs  with
1367       function out , and flushes with function flush .
1368
1369       For instance,
1370           make_formatter
1371             (Stdlib.output oc)
1372             (fun () -> Stdlib.flush oc)
1373       returns a formatter to the out_channel oc .
1374
1375
1376
1377       val formatter_of_out_functions : formatter_out_functions -> formatter
1378
1379
1380       formatter_of_out_functions out_funs returns a new formatter that writes
1381       with the set of output functions out_funs .
1382
1383       See definition of type Format.formatter_out_functions for  the  meaning
1384       of argument out_funs .
1385
1386
1387       Since 4.06.0
1388
1389
1390
1391
1392   Symbolic pretty-printing
1393       Symbolic pretty-printing is pretty-printing using a symbolic formatter,
1394       i.e. a formatter that outputs symbolic pretty-printing items.
1395
1396       When using a symbolic formatter, all regular pretty-printing activities
1397       occur  but output material is symbolic and stored in a buffer of output
1398       items.  At the end of pretty-printing, flushing the output  buffer  al‐
1399       lows  post-processing  of  symbolic  output before performing low level
1400       output operations.
1401
1402       In practice, first define a symbolic output buffer b using:
1403
1404       - let sob = make_symbolic_output_buffer () .  Then  define  a  symbolic
1405       formatter with:
1406
1407       - let ppf = formatter_of_symbolic_output_buffer sob
1408
1409       Use symbolic formatter ppf as usual, and retrieve symbolic items at end
1410       of pretty-printing by flushing symbolic output buffer sob with:
1411
1412       - flush_symbolic_output_buffer sob .
1413
1414
1415       type symbolic_output_item =
1416        | Output_flush  (* symbolic flush command
1417        *)
1418        | Output_newline  (* symbolic newline command
1419        *)
1420        | Output_string of string
1421         (* Output_string s : symbolic output for string s
1422
1423        *)
1424        | Output_spaces of int
1425         (* Output_spaces n : symbolic command to output n spaces
1426        *)
1427        | Output_indent of int
1428         (* Output_indent i : symbolic indentation of size i
1429
1430        *)
1431
1432
1433       Items produced by symbolic pretty-printers
1434
1435
1436       Since 4.06.0
1437
1438
1439       type symbolic_output_buffer
1440
1441
1442       The output buffer of a symbolic pretty-printer.
1443
1444
1445       Since 4.06.0
1446
1447
1448
1449       val make_symbolic_output_buffer : unit -> symbolic_output_buffer
1450
1451
1452       make_symbolic_output_buffer () returns a fresh buffer for symbolic out‐
1453       put.
1454
1455
1456       Since 4.06.0
1457
1458
1459
1460       val clear_symbolic_output_buffer : symbolic_output_buffer -> unit
1461
1462
1463       clear_symbolic_output_buffer sob resets buffer sob .
1464
1465
1466       Since 4.06.0
1467
1468
1469
1470       val   get_symbolic_output_buffer   :   symbolic_output_buffer  ->  sym‐
1471       bolic_output_item list
1472
1473
1474       get_symbolic_output_buffer sob returns the contents of buffer sob .
1475
1476
1477       Since 4.06.0
1478
1479
1480
1481       val  flush_symbolic_output_buffer  :  symbolic_output_buffer  ->   sym‐
1482       bolic_output_item list
1483
1484
1485       flush_symbolic_output_buffer sob returns the contents of buffer sob and
1486       resets buffer sob .  flush_symbolic_output_buffer sob is equivalent  to
1487       let items = get_symbolic_output_buffer sob in
1488          clear_symbolic_output_buffer sob; items
1489
1490
1491
1492       Since 4.06.0
1493
1494
1495
1496       val  add_symbolic_output_item : symbolic_output_buffer -> symbolic_out‐
1497       put_item -> unit
1498
1499
1500       add_symbolic_output_item sob itm adds item itm to buffer sob .
1501
1502
1503       Since 4.06.0
1504
1505
1506
1507       val  formatter_of_symbolic_output_buffer  :  symbolic_output_buffer  ->
1508       formatter
1509
1510
1511       formatter_of_symbolic_output_buffer  sob  returns  a symbolic formatter
1512       that outputs to symbolic_output_buffer sob .
1513
1514
1515       Since 4.06.0
1516
1517
1518
1519
1520   Convenience formatting functions.
1521       val pp_print_list : ?pp_sep:(formatter -> unit -> unit)  ->  (formatter
1522       -> 'a -> unit) -> formatter -> 'a list -> unit
1523
1524
1525       pp_print_list ?pp_sep pp_v ppf l prints items of list l , using pp_v to
1526       print each item, and calling pp_sep between items ( pp_sep defaults  to
1527       Format.pp_print_cut .  Does nothing on empty lists.
1528
1529
1530       Since 4.02.0
1531
1532
1533
1534       val pp_print_text : formatter -> string -> unit
1535
1536
1537       pp_print_text  ppf  s  prints  s  with spaces and newlines respectively
1538       printed using Format.pp_print_space and Format.pp_force_newline .
1539
1540
1541       Since 4.02.0
1542
1543
1544
1545       val pp_print_option : ?none:(formatter -> unit -> unit)  ->  (formatter
1546       -> 'a -> unit) -> formatter -> 'a option -> unit
1547
1548
1549       pp_print_option  ?none  pp_v  ppf  o prints o on ppf using pp_v if o is
1550       Some v and none if it is None .  none prints nothing by default.
1551
1552
1553       Since 4.08
1554
1555
1556
1557       val pp_print_result : ok:(formatter -> 'a -> unit) ->  error:(formatter
1558       -> 'e -> unit) -> formatter -> ('a, 'e) result -> unit
1559
1560
1561       pp_print_result  ~ok ~error ppf r prints r on ppf using ok if r is Ok _
1562       and error if r is Error _ .
1563
1564
1565       Since 4.08
1566
1567
1568
1569
1570   Formatted pretty-printing
1571       Module Format provides a complete set  of  printf  like  functions  for
1572       pretty-printing using format string specifications.
1573
1574       Specific  annotations  may  be  added  in  the  format  strings to give
1575       pretty-printing commands to the pretty-printing engine.
1576
1577       Those annotations are introduced in the  format  strings  using  the  @
1578       character.  For  instance,  @  means  a space break, @, means a cut, @[
1579       opens a new box, and @] closes the last open box.
1580
1581       val fprintf : formatter -> ('a, formatter, unit) format -> 'a
1582
1583
1584
1585
1586
1587       fprintf ff fmt arg1 ... argN formats the arguments arg1 to argN accord‐
1588       ing  to the format string fmt , and outputs the resulting string on the
1589       formatter ff .
1590
1591       The format string fmt is a character string which contains three  types
1592       of objects: plain characters and conversion specifications as specified
1593       in the Printf module, and pretty-printing indications specific  to  the
1594       Format module.
1595
1596       The pretty-printing indication characters are introduced by a @ charac‐
1597       ter, and their meanings are:
1598
1599       - @[ : open a pretty-printing box. The type and offset of the  box  may
1600       be  optionally  specified  with  the following syntax: the < character,
1601       followed by an optional box type indication, then an  optional  integer
1602       offset,  and  the closing > character.  Pretty-printing box type is one
1603       of h , v , hv , b , or  hov  .   '  h  '  stands  for  an  'horizontal'
1604       pretty-printing box, ' v ' stands for a 'vertical' pretty-printing box,
1605       ' hv ' stands for an 'horizontal/vertical' pretty-printing box, '  b  '
1606       stands  for an 'horizontal-or-vertical' pretty-printing box demonstrat‐
1607       ing indentation, '  hov  '  stands  a  simple  'horizontal-or-vertical'
1608       pretty-printing  box.   For  instance,  @[<hov  2>  opens  an 'horizon‐
1609       tal-or-vertical' pretty-printing box with  indentation  2  as  obtained
1610       with open_hovbox 2 .  For more details about pretty-printing boxes, see
1611       the various box opening functions open_*box .
1612
1613       - @] : close the most recently opened pretty-printing box.
1614
1615       - @, : output a 'cut' break hint, as with print_cut () .
1616
1617       - @ : output a 'space' break hint, as with print_space () .
1618
1619       - @; : output a 'full' break hint as with print_break . The nspaces and
1620       offset  parameters  of  the break hint may be optionally specified with
1621       the following syntax: the < character, followed by an  integer  nspaces
1622       value,  then  an integer offset , and a closing > character.  If no pa‐
1623       rameters are provided, the good break defaults to a 'space' break hint.
1624
1625       - @.  : flush the pretty-printer and split the line, as with print_new‐
1626       line () .
1627
1628       -  @<n>  : print the following item as if it were of length n .  Hence,
1629       printf "@<0>%s" arg prints arg as a zero length string.  If @<n> is not
1630       followed by a conversion specification, then the following character of
1631       the format is printed as if it were of length n .
1632
1633       - @{ : open a semantic tag. The name of the tag may be optionally spec‐
1634       ified  with  the  following syntax: the < character, followed by an op‐
1635       tional string specification, and the closing >  character.  The  string
1636       specification is any character string that does not contain the closing
1637       character '>' . If omitted, the tag name defaults to the empty  string.
1638       For   more   details  about  semantic  tags,  see  the  functions  For‐
1639       mat.open_stag and Format.close_stag .
1640
1641       - @} : close the most recently opened semantic tag.
1642
1643       - @?  : flush the pretty-printer as with  print_flush  ()  .   This  is
1644       equivalent to the conversion %!  .
1645
1646       -  @\n : force a newline, as with force_newline () , not the normal way
1647       of pretty-printing, you should prefer using break hints inside a verti‐
1648       cal pretty-printing box.
1649
1650       Note: To prevent the interpretation of a @ character as a pretty-print‐
1651       ing indication, escape it with a % character.  Old quotation mode @@ is
1652       deprecated  since it is not compatible with formatted input interpreta‐
1653       tion of character '@' .
1654
1655       Example: printf "@[%s@ %d@]@." "x =" 1 is equivalent  to  open_box  ();
1656       print_string "x ="; print_space ();
1657           print_int  1;  close_box  ();  print_newline  () .  It prints x = 1
1658       within a pretty-printing 'horizontal-or-vertical' box.
1659
1660       val printf : ('a, formatter, unit) format -> 'a
1661
1662       Same as fprintf above, but output on std_formatter .
1663
1664
1665
1666       val eprintf : ('a, formatter, unit) format -> 'a
1667
1668       Same as fprintf above, but output on err_formatter .
1669
1670
1671
1672       val sprintf : ('a, unit, string) format -> 'a
1673
1674       Same as printf above, but instead of printing on a formatter, returns a
1675       string  containing  the  result of formatting the arguments.  Note that
1676       the pretty-printer queue is flushed at the end of each call to  sprintf
1677       .
1678
1679       In  case of multiple and related calls to sprintf to output material on
1680       a single string, you should consider using fprintf with the  predefined
1681       formatter  str_formatter and call flush_str_formatter () to get the fi‐
1682       nal result.
1683
1684       Alternatively, you can use Format.fprintf with a formatter writing to a
1685       buffer of your own: flushing the formatter and the buffer at the end of
1686       pretty-printing returns the desired string.
1687
1688
1689
1690       val asprintf : ('a, formatter, unit, string) format4 -> 'a
1691
1692       Same as printf above, but instead of printing on a formatter, returns a
1693       string  containing the result of formatting the arguments.  The type of
1694       asprintf is general enough to interact nicely with %a conversions.
1695
1696
1697       Since 4.01.0
1698
1699
1700
1701       val dprintf : ('a, formatter, unit, formatter -> unit) format4 -> 'a
1702
1703       Same as Format.fprintf , except the formatter  is  the  last  argument.
1704       dprintf  "..."  a b c is a function of type formatter -> unit which can
1705       be given to a format specifier %t .
1706
1707       This can be used as a replacement for Format.asprintf to delay  format‐
1708       ting  decisions. Using the string returned by Format.asprintf in a for‐
1709       matting context forces formatting decisions to be taken  in  isolation,
1710       and the final string may be created prematurely.  Format.dprintf allows
1711       delay of formatting decisions until the  final  formatting  context  is
1712       known.  For example:
1713         let t = Format.dprintf "%i@ %i@ %i" 1 2 3 in
1714         ...
1715         Format.printf "@[<v>%t@]" t
1716
1717
1718
1719       Since 4.08.0
1720
1721
1722
1723       val ifprintf : formatter -> ('a, formatter, unit) format -> 'a
1724
1725       Same  as  fprintf above, but does not print anything.  Useful to ignore
1726       some material when conditionally printing.
1727
1728
1729       Since 3.10.0
1730
1731
1732
1733
1734       Formatted Pretty-Printing with continuations.
1735
1736       val kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter,  unit,
1737       'a) format4 -> 'b
1738
1739       Same as fprintf above, but instead of returning immediately, passes the
1740       formatter to its first argument at the end of printing.
1741
1742
1743
1744       val kdprintf : ((formatter -> unit) -> 'a) -> ('b, formatter, unit, 'a)
1745       format4 -> 'b
1746
1747       Same  as  Format.dprintf  above,  but instead of returning immediately,
1748       passes the suspended printer to its first argument at the end of print‐
1749       ing.
1750
1751
1752       Since 4.08.0
1753
1754
1755
1756       val ikfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1757       'a) format4 -> 'b
1758
1759       Same as kfprintf above, but does not print anything.  Useful to  ignore
1760       some material when conditionally printing.
1761
1762
1763       Since 3.12.0
1764
1765
1766
1767       val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b
1768
1769       Same  as  sprintf above, but instead of returning the string, passes it
1770       to the first argument.
1771
1772
1773
1774       val kasprintf : (string -> 'a) -> ('b, formatter, unit, 'a) format4  ->
1775       'b
1776
1777       Same  as asprintf above, but instead of returning the string, passes it
1778       to the first argument.
1779
1780
1781       Since 4.03
1782
1783
1784
1785
1786   Deprecated
1787       val bprintf : Buffer.t -> ('a, formatter, unit) format -> 'a
1788
1789       Deprecated.  This function is error prone. Do not use it.   This  func‐
1790       tion  is  neither  compositional  nor incremental, since it flushes the
1791       pretty-printer queue at each call.
1792
1793       If you need to print to some buffer b , you must first define a format‐
1794       ter  writing  to  b , using let to_b = formatter_of_buffer b ; then use
1795       regular calls to Format.fprintf with formatter to_b .
1796
1797
1798
1799       val kprintf : (string -> 'a) -> ('b, unit, string, 'a) format4 -> 'b
1800
1801       Deprecated.  An alias for ksprintf .
1802
1803
1804
1805       val set_all_formatter_output_functions : out:(string -> int ->  int  ->
1806       unit)  -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int
1807       -> unit) -> unit
1808
1809       Deprecated.  Subsumed by set_formatter_out_functions .
1810
1811
1812
1813       val get_all_formatter_output_functions : unit -> (string -> int ->  int
1814       -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
1815
1816       Deprecated.  Subsumed by get_formatter_out_functions .
1817
1818
1819
1820       val pp_set_all_formatter_output_functions : formatter -> out:(string ->
1821       int -> int -> unit) -> flush:(unit -> unit) -> newline:(unit  ->  unit)
1822       -> spaces:(int -> unit) -> unit
1823
1824       Deprecated.  Subsumed by pp_set_formatter_out_functions .
1825
1826
1827
1828       val   pp_get_all_formatter_output_functions  :  formatter  ->  unit  ->
1829       (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int
1830       -> unit)
1831
1832       Deprecated.  Subsumed by pp_get_formatter_out_functions .
1833
1834
1835
1836
1837   String tags
1838       val pp_open_tag : formatter -> tag -> unit
1839
1840       Deprecated.  Subsumed by Format.pp_open_stag .
1841
1842
1843
1844       val open_tag : tag -> unit
1845
1846       Deprecated.  Subsumed by Format.open_stag .
1847
1848
1849
1850       val pp_close_tag : formatter -> unit -> unit
1851
1852       Deprecated.  Subsumed by Format.pp_close_stag .
1853
1854
1855
1856       val close_tag : unit -> unit
1857
1858       Deprecated.  Subsumed by Format.close_stag .
1859
1860
1861       type formatter_tag_functions = {
1862        mark_open_tag : tag -> string ;
1863        mark_close_tag : tag -> string ;
1864        print_open_tag : tag -> unit ;
1865        print_close_tag : tag -> unit ;
1866        }
1867
1868
1869       Deprecated.  Subsumed by Format.formatter_stag_functions .
1870
1871
1872
1873       val  pp_set_formatter_tag_functions  : formatter -> formatter_tag_func‐
1874       tions -> unit
1875
1876       Deprecated.  Subsumed by Format.pp_set_formatter_stag_functions .
1877
1878
1879       This function will erase non-string tag formatting functions.
1880
1881
1882
1883       val set_formatter_tag_functions : formatter_tag_functions -> unit
1884
1885       Deprecated.  Subsumed by Format.set_formatter_stag_functions .
1886
1887
1888
1889       val pp_get_formatter_tag_functions  :  formatter  ->  unit  ->  format‐
1890       ter_tag_functions
1891
1892       Deprecated.  Subsumed by Format.pp_get_formatter_stag_functions .
1893
1894
1895
1896       val get_formatter_tag_functions : unit -> formatter_tag_functions
1897
1898       Deprecated.  Subsumed by Format.get_formatter_stag_functions .
1899
1900
1901
1902
1903
1904OCamldoc                          2021-01-26                         Format(3)
Impressum