1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
|
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<link rel="Start" href="index.html">
<link rel="next" href="Errormsg.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of class methods" rel=Appendix href="index_methods.html">
<link title="Index of classes" rel=Appendix href="index_classes.html">
<link title="Index of class types" rel=Appendix href="index_class_types.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="Pretty" rel="Chapter" href="Pretty.html">
<link title="Errormsg" rel="Chapter" href="Errormsg.html">
<link title="Clist" rel="Chapter" href="Clist.html">
<link title="Stats" rel="Chapter" href="Stats.html">
<link title="Cil" rel="Chapter" href="Cil.html">
<link title="Formatcil" rel="Chapter" href="Formatcil.html">
<link title="Alpha" rel="Chapter" href="Alpha.html">
<link title="Cillower" rel="Chapter" href="Cillower.html">
<link title="Cfg" rel="Chapter" href="Cfg.html">
<link title="Dataflow" rel="Chapter" href="Dataflow.html">
<link title="Dominators" rel="Chapter" href="Dominators.html"><title>CIL API Documentation (version 1.3.5) : Pretty</title>
</head>
<body>
<div class="navbar"> <a href="index.html">Up</a>
<a href="Errormsg.html">Next</a>
</div>
<center><h1>Module <a href="type_Pretty.html">Pretty</a></h1></center>
<br>
<pre><span class="keyword">module</span> Pretty: <code class="code">sig</code> <a href="Pretty.html">..</a> <code class="code">end</code></pre>Utility functions for pretty-printing. The major features provided by
this module are <ul>
<li>An <code class="code">fprintf</code>-style interface with support for user-defined printers</li>
<li>The printout is fit to a width by selecting some of the optional newlines</li>
<li>Constructs for alignment and indentation</li>
<li>Print ellipsis starting at a certain nesting depth</li>
<li>Constructs for printing lists and arrays</li>
</ul>
Pretty-printing occurs in two stages:<ul>
<li>Construct a <a href="Pretty.html#TYPEdoc"><code class="code">Pretty.doc</code></a> object that encodes all of the elements to be
printed
along with alignment specifiers and optional and mandatory newlines</li>
<li>Format the <a href="Pretty.html#TYPEdoc"><code class="code">Pretty.doc</code></a> to a certain width and emit it as a string, to an
output stream or pass it to a user-defined function</li>
</ul>
The formatting algorithm is not optimal but it does a pretty good job while
still operating in linear time. The original version was based on a pretty
printer by Philip Wadler which turned out to not scale to large jobs.<br>
<hr width="100%">
<br>
API<br>
<pre><span class="keyword">type</span> <a name="TYPEdoc"></a><code class="type"></code>doc </pre>
<div class="info">
The type of unformated documents. Elements of this type can be
constructed in two ways. Either with a number of constructor shown below,
or using the <a href="Pretty.html#VALdprintf"><code class="code">Pretty.dprintf</code></a> function with a <code class="code">printf</code>-like interface.
The <a href="Pretty.html#VALdprintf"><code class="code">Pretty.dprintf</code></a> method is slightly slower so we do not use it for
large jobs such as the output routines for a compiler. But we use it for
small jobs such as logging and error messages.<br>
</div>
<br>
Constructors for the doc type.<br>
<pre><span class="keyword">val</span> <a name="VALnil"></a>nil : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Constructs an empty document<br>
</div>
<pre><span class="keyword">val</span> <a name="VAL(++)"></a>(++) : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Concatenates two documents. This is an infix operator that associates to
the left.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALconcat"></a>concat : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><pre><span class="keyword">val</span> <a name="VALtext"></a>text : <code class="type">string -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A document that prints the given string<br>
</div>
<pre><span class="keyword">val</span> <a name="VALnum"></a>num : <code class="type">int -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A document that prints an integer in decimal form<br>
</div>
<pre><span class="keyword">val</span> <a name="VALreal"></a>real : <code class="type">float -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A document that prints a real number<br>
</div>
<pre><span class="keyword">val</span> <a name="VALchr"></a>chr : <code class="type">char -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A document that prints a character. This is just like <a href="Pretty.html#VALtext"><code class="code">Pretty.text</code></a>
with a one-character string.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALline"></a>line : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A document that consists of a mandatory newline. This is just like <code class="code">(text
"\n")</code>. The new line will be indented to the current indentation level,
unless you use <a href="Pretty.html#VALleftflush"><code class="code">Pretty.leftflush</code></a> right after this.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALleftflush"></a>leftflush : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Use after a <a href="Pretty.html#VALline"><code class="code">Pretty.line</code></a> to prevent the indentation. Whatever follows
next will be flushed left. Indentation resumes on the next line.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALbreak"></a>break : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A document that consists of either a space or a line break. Also called
an optional line break. Such a break will be
taken only if necessary to fit the document in a given width. If the break
is not taken a space is printed instead.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALalign"></a>align : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Mark the current column as the current indentation level. Does not print
anything. All taken line breaks will align to this column. The previous
alignment level is saved on a stack.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALunalign"></a>unalign : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Reverts to the last saved indentation level.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmark"></a>mark : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Mark the beginning of a markup section. The width of a markup section is
considered 0 for the purpose of computing identation<br>
</div>
<pre><span class="keyword">val</span> <a name="VALunmark"></a>unmark : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
The end of a markup section<br>
</div>
<br>
Syntactic sugar<br>
<pre><span class="keyword">val</span> <a name="VALindent"></a>indent : <code class="type">int -> <a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Indents the document. Same as <code class="code">((text " ") ++ align ++ doc ++ unalign)</code>,
with the specified number of spaces.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALmarkup"></a>markup : <code class="type"><a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Prints a document as markup. The marked document cannot contain line
breaks or alignment constructs.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALseq"></a>seq : <code class="type">sep:<a href="Pretty.html#TYPEdoc">doc</a> -> doit:('a -> <a href="Pretty.html#TYPEdoc">doc</a>) -> elements:'a list -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Formats a sequence. <code class="code">sep</code> is a separator, <code class="code">doit</code> is a function that
converts an element to a document.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdocList"></a>docList : <code class="type">?sep:<a href="Pretty.html#TYPEdoc">doc</a> -> ('a -> <a href="Pretty.html#TYPEdoc">doc</a>) -> unit -> 'a list -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
An alternative function for printing a list. The <code class="code">unit</code> argument is there
to make this function more easily usable with the <a href="Pretty.html#VALdprintf"><code class="code">Pretty.dprintf</code></a>
interface. The first argument is a separator, by default a comma.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALd_list"></a>d_list : <code class="type">string -> (unit -> 'a -> <a href="Pretty.html#TYPEdoc">doc</a>) -> unit -> 'a list -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
sm: Yet another list printer. This one accepts the same kind of
printing function that <a href="Pretty.html#VALdprintf"><code class="code">Pretty.dprintf</code></a> does, and itself works
in the dprintf context. Also accepts
a string as the separator since that's by far the most common.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdocArray"></a>docArray : <code class="type">?sep:<a href="Pretty.html#TYPEdoc">doc</a> -><br> (int -> 'a -> <a href="Pretty.html#TYPEdoc">doc</a>) -> unit -> 'a array -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Formats an array. A separator and a function that prints an array
element. The default separator is a comma.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdocOpt"></a>docOpt : <code class="type">('a -> <a href="Pretty.html#TYPEdoc">doc</a>) -> unit -> 'a option -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Prints an <code class="code">'a option</code> with <code class="code">None</code> or <code class="code">Some</code><br>
</div>
<pre><span class="keyword">val</span> <a name="VALd_int32"></a>d_int32 : <code class="type">int32 -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
Print an int32<br>
</div>
<pre><span class="keyword">val</span> <a name="VALf_int32"></a>f_int32 : <code class="type">unit -> int32 -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><pre><span class="keyword">val</span> <a name="VALd_int64"></a>d_int64 : <code class="type">int64 -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><pre><span class="keyword">val</span> <a name="VALf_int64"></a>f_int64 : <code class="type">unit -> int64 -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><pre><span class="keyword">module</span> <a href="Pretty.MakeMapPrinter.html">MakeMapPrinter</a>: <div class="sig_block"><code class="code">functor (</code><code class="code">Map</code><code class="code"> : </code><code class="code">sig</code><div class="sig_block"><pre><span class="keyword">type</span> <a name="TYPEkey"></a><code class="type"></code>key </pre>
<pre><span class="keyword">type</span> <a name="TYPEt"></a><code class="type">'a</code> t </pre>
<pre><span class="keyword">val</span> <a name="VALfold"></a>fold : <code class="type">(key -> 'a -> 'b -> 'b) -><br> 'a t -> 'b -> 'b</code></pre></div><code class="code">end</code><code class="code">) -> </code><code class="code">sig</code> <a href="Pretty.MakeMapPrinter.html">..</a> <code class="code">end</code></div></pre><div class="info">
Format maps.
</div>
<pre><span class="keyword">module</span> <a href="Pretty.MakeSetPrinter.html">MakeSetPrinter</a>: <div class="sig_block"><code class="code">functor (</code><code class="code">Set</code><code class="code"> : </code><code class="code">sig</code><div class="sig_block"><pre><span class="keyword">type</span> <a name="TYPEelt"></a><code class="type"></code>elt </pre>
<pre><span class="keyword">type</span> <a name="TYPEt"></a><code class="type"></code>t </pre>
<pre><span class="keyword">val</span> <a name="VALfold"></a>fold : <code class="type">(elt -> 'a -> 'a) -><br> t -> 'a -> 'a</code></pre></div><code class="code">end</code><code class="code">) -> </code><code class="code">sig</code> <a href="Pretty.MakeSetPrinter.html">..</a> <code class="code">end</code></div></pre><div class="info">
Format sets.
</div>
<pre><span class="keyword">val</span> <a name="VALinsert"></a>insert : <code class="type">unit -> <a href="Pretty.html#TYPEdoc">doc</a> -> <a href="Pretty.html#TYPEdoc">doc</a></code></pre><div class="info">
A function that is useful with the <code class="code">printf</code>-like interface<br>
</div>
<pre><span class="keyword">val</span> <a name="VALdprintf"></a>dprintf : <code class="type">('a, unit, <a href="Pretty.html#TYPEdoc">doc</a>, <a href="Pretty.html#TYPEdoc">doc</a>) format4 -> 'a</code></pre><div class="info">
This function provides an alternative method for constructing
<code class="code">doc</code> objects. The first argument for this function is a format string
argument (of type <code class="code">('a, unit, doc) format</code>; if you insist on
understanding what that means see the module <code class="code">Printf</code>). The format string
is like that for the <code class="code">printf</code> function in C, except that it understands a
few more formatting controls, all starting with the @ character.
<p>
See the gprintf function if you want to pipe the result of dprintf into
some other functions.
<p>
The following special formatting characters are understood (these do not
correspond to arguments of the function):<ul>
<li> @[ Inserts an <a href="Pretty.html#VALalign"><code class="code">Pretty.align</code></a>. Every format string must have matching
<a href="Pretty.html#VALalign"><code class="code">Pretty.align</code></a> and <a href="Pretty.html#VALunalign"><code class="code">Pretty.unalign</code></a>. </li>
<li> @] Inserts an <a href="Pretty.html#VALunalign"><code class="code">Pretty.unalign</code></a>.</li>
<li> @! Inserts a <a href="Pretty.html#VALline"><code class="code">Pretty.line</code></a>. Just like "\n"</li>
<li> @? Inserts a <a href="Pretty.html#VALbreak"><code class="code">Pretty.break</code></a>.</li>
<li> @< Inserts a <a href="Pretty.html#VALmark"><code class="code">Pretty.mark</code></a>. </li>
<li> @> Inserts a <a href="Pretty.html#VALunmark"><code class="code">Pretty.unmark</code></a>.</li>
<li> @^ Inserts a <a href="Pretty.html#VALleftflush"><code class="code">Pretty.leftflush</code></a>
Should be used immediately after @! or "\n".</li>
<li> @@ : inserts a @ character</li>
</ul>
In addition to the usual <code class="code">printf</code> % formatting characters the following two
new characters are supported:<ul>
<li>%t Corresponds to an argument of type <code class="code">unit -> doc</code>. This argument is
invoked to produce a document</li>
<li>%a Corresponds to <b>two</b> arguments. The first of type <code class="code">unit -> 'a -> doc</code>
and the second of type <code class="code">'a</code>. (The extra <code class="code">unit</code> is do to the
peculiarities of the built-in support for format strings in Ocaml. It
turns out that it is not a major problem.) Here is an example of how
you use this:</li>
</ul>
<pre>dprintf "Name=%s, SSN=%7d, Children=@[%a@]\n"
pers.name pers.ssn (docList (chr ',' ++ break) text)
pers.children</pre>
<p>
The result of <code class="code">dprintf</code> is a <a href="Pretty.html#TYPEdoc"><code class="code">Pretty.doc</code></a>. You can format the document and
emit it using the functions <a href="Pretty.html#VALfprint"><code class="code">Pretty.fprint</code></a> and <a href="Pretty.html#VALsprint"><code class="code">Pretty.sprint</code></a>.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALgprintf"></a>gprintf : <code class="type">(<a href="Pretty.html#TYPEdoc">doc</a> -> 'a) -> ('b, unit, <a href="Pretty.html#TYPEdoc">doc</a>, 'a) format4 -> 'b</code></pre><div class="info">
Like <a href="Pretty.html#VALdprintf"><code class="code">Pretty.dprintf</code></a> but more general. It also takes a function that is
invoked on the constructed document but before any formatting is done. The
type of the format argument means that 'a is the type of the parameters of
this function, unit is the type of the first argument to %a and %t
formats, doc is the type of the intermediate result, and 'b is the type of
the result of gprintf.<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfprint"></a>fprint : <code class="type">Pervasives.out_channel -> width:int -> <a href="Pretty.html#TYPEdoc">doc</a> -> unit</code></pre><div class="info">
Format the document to the given width and emit it to the given channel<br>
</div>
<pre><span class="keyword">val</span> <a name="VALsprint"></a>sprint : <code class="type">width:int -> <a href="Pretty.html#TYPEdoc">doc</a> -> string</code></pre><div class="info">
Format the document to the given width and emit it as a string<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfprintf"></a>fprintf : <code class="type">Pervasives.out_channel -> ('a, unit, <a href="Pretty.html#TYPEdoc">doc</a>) Pervasives.format -> 'a</code></pre><div class="info">
Like <a href="Pretty.html#VALdprintf"><code class="code">Pretty.dprintf</code></a> followed by <a href="Pretty.html#VALfprint"><code class="code">Pretty.fprint</code></a><br>
</div>
<pre><span class="keyword">val</span> <a name="VALprintf"></a>printf : <code class="type">('a, unit, <a href="Pretty.html#TYPEdoc">doc</a>) Pervasives.format -> 'a</code></pre><div class="info">
Like <a href="Pretty.html#VALfprintf"><code class="code">Pretty.fprintf</code></a> applied to <code class="code">stdout</code><br>
</div>
<pre><span class="keyword">val</span> <a name="VALeprintf"></a>eprintf : <code class="type">('a, unit, <a href="Pretty.html#TYPEdoc">doc</a>) Pervasives.format -> 'a</code></pre><div class="info">
Like <a href="Pretty.html#VALfprintf"><code class="code">Pretty.fprintf</code></a> applied to <code class="code">stderr</code><br>
</div>
<pre><span class="keyword">val</span> <a name="VALwithPrintDepth"></a>withPrintDepth : <code class="type">int -> (unit -> unit) -> unit</code></pre><div class="info">
Invokes a thunk, with printDepth temporarily set to the specified value<br>
</div>
<br>
The following variables can be used to control the operation of the printer<br>
<pre><span class="keyword">val</span> <a name="VALprintDepth"></a>printDepth : <code class="type">int Pervasives.ref</code></pre><div class="info">
Specifies the nesting depth of the <code class="code">align</code>/<code class="code">unalign</code> pairs at which
everything is replaced with ellipsis<br>
</div>
<pre><span class="keyword">val</span> <a name="VALprintIndent"></a>printIndent : <code class="type">bool Pervasives.ref</code></pre><div class="info">
If false then does not indent<br>
</div>
<pre><span class="keyword">val</span> <a name="VALfastMode"></a>fastMode : <code class="type">bool Pervasives.ref</code></pre><div class="info">
If set to <code class="code">true</code> then optional breaks are taken only when the document
has exceeded the given width. This means that the printout will looked
more ragged but it will be faster<br>
</div>
<pre><span class="keyword">val</span> <a name="VALflushOften"></a>flushOften : <code class="type">bool Pervasives.ref</code></pre><div class="info">
If true the it flushes after every print<br>
</div>
<pre><span class="keyword">val</span> <a name="VALcountNewLines"></a>countNewLines : <code class="type">int Pervasives.ref</code></pre><div class="info">
Keep a running count of the taken newlines. You can read and write this
from the client code if you want<br>
</div>
<pre><span class="keyword">val</span> <a name="VALauto_printer"></a>auto_printer : <code class="type">string -> 'a</code></pre><div class="info">
A function that when used at top-level in a module will direct
the pa_prtype module generate automatically the printing functions for a
type<br>
</div>
</body></html>
|
