/
PolyMLStructure.html
770 lines (741 loc) · 45.4 KB
/
PolyMLStructure.html
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
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>The PolyML structure</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="docstyle.css" rel="stylesheet" type="text/css">
</head>
<body>
<ul class="nav">
<li><a href="Foreign.html">Previous</a></li>
<li><a href="Basis.html">Up</a></li>
<li><a href="Signal.html">Next</a></li>
</ul>
<H2><STRONG><font face="Arial, Helvetica, sans-serif">The PolyML structure</font></STRONG></H2>
<p>Generally, the basis library of Poly/ML follows the ML standard libraries.
With a few exceptions the extensions are all contained in the PolyML structure.
There are a number of sub-structures that are documented separately.</p>
<pre class="mainsig">structure PolyML:
sig
type <a href="#location">location</a> =
{file: string, startLine: int, endLine: int, startPosition: int, endPosition: int}
structure <a href="PolyMLCodetree.html">CodeTree</a> : sig ... end
structure <a href="PolyMLCompiler.html">Compiler</a> : sig ... end
val <a href="#compiler">compiler</a>: (unit -> char option) * Compiler.compilerParameters list -> unit -> unit
structure <a href="PolyMLDebug.html">Debug</a> : sig ... end
structure <a href="PolyMLDebuggerInterface.html">DebuggerInterface</a> : sig ... end
structure <a href="PolyMLException.html">Exception</a> : sig ... end
val <a href="#exceptionLocation">exceptionLocation</a>: exn -> location option
val <a href="#raiseWithLocation">raiseWithLocation</a> : exn * location -> 'a
val <a href="#exception_trace">exception_trace</a>: (unit -> 'a) -> 'a
structure <a href="#NameSpace">NameSpace</a> : sig ... end
val <a href="#globalNameSpace">globalNameSpace</a>: NameSpace.nameSpace
structure <a href="PolyMLProfiling.html">Profiling</a>: sig ... end
structure <a href="PolyMLSaveState.html">SaveState</a> : sig ... end
val <a href="#loadModule">loadModule</a>: string -> unit
structure <a href="PolyMLStatistics.html">Statistics</a> : sig ... end
structure IDEInterface :
sig
val parseTree : (string * (location * ptProperties list) list) ref
val runIDEProtocol : unit -> unit
end
structure <a href="#IntInf">IntInf</a>:
sig
val gcd : int * int -> int
val lcm : int * int -> int
end
val <a href="#export">export</a>: string * (unit -> unit) -> unit
val <a href="#exportPortable">exportPortable</a>: string * (unit -> unit) -> unit
val <a href="#shareCommonData">shareCommonData</a> : 'a -> unit
val <a href="#onEntry">onEntry</a> : (unit -> unit) -> unit
val <a href="#architecture">architecture</a> : unit -> string
val <a href="#rtsArgumentHelp">rtsArgumentHelp</a> : unit -> string
val <a href="#rtsVersion">rtsVersion</a> : unit -> int
val <a href="#make">make</a>: string -> unit
val <a href="#use">use</a> : string -> unit
val <a href="#getUseFileName">getUseFileName</a>: unit -> string option
val <a href="#suffixes">suffixes</a> = ref ["", ".ML", ".sml"]: string list ref
val <a href="#objSize">objSize</a>: 'a -> int
val <a href="#showSize">showSize</a> : 'a -> int
val <a href="#objProfile">objProfile</a> : 'a -> int
datatype <a href="#ptProperties">ptProperties</a> =
PTbreakPoint of bool ref<br> | PTcompletions of string list<br> | PTdeclaredAt of location<br> | PTdefId of int<br> | PTfirstChild of unit -> parseTree<br> | PTnextSibling of unit -> parseTree<br> | PTopenedAt of location<br> | PTparent of unit -> parseTree<br> | PTpreviousSibling of unit -> parseTree<br> | PTprint of int -> pretty<br> | PTreferences of bool * location list<br> | PTrefId of int<br> | PTstructureAt of location<br> | PTtype of NameSpace.Values.typeExpression
type <a href="#parseTree">parseTree</a> = location * ptProperties list
datatype <a href="#context">context</a> =
ContextLocation of location
| ContextProperty of string * string
datatype <a href="#pretty">pretty</a> =
PrettyBlock of int * bool * context list * pretty list
| PrettyBreak of int * int
| PrettyLineBreak
| PrettyString of string
| PrettyStringWithWidth of string * int
val <a href="#prettyPrint">prettyPrint</a> : (string -> unit) * int -> pretty -> unit
val <a href="#prettyMarkup">prettyMarkup</a> :
(context list -> unit) * (context list -> unit) ->
(string -> unit) * int -> pretty -> unit
val <a href="#prettyPrintWithIDEMarkup">prettyPrintWithIDEMarkup</a> : (string -> unit) * int -> pretty -> unit
val <a href="#addPrettyPrinter">addPrettyPrinter</a> : (int -> 'a -> 'b -> pretty) -> unit
val <a href="#prettyRepresentation">prettyRepresentation</a> : 'a * int -> pretty
val <a href="#print">print</a>: 'a -> 'a
val <a href="#makestring">makestring</a>: 'a -> string
val <a href="#print_depth">print_depth</a>: int -> unit
val error_depth: int -> unit
val line_length: int -> unit
val <a href="#rootFunction">rootFunction</a> : unit -> unit
val <a href="#shell">shell</a> : unit -> unit
val <a href="#sourceLocation">sourceLocation</a> : unit -> location
val <a href="#fullGC">fullGC</a> : unit -> unit
val <a href="#pointerEq">pointerEq</a> : 'a * 'a -> bool
val <a href="#stackTrace">stackTrace</a> : unit -> unit
val <a href="#profiling">profiling</a> : int -> unit
val <a href="#timing">timing</a> : bool -> unit
end
</pre>
<p>The <span class="identifier">PolyML</span> structure contains a large collection
of functions, structures and types that are specific to Poly/ML.</p>
<div class="entryblock">
<pre class="entrycode"><a name="CodeTree"></a>structure CodeTree : sig ... end </pre>
<div class="entrytext">
<p><a href="PolyMLCodetree.html">Functions related to the intermediate code
structure.</a></p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="Compiler"></a>structure Compiler : sig ... end
</pre>
<div class="entrytext">
<p><a href="PolyMLCompiler.html">Functions and types specific to the Poly/ML
compiler.</a></p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="compiler" id="compiler"></a>val compiler: (unit -> char option) * Compiler.compilerParameters list -> unit -> unit</pre>
<div class="entrytext">
<p>The <span class="identifier">PolyML.compiler</span> function provides direct
access to the compiler for Poly/ML. It is used by all the functions, such
as <a href="#use"><span class="identifier">use</span></a>, <a href="#shell"><span class="identifier">shell</span></a>
and <a href="#make"><span class="identifier">make</span></a> that compile
Standard ML source code into executable code.</p>
<p><span class="identifier">compiler(instream, parms)</span> takes an input
stream, <span class="identifier">instream</span>, and a set of optional
parameters, <span class="identifier">parms</span>, of type <span class="identifier"><a href="PolyMLCompiler.html#compilerParameters">Compiler.compilerParameters</a></span>.
The input stream is called whenever the compiler wants to read the next
character from the input. If it returns <span class="identifier">NONE</span>
the compiler assumes that it has reached an end-of-stream and does not read
further. Otherwise the compiler stops when it has parsed a valid <em>topdec</em>,
generally a declaration or expression with a final semicolon. The parameters,
<span class="identifier">parms</span>, provide a set of options to the compiler.
There are default values for these options so it is possible to provide
an empty list. The parameters, their meanings and the default values are
listed under <span class="identifier"><a href="PolyMLCompiler.html#compilerParameters">Compiler.compilerParameters</a></span>.</p>
<p>If an error is detected <span class="identifier">compiler</span> raises
the <span class="identifier">Fail</span> exception, otherwise the result
of the compilation is a function of type <span class="identifier">unit->unit</span>.
This function represents the compiled code and calling this function executes
the code. At that point any side-effects will be performed and bindings
made by the code will be added to the name-space.</p>
<p>The <span class="identifier">compiler</span> function itself is thread-safe,
that is multiple instances of it can be executed in parallel without interference,
provided suitable parameters are provided. In particular it may be necessary
to ensure that the name-spaces passed as <span class="identifier"><a href="PolyMLCompiler.html#CPNameSpace">CPNameSpace</a></span>
parameters do not interfere.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="Debug"></a>structure Debug : sig ... end</pre>
<div class="entrytext">
<p>Functions to aid interactive debugging. There is a <a href="PolyMLDebug.html">reference
here</a> and a <a href="../Tutorials/Debugging.html">tutorial here</a>.
</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="DebuggerInterface"></a>structure DebuggerInterface : sig ... end
</pre>
<div class="entrytext">
<p>The <a href="PolyMLDebuggerInterface.html" class="identifier">DebuggerInterface</a>
structure contains functions to allow application code to access information
about a program that has been compiled for debugging. It is intended for
applications that replace the default Poly/ML top-level.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="Exception"></a>structure Exception : sig ... end
<a name="exceptionLocation"></a>val exceptionLocation: exn -> location option
<a name="raiseWithLocation"></a>val raiseWithLocation : exn * location -> 'a
<a name="exception_trace"></a>val exception_trace: (unit -> 'a) -> 'a</pre>
<div class="entrytext">
<p>The <a href="PolyMLException.html" class="identifier">Exception</a> structure
contains functions to assist with the location and tracing of exceptions.
Three functions, <span class="identifier">exception_trace</span>, <span class="identifier">exceptionLocation</span>
and <span class="identifier">raiseWithLocation</span> were originally contained
in the <span class="identifier">PolyML</span> structure itself so for backwards
compatibility they are available both in <span class="identifier">PolyML</span>
and <span class="identifier">PolyML.Exception</span>. </p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="NameSpace"></a>structure NameSpace : sig ... end
<a name="globalNameSpace"></a>val globalNameSpace: NameSpace.nameSpace
</pre>
<div class="entrytext">
<p>The <a href="PolyMLNameSpace.html" class="identifier">NameSpace</a> structure
contains functions and types for printing the values produced by the compiler.
<span class="identifier">globalNameSpace</span> is the default name space.
It contains the top-level bindings made by compiling source code with <a href="#use"><span class="identifier">use</span></a>
or <a href="#make"><span class="identifier">make</span></a> or entering
code at the top-level. Values in <span class="identifier">globalNameSpace</span>
can be extracted and displayed in the same way as any other values of the
<span class="identifier"><a href="PolyMLNameSpace.html#nameSpace">nameSpace</a></span>
type. Values can be deleted using <span class="identifier"><a href="PolyMLCompiler.html#forgetValue">Compiler.forgetValue</a></span>
etc.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="Profiling"></a>structure Profiling : sig ... end
</pre>
<div class="entrytext">
<p>The <a href="PolyMLProfiling.html" class="identifier">Profiling</a> structure
contains functions to profile Poly/ML programs. As well as measuring the
time spent in a function it can also measure the amount of memory allocated
to identify functions that lead to excessive garbage-collection.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="SaveState"></a>structure SaveState : sig ... end
<a name="loadModule"></a>val loadModule: string -> unit
</pre>
<div class="entrytext">
<p>The <a href="PolyMLSaveState.html" class="identifier">SaveState</a> structure
contains functions to save the current state to a file and restore the previous
state. <span class="identifier">loadModule</span> is a synonym for <span class="identifier">SaveState.loadModule</span>.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="Statistics"></a>structure Statistics : sig ... end
</pre>
<div class="entrytext">
<p>The <a href="PolyMLStatistics.html" class="identifier">Statistics</a> structure
contains functions to extract information about the Poly/ML run-time system.
It can also be used to query statistics about other Poly/ML processes run
by the same user.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="fullGC" id="fullGC"></a>val fullGC: unit -> unit</pre>
<div class="entrytext">
<p>The <span class="identifier">fullGC</span> function forces the run-time
system to execute a full garbage collection. Normally this will not be required.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="pointerEq" id="pointerEq"></a>val pointerEq: 'a * 'a -> bool</pre>
<div class="entrytext">
<p>The <span class="identifier">pointerEq</span> function compares two values
for identity. The normal ML rules for equality state that two values are
equal if they have the same contents. The exception is <em>mutable</em>
values, such as refs and arrays, which are considered equal only if they
are the same ref or array. Equality is only possible for equality types,
which excludes functions and values of type real.</p>
<p><span class="identifier">PolyML.pointerEq</span> can be applied to values
of any type and returns true if the values are identifical. It is intended
for use in user functions that wish to test for equality in a general sense
and where a potentially expensive operation can be cut short if it is known
that the arguments are actually the same. It should be used with care. Poly/ML
only guarantees the ML equality property and the compiler and run-time system
may merge or split immutable values. For example, <a href="#shareCommonData" class="identifier">shareCommonData</a>,
combines immutable values with the same contents.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="shareCommonData" id="shareCommonData"></a>val shareCommonData : 'a -> unit</pre>
<div class="entrytext">
<p>The <span class="identifier">shareCommonData</span> function is intended
to reduce the storage requirements by merging <em>immutable</em> data, such
as lists and strings, that have the same contents. Since the ML equality
function tests for equality of contents rather than pointer equality, running
<span class="identifier">shareCommonData</span> does not affect the behaviour
of an ML program unless it relies on non-standard functions such as <a href="#pointerEq" class="identifier">PolyML.pointerEq</a>.
The <span class="identifier">shareCommonData</span> function requires extra
space on the heap and sorts the data before merging so can be expensive
to run when the heap is large. The argument is the root of the data that
should be shared. To share everything pass <span class="identifier"><a href="#rootFunction">PolyML.rootFunction</a></span>
as the argument. It is frequently used before the heap is saved with <a href="#export" class="identifier">PolyML.export</a>
or <span class="identifier"><a href="#SaveState">PolyML.SaveState</a>.saveState</span>.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="export" id="export"></a>val export: string * (unit -> unit) -> unit
<a name="exportPortable"></a>val exportPortable: string * (unit -> unit) -> unit
</pre>
<div class="entrytext">
<p>The <span class="identifier">export</span> and <span class="identifier">exportPortable</span>
functions are used to create object modules or object files. They both take
arguments which are the name of the file to be written and a function to
use as the root. All data reachable from the root are written to the output
file. <span class="identifier">export</span> writes an object file whose
format depends on the particular operating system. On Linux and other similar
systems this is an ELF object file, on Windows a PECOFF file and on Mac
OS a Mach-O file. It can then be linked with the Poly/ML libraries to produce
an executable file. <span class="identifier">exportPortable</span> writes
an operating-system-independent text file that can be read by the <span class="identifier">polyImport</span>
program. It is intended primarily to allow the Poly/ML system itself to
be distributed by avoiding the necessity of having separate object files
for each operating system. Note that the file contains machine code so while
it is operating-system independent it is not independent of the architecture.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="onEntry" id="onEntry"></a>val onEntry: (unit -> unit) -> unit</pre>
<div class="entrytext">
<p>The <span class="identifier">onEntry</span> function adds a function to
a list of functions that are executed when a Poly/ML program begins. It
is primarily intended for libraries that need to be initialised.</p>
</div>
</div>
<pre class="entrycode"><a name="make" id="make"></a>val make: string -> unit</pre>
<div class="entrytext">
<p>The <a href="PolyMLMake.html" class="identifier">make</a> function is used
to compile and build a set of modules from source. There is a separate <a href="PolyMLMake.html">description
and tutorial</a>.</p>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="use" id="use"></a>val use: string -> unit</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.use</span> is the same function as the
top-level <span class="identifier">use</span> function. It takes a file
name as its argument and compiles and executes the Standard ML code in the
file. The file-name extension may be omitted if it is one of those listed
in <span class="identifier"><a href="#suffixes">PolyML.suffixes</a></span>.
The inclusion of <span class="identifier">PolyML.use</span> is really a
relic from an early version of Standard ML which did not include a <span class="identifier">use</span>
function.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="getUseFileName" id="getUseFileName"></a>val getUseFileName: unit -> string option</pre>
<div class="entrytext">
<p>This function can be called within a piece of ML code that is being compiled
with <span class="identifier">use</span> to return the file name and specifically
the path that was used to refer to the file. It is useful if the ML code
itself calls <span class="identifier">use</span> because it can then adjust
the path.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="suffixes" id="suffixes"></a>val suffixes = ref ["", ".ML", ".sml"]: string list ref</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.suffixes</span> holds a list of file-name
extensions of ML source files. This is used by <span class="identifier"><a href="#use">PolyML.use</a></span>
and <span class="identifier"><a href="#make">PolyML.make</a></span>. If
they are given a file-name as an argument and the file does not exist they
attempt to open a file with a name constructed from the original argument
by adding each of the extensions in turn.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="ptProperties" id="ptProperties"></a>datatype ptProperties =
PTbreakPoint of bool ref<br> | PTcompletions of string list<br> | PTdeclaredAt of location<br> | PTdefId of int<br> | PTfirstChild of unit -> parseTree<br> | PTnextSibling of unit -> parseTree<br> | PTopenedAt of location<br> | PTparent of unit -> parseTree<br> | PTpreviousSibling of unit -> parseTree<br> | PTprint of int -> pretty<br> | PTreferences of bool * location list<br> | PTrefId of int<br> | PTstructureAt of location<br> | PTtype of NameSpace.Values.typeExpression
withtype parseTree = <a href="#location">location</a> * ptProperties list
</pre>
<div class="entrytext">
<p>The <span class="identifier">ptProperties</span> datatype is associated
with a parse-tree that has been exported from the compiler. The parse-tree
is an abstract tree where each node has a <a href="#location"><span class="identifier">location</span></a>
and a set of properties. The properties associated with a particular node
vary according to the underlying parse-tree and circumstances.</p>
<p><span class="identifier"><a name="PTfirstChild"></a>PTfirstChild</span>,
<span class="identifier"><a name="PTnextSibling"></a>PTnextSibling</span>,
<span class="identifier"><a name="PTpreviousSibling"></a>PTpreviousSibling</span> and <span class="identifier"><a name="PTparent"></a>PTparent</span>
are used to move between nodes. They are only present if the appropriate
node exists. <span class="identifier">PPTfirstChild</span> is present if
the node has children and returns the first (leftmost) node. <span class="identifier">PTnextSibling</span>
and <span class="identifier">PTpreviousSibling</span> return the next (right)
and previous (left) nodes at the same level. <span class="identifier">PTparent</span>
returns the parent node.</p>
<p><span class="identifier"><a name="PTtype"></a>PTtype</span> returns a value that represents
the type of the node. It is present on nodes that represent values and can
have a type. </p>
<p><span class="identifier"><a name="PTdeclaredAt"></a>PTdeclaredAt</span>, <span class="identifier"><a name="PTopenedAt"></a>PTopenedAt</span>,
<span class="identifier"><a name="PTstructureAt"></a>PTstructureAt</span> and <span class="identifier"><a name="PTreferences"></a>PTreferences</span>
may be present on nodes that represent identifiers. They provide location
information. <span class="identifier">PTdeclaredAt</span> provides the location
where the identifier was declared. <span class="identifier">PTopenedAt</span>
and <span class="identifier">PTstructureAt</span> are only present if the
identifier came from a structure that had been opened and give the location
where the structure had been opened and where the structure itself was declared.</p>
<p><span class="identifier"><a name="PTprint"></a>PTprint</span> produces a pretty-print structure
of the node. It is present on most nodes. The argument is the depth of the
data structure to produce before eliding the detail.</p>
<p><span class="identifier"><a name="PTbreakPoint"></a>PTbreakPoint</span> is only present if debugging
has been enabled. It returns the debugger identifier for the node.</p>
<p><span class="identifier"><a name="PTcompletions"></a>PTcompletions</span>
returns possible completions of an invalid identifier.</p>
<p><span class="identifier">PTrefId</span> and <span class="identifier">PTdefId</span>
properties are used with identifiers. <span class="identifier">PTdefId</span>
is a defining occurence of an identifier while <span class="identifier">PTrefId</span>
is a referencing occurrence.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="context"></a>datatype context =
ContextLocation of location
| ContextProperty of string * string
</pre>
<div class="entrytext">
<p>The context type is primarily used by the IDE when providing error messages.
For most purposes the <span class="identifier">context</span> argument to
<span class="identifier">PrettyBlock</span> can be the empty list. <span class="identifier">ContextLocation</span>
provides the location associated with the item being printed, typically
the location where it was declared. <span class="identifier">ContextProperty</span>
can be used by a user-supplied pretty printer to provide extra information
which may be useful if the result of pretty printing is to be processed
by a user function. It is not produced by Poly/ML pretty printers and the
default printers ignore this item.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="pretty"></a>datatype pretty =
PrettyBlock of int * bool * context list * pretty list
| PrettyBreak of int * int
| PrettyLineBreak
| PrettyString of string
| PrettyStringWithWidth of string * int
</pre>
<div class="entrytext">
<p>The <span class="identifier">pretty</span> datatype is used in connection
with formatting data for display. Rather than create text directly most
display functions create values of this type. It is used with a pretty-printer
based around the model described by D.C. Oppen in ACM ToPLAS Vol. 2 No.
4 Oct 1980.</p>
<p><span class="identifier"><a name="PrettyString"></a>PrettyString s</span>
contains a string to be printed.</p>
<p><span class="identifier"><a name="PrettyStringWithWidth"></a>PrettyStringWithWidth
(s, n)</span> is similar to <span class="identifier">PrettyString</span>
except that it contains an explicit width. It is used when the width of
the displayed string is not the same as the number of characters. This may
happen if the string contains UTF-8 encoded characters.</p>
<p><span class="identifier"><a name="PrettyBlock"></a>PrettyBlock(indent,
consistent, context, items)</span> defines a block of <span class="identifier">items</span>
which may be strings, breaks or blocks. The items will be retained on a
single line if possible. The <span class="identifier">indent</span> parameter
is an indentation that will be added to the current indentation if the block
has to be broken. Note that this does not apply to the first item in the
block which will always be printed with the current indentation. The <span class="identifier">consistent</span>
parameter indicates whether the block is to be broken consistently (true)
or not (false). If it is true then if the block will not all fit on a line
and must be broken then it will be broken at all the breaks in the block
whether this is necessary or not. If it is false it will only be broken
where necessary. Neither of these parameters are used if the block will
fit on a line.</p>
<p><span class="identifier"><a name="PrettyBreak"></a>PrettyBreak(blanks,
breakOffset)</span> indicates a break between items. If the line is not
broken at this point then <span class="identifier">blanks</span> is the
number of space characters that will be inserted. If the line is broken
at that point then instead the following item is indented by an extra <span class="identifier">breakOffset</span>
spaces.</p>
<p><span class="identifier"><a name="PrettyLineBreak"></a>PrettyLineBreak</span>
inserts an explicit line-break.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="prettyPrint"></a>val prettyPrint : (string -> unit) * int -> pretty -> unit</pre>
<div class="entrytext">
<p><span class="identifier">prettyPrint</span> provides a basic formatting
of a <span class="identifier">pretty</span> structure.<span class="identifier">
prettyPrint (output, width) p</span> formats the <span class="identifier">pretty</span>
structure <span class="identifier">p</span> and calls the <span class="identifier">output</span>
function to display it. The <span class="identifier">width</span> is the
number of characters that can be displayed on a single line. Spaces and
line-breaks are produced by calling output with strings containing spaces
and the newline character<span class="identifier"> "\n"</span>.
Context information in <span class="identifier"><a href="#PrettyBlock">PrettyBlock</a></span>
nodes is ignored.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="prettyMarkup"></a>val prettyMarkup :
(context list -> unit) * (context list -> unit) ->
(string -> unit) * int -> pretty -> unit
</pre>
<div class="entrytext"><span class="identifier">prettyMarkup</span> provides
the same formatting as <a href="#prettyPrint"><span class="identifier">prettyPrint</span></a>
except that it includes processing of context information. <span class="identifier">prettyMarkup(startC,
endC) (output, width) p</span> formats the pretty structure <span class="identifier">p</span>
using <span class="identifier">output</span> and <span class="identifier">width</span>
with the addition that whenever a <span class="identifier">PrettyBlock</span>
is encountered with non-empty context list <span class="identifier">startC</span>
is called with the list before the block is output and <span class="identifier">endC</span>
is called with the same list when the block is complete. </div>
<div class="entrytext"></div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="prettyPrintWithIDEMarkup"></a>val prettyPrintWithIDEMarkup : (string -> unit) * int -> pretty -> unit
</pre>
<div class="entrytext">
<p></p>
</div>
<div class="entrytext">
<p><span class="identifier">prettyPrintWithIDEMarkup</span> is the same as
<span class="identifier">prettyPrint</span> except that it adds <a href="../IDEProtocol.html">IDE
mark-up</a> for location properties.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="addPrettyPrinter"></a>val addPrettyPrinter : (int -> 'a -> 'b -> pretty) -> unit
</pre>
<div class="entrytext">
<p><span class="identifier">addPrettyPrinter</span> is used to associate a
printing function with a type so that it can be displayed in a more user-friendly
form than the default. It appears to have a polymorphic type but is specially
handled by the compiler. Pretty-printers can be installed for datatypes
or types produced by opaque signature matching or returned from functors.
It is not possible to install a pretty-printer for a <em>type function</em>
(i.e. a type defined by <span class="identifier">type t = ...</span>) unless
the type function is simply giving an alternative name to a datatype.</p>
<p><span class="identifier">addPrettyPrinter pp</span> installs a pretty printer
<span class="identifier">pp</span> where <span class="identifier">pp</span>
has arguments <span class="identifier">depth printArgTypes value</span>.
The first argument, <span class="identifier">depth</span>, is the print
depth. This is a value that indicates how much of the data structure should
be displayed. If this value is zero or negative the pretty printer should
always print a simple string such as <span class="identifier">PrettyString
"..."</span>. The intention is that the user can control how much
output to produce when printing a large data structure. Larger values produce
more of the structure. For values produced by the top-level this will generally
be controlled by <a href="#print_depth"><span class="identifier">PolyML.print_depth</span></a>.
The third argument, <span class="identifier">value</span>, is the actual
value of the type that is to be printed. When installing a pretty printer
there must be sufficient type constraint so that the compiler is able to
determine the type unambiguiously. </p>
<p>The second argument, <span class="identifier">printArgTypes</span>, is
only used for <em>polytypes</em> i.e. datatypes with type parameters defined
as <span class="identifier">'a t</span> or <span class="identifier">('a,
'b', 'c ...) t</span>. It is not used for <em>monotypes</em>. If the type
takes a single argument then <span class="identifier">printArgTypes</span>
has type <span class="identifier">'a * int -> pretty</span> and is the
function that will generate the pretty data structure for the argument type.
The <span class="identifier">int</span> argument is the adjusted print depth
and should normally be one less than the value of <span class="identifier">depth</span>.
If the type takes multiple arguments then <span class="identifier">printArgTypes</span>
is a tuple with each field being a function of type <span class="identifier">'a
* int -> pretty</span> that is used for the corresponding argument of
the datatype.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="prettyRepresentation"></a>val prettyRepresentation : 'a * int -> pretty</pre>
<div class="entrytext">
<p><span class="identifier">prettyRepresentation</span> returns the <code>pretty</code>
structure that can be used to print a value of the given type up to the
specified depth. It is similar to <code>PolyML.print</code> in being infinitely
overloaded. It can be useful when writing a pretty printer for a datatype
that includes types that already have pretty printers installed or where
they will be installed later since it uses any pretty printers for the types
when it is actually called.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="print" id="print"></a>val print: 'a -> 'a</pre>
<div class="entrytext">
<p>The <span class="identifier">PolyML.print</span> function is a special
<em>infinitely overloaded</em> function that prints its argument and returns
the original result. It is treated specially by the compiler which uses
type information to format the output.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="makestring" id="makestring"></a>val makestring: 'a -> string</pre>
<div class="entrytext">
<p>The <span class="identifier">PolyML.makestring</span> function is similar
to <a href="#print"><span class="identifier">PolyML.print</span></a> in
being infinitely overloaded. It returns a string representation of its argument.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="rootFunction" id="rootFunction"></a>val rootFunction : unit -> unit
</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.rootFunction</span> is the initial function
for the default Poly/ML system. It processes the command line arguments
and then calls <span class="identifier"><a href="#shell">PolyML.shell</a></span>
to start the main top-level, read-eval-print loop. It is the root of everything
in the Poly/ML system so it may be used as an argument to <a href="#shareCommonData"><span class="identifier">PolyML.shareCommonData</span></a>
to minimise the size of the heap before it is saved.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="shell" id="shell"></a>val shell : unit -> unit</pre>
<div class="entrytext">
<p>The shell function runs the normal Poly/ML top-level read-eval-print loop
(REPL). This function is provided for the situation where a user might wish
to export an alternative top-level function but in some cases switch to
the default. It returns only when it detects end-of-file on <span class="identifier">TextIO.stdIn</span>.
The top-level prompts the user for input using the value held in <span class="identifier"><a href="PolyMLCompiler.html#prompt1">Compiler.prompt1</a></span>,
<span class="identifier">"> "</span> by default, for the first
line of a <em>topdec</em>. Subsequent lines are prompted for using the value
in <span class="identifier"><a href="PolyMLCompiler.html#prompt2">Compiler.prompt2</a></span>,
default <span class="identifier">"# "</span>.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="architecture" id="architecture"></a>val architecture : unit -> string</pre>
<div class="entrytext">
<p>The <span class="identifier">architecture</span> function returns a string
that identifies the computer architecture for which the current version
of Poly/ML has been built and the code that the compiler generates. Currently,
it returns one of the following values: <span class="identifier">"I386"</span>,
<span class="identifier"> "X86_64"</span> or <span class="identifier">"Interpreted"</span>.
The last is used when Poly/ML has been built for the portable byte-code
version. </p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="rtsArgumentHelp" id="rtsArgumentHelp"></a>val rtsArgumentHelp : unit -> string</pre>
<div class="entrytext">
<p>PolyML.rtsArgumentHelp returns a string that describes the command-line
arguments that are used by the run-time system. The main purpose of this
function is to enable Poly/ML programs that accept a command-line "help"
argument to provide information to the user about arguments that will be
interpreted by the run-time system in addition to information about their
own arguments.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="rtsVersion" id="rtsVersion"></a>val rtsVersion : unit -> int</pre>
<div class="entrytext">
<p>The <span class="identifier">rtsVersion</span> function returns a number
that identifies the version of the run-time system. For version 5.5.3 it
returns 553.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="objSize" id="objSize"></a>val objSize: 'a -> int
</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.objSize</span> returns the number of words
of heap space used in its argument. It is primarily intended for debugging
when the heap requirements of a program are larger than expected. It returns
the total size of everything reachable from its argument. It takes account
of sharing so if parts of the data structure are shared they will be counted
only once.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="showSize" id="showSize"></a>val showSize : 'a -> int</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.showSize</span> returns the same result
as <span class="identifier">objSize</span> but as a side-effect it prints
a low-level representation of the data to the standard output. It should
be used with care as the output can be very large.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="objProfile" id="objProfile"></a>val objProfile : 'a -> int</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.</span>objProfile returns the same result
as <span class="identifier">objSize</span> but as a side-effect it prints
a profile of the sizes of cells, the number of cells of each size. Separate
profiles are produced for <em>mutable</em> cells i.e. refs and arrays, and
<em>immutable</em> cells such as lists and tuples.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="stackTrace" id="stackTrace"></a>val stackTrace : unit -> unit</pre>
<div class="entrytext">
<p>The <span class="identifier">stackTrace</span> function prints a trace
of the current stack; that is the name of the calling function and the function
that called it back to the start of the thread.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="profiling" id="profiling"></a>val profiling : int -> unit</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.profiling</span> enables profiling for
executed code. It takes an integer argument that sets the kind of profiling.
Zero disables profiling; non-zero values enable different kinds of profiling.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="timing" id="timing"></a>val timing : bool -> unit</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.timing</span> enables or disables the timing
of each expression typed at the top-level. For each expression figures are
shown for various passes of the compiler and the execution time of the expression.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="sourceLocation" id="sourceLocation"></a>val sourceLocation : unit -> location</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.sourceLocation </span>is a function that
is treated specially by the compiler. It returns the <a href="#location"><span class="identifier">location</span></a>
in the source file where its call appears. Exactly what information is returned
depends on what options have been provided to the compiler.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="location" id="location"></a>type location = {file: string, startLine: int, endLine: int, startPosition: int, endPosition: int}
</pre>
<div class="entrytext">
<p>The <span class="identifier">location</span> type is associated with the
compiler. It represents a position in some program source, usually a source
file. The information that is included depends on the particular function
that has returned the <span class="identifier">location</span> and how the
compiler was called. Generally, <span class="identifier">file</span> will
contain the source file name, <span class="identifier">startLine</span>
and <span class="identifier">endLine</span> will contain the line numbers
where the item started and ended and <span class="identifier">startPosition</span>
and <span class="identifier">endPosition</span> the byte position in the
file. The file name may be the empty string and any of the other arguments
may be zero if the information is not available.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="IntInf" id="IntInf"></a>structure IntInf: sig val gcd : int * int -> int val lcm : int * int -> int end</pre>
<div class="entrytext">
<p>The <span class="identifier">IntInf</span> structure contains two functions
that have been added to the arbitrary-precision arithmetic library. They
compute the greatest common divisor and the lowest common multiple. If Poly/ML
has been built to use the GMP library these functions will make use of that
library.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="print_depth" id="print_depth"></a>val print_depth: int -> unit</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.print_depth</span> sets the depth for printing
the results of each top-level expression. Passing zero or a negative value
as the argument disables all printing of top-level results. When a large
data structure is to be printed the print depth controls how much of the
structure is displayed. <span class="identifier">PolyML.print_depth</span>
sets the value of <span class="identifier"><a href="PolyMLCompiler.html#printDepth">PolyML.Compiler.printDepth</a></span>.</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="error_depth" id="error_depth"></a>val error_depth: int -> unit
</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.error_depth</span> controls the amount
of output to produce when printing information in an error message. It behaves
in the same way as <a href="#print_depth"><span class="identifier">PolyML.print_depth</span></a>.
<span class="identifier"><a href="PolyMLCompiler.html#errorDepth">PolyML.error_depth</a></span>
sets the value of <span class="identifier">PolyML.Compiler.errorDepth</span>.
</p>
</div>
</div>
<div class="entryblock">
<pre class="entrycode"><a name="line_length" id="line_length"></a>val line_length: int -> unit</pre>
<div class="entrytext">
<p><span class="identifier">PolyML.line_length</span> sets the length of a
line which is used when produced pretty-printed output. <span class="identifier">PolyML.line_length</span>
sets the value of <span class="identifier"><a href="PolyMLCompiler.html#lineLength">PolyML.Compiler.lineLength</a></span>.</p>
</div>
</div>
<ul class="nav">
<li><a href="Foreign.html">Previous</a></li>
<li><a href="Basis.html">Up</a></li>
<li><a href="Signal.html">Next</a></li>
</ul>
</body>
</html>