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 text within
19       ``pretty-printing boxes''. The pretty-printer breaks lines at specified
20       break hints, and indents lines according to the box structure.
21
22       For a gentle introduction to the basics of pretty-printing using Format
23       , read http://caml.inria.fr/resources/doc/guides/format.html.
24
25       You may consider this module as providing an extension  to  the  printf
26       facility   to   provide   automatic  line  breaking.  The  addition  of
27       pretty-printing annotations to your regular printf  formats  gives  you
28       fancy  indentation  and  line  breaks.  Pretty-printing annotations are
29       described below in the documentation of the function Format.fprintf .
30
31       You may also use the explicit box  management  and  printing  functions
32       provided by this module. This style is more basic but more verbose than
33       the fprintf concise formats.
34
35       For instance, the sequence open_box 0; print_string x =  ;  print_space
36       ();  print_int 1; close_box () that prints x = 1 within a pretty-print‐
37       ing box, can be abbreviated as printf @[%s@  %i@]  x  =  1  ,  or  even
38       shorter printf @[x =@ %i@] 1 .
39
40       Rule of thumb for casual users of this library:
41
42       -use simple boxes (as obtained by open_box 0 );
43
44       -use  simple  break  hints  (as obtained by print_cut () that outputs a
45       simple break hint, or by print_space () that outputs a space indicating
46       a break hint);
47
48       -once  a  box is opened, display its material with basic printing func‐
49       tions (e. g.  print_int and print_string );
50
51       -when the material for a box has been printed,  call  close_box  ()  to
52       close the box;
53
54       -at  the  end  of  your routine, evaluate print_newline () to close all
55       remaining boxes and flush the pretty-printer.
56
57       The behaviour of pretty-printing commands is unspecified if there is no
58       opened  pretty-printing box. Each box opened via one of the open_ func‐
59       tions below must be closed using close_box for proper formatting.  Oth‐
60       erwise, some of the material printed in the boxes may not be output, or
61       may be formatted incorrectly.
62
63       In case of interactive use, the system  closes  all  opened  boxes  and
64       flushes  all  pending  text  (as with the print_newline function) after
65       each phrase. Each phrase is therefore executed in the initial state  of
66       the pretty-printer.
67
68       Warning:  the  material output by the following functions is delayed in
69       the pretty-printer queue in order to compute the proper line  breaking.
70       Hence,  you should not mix calls to the printing functions of the basic
71       I/O system with calls to the  functions  of  this  module:  this  could
72       result  in  some strange output seemingly unrelated with the evaluation
73       order of printing commands.
74
75
76
77
78
79
80
81
82       === Boxes ===
83
84
85       val open_box : int -> unit
86
87
88       open_box d opens a new pretty-printing box with offset d .  This box is
89       the  general purpose pretty-printing box.  Material in this box is dis‐
90       played ``horizontal or vertical'': break hints inside the box may  lead
91       to  a  new  line,  if  there  is  no more room on the line to print the
92       remainder of the box, or if a new line may lead to  a  new  indentation
93       (demonstrating the indentation of the box).  When a new line is printed
94       in the box, d is added to the current indentation.
95
96
97
98
99       val close_box : unit -> unit
100
101       Closes the most recently opened pretty-printing box.
102
103
104
105
106
107       === Formatting functions ===
108
109
110       val print_string : string -> unit
111
112
113       print_string str prints str in the current box.
114
115
116
117
118       val print_as : int -> string -> unit
119
120
121       print_as len str prints str in the current box. The pretty-printer for‐
122       mats str as if it were of length len .
123
124
125
126
127       val print_int : int -> unit
128
129       Prints an integer in the current box.
130
131
132
133
134       val print_float : float -> unit
135
136       Prints a floating point number in the current box.
137
138
139
140
141       val print_char : char -> unit
142
143       Prints a character in the current box.
144
145
146
147
148       val print_bool : bool -> unit
149
150       Prints a boolean in the current box.
151
152
153
154
155
156       === Break hints ===
157
158
159       val print_space : unit -> unit
160
161
162       print_space  ()  is  used to separate items (typically to print a space
163       between two words).  It indicates that the line may be  split  at  this
164       point. It either prints one space or splits the line.  It is equivalent
165       to print_break 1 0 .
166
167
168
169
170       val print_cut : unit -> unit
171
172
173       print_cut () is used to mark a good break position.  It indicates  that
174       the line may be split at this point. It either prints nothing or splits
175       the line.  This allows line splitting at  the  current  point,  without
176       printing spaces or adding indentation.  It is equivalent to print_break
177       0 0 .
178
179
180
181
182       val print_break : int -> int -> unit
183
184       Inserts a break hint in a  pretty-printing  box.   print_break  nspaces
185       offset  indicates  that  the  line may be split (a newline character is
186       printed) at this point, if the contents of the current box does not fit
187       on  the  current  line.   If the line is split at that point, offset is
188       added to the current indentation. If the line  is  not  split,  nspaces
189       spaces are printed.
190
191
192
193
194       val print_flush : unit -> unit
195
196       Flushes  the pretty printer: all opened boxes are closed, and all pend‐
197       ing text is displayed.
198
199
200
201
202       val print_newline : unit -> unit
203
204       Equivalent to print_flush followed by a new line.
205
206
207
208
209       val force_newline : unit -> unit
210
211       Forces  a  newline  in  the  current  box.  Not  the  normal   way   of
212       pretty-printing, you should prefer break hints.
213
214
215
216
217       val print_if_newline : unit -> unit
218
219       Executes  the  next  formatting  command if the preceding line has just
220       been split. Otherwise, ignore the next formatting command.
221
222
223
224
225
226       === Margin ===
227
228
229       val set_margin : int -> unit
230
231
232       set_margin d sets the value of the right margin to d  (in  characters):
233       this  value is used to detect line overflows that leads to split lines.
234       Nothing happens if d is smaller than 2.  If d is too large,  the  right
235       margin  is  set  to the maximum admissible value (which is greater than
236       10^10 ).
237
238
239
240
241       val get_margin : unit -> int
242
243       Returns the position of the right margin.
244
245
246
247
248
249       === Maximum indentation limit ===
250
251
252       val set_max_indent : int -> unit
253
254
255       set_max_indent d sets the value of the maximum indentation limit  to  d
256       (in  characters): once this limit is reached, boxes are rejected to the
257       left, if they do not fit on the current line.  Nothing happens if d  is
258       smaller  than  2.   If  d is too large, the limit is set to the maximum
259       admissible value (which is greater than 10^10 ).
260
261
262
263
264       val get_max_indent : unit -> int
265
266       Return the value of the maximum indentation limit (in characters).
267
268
269
270
271
272       === Formatting depth: maximum number of boxes allowed  before  ellipsis
273       ===
274
275
276       val set_max_boxes : int -> unit
277
278
279       set_max_boxes  max  sets  the  maximum  number  of boxes simultaneously
280       opened.  Material inside boxes nested deeper is printed as an  ellipsis
281       (more  precisely as the text returned by get_ellipsis_text () ).  Noth‐
282       ing happens if max is smaller than 2.
283
284
285
286
287       val get_max_boxes : unit -> int
288
289       Returns the maximum number of boxes allowed before ellipsis.
290
291
292
293
294       val over_max_boxes : unit -> bool
295
296       Tests if the maximum number of boxes allowed have already been opened.
297
298
299
300
301
302       === Advanced formatting ===
303
304
305       val open_hbox : unit -> unit
306
307
308       open_hbox () opens a new pretty-printing box.  This box  is  ``horizon‐
309       tal'':  the  line  is  not split in this box (new lines may still occur
310       inside boxes nested deeper).
311
312
313
314
315       val open_vbox : int -> unit
316
317
318       open_vbox d opens a new pretty-printing box with offset d .   This  box
319       is  ``vertical'': every break hint inside this box leads to a new line.
320       When a new line is printed in the box, d is added to the current inden‐
321       tation.
322
323
324
325
326       val open_hvbox : int -> unit
327
328
329       open_hvbox  d opens a new pretty-printing box with offset d .  This box
330       is ``horizontal-vertical'': it behaves as an ``horizontal'' box  if  it
331       fits  on  a  single  line,  otherwise it behaves as a ``vertical'' box.
332       When a new line is printed in the box, d is added to the current inden‐
333       tation.
334
335
336
337
338       val open_hovbox : int -> unit
339
340
341       open_hovbox d opens a new pretty-printing box with offset d .  This box
342       is ``horizontal or vertical'': break hints inside this box may lead  to
343       a new line, if there is no more room on the line to print the remainder
344       of the box.  When a new line is printed in the box, d is added  to  the
345       current indentation.
346
347
348
349
350
351       === Tabulations ===
352
353
354       val open_tbox : unit -> unit
355
356       Opens a tabulation box.
357
358
359
360
361       val close_tbox : unit -> unit
362
363       Closes the most recently opened tabulation box.
364
365
366
367
368       val print_tbreak : int -> int -> unit
369
370       Break  hint  in a tabulation box.  print_tbreak spaces offset moves the
371       insertion point to the next tabulation ( spaces  being  added  to  this
372       position).   Nothing  occurs if insertion point is already on a tabula‐
373       tion mark.  If there is no next tabulation on the line, then a  newline
374       is printed and the insertion point moves to the first tabulation of the
375       box.  If a new line is printed, offset is added to the current indenta‐
376       tion.
377
378
379
380
381       val set_tab : unit -> unit
382
383       Sets a tabulation mark at the current insertion point.
384
385
386
387
388       val print_tab : unit -> unit
389
390
391       print_tab () is equivalent to print_tbreak 0 0 .
392
393
394
395
396
397       === Ellipsis ===
398
399
400       val set_ellipsis_text : string -> unit
401
402       Set  the text of the ellipsis printed when too many boxes are opened (a
403       single dot, .  , by default).
404
405
406
407
408       val get_ellipsis_text : unit -> string
409
410       Return the text of the ellipsis.
411
412
413
414
415
416       === Semantics Tags ===
417
418
419       type tag = string
420
421
422
423
424
425
426       === Semantics tags (or simply tags) are used to decorate printed  enti‐
427       ties  for  user's  defined  purposes, e.g. setting font and giving size
428       indications for a display device, or marking delimitation of  semantics
429       entities  (e.g. HTML or TeX elements or terminal escape sequences).  By
430       default, those tags do not influence line breaking calculation: the tag
431       ``markers''  are  not  considered as part of the printing material that
432       drives line breaking (in other words, the length of  those  strings  is
433       considered  as  zero for line breaking).  Thus, tag handling is in some
434       sense transparent to pretty-printing and does not interfere with  usual
435       pretty-printing.  Hence,  a  single  pretty printing routine can output
436       both simple ``verbatim'' material or richer decorated output  depending
437       on  the  treatment  of tags. By default, tags are not active, hence the
438       output is not decorated with tag information. Once set_tags is  set  to
439       true,  the  pretty printer engine honours tags and decorates the output
440       accordingly.  When a tag has been opened (or closed), it  is  both  and
441       successively ``printed'' and ``marked''. Printing a tag means calling a
442       formatter specific function with the name of the tag as argument:  that
443       ``tag  printing''  function  can then print any regular material to the
444       formatter (so that this material is enqueued as usual in the  formatter
445       queue  for  further  line-breaking computation). Marking a tag means to
446       output an arbitrary string (the ``tag marker''), directly into the out‐
447       put  device of the formatter. Hence, the formatter specific ``tag mark‐
448       ing'' function must return the tag marker string associated to its  tag
449       argument.  Being flushed directly into the output device of the format‐
450       ter, tag marker strings are not considered  as  part  of  the  printing
451       material  that  drives line breaking (in other words, the length of the
452       strings corresponding to tag markers is considered  as  zero  for  line
453       breaking). In addition, advanced users may take advantage of the speci‐
454       ficity of tag markers to be precisely output when  the  pretty  printer
455       has  already  decided  where to break the lines, and precisely when the
456       queue is flushed into the output device.  In the spirit of  HTML  tags,
457       the  default  tag  marking  functions output tags enclosed in < and > :
458       hence, the opening marker of tag t is <t> and the closing marker </t> .
459       Default  tag  printing  functions just do nothing.  Tag marking and tag
460       printing functions are  user  definable  and  can  be  set  by  calling
461       set_formatter_tag_functions. ===
462
463
464       val open_tag : tag -> unit
465
466
467       open_tag  t  opens the tag named t ; the print_open_tag function of the
468       formatter is called with t as argument; the tag marker mark_open_tag  t
469       will be flushed into the output device of the formatter.
470
471
472
473
474       val close_tag : unit -> unit
475
476
477       close_tag  () closes the most recently opened tag t .  In addition, the
478       print_close_tag function of the formatter is called with t as argument.
479       The  marker  mark_close_tag t will be flushed into the output device of
480       the formatter.
481
482
483
484
485       val set_tags : bool -> unit
486
487
488       set_tags b turns on or off the treatment of tags (default is off).
489
490
491
492
493       val set_print_tags : bool -> unit
494
495
496
497
498       val set_mark_tags : bool -> unit
499
500
501       set_print_tags  b  turns  on  or  off  the  printing  of  tags,   while
502       set_mark_tags b turns on or off the output of tag markers.
503
504
505
506
507       val get_print_tags : unit -> bool
508
509
510
511
512       val get_mark_tags : unit -> bool
513
514       Return the current status of tags printing and tags marking.
515
516
517
518
519
520       === Redirecting the standard formatter output ===
521
522
523       val set_formatter_out_channel : Pervasives.out_channel -> unit
524
525       Redirect the pretty-printer output to the given channel.
526
527
528
529
530       val  set_formatter_output_functions : (string -> int -> int -> unit) ->
531       (unit -> unit) -> unit
532
533
534       set_formatter_output_functions out flush redirects  the  pretty-printer
535       output to the functions out and flush .
536
537       The  out  function  performs  the  pretty-printer  string output. It is
538       called with a string s , a start position p , and a number  of  charac‐
539       ters  n ; it is supposed to output characters p to p + n - 1 of s . The
540       flush function is called whenever the pretty-printer  is  flushed  (via
541       conversion  %!  , pretty-printing indications @?  or @.  , or using low
542       level function print_flush or print_newline ).
543
544
545
546
547       val get_formatter_output_functions : unit -> (string -> int ->  int  ->
548       unit) * (unit -> unit)
549
550       Return the current output functions of the pretty-printer.
551
552
553
554
555
556       === Changing the meaning of standard formatter pretty printing ===
557
558
559       ===  The  Format module is versatile enough to let you completely rede‐
560       fine the meaning of pretty printing: you may provide your own functions
561       to  define  how to handle indentation, line breaking, and even printing
562       of all the characters that have to be printed! ===
563
564
565       val set_all_formatter_output_functions : out:(string -> int ->  int  ->
566       unit)  -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int
567       -> unit) -> unit
568
569
570       set_all_formatter_output_functions out flush outnewline outspace  redi‐
571       rects  the  pretty-printer  output  to  the  functions out and flush as
572       described  in  set_formatter_output_functions  .   In   addition,   the
573       pretty-printer  function  that outputs a newline is set to the function
574       outnewline and the function that outputs indentation spaces is  set  to
575       the function outspace .
576
577       This way, you can change the meaning of indentation (which can be some‐
578       thing else than just printing space characters) and the meaning of  new
579       lines opening (which can be connected to any other action needed by the
580       application at hand). The two functions  outspace  and  outnewline  are
581       normally  connected  to  out  and flush : respective default values for
582       outspace and outnewline are out (String.make n ' ') 0 n and out \n 0  1
583       .
584
585
586
587
588       val  get_all_formatter_output_functions : unit -> (string -> int -> int
589       -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
590
591       Return the current output functions of  the  pretty-printer,  including
592       line  breaking  and indentation functions. Useful to record the current
593       setting and restore it afterwards.
594
595
596
597
598
599       === Changing the meaning of printing semantics tags ===
600
601
602       type formatter_tag_functions = {
603        mark_open_tag : tag -> string ;
604        mark_close_tag : tag -> string ;
605        print_open_tag : tag -> unit ;
606        print_close_tag : tag -> unit ;
607        }
608
609
610       The tag handling functions specific to a formatter: mark  versions  are
611       the  ``tag  marking'' functions that associate a string marker to a tag
612       in order for the pretty-printing engine to flush  those  markers  as  0
613       length  tokens  in  the output device of the formatter.  print versions
614       are the ``tag printing'' functions that can  perform  regular  printing
615       when a tag is closed or opened.
616
617
618
619
620       val set_formatter_tag_functions : formatter_tag_functions -> unit
621
622
623
624
625
626       === set_formatter_tag_functions tag_funs changes the meaning of opening
627       and closing tags to use the functions in tag_funs.  When opening a  tag
628       name t, the string t is passed to the opening tag marking function (the
629       mark_open_tag field of the record tag_funs), that must return the open‐
630       ing  tag  marker for that name. When the next call to close_tag () hap‐
631       pens, the tag name t is sent back to the closing tag  marking  function
632       (the mark_close_tag field of record tag_funs), that must return a clos‐
633       ing tag marker for that name.  The print_ field of the record  contains
634       the  functions  that are called at tag opening and tag closing time, to
635       output regular material in the pretty-printer queue. ===
636
637
638       val get_formatter_tag_functions : unit -> formatter_tag_functions
639
640       Return the current tag functions of the pretty-printer.
641
642
643
644
645
646       === Multiple formatted output ===
647
648
649       type formatter
650
651
652       Abstract data type corresponding to a  pretty-printer  (also  called  a
653       formatter) and all its machinery.  Defining new pretty-printers permits
654       the output of material in parallel on several channels.  Parameters  of
655       a  pretty-printer  are  local  to  this pretty-printer: margin, maximum
656       indentation limit,  maximum  number  of  boxes  simultaneously  opened,
657       ellipsis,  and  so  on,  are specific to each pretty-printer and may be
658       fixed independently.  Given an output channel  oc  ,  a  new  formatter
659       writing to that channel is obtained by calling formatter_of_out_channel
660       oc .  Alternatively, the make_formatter function allocates a  new  for‐
661       matter  with explicit output and flushing functions (convenient to out‐
662       put material to strings for instance).
663
664
665
666
667       val formatter_of_out_channel : Pervasives.out_channel -> formatter
668
669
670       formatter_of_out_channel oc returns a new formatter that writes to  the
671       corresponding channel oc .
672
673
674
675
676       val std_formatter : formatter
677
678       The  standard  formatter  used by the formatting functions above. It is
679       defined as formatter_of_out_channel stdout .
680
681
682
683
684       val err_formatter : formatter
685
686       A formatter to use with formatting functions below for output to  stan‐
687       dard error. It is defined as formatter_of_out_channel stderr .
688
689
690
691
692       val formatter_of_buffer : Buffer.t -> formatter
693
694
695       formatter_of_buffer  b returns a new formatter writing to buffer b . As
696       usual, the formatter has to be flushed at the end of  pretty  printing,
697       using  pp_print_flush  or pp_print_newline , to display all the pending
698       material.
699
700
701
702
703       val stdbuf : Buffer.t
704
705       The string buffer in which str_formatter writes.
706
707
708
709
710       val str_formatter : formatter
711
712       A formatter to use with formatting functions below for  output  to  the
713       stdbuf  string buffer.  str_formatter is defined as formatter_of_buffer
714       stdbuf .
715
716
717
718
719       val flush_str_formatter : unit -> string
720
721       Returns the material printed with str_formatter , flushes the formatter
722       and resets the corresponding buffer.
723
724
725
726
727       val  make_formatter  : (string -> int -> int -> unit) -> (unit -> unit)
728       -> formatter
729
730
731       make_formatter out flush returns a new formatter that writes  according
732       to the output function out , and the flushing function flush . Hence, a
733       formatter to the out channel oc is returned by  make_formatter  (output
734       oc) (fun () -> flush oc) .
735
736
737
738
739
740       === Basic functions to use with formatters ===
741
742
743       val pp_open_hbox : formatter -> unit -> unit
744
745
746
747
748       val pp_open_vbox : formatter -> int -> unit
749
750
751
752
753       val pp_open_hvbox : formatter -> int -> unit
754
755
756
757
758       val pp_open_hovbox : formatter -> int -> unit
759
760
761
762
763       val pp_open_box : formatter -> int -> unit
764
765
766
767
768       val pp_close_box : formatter -> unit -> unit
769
770
771
772
773       val pp_open_tag : formatter -> string -> unit
774
775
776
777
778       val pp_close_tag : formatter -> unit -> unit
779
780
781
782
783       val pp_print_string : formatter -> string -> unit
784
785
786
787
788       val pp_print_as : formatter -> int -> string -> unit
789
790
791
792
793       val pp_print_int : formatter -> int -> unit
794
795
796
797
798       val pp_print_float : formatter -> float -> unit
799
800
801
802
803       val pp_print_char : formatter -> char -> unit
804
805
806
807
808       val pp_print_bool : formatter -> bool -> unit
809
810
811
812
813       val pp_print_break : formatter -> int -> int -> unit
814
815
816
817
818       val pp_print_cut : formatter -> unit -> unit
819
820
821
822
823       val pp_print_space : formatter -> unit -> unit
824
825
826
827
828       val pp_force_newline : formatter -> unit -> unit
829
830
831
832
833       val pp_print_flush : formatter -> unit -> unit
834
835
836
837
838       val pp_print_newline : formatter -> unit -> unit
839
840
841
842
843       val pp_print_if_newline : formatter -> unit -> unit
844
845
846
847
848       val pp_open_tbox : formatter -> unit -> unit
849
850
851
852
853       val pp_close_tbox : formatter -> unit -> unit
854
855
856
857
858       val pp_print_tbreak : formatter -> int -> int -> unit
859
860
861
862
863       val pp_set_tab : formatter -> unit -> unit
864
865
866
867
868       val pp_print_tab : formatter -> unit -> unit
869
870
871
872
873       val pp_set_tags : formatter -> bool -> unit
874
875
876
877
878       val pp_set_print_tags : formatter -> bool -> unit
879
880
881
882
883       val pp_set_mark_tags : formatter -> bool -> unit
884
885
886
887
888       val pp_get_print_tags : formatter -> unit -> bool
889
890
891
892
893       val pp_get_mark_tags : formatter -> unit -> bool
894
895
896
897
898       val pp_set_margin : formatter -> int -> unit
899
900
901
902
903       val pp_get_margin : formatter -> unit -> int
904
905
906
907
908       val pp_set_max_indent : formatter -> int -> unit
909
910
911
912
913       val pp_get_max_indent : formatter -> unit -> int
914
915
916
917
918       val pp_set_max_boxes : formatter -> int -> unit
919
920
921
922
923       val pp_get_max_boxes : formatter -> unit -> int
924
925
926
927
928       val pp_over_max_boxes : formatter -> unit -> bool
929
930
931
932
933       val pp_set_ellipsis_text : formatter -> string -> unit
934
935
936
937
938       val pp_get_ellipsis_text : formatter -> unit -> string
939
940
941
942
943       val  pp_set_formatter_out_channel : formatter -> Pervasives.out_channel
944       -> unit
945
946
947
948
949       val pp_set_formatter_output_functions : formatter -> (string -> int  ->
950       int -> unit) -> (unit -> unit) -> unit
951
952
953
954
955       val pp_get_formatter_output_functions : formatter -> unit -> (string ->
956       int -> int -> unit) * (unit -> unit)
957
958
959
960
961       val pp_set_all_formatter_output_functions : formatter -> out:(string ->
962       int  ->  int -> unit) -> flush:(unit -> unit) -> newline:(unit -> unit)
963       -> spaces:(int -> unit) -> unit
964
965
966
967
968       val  pp_get_all_formatter_output_functions  :  formatter  ->  unit   ->
969       (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int
970       -> unit)
971
972
973
974
975       val pp_set_formatter_tag_functions : formatter  ->  formatter_tag_func‐
976       tions -> unit
977
978
979
980
981       val  pp_get_formatter_tag_functions  :  formatter  ->  unit  -> format‐
982       ter_tag_functions
983
984       These functions are the basic ones: usual functions  operating  on  the
985       standard  formatter  are defined via partial evaluation of these primi‐
986       tives. For instance, print_string is equal to pp_print_string  std_for‐
987       matter .
988
989
990
991
992
993       === printf like functions for pretty-printing.  ===
994
995
996       val  fprintf  : formatter -> ('a, formatter, unit) Pervasives.format ->
997       'a
998
999
1000       fprintf ff format arg1 ... argN formats  the  arguments  arg1  to  argN
1001       according  to  the  format  string  format  , and outputs the resulting
1002       string on the formatter ff .  The format is a  character  string  which
1003       contains three types of objects: plain characters and conversion speci‐
1004       fications as specified in the printf module, and pretty-printing  indi‐
1005       cations.  The pretty-printing indication characters are introduced by a
1006       @ character, and their meanings are:
1007
1008       - @[ : open a pretty-printing box. The type and offset of the  box  may
1009       be  optionally  specified  with  the following syntax: the < character,
1010       followed by an optional box type indication, then an  optional  integer
1011       offset, and the closing > character.  Box type is one of h , v , hv , b
1012       , or hov , which stand respectively for an horizontal box,  a  vertical
1013       box,  an  ``horizontal-vertical'' box, or an ``horizontal or vertical''
1014       box ( b standing for an ``horizontal or  vertical''  box  demonstrating
1015       indentation  and  hov  standing for a regular``horizontal or vertical''
1016       box).  For instance, @[<hov 2> opens an ``horizontal or vertical''  box
1017       with  indentation  2 as obtained with open_hovbox 2 .  For more details
1018       about boxes, see the various box opening functions open_*box .
1019
1020       - @] : close the most recently opened pretty-printing box.
1021
1022       - @, : output a good break as with print_cut () .
1023
1024       - @ : output a space, as with print_space () .
1025
1026       - @\n : force a newline, as with force_newline () .
1027
1028       - @; : output a good break as with print_break . The nspaces and offset
1029       parameters  of the break may be optionally specified with the following
1030       syntax: the < character, followed by an integer nspaces value, then  an
1031       integer  offset , and a closing > character.  If no parameters are pro‐
1032       vided, the good break defaults to a space.
1033
1034       - @?  : flush the pretty printer as with  print_flush  ()  .   This  is
1035       equivalent to the conversion %!  .
1036
1037       -  @.   :  flush  the  pretty  printer  and  output a new line, as with
1038       print_newline () .
1039
1040       - @<n> : print the following item as if it were of length n  .   Hence,
1041       printf  @<0>%s  arg  is  equivalent to print_as 0 arg .  If @<n> is not
1042       followed by a conversion specification, then the following character of
1043       the format is printed as if it were of length n .
1044
1045       - @{ : open a tag. The name of the tag may be optionally specified with
1046       the following syntax: the < character, followed by an  optional  string
1047       specification, and the closing > character. The string specification is
1048       any character string that does not contain the closing character '>'  .
1049       If  omitted,  the  tag  name  defaults  to  the empty string.  For more
1050       details about tags, see the functions open_tag and close_tag .
1051
1052       - @} : close the most recently opened tag.
1053
1054       - @@ : print a plain @ character.
1055
1056       Example: printf @[%s@  %d@]  x  =  1  is  equivalent  to  open_box  ();
1057       print_string  x  =  ;  print_space  (); print_int 1; close_box () .  It
1058       prints x = 1 within a pretty-printing box.
1059
1060
1061
1062
1063       val printf : ('a, formatter, unit) Pervasives.format -> 'a
1064
1065       Same as fprintf above, but output on std_formatter .
1066
1067
1068
1069
1070       val eprintf : ('a, formatter, unit) Pervasives.format -> 'a
1071
1072       Same as fprintf above, but output on err_formatter .
1073
1074
1075
1076
1077       val sprintf : ('a, unit, string) Pervasives.format -> 'a
1078
1079       Same as printf above, but instead of printing on a formatter, returns a
1080       string  containing  the  result of formatting the arguments.  Note that
1081       the pretty-printer queue is flushed at the end of each call to  sprintf
1082       .
1083
1084       In  case of multiple and related calls to sprintf to output material on
1085       a single string, you should consider using  fprintf  with  a  formatter
1086       writing  to a buffer: flushing the buffer at the end of pretty-printing
1087       returns the desired string. You can also use the  predefined  formatter
1088       str_formatter and call flush_str_formatter () to get the result.
1089
1090
1091
1092
1093       val bprintf : Buffer.t -> ('a, formatter, unit) Pervasives.format -> 'a
1094
1095       Same as sprintf above, but instead of printing on a string, writes into
1096       the given extensible buffer.  As for sprintf , the pretty-printer queue
1097       is flushed at the end of each call to bprintf .
1098
1099       In  case of multiple and related calls to bprintf to output material on
1100       the same buffer b , you should consider using fprintf with a  formatter
1101       writing to the buffer b (as obtained by formatter_of_buffer b ), other‐
1102       wise the repeated flushes of the pretty-printer queue would  result  in
1103       unexpected and badly formatted output.
1104
1105
1106
1107
1108       val  kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1109       'a) Pervasives.format4 -> 'b
1110
1111       Same as fprintf above, but instead of returning immediately, passes the
1112       formatter to its first argument at the end of printing.
1113
1114
1115
1116
1117       val  ifprintf : formatter -> ('a, formatter, unit) Pervasives.format ->
1118       'a
1119
1120       Same as fprintf above, but does not print anything.  Useful  to  ignore
1121       some material when conditionally printing.
1122
1123
1124
1125
1126       val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.for‐
1127       mat4 -> 'b
1128
1129       Same as sprintf above, but instead of returning the string,  passes  it
1130       to the first argument.
1131
1132
1133
1134
1135       val  kprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.for‐
1136       mat4 -> 'b
1137
1138       A deprecated synonym for ksprintf .
1139
1140
1141
1142
1143
1144
1145OCamldoc                          2017-03-22                         Format(3)
Impressum