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
21       indents lines according to the box structure.   Similarly,  Format.tags
22       can 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 Pervasives.stdout
29
30
31       - Format.err_formatter outputs to Pervasives.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   For   a  gentle  introduction  to  the  basics  of
48       pretty-printing             using             Format,              read
49       [http://caml.inria.fr/resources/doc/guides/format.en.html]
50       http://caml.inria.fr/resources/doc/guides/format.en.html.  You may con‐
51       sider  this  module as providing an extension to the printf facility to
52       provide automatic line splitting. The addition of pretty-printing anno‐
53       tations  to your regular printf format strings gives you fancy indenta‐
54       tion and line breaks.  Pretty-printing annotations are described  below
55       in  the documentation of the function Format.fprintf.  You may also use
56       the explicit pretty-printing box management and printing functions pro‐
57       vided  by  this  module. This style is more basic but more verbose than
58       the  concise  fprintf  format  strings.   For  instance,  the  sequence
59       open_box  0;  print_string x = ; print_space (); print_int 1; close_box
60       (); print_newline () that prints x = 1 within  a  pretty-printing  box,
61       can be abbreviated as printf @[%s@ %i@]@. x = 1, or even shorter printf
62       @[x =@ %i@]@. 1.  Rule of thumb for casual users of this library: - use
63       simple  pretty-printing boxes (as obtained by open_box 0); - use simple
64       break hints as obtained by print_cut () that  outputs  a  simple  break
65       hint,  or  by  print_space  ()  that outputs a space indicating a break
66       hint; - once a pretty-printing box is open, display its  material  with
67       basic printing functions (e. g. print_int and print_string); - when the
68       material for a pretty-printing box has been printed, call close_box  ()
69       to  close  the  box;  -  at  the  end  of  pretty-printing,  flush  the
70       pretty-printer to display all the  remaining  material,  e.g.  evaluate
71       print_newline ().  The behavior of pretty-printing commands is unspeci‐
72       fied if there is no open pretty-printing box. Each box opened by one of
73       the  open_  functions  below  must be closed using close_box for proper
74       formatting. Otherwise, some of the material printed in  the  boxes  may
75       not be output, or may be formatted incorrectly.  In case of interactive
76       use, each phrase is executed in  the  initial  state  of  the  standard
77       pretty-printer:  after  each  phrase  execution, the interactive system
78       closes all open pretty-printing boxes, flushes all  pending  text,  and
79       resets   the   standard   pretty-printer.   Warning:  mixing  calls  to
80       pretty-printing functions of this module with calls to  Pervasives  low
81       level  output  functions is error prone.  The pretty-printing functions
82       output material that is delayed in the pretty-printer queue and  stacks
83       in  order to compute proper line splitting. In contrast, basic I/O out‐
84       put functions write directly in their output device. As a  consequence,
85       the  output  of  a basic I/O function may appear before the output of a
86       pretty-printing function that has been  called  before.  For  instance,
87       Pervasives.print_string   <   ;  Format.print_string  PRETTY  ;  Perva‐
88       sives.print_string > ;  Format.print_string  TEXT  ;  leads  to  output
89       <>PRETTYTEXT. ===
90
91
92       type formatter
93
94
95       Abstract  data corresponding to a pretty-printer (also called a format‐
96       ter) and all its machinery. See also Format.formatter .
97
98
99
100
101       === Pretty-printing boxes ===
102
103
104       === The pretty-printing engine uses the concepts of pretty-printing box
105       and  break hint to drive indentation and line splitting behavior of the
106       pretty-printer.  Each different pretty-printing box kind  introduces  a
107       specific line splitting policy: - within an horizontal box, break hints
108       never split the line (but the  line  may  be  split  in  a  box  nested
109       deeper),  - within a vertical box, break hints always split the line, -
110       within an horizontal/vertical box, if the box fits on the current  line
111       then  break  hints  never  split  the line, otherwise break hint always
112       split the line, - within a compacting box, a break  hint  never  splits
113       the  line, unless there is no more room on the current line.  Note that
114       line splitting policy is box specific: the policy of  a  box  does  not
115       rule  the  policy  of  inner  boxes. For instance, if a vertical box is
116       nested in an horizontal box, all break hints within  the  vertical  box
117       will split the line. ===
118
119
120       val pp_open_box : formatter -> int -> unit
121
122
123
124
125       val open_box : int -> unit
126
127
128       pp_open_box  ppf d opens a new compacting pretty-printing box with off‐
129       set d in the formatter ppf .
130
131       Within this box, the pretty-printer prints as much as possible material
132       on every line.
133
134       A  break  hint  splits the line if there is no more room on the line to
135       print the remainder of the box.
136
137       Within this box, the pretty-printer emphasizes  the  box  structure:  a
138       break  hint also splits the line if the splitting ``moves to the left''
139       (i.e. the new line gets an indentation smaller than the one of the cur‐
140       rent line).
141
142       This box is the general purpose pretty-printing box.
143
144       If  the pretty-printer splits the line in the box, offset d is added to
145       the current indentation.
146
147
148
149       val pp_close_box : formatter -> unit -> unit
150
151
152
153
154       val close_box : unit -> unit
155
156       Closes the most recently open pretty-printing box.
157
158
159
160       val pp_open_hbox : formatter -> unit -> unit
161
162
163
164
165       val open_hbox : unit -> unit
166
167
168       pp_open_hbox ppf () opens a new 'horizontal' pretty-printing box.
169
170       This box prints material on a single line.
171
172       Break hints in a horizontal box never split the line.  (Line  splitting
173       may still occur inside boxes nested deeper).
174
175
176
177       val pp_open_vbox : formatter -> int -> unit
178
179
180
181
182       val open_vbox : int -> unit
183
184
185       pp_open_vbox ppf d opens a new 'vertical' pretty-printing box with off‐
186       set d .
187
188       This box prints material on as many lines as break hints in the box.
189
190       Every break hint in a vertical box splits the line.
191
192       If the pretty-printer splits the line in the box, d  is  added  to  the
193       current indentation.
194
195
196
197       val pp_open_hvbox : formatter -> int -> unit
198
199
200
201
202       val open_hvbox : int -> unit
203
204
205       pp_open_hvbox  ppf  d opens a new 'horizontal/vertical' pretty-printing
206       box with offset d .
207
208       This box behaves as an horizontal box if it fits on a single line, oth‐
209       erwise it behaves as a vertical box.
210
211       If  the  pretty-printer  splits  the line in the box, d is added to the
212       current indentation.
213
214
215
216       val pp_open_hovbox : formatter -> int -> unit
217
218
219
220
221       val open_hovbox : int -> unit
222
223
224       pp_open_hovbox ppf d opens a new 'horizontal-or-vertical' pretty-print‐
225       ing box with offset d .
226
227       This box prints material as much as possible on every line.
228
229       A  break  hint  splits the line if there is no more room on the line to
230       print the remainder of the box.
231
232       If the pretty-printer splits the line in the box, d  is  added  to  the
233       current indentation.
234
235
236
237
238       === Formatting functions ===
239
240
241       val pp_print_string : formatter -> string -> unit
242
243
244
245
246       val print_string : string -> unit
247
248
249       pp_print_string ppf s prints s in the current pretty-printing box.
250
251
252
253       val pp_print_as : formatter -> int -> string -> unit
254
255
256
257
258       val print_as : int -> string -> unit
259
260
261       pp_print_as ppf len s prints s in the current pretty-printing box.  The
262       pretty-printer formats s as if it were of length len .
263
264
265
266       val pp_print_int : formatter -> int -> unit
267
268
269
270
271       val print_int : int -> unit
272
273       Print an integer in the current pretty-printing box.
274
275
276
277       val pp_print_float : formatter -> float -> unit
278
279
280
281
282       val print_float : float -> unit
283
284       Print a floating point number in the current pretty-printing box.
285
286
287
288       val pp_print_char : formatter -> char -> unit
289
290
291
292
293       val print_char : char -> unit
294
295       Print a character in the current pretty-printing box.
296
297
298
299       val pp_print_bool : formatter -> bool -> unit
300
301
302
303
304       val print_bool : bool -> unit
305
306       Print a boolean in the current pretty-printing box.
307
308
309
310
311       === Break hints ===
312
313
314       === A 'break hint' tells the pretty-printer to  output  some  space  or
315       split  the  line  whichever  way  is  more  appropriate  to the current
316       pretty-printing box splitting rules.  Break hints are used to  separate
317       printing  items  and  are mandatory to let the pretty-printer correctly
318       split lines and indent items.  Simple break hints are: -  the  'space':
319       output a space or split the line if appropriate, - the 'cut': split the
320       line if appropriate.  Note: the notions of space and line splitting are
321       abstract  for  the  pretty-printing  engine, since those notions can be
322       completely redefined by the programmer.  However, in the pretty-printer
323       default setting, ``output a space'' simply means printing a space char‐
324       acter (ASCII code 32) and ``split the line'' means printing  a  newline
325       character (ASCII code 10). ===
326
327
328       val pp_print_space : formatter -> unit -> unit
329
330
331
332
333       val print_space : unit -> unit
334
335
336       pp_print_space  ppf  ()  emits a 'space' break hint: the pretty-printer
337       may split the line at this point, otherwise it prints one space.
338
339
340       pp_print_space ppf () is equivalent to pp_print_break ppf 1 0 .
341
342
343
344       val pp_print_cut : formatter -> unit -> unit
345
346
347
348
349       val print_cut : unit -> unit
350
351
352       pp_print_cut ppf () emits a 'cut' break hint:  the  pretty-printer  may
353       split the line at this point, otherwise it prints nothing.
354
355
356       pp_print_cut ppf () is equivalent to pp_print_break ppf 0 0 .
357
358
359
360       val pp_print_break : formatter -> int -> int -> unit
361
362
363
364
365       val print_break : int -> int -> unit
366
367
368       pp_print_break  ppf  nspaces  offset  emits  a  'full'  break hint: the
369       pretty-printer may split the line at this point,  otherwise  it  prints
370       nspaces spaces.
371
372       If  the  pretty-printer splits the line, offset is added to the current
373       indentation.
374
375
376
377       val pp_force_newline : formatter -> unit -> unit
378
379
380
381
382       val force_newline : unit -> unit
383
384       Force a new line in the current pretty-printing box.
385
386       The pretty-printer must split the line at this point,
387
388       Not the normal way of pretty-printing, since imperative line  splitting
389       may  interfere  with  current  line  counters and box size calculation.
390       Using break hints within an enclosing vertical box is a better alterna‐
391       tive.
392
393
394
395       val pp_print_if_newline : formatter -> unit -> unit
396
397
398
399
400       val print_if_newline : unit -> unit
401
402       Execute the next formatting command if the preceding line has just been
403       split. Otherwise, ignore the next formatting command.
404
405
406
407
408       === Pretty-printing termination ===
409
410
411       val pp_print_flush : formatter -> unit -> unit
412
413
414
415
416       val print_flush : unit -> unit
417
418       End of pretty-printing: resets the pretty-printer to initial state.
419
420       All open pretty-printing boxes are closed, all pending text is printed.
421       In  addition,  the pretty-printer low level output device is flushed to
422       ensure that all pending text is really displayed.
423
424       Note: never use print_flush in the normal course of  a  pretty-printing
425       routine, since the pretty-printer uses a complex buffering machinery to
426       properly indent the output; manually flushing those buffers  at  random
427       would conflict with the pretty-printer strategy and result to poor ren‐
428       dering.
429
430       Only consider using print_flush when displaying all pending material is
431       mandatory  (for  instance  in case of interactive use when you want the
432       user to read some text) and when  resetting  the  pretty-printer  state
433       will not disturb further pretty-printing.
434
435       Warning:  If the output device of the pretty-printer is an output chan‐
436       nel, repeated calls to  print_flush  means  repeated  calls  to  Perva‐
437       sives.flush  to flush the out channel; these explicit flush calls could
438       foil the buffering strategy of output channels and  could  dramatically
439       impact efficiency.
440
441
442
443       val pp_print_newline : formatter -> unit -> unit
444
445
446
447
448       val print_newline : unit -> unit
449
450       End of pretty-printing: resets the pretty-printer to initial state.
451
452       All open pretty-printing boxes are closed, all pending text is printed.
453
454       Equivalent  to  Format.print_flush  followed by a new line.  See corre‐
455       sponding words of caution for Format.print_flush .
456
457       Note: this is not the normal way to output a new  line;  the  preferred
458       method is using break hints within a vertical pretty-printing box.
459
460
461
462
463       === Margin ===
464
465
466       val pp_set_margin : formatter -> int -> unit
467
468
469
470
471       val set_margin : int -> unit
472
473
474       pp_set_margin  ppf  d  sets  the right margin to d (in characters): the
475       pretty-printer splits lines that overflow the right margin according to
476       the  break  hints given.  Nothing happens if d is smaller than 2.  If d
477       is too large, the right margin is set to the maximum  admissible  value
478       (which is greater than 10 ^ 9 ).  If d is less than the current maximum
479       indentation limit, the maximum indentation  limit  is  decreased  while
480       trying to preserve a minimal ratio max_indent/margin>=50% and if possi‐
481       ble the current difference margin - max_indent .
482
483
484
485       val pp_get_margin : formatter -> unit -> int
486
487
488
489
490       val get_margin : unit -> int
491
492       Returns the position of the right margin.
493
494
495
496
497       === Maximum indentation limit ===
498
499
500       val pp_set_max_indent : formatter -> int -> unit
501
502
503
504
505       val set_max_indent : int -> unit
506
507
508       pp_set_max_indent ppf d sets the maximum indentation limit of lines  to
509       d  (in  characters):  once  this  limit is reached, new pretty-printing
510       boxes are rejected to the left, if they do not fit on the current line.
511
512       Nothing happens if d is smaller than 2.  If d is too large,  the  limit
513       is set to the maximum admissible value (which is greater than 10 ^ 9 ).
514
515       If  d  is  greater or equal than the current margin, it is ignored, and
516       the current maximum indentation limit is kept.
517
518
519
520       val pp_get_max_indent : formatter -> unit -> int
521
522
523
524
525       val get_max_indent : unit -> int
526
527       Return the maximum indentation limit (in characters).
528
529
530
531
532       === Maximum formatting depth ===
533
534
535       === The maximum formatting depth is the maximum number of pretty-print‐
536       ing  boxes simultaneously open.  Material inside boxes nested deeper is
537       printed as an ellipsis (more precisely as the  text  returned  by  For‐
538       mat.get_ellipsis_text ()). ===
539
540
541       val pp_set_max_boxes : formatter -> int -> unit
542
543
544
545
546       val set_max_boxes : int -> unit
547
548
549       pp_set_max_boxes  ppf  max  sets  the maximum number of pretty-printing
550       boxes simultaneously open.
551
552       Material inside boxes nested deeper is printed  as  an  ellipsis  (more
553       precisely as the text returned by Format.get_ellipsis_text () ).
554
555       Nothing happens if max is smaller than 2.
556
557
558
559       val pp_get_max_boxes : formatter -> unit -> int
560
561
562
563
564       val get_max_boxes : unit -> int
565
566       Returns  the  maximum  number  of  pretty-printing boxes allowed before
567       ellipsis.
568
569
570
571       val pp_over_max_boxes : formatter -> unit -> bool
572
573
574
575
576       val over_max_boxes : unit -> bool
577
578       Tests if the maximum  number  of  pretty-printing  boxes  allowed  have
579       already been opened.
580
581
582
583
584       === Tabulation boxes ===
585
586
587       ===  A  tabulation  box  prints material on lines divided into cells of
588       fixed length. A tabulation box provides a simple way to display  verti‐
589       cal  columns  of left adjusted text.  This box features command set_tab
590       to define cell boundaries, and command print_tab to move from  cell  to
591       cell  and  split  the  line when there is no more cells to print on the
592       line.  Note: printing within tabulation box is line directed, so  arbi‐
593       trary  line  splitting inside a tabulation box leads to poor rendering.
594       Yet, controlled use of tabulation boxes allows simple printing of  col‐
595       umns within module Format. ===
596
597
598       val pp_open_tbox : formatter -> unit -> unit
599
600
601
602
603       val open_tbox : unit -> unit
604
605
606       open_tbox () opens a new tabulation box.
607
608       This box prints lines separated into cells of fixed width.
609
610       Inside  a  tabulation box, special tabulation markers defines points of
611       interest on the line (for instance to delimit cell boundaries).   Func‐
612       tion Format.set_tab sets a tabulation marker at insertion point.
613
614       A  tabulation  box  features specific tabulation breaks to move to next
615       tabulation marker  or  split  the  line.  Function  Format.print_tbreak
616       prints a tabulation break.
617
618
619
620       val pp_close_tbox : formatter -> unit -> unit
621
622
623
624
625       val close_tbox : unit -> unit
626
627       Closes the most recently opened tabulation box.
628
629
630
631       val pp_set_tab : formatter -> unit -> unit
632
633
634
635
636       val set_tab : unit -> unit
637
638       Sets a tabulation marker at current insertion point.
639
640
641
642       val pp_print_tab : formatter -> unit -> unit
643
644
645
646
647       val print_tab : unit -> unit
648
649
650       print_tab  ()  emits a 'next' tabulation break hint: if not already set
651       on a tabulation marker, the insertion point moves to the first  tabula‐
652       tion  marker  on  the  right, or the pretty-printer splits the line and
653       insertion point moves to the leftmost tabulation marker.
654
655       It is equivalent to print_tbreak 0 0 .
656
657
658
659       val pp_print_tbreak : formatter -> int -> int -> unit
660
661
662
663
664       val print_tbreak : int -> int -> unit
665
666
667       print_tbreak nspaces offset emits a 'full' tabulation break hint.
668
669       If not already set on a tabulation marker, the insertion point moves to
670       the  first tabulation marker on the right and the pretty-printer prints
671       nspaces spaces.
672
673       If there is no next tabulation marker on the right, the  pretty-printer
674       splits  the line at this point, then insertion point moves to the left‐
675       most tabulation marker of the box.
676
677       If the pretty-printer splits the line, offset is added to  the  current
678       indentation.
679
680
681
682
683       === Ellipsis ===
684
685
686       val pp_set_ellipsis_text : formatter -> string -> unit
687
688
689
690
691       val set_ellipsis_text : string -> unit
692
693       Set  the  text  of  the  ellipsis printed when too many pretty-printing
694       boxes are open (a single dot, .  , by default).
695
696
697
698       val pp_get_ellipsis_text : formatter -> unit -> string
699
700
701
702
703       val get_ellipsis_text : unit -> string
704
705       Return the text of the ellipsis.
706
707
708
709
710       === Semantic tags ===
711
712
713       type tag = string
714
715
716
717
718
719
720       === Semantic tags (or simply tags) are user's defined delimiters to as‐
721       sociate  user's  specific operations to printed entities.  Common usage
722       of semantic tags is text decoration to get specific font or  text  size
723       rendering  for  a  display  device, or marking delimitation of entities
724       (e.g. HTML or TeX elements or terminal escape sequences).  More sophis‐
725       ticated usage of semantic tags could handle dynamic modification of the
726       pretty-printer behavior to properly print the material within some spe‐
727       cific  tags.  In order to properly delimit printed entities, a semantic
728       tag must be opened before and closed after the  entity.  Semantic  tags
729       must  be  properly  nested  like  parentheses.  Tag specific operations
730       occur any time a tag is opened or closed, At each occurrence, two kinds
731       of  operations  are  performed  tag-marking  and  tag-printing:  -  The
732       tag-marking operation is the simpler tag specific operation: it  simply
733       writes  a  tag specific string into the output device of the formatter.
734       Tag-marking does not interfere with line-splitting computation.  -  The
735       tag-printing  operation is the more involved tag specific operation: it
736       can print arbitrary material to the formatter. Tag-printing is  tightly
737       linked  to  the  current  pretty-printer operations.  Roughly speaking,
738       tag-marking is commonly used to get a better rendering of texts in  the
739       rendering  device,  while  tag-printing  allows fine tuning of printing
740       routines to print the same entity differently according to the semantic
741       tags (i.e. print additional material or even omit parts of the output).
742       More precisely: when a semantic tag is opened or closed then  both  and
743       successive   'tag-printing'   and  'tag-marking'  operations  occur:  -
744       Tag-printing a semantic tag means calling the formatter specific  func‐
745       tion print_open_tag (resp. print_close_tag) with the name of the tag as
746       argument: that tag-printing function can then print any  regular  mate‐
747       rial  to  the  formatter (so that this material is enqueued as usual in
748       the  formatter  queue  for  further  line  splitting  computation).   -
749       Tag-marking  a  semantic tag means calling the formatter specific func‐
750       tion mark_open_tag (resp. mark_close_tag) with the name of the  tag  as
751       argument:  that  tag-marking  function can then return the 'tag-opening
752       marker' (resp. `tag-closing marker') for direct output into the  output
753       device of the formatter.  Being written directly into the output device
754       of the formatter, semantic tag marker strings  are  not  considered  as
755       part  of  the  printing  material  that drives line splitting (in other
756       words, the length of the strings corresponding to tag markers  is  con‐
757       sidered as zero for line splitting).  Thus, semantic tag handling is in
758       some sense transparent to pretty-printing and does not  interfere  with
759       usual  indentation.  Hence, a single pretty-printing routine can output
760       both simple 'verbatim' material or richer decorated output depending on
761       the  treatment of tags. By default, tags are not active, hence the out‐
762       put is not decorated with tag information.  Once  set_tags  is  set  to
763       true,  the  pretty-printer  engine honors tags and decorates the output
764       accordingly.  Default tag-marking functions behave the HTML  way:  tags
765       are  enclosed  in  < and > ; hence, opening marker for tag t is <t> and
766       closing marker is </t> .  Default tag-printing functions just do  noth‐
767       ing.  Tag-marking and tag-printing functions are user definable and can
768       be set by  calling  Format.set_formatter_tag_functions.   Semantic  tag
769       operations  may  be  set  on  or off with Format.set_tags.  Tag-marking
770       operations may be set on or off with Format.set_mark_tags.   Tag-print‐
771       ing operations may be set on or off with Format.set_print_tags. ===
772
773
774       val pp_open_tag : formatter -> string -> unit
775
776
777
778
779       val open_tag : tag -> unit
780
781
782       pp_open_tag ppf t opens the semantic tag named t .
783
784       The  print_open_tag  tag-printing  function  of the formatter is called
785       with t as argument; then the opening tag marker for t  ,  as  given  by
786       mark_open_tag t , is written into the output device of the formatter.
787
788
789
790       val pp_close_tag : formatter -> unit -> unit
791
792
793
794
795       val close_tag : unit -> unit
796
797
798       pp_close_tag ppf () closes the most recently opened semantic tag t .
799
800       The  closing tag marker, as given by mark_close_tag t , is written into
801       the output device of the formatter; then the print_close_tag tag-print‐
802       ing function of the formatter is called with t as argument.
803
804
805
806       val pp_set_tags : formatter -> bool -> unit
807
808
809
810
811       val set_tags : bool -> unit
812
813
814       pp_set_tags  ppf  b  turns  on  or  off  the treatment of semantic tags
815       (default is off).
816
817
818
819       val pp_set_print_tags : formatter -> bool -> unit
820
821
822
823
824       val set_print_tags : bool -> unit
825
826
827       pp_set_print_tags ppf b turns on or off the tag-printing operations.
828
829
830
831       val pp_set_mark_tags : formatter -> bool -> unit
832
833
834
835
836       val set_mark_tags : bool -> unit
837
838
839       pp_set_mark_tags ppf b turns on or off the tag-marking operations.
840
841
842
843       val pp_get_print_tags : formatter -> unit -> bool
844
845
846
847
848       val get_print_tags : unit -> bool
849
850       Return the current status of tag-printing operations.
851
852
853
854       val pp_get_mark_tags : formatter -> unit -> bool
855
856
857
858
859       val get_mark_tags : unit -> bool
860
861       Return the current status of tag-marking operations.
862
863
864
865       val pp_set_formatter_out_channel : formatter ->  Pervasives.out_channel
866       -> unit
867
868
869       Redirecting the standard formatter output
870
871
872
873
874       val set_formatter_out_channel : Pervasives.out_channel -> unit
875
876       Redirect the standard pretty-printer output to the given channel.  (All
877       the output functions of the standard formatter are set to  the  default
878       output functions printing to the given channel.)
879
880
881       set_formatter_out_channel   is   equivalent   to  Format.pp_set_format‐
882       ter_out_channel std_formatter .
883
884
885
886       val pp_set_formatter_output_functions : formatter -> (string -> int  ->
887       int -> unit) -> (unit -> unit) -> unit
888
889
890
891
892       val  set_formatter_output_functions : (string -> int -> int -> unit) ->
893       (unit -> unit) -> unit
894
895
896       pp_set_formatter_output_functions ppf out flush redirects the  standard
897       pretty-printer output functions to the functions out and flush .
898
899       The  out function performs all the pretty-printer string output.  It is
900       called with a string s , a start position p , and a number  of  charac‐
901       ters n ; it is supposed to output characters p to p + n - 1 of s .
902
903       The  flush  function  is  called whenever the pretty-printer is flushed
904       (via conversion %!  , or pretty-printing indications @?  or  @.   ,  or
905       using low level functions print_flush or print_newline ).
906
907
908
909       val pp_get_formatter_output_functions : formatter -> unit -> (string ->
910       int -> int -> unit) * (unit -> unit)
911
912
913
914
915       val get_formatter_output_functions : unit -> (string -> int ->  int  ->
916       unit) * (unit -> unit)
917
918       Return the current output functions of the standard pretty-printer.
919
920
921
922
923       === Redefining formatter output ===
924
925
926       ===  The  Format module is versatile enough to let you completely rede‐
927       fine the meaning of pretty-printing output: you may  provide  your  own
928       functions to define how to handle indentation, line splitting, and even
929       printing of all the characters that have to be printed! ===
930
931
932       === Redefining output functions ===
933
934
935       type formatter_out_functions = {
936        out_string : string -> int -> int -> unit ;
937        out_flush : unit -> unit ;
938        out_newline : unit -> unit ;
939        out_spaces : int -> unit ;
940        out_indent : int -> unit ;
941        }
942
943
944       The set of output functions specific to a formatter:
945
946       -the out_string function performs all the pretty-printer string output.
947       It  is  called  with  a string s , a start position p , and a number of
948       characters n ; it is supposed to output characters p to p + n - 1 of  s
949       .
950
951       -the out_flush function flushes the pretty-printer output device.
952
953       -  out_newline  is  called  to  open a new line when the pretty-printer
954       splits the line.
955
956       -the out_spaces function outputs spaces when a break hint leads to spa‐
957       ces  instead of a line split. It is called with the number of spaces to
958       output.
959
960       -the  out_indent  function  performs  new  line  indentation  when  the
961       pretty-printer splits the line. It is called with the indentation value
962       of the new line.
963
964       By default:
965
966       -fields out_string and out_flush  are  output  device  specific;  (e.g.
967       Pervasives.output_string    and    Pervasives.flush    for   a   Perva‐
968       sives.out_channel device, or Buffer.add_substring and Pervasives.ignore
969       for a Buffer.t output device),
970
971       -field out_newline is equivalent to out_string \n 0 1 ;
972
973       -fields   out_spaces   and  out_indent  are  equivalent  to  out_string
974       (String.make n ' ') 0 n .
975
976
977
978       Since 4.01.0
979
980
981
982       val pp_set_formatter_out_functions : formatter  ->  formatter_out_func‐
983       tions -> unit
984
985
986
987
988       val set_formatter_out_functions : formatter_out_functions -> unit
989
990
991       pp_set_formatter_out_functions  ppf out_funs Set all the pretty-printer
992       output functions of ppf to those of argument out_funs ,
993
994       This way, you can change the meaning of indentation (which can be some‐
995       thing  else than just printing space characters) and the meaning of new
996       lines opening (which can be connected to any other action needed by the
997       application at hand).
998
999       Reasonable  defaults  for  functions  out_spaces  and  out_newline  are
1000       respectively  out_funs.out_string  (String.make  n  '  ')   0   n   and
1001       out_funs.out_string \n 0 1 .
1002
1003
1004       Since 4.01.0
1005
1006
1007
1008       val  pp_get_formatter_out_functions  :  formatter  ->  unit  -> format‐
1009       ter_out_functions
1010
1011
1012
1013
1014       val get_formatter_out_functions : unit -> formatter_out_functions
1015
1016       Return the current output functions of  the  pretty-printer,  including
1017       line  splitting and indentation functions. Useful to record the current
1018       setting and restore it afterwards.
1019
1020
1021       Since 4.01.0
1022
1023
1024
1025
1026       === Redefining semantic tag operations ===
1027
1028
1029       type formatter_tag_functions = {
1030        mark_open_tag : tag -> string ;
1031        mark_close_tag : tag -> string ;
1032        print_open_tag : tag -> unit ;
1033        print_close_tag : tag -> unit ;
1034        }
1035
1036
1037       The semantic tag handling functions specific to a formatter: mark  ver‐
1038       sions are the 'tag-marking' functions that associate a string marker to
1039       a tag in order for the pretty-printing engine to write those markers as
1040       0  length tokens in the output device of the formatter.  print versions
1041       are the 'tag-printing' functions that can perform regular printing when
1042       a tag is closed or opened.
1043
1044
1045
1046       val  pp_set_formatter_tag_functions  : formatter -> formatter_tag_func‐
1047       tions -> unit
1048
1049
1050
1051
1052       val set_formatter_tag_functions : formatter_tag_functions -> unit
1053
1054
1055       pp_set_formatter_tag_functions ppf  tag_funs  changes  the  meaning  of
1056       opening  and  closing  semantic  tag operations to use the functions in
1057       tag_funs when printing on ppf .
1058
1059       When opening a semantic tag with name t , the string t is passed to the
1060       opening  tag-marking  function  (the  mark_open_tag field of the record
1061       tag_funs ), that must return the opening tag marker for that name. When
1062       the  next call to close_tag () happens, the semantic tag name t is sent
1063       back to the closing tag-marking function (the mark_close_tag  field  of
1064       record tag_funs ), that must return a closing tag marker for that name.
1065
1066       The print_ field of the record contains the tag-printing functions that
1067       are called at tag opening and tag closing time, to output regular mate‐
1068       rial in the pretty-printer queue.
1069
1070
1071
1072       val  pp_get_formatter_tag_functions  :  formatter  ->  unit  -> format‐
1073       ter_tag_functions
1074
1075
1076
1077
1078       val get_formatter_tag_functions : unit -> formatter_tag_functions
1079
1080       Return the current semantic tag operation  functions  of  the  standard
1081       pretty-printer.
1082
1083
1084
1085
1086       ===  Defining formatters Defining new formatters permits unrelated out‐
1087       put of material in parallel on several output devices.  All the parame‐
1088       ters  of  a formatter are local to the formatter: right margin, maximum
1089       indentation limit, maximum number of pretty-printing  boxes  simultane‐
1090       ously open, ellipsis, and so on, are specific to each formatter and may
1091       be fixed independently.  For instance, given a Buffer.t buffer b,  For‐
1092       mat.formatter_of_buffer b returns a new formatter using buffer b as its
1093       output device.  Similarly, given a Pervasives.out_channel output  chan‐
1094       nel  oc,  Format.formatter_of_out_channel  oc  returns  a new formatter
1095       using channel oc as its output device.  Alternatively, given  out_funs,
1096       a complete set of output functions for a formatter, then Format.format‐
1097       ter_of_out_functions out_funs computes  a  new  formatter  using  those
1098       functions for output. ===
1099
1100
1101       val formatter_of_out_channel : Pervasives.out_channel -> formatter
1102
1103
1104       formatter_of_out_channel oc returns a new formatter writing to the cor‐
1105       responding output channel oc .
1106
1107
1108
1109       val std_formatter : formatter
1110
1111       The standard formatter to write to standard output.
1112
1113       It is defined as Format.formatter_of_out_channel Pervasives.stdout .
1114
1115
1116
1117       val err_formatter : formatter
1118
1119       A formatter to write to standard error.
1120
1121       It is defined as Format.formatter_of_out_channel Pervasives.stderr .
1122
1123
1124
1125       val formatter_of_buffer : Buffer.t -> formatter
1126
1127
1128       formatter_of_buffer b returns a new formatter writing to buffer b .  At
1129       the  end  of  pretty-printing, the formatter must be flushed using For‐
1130       mat.pp_print_flush or Format.pp_print_newline , to print all the  pend‐
1131       ing material into the buffer.
1132
1133
1134
1135       val stdbuf : Buffer.t
1136
1137       The string buffer in which str_formatter writes.
1138
1139
1140
1141       val str_formatter : formatter
1142
1143       A formatter to output to the Format.stdbuf string buffer.
1144
1145
1146       str_formatter is defined as Format.formatter_of_buffer Format.stdbuf .
1147
1148
1149
1150       val flush_str_formatter : unit -> string
1151
1152       Returns the material printed with str_formatter , flushes the formatter
1153       and resets the corresponding buffer.
1154
1155
1156
1157       val make_formatter : (string -> int -> int -> unit) -> (unit  ->  unit)
1158       -> formatter
1159
1160
1161       make_formatter  out  flush  returns  a  new formatter that outputs with
1162       function out , and flushes with function flush .
1163
1164       For instance, make_formatter (Pervasives.output oc) (fun ()  ->  Perva‐
1165       sives.flush oc) returns a formatter to the Pervasives.out_channel oc .
1166
1167
1168
1169       val formatter_of_out_functions : formatter_out_functions -> formatter
1170
1171
1172       formatter_of_out_functions out_funs returns a new formatter that writes
1173       with the set of output functions out_funs .
1174
1175       See definition of type Format.formatter_out_functions for  the  meaning
1176       of argument out_funs .
1177
1178
1179       Since 4.06.0
1180
1181
1182
1183
1184       === Symbolic pretty-printing ===
1185
1186
1187       ===  Symbolic  pretty-printing is pretty-printing using a symbolic for‐
1188       matter, i.e. a formatter that outputs symbolic  pretty-printing  items.
1189       When using a symbolic formatter, all regular pretty-printing activities
1190       occur but output material is symbolic and stored in a buffer of  output
1191       items.   At  the  end  of  pretty-printing,  flushing the output buffer
1192       allows post-processing of symbolic output before performing  low  level
1193       output  operations.  In practice, first define a symbolic output buffer
1194       b using: - let sob = make_symbolic_output_buffer  ().   Then  define  a
1195       symbolic  formatter with: - let ppf = formatter_of_symbolic_output_buf‐
1196       fer sob Use symbolic formatter ppf  as  usual,  and  retrieve  symbolic
1197       items  at end of pretty-printing by flushing symbolic output buffer sob
1198       with: - flush_symbolic_output_buffer sob.  ===
1199
1200
1201       type symbolic_output_item =
1202        | Output_flush  (* symbolic flush command
1203        *)
1204        | Output_newline  (* symbolic newline command
1205        *)
1206        | Output_string of string
1207         (* Output_string s : symbolic output for string s
1208
1209        *)
1210        | Output_spaces of int
1211         (* Output_spaces n : symbolic command to output n spaces
1212        *)
1213        | Output_indent of int
1214         (* Output_indent i : symbolic indentation of size i
1215
1216        *)
1217
1218
1219       Items produced by symbolic pretty-printers
1220
1221
1222       Since 4.06.0
1223
1224
1225       type symbolic_output_buffer
1226
1227
1228       The output buffer of a symbolic pretty-printer.
1229
1230
1231       Since 4.06.0
1232
1233
1234
1235       val make_symbolic_output_buffer : unit -> symbolic_output_buffer
1236
1237
1238       make_symbolic_output_buffer () returns a fresh buffer for symbolic out‐
1239       put.
1240
1241
1242       Since 4.06.0
1243
1244
1245
1246       val clear_symbolic_output_buffer : symbolic_output_buffer -> unit
1247
1248
1249       clear_symbolic_output_buffer sob resets buffer sob .
1250
1251
1252       Since 4.06.0
1253
1254
1255
1256       val   get_symbolic_output_buffer   :   symbolic_output_buffer  ->  sym‐
1257       bolic_output_item list
1258
1259
1260       get_symbolic_output_buffer sob returns the contents of buffer sob .
1261
1262
1263       Since 4.06.0
1264
1265
1266
1267       val  flush_symbolic_output_buffer  :  symbolic_output_buffer  ->   sym‐
1268       bolic_output_item list
1269
1270
1271       flush_symbolic_output_buffer sob returns the contents of buffer sob and
1272       resets buffer sob .  flush_symbolic_output_buffer sob is equivalent  to
1273       let  items  =  get_symbolic_output_buffer  sob  in  clear_symbolic_out‐
1274       put_buffer sob; items
1275
1276
1277
1278       Since 4.06.0
1279
1280
1281
1282       val add_symbolic_output_item : symbolic_output_buffer ->  symbolic_out‐
1283       put_item -> unit
1284
1285
1286       add_symbolic_output_item sob itm adds item itm to buffer sob .
1287
1288
1289       Since 4.06.0
1290
1291
1292
1293       val  formatter_of_symbolic_output_buffer  :  symbolic_output_buffer  ->
1294       formatter
1295
1296
1297       formatter_of_symbolic_output_buffer sob returns  a  symbolic  formatter
1298       that outputs to symbolic_output_buffer sob .
1299
1300
1301       Since 4.06.0
1302
1303
1304
1305
1306       === Convenience formatting functions.  ===
1307
1308
1309       val  pp_print_list  : ?pp_sep:(formatter -> unit -> unit) -> (formatter
1310       -> 'a -> unit) -> formatter -> 'a list -> unit
1311
1312
1313       pp_print_list ?pp_sep pp_v ppf l prints items of list l , using pp_v to
1314       print  each item, and calling pp_sep between items ( pp_sep defaults to
1315       Format.pp_print_cut .  Does nothing on empty lists.
1316
1317
1318       Since 4.02.0
1319
1320
1321
1322       val pp_print_text : formatter -> string -> unit
1323
1324
1325       pp_print_text ppf s prints s  with  spaces  and  newlines  respectively
1326       printed using Format.pp_print_space and Format.pp_force_newline .
1327
1328
1329       Since 4.02.0
1330
1331
1332
1333
1334       === Formatted pretty-printing ===
1335
1336
1337       ===  Module Format provides a complete set of printf like functions for
1338       pretty-printing using format string specifications.   Specific  annota‐
1339       tions  may  be added in the format strings to give pretty-printing com‐
1340       mands to the pretty-printing engine.  Those annotations are  introduced
1341       in  the  format  strings using the @ character. For instance, @ means a
1342       space break, @, means a cut, @[ opens a new box, and @] closes the last
1343       open box. ===
1344
1345
1346       val  fprintf  : formatter -> ('a, formatter, unit) Pervasives.format ->
1347       'a
1348
1349
1350
1351
1352
1353       === fprintf ff fmt arg1 ... argN formats the  arguments  arg1  to  argN
1354       according to the format string fmt, and outputs the resulting string on
1355       the formatter ff.  The format string fmt is a  character  string  which
1356       contains three types of objects: plain characters and conversion speci‐
1357       fications as specified in the Printf module, and pretty-printing  indi‐
1358       cations  specific to the Format module.  The pretty-printing indication
1359       characters are introduced by a @ character, and their meanings  are:  -
1360       @[:  open  a pretty-printing box. The type and offset of the box may be
1361       optionally specified with the following syntax: the <  character,  fol‐
1362       lowed by an optional box type indication, then an optional integer off‐
1363       set, and the closing > character.  Pretty-printing box type is  one  of
1364       h,  v,  hv,  b, or hov.  'h' stands for an 'horizontal' pretty-printing
1365       box, 'v' stands for a 'vertical' pretty-printing box, 'hv'  stands  for
1366       an  'horizontal/vertical' pretty-printing box, 'b' stands for an 'hori‐
1367       zontal-or-vertical'  pretty-printing  box  demonstrating   indentation,
1368       'hov'  stands  a  simple  'horizontal-or-vertical' pretty-printing box.
1369       For instance, @[<hov 2> opens an 'horizontal-or-vertical' pretty-print‐
1370       ing  box  with  indentation 2 as obtained with open_hovbox 2.  For more
1371       details about pretty-printing boxes, see the various box opening  func‐
1372       tions  open_*box.  - @]: close the most recently opened pretty-printing
1373       box.  - @,: output a 'cut' break hint, as with print_cut  ().   -  @  :
1374       output  a  'space'  break hint, as with print_space ().  - @;: output a
1375       'full' break hint as with print_break. The nspaces and  offset  parame‐
1376       ters  of  the break hint may be optionally specified with the following
1377       syntax: the < character, followed by an integer nspaces value, then  an
1378       integer  offset,  and a closing > character.  If no parameters are pro‐
1379       vided, the good break defaults to a 'space' break hint.   -  @.:  flush
1380       the  pretty-printer  and  split  the line, as with print_newline ().  -
1381       @<n>: print the following item as if  it  were  of  length  n.   Hence,
1382       printf  @<0>%s  arg prints arg as a zero length string.  If @<n> is not
1383       followed by a conversion specification, then the following character of
1384       the format is printed as if it were of length n.  - @{: open a semantic
1385       tag. The name of the tag may be optionally specified with the following
1386       syntax:  the < character, followed by an optional string specification,
1387       and the closing > character. The string specification is any  character
1388       string that does not contain the closing character '>'. If omitted, the
1389       tag name defaults to the empty string.  For more details about semantic
1390       tags,  see  the  functions Format.open_tag and Format.close_tag.  - @}:
1391       close  the  most  recently  opened  semantic  tag.   -  @?:  flush  the
1392       pretty-printer  as with print_flush ().  This is equivalent to the con‐
1393       version %!.  - @\n: force a newline, as with force_newline (), not  the
1394       normal  way  of  pretty-printing,  you  should prefer using break hints
1395       inside a vertical pretty-printing box.  Note: To prevent the  interpre‐
1396       tation of a @ character as a pretty-printing indication, escape it with
1397       a % character.  Old quotation mode @@ is deprecated  since  it  is  not
1398       compatible with formatted input interpretation of character '@'.  Exam‐
1399       ple:  printf  @[%s@  %d@]@.  x  =  1  is  equivalent  to  open_box  ();
1400       print_string   x  =  ;  print_space  ();  print_int  1;  close_box  ();
1401       print_newline ().  It prints x = 1 within a  pretty-printing  'horizon‐
1402       tal-or-vertical' box. ===
1403
1404
1405       val printf : ('a, formatter, unit) Pervasives.format -> 'a
1406
1407       Same as fprintf above, but output on std_formatter .
1408
1409
1410
1411       val eprintf : ('a, formatter, unit) Pervasives.format -> 'a
1412
1413       Same as fprintf above, but output on err_formatter .
1414
1415
1416
1417       val sprintf : ('a, unit, string) Pervasives.format -> 'a
1418
1419       Same as printf above, but instead of printing on a formatter, returns a
1420       string containing the result of formatting the  arguments.   Note  that
1421       the  pretty-printer queue is flushed at the end of each call to sprintf
1422       .
1423
1424       In case of multiple and related calls to sprintf to output material  on
1425       a  single string, you should consider using fprintf with the predefined
1426       formatter str_formatter and call  flush_str_formatter  ()  to  get  the
1427       final result.
1428
1429       Alternatively, you can use Format.fprintf with a formatter writing to a
1430       buffer of your own: flushing the formatter and the buffer at the end of
1431       pretty-printing returns the desired string.
1432
1433
1434
1435       val asprintf : ('a, formatter, unit, string) Pervasives.format4 -> 'a
1436
1437       Same as printf above, but instead of printing on a formatter, returns a
1438       string containing the result of formatting the arguments.  The type  of
1439       asprintf is general enough to interact nicely with %a conversions.
1440
1441
1442       Since 4.01.0
1443
1444
1445
1446       val  ifprintf : formatter -> ('a, formatter, unit) Pervasives.format ->
1447       'a
1448
1449       Same as fprintf above, but does not print anything.  Useful  to  ignore
1450       some material when conditionally printing.
1451
1452
1453       Since 3.10.0
1454
1455
1456
1457
1458       === Formatted Pretty-Printing with continuations. ===
1459
1460
1461       val  kfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1462       'a) Pervasives.format4 -> 'b
1463
1464       Same as fprintf above, but instead of returning immediately, passes the
1465       formatter to its first argument at the end of printing.
1466
1467
1468
1469       val ikfprintf : (formatter -> 'a) -> formatter -> ('b, formatter, unit,
1470       'a) Pervasives.format4 -> 'b
1471
1472       Same as kfprintf above, but does not print anything.  Useful to  ignore
1473       some material when conditionally printing.
1474
1475
1476       Since 3.12.0
1477
1478
1479
1480       val ksprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.for‐
1481       mat4 -> 'b
1482
1483       Same as sprintf above, but instead of returning the string,  passes  it
1484       to the first argument.
1485
1486
1487
1488       val  kasprintf  :  (string  ->  'a) -> ('b, formatter, unit, 'a) Perva‐
1489       sives.format4 -> 'b
1490
1491       Same as asprintf above, but instead of returning the string, passes  it
1492       to the first argument.
1493
1494
1495       Since 4.03
1496
1497
1498
1499
1500       === Deprecated ===
1501
1502
1503       val bprintf : Buffer.t -> ('a, formatter, unit) Pervasives.format -> 'a
1504
1505       Deprecated.   This  function is error prone. Do not use it.  This func‐
1506       tion is neither compositional nor incremental,  since  it  flushes  the
1507       pretty-printer queue at each call.
1508
1509       If you need to print to some buffer b , you must first define a format‐
1510       ter writing to b , using let to_b = formatter_of_buffer b  ;  then  use
1511       regular calls to Format.fprintf with formatter to_b .
1512
1513
1514
1515       val  kprintf : (string -> 'a) -> ('b, unit, string, 'a) Pervasives.for‐
1516       mat4 -> 'b
1517
1518       Deprecated.  An alias for ksprintf .
1519
1520
1521
1522       val set_all_formatter_output_functions : out:(string -> int ->  int  ->
1523       unit)  -> flush:(unit -> unit) -> newline:(unit -> unit) -> spaces:(int
1524       -> unit) -> unit
1525
1526       Deprecated.  Subsumed by set_formatter_out_functions .
1527
1528
1529
1530       val get_all_formatter_output_functions : unit -> (string -> int ->  int
1531       -> unit) * (unit -> unit) * (unit -> unit) * (int -> unit)
1532
1533       Deprecated.  Subsumed by get_formatter_out_functions .
1534
1535
1536
1537       val pp_set_all_formatter_output_functions : formatter -> out:(string ->
1538       int -> int -> unit) -> flush:(unit -> unit) -> newline:(unit  ->  unit)
1539       -> spaces:(int -> unit) -> unit
1540
1541       Deprecated.  Subsumed by pp_set_formatter_out_functions .
1542
1543
1544
1545       val   pp_get_all_formatter_output_functions  :  formatter  ->  unit  ->
1546       (string -> int -> int -> unit) * (unit -> unit) * (unit -> unit) * (int
1547       -> unit)
1548
1549       Deprecated.  Subsumed by pp_get_formatter_out_functions .
1550
1551
1552
1553
1554
1555OCamldoc                          2018-07-14                         Format(3)
Impressum