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