1Format(3) OCaml library Format(3)
2
3
4
6 Format - Pretty printing.
7
9 Module Format
10
12 Module Format
13 : sig end
14
15
16 Pretty printing.
17
18 This module implements a pretty-printing facility to format 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)