Project

General

Profile

Statistics
| Branch: | Tag: | Revision:

lustrec / src / Print.mli @ 22fe1c93

History | View | Annotate | Download (5.31 KB)

1
(* $Id$ *)
2

    
3
(*
4
 * Copyright (c) 2009 CNRS & Université Bordeaux 1.
5
 *
6
 * Author(s): Grégoire Sutre <gregoire.sutre@labri.fr>
7
 *
8
 * Permission to use, copy, modify, and distribute this software for any
9
 * purpose with or without fee is hereby granted, provided that the above
10
 * copyright notice and this permission notice appear in all copies.
11
 *
12
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
13
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
15
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
18
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19
 *)
20

    
21

    
22
(**
23
  Signatures and helper functions for pretty-printing.
24
 
25
  This module follows the standard OCaml pretty-printing facility provided in
26
  the module [Format] of the standard library.  In particular, pretty-printing
27
  commands assume that there is an opened pretty-printing box.  This permits
28
  more flexibility, since the choice of the enclosing pretty-printing box may
29
  depend on the context.
30
 
31
  @see <http://caml.inria.fr/pub/docs/manual-ocaml/libref/Format.html> Format
32
 *)
33

    
34

    
35
(** Signature for a type equipped with a pretty-printing function. *)
36
module type PRINTABLE_TYPE =
37
sig
38
  (** The type. *)
39
  type t
40

    
41
  (** A pretty-printer for this type.  This function prints values of
42
   type [t] in the current pretty-printing box. *) val print :
43
   Format.formatter -> t -> unit end
44

    
45

    
46
(** Transform a pretty-printer into a string converter. *)
47
val string_converter_from_printer :
48
  (Format.formatter -> 'a -> unit) -> 'a -> string
49

    
50
(** [hashtbl_printer_from_printer beg sep endf printer] returns a
51
  pretty-printer for hashtbls of type [('a,'b) Hashtbl.t], given a three formatters
52
  [beg], [sep] and [endf], and a pretty-printer [printer] for values of
53
  type [('a,'b)].  The resulting pretty-printer first prints [beg], then each
54
  element of its argument list with [sep] between each element, and
55
  finally prints [endf].  Each element in the hashtbl is printed in a new
56
  enclosing pretty-printing box.  In other words,
57
  [hashtbl_printer_from_printer sep printer fmt [{k1|->v1; ...; kn|->vn}]] is
58
  equivalent to [
59
  begin
60
    Format.fprintf fmt beg;
61
    Format.fprintf fmt "@[%a@]" printer (k1,v1) ;
62
    Format.fprintf fmt sep ;
63
    ... ;
64
    Format.fprintf fmt sep ;
65
    Format.fprintf fmt "@[%a@]" printer (kn,vn);
66
    Format.fprintf fmt endf;
67
    end
68
  ].  Note that the separator [sep] may contain pretty-printing commands.  For
69
  instance [";@ "] could be used as a separator argument to this function.
70
 *)
71
val hashtbl_printer_from_printer :
72
    (unit, Format.formatter, unit) format ->
73
  (unit, Format.formatter, unit) format ->
74
  (unit, Format.formatter, unit) format ->
75
  (Format.formatter -> ('a*'b) -> unit) ->
76
  Format.formatter -> ('a,'b) Hashtbl.t -> unit
77

    
78
(** [list_printer_from_printer beg sep endf printer] returns a
79
  pretty-printer for lists of type ['a list], given three formatters
80
  [beg], [sep] and [endf], and a pretty-printer [printer] for values of
81
  type ['a].  The resulting pretty-printer first prints [beg], then each
82
  element of its argument list with [sep] between each element, and
83
  finally prints [endf].  Each element in the list is printed in a new
84
  enclosing pretty-printing box.  In other words,
85
  [list_printer_from_printer beg sep endf printer fmt [a1; ...; aN]] is
86
  equivalent to [
87
  begin
88
    Format.fprintf fmt beg;
89
    Format.fprintf fmt "@[%a@]" printer a1 ;
90
    Format.fprintf fmt sep ;
91
    ... ;
92
    Format.fprintf fmt sep ;
93
    Format.fprintf fmt "@[%a@]" printer aN
94
    Format.fprintf fmt endf;
95
    end
96
  ].  Note that the separator [sep] may contain pretty-printing commands.  For
97
  instance [";@ "] could be used as a separator argument to this function.
98
 *)
99
val list_printer_from_printer :
100
  (unit, Format.formatter, unit) format ->
101
  (unit, Format.formatter, unit) format ->
102
  (unit, Format.formatter, unit) format ->
103
  (Format.formatter -> 'a -> unit) ->
104
  Format.formatter -> 'a list -> unit
105

    
106
(** [array_printer_from_printer sep printer] returns a pretty-printer
107
  for arrays of type ['a array], given three formatters [beg], [sep] and
108
  [endf], and a pretty-printer [printer] for values of type [int * 'a].
109
  The resulting pretty-printer first prints [beg], then prints each pair
110
  [(i, a.(i))] of its argument array [a] and prints [sep] between each
111
  pair and finally prints [endf]. Each pair in the array is printed in
112
  a new enclosing pretty-printing box. In other words,
113
  [array_printer_from_printer beg sep end printer fmt [|a1; ...; aN|]] is
114
  equivalent to [
115
  begin
116
    Format.fprintf fmt beg;
117
    Format.fprintf fmt "@[%a@]" printer (0, a1) ;
118
    Format.fprintf fmt sep ;
119
    ... ;
120
    Format.fprintf fmt sep ;
121
    Format.fprintf fmt "@[%a@]" printer (N-1, aN)
122
    Format.fprintf fmt endf;
123
    end
124
  ].  Note that the separator [sep] may contain pretty-printing commands.
125
  For instance [";@ "] could be used as a separator argument to this function.
126
*)
127
val
128
  array_printer_from_printer : (unit, Format.formatter, unit) format ->
129
  (unit, Format.formatter, unit) format -> (unit, Format.formatter,
130
  unit) format -> (Format.formatter -> (int * 'a) -> unit) ->
131
  Format.formatter -> 'a array -> unit