![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to help CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / cmd / sml / doc|
Return to help CVS log | Up to [Research Unix] / researchv10no / cmd / sml / doc |
1.1 root 1: Help: A few hints for beginning users of SML of NJ
2:
3: 1. running Standard ML
4:
5: Type "sml". This puts you into the interactive system. The top level
6: prompt is "- ", and the secondary prompt (printed when input is
7: incomplete) is "= ". If you get the secondary prompt when you don't
8: expect it, typing ";<return>" will often complete your input, or type
9: your interrupt character (e.g. ^C) to cancel your input and return you
10: to top level.
11:
12: If "sml" doesn't work, ask where sml has been installed on your machine
13: and use the appropriate path name or redefine your PATH environment variable.
14:
15: 2. interactive input
16:
17: Input to the top level interpreter (i.e. declarations and expressions)
18: must be terminated by a semicolon (and carriage return) before the
19: system will evaluate it. The system then prints out a response
20: indicating the effect of the evaluation. Expressions are treated as
21: implicit declarations of a standard variable "it". For example,
22:
23: - 3; <return> <- user input after prompt
24: val it = 3 : int <- system response
25:
26: This means that the value of the last top level expression evaluated
27: can be referred to using the variable "it".
28:
29: 2. changing the prompts
30:
31: The primary and secondary prompt strings are the contents of the
32: references
33:
34: System.Control.primaryPrompt
35: System.Control.secondaryPrompt
36:
37: These can be redefined by assignment, e.g.:
38:
39: - System.Control.secondaryPrompt := "(**)";
40:
41: 3. interrupting parsing or computation
42:
43: Typing your interrupt character should interrupt the compiler and
44: return you to top level, unless some function is catching the
45: Interrupt exception (a dangerous thing to do).
46:
47: 4. exiting the interactive system
48:
49: Typing ^D (EOF) at top level will cause an exit to the shell (or the
50: parent process from which sml was run).
51:
52: 5. loading ML source text from a file
53:
54: The operator use: string->unit interprets its argument as a Unix file
55: name relative to sml's current directory and loads the text from that
56: file as though it had been typed in. "use" should normally be
57: executed at top level, but the loaded files can also contain calls of
58: use to recursively load other files. It is a bad idea to call use
59: within an expression or declaration, because the effects are not
60: well-defined.
61:
62: 6. saving an image of the system
63:
64: Use the function exportML: string->bool to dump an image of the
65: current sml system including the environment that you have built. The
66: argument is the path name of the image file that is created. The
67: result false is returned in the original system, while in the saved
68: image the value returned is true. The call of exportML can be
69: embedded in an expression which will continue evaluation (e.g. to
70: print a message) in both the original system and in the image when it
71: is run, and its effect can depend on the result of the exportML call.
72: For example:
73:
74: if exportML("saved")
75: then print "this is the saved image\n"
76: else print "this is the original process\n"
77:
78: The saved image file is an executable binary, and can be run by typing
79: the file name as a command to the shell. (Access to command-line
80: arguments and Unix environment variables when running the saved image
81: may be accomplished by System.argv and System.environ.)
82:
83: 7. executing System commands and changing directories
84:
85: The function system : string->unit spawns a process to execute its argument
86: string as a shell command. Thus to find out what the current directory is
87: within sml you can evaluate the expression
88:
89: system "pwd";
90:
91: which will cause the current directory to be printed out (there is no
92: way at the moment to return the current directory as a string). To
93: change the current working directory of sml use the function
94: cd :string -> unit, whose argument should be a path name denoting a
95: directory.
96:
97: 8. error messages
98:
99: The error messages produced by the compiler are not always as helpful
100: as they should be, and there are often too many of them.
101:
102: The compiler attempts to recover from syntactic and type errors so
103: that it can detect as many errors as possible during a compilation.
104: Unfortunately, it is not very graceful in recovery, and the process
105: can cause numerous spurious secondary error messages.
106:
107: When compiling files, the error messages include a line number. For
108: simple syntactic errors this line number is often accurate or off by
109: just one line. For other classes of errors, including type errors,
110: the line number may not be very useful, since it will often just
111: indicate the end of the declaration containing the error, and this
112: declaration can be quite large.
113:
114: There are a number of different forms of type error message, and it
115: may require some practice before you become adept at interpreting
116: them. The most common form indicates a mismatch between the type of a
117: function (or operator) and its argument (or operand). A
118: representation of the offending expression is usually included, but
119: this is an image of the internal abstract syntax for the expression
120: and may differ significantly from the original source code. For
121: instance, an "if...then...else..." expression is represented
122: internally as a case expression over a boolean value:
123: "case ... of true => ... | false => ...".
124:
125: 9. useful system flags
126:
127: There are a number of useful system flags and variables, which are
128: found in the structure System.Control and its substructures. The
129: primary and secondary prompt variable have already been mentioned;
130: here are some more:
131:
132: Printing: System.Control.Print. ...
133:
134: printDepth : int ref
135: controls depth to which complex values and syntax trees are printed
136: (default 5)
137:
138: stringDepth : int ref
139: controls how much of a long string will be printed (default 70)
140:
141: signatures : bool ref
142: when true, signatures, and the signatures of structures, will be
143: printed when these are defined at top level (default true)
144:
145: Garbage collection messages:
146:
147: System.Control.Runtime.gcmessages: int ref
148: when 0, no messages are printed
149: when 1, only major collections are reported (the default)
150: when 2, major collections and heap resizings are reported
151: when 3, minor and major collections and heap resizings are reported
152:
153: Memory use:
154:
155: System.Control.Runtime.ratio : int ref
156: determines the desired ratio between size of live data and total heap
157: size. Default is 5, and 3 is the smallest acceptable value. A higher
158: ratio causes more aggressive use of memory (up to the softmax bound).
159:
160: System.Control.Runtime.softmax : int ref
161: suggested ceiling on heap size, in bytes. Heap size will not grow
162: beyond this value except to maintain the "minimum" ratio of 3. Actually,
163: when hard limits are reached (e.g. as determined by limit datasize), the
164: system can continue to run as long as the actual ratio is greater than 2.
165: A good value for softmax is one that reflects the amount of physical
166: (not virtual) memory that is expected to be available for the sml process,
167: for instance, 5000000 (5MB) might be appropriate on an 8MB Sun 3.
168:
169: 10. Timing
170:
171: The structure System.Timer, which has the signature
172:
173: signature TIMER =
174: sig
175: datatype time = TIME of {sec : int, usec : int}
176: type timer
177: val start_timer : unit -> timer
178: val check_timer : timer -> time
179: val makestring : time -> string
180: val add_time : time * time -> time
181: end
182:
183: provides basic facilities for timing your code. Here is how a typical
184: timing function could be implemented:
185:
186: fun timeit (f: unit->'a) =
187: let open System.Timer
188: val start = start_timer()
189: val result = f()
190: in print(makestring(check_timer(start)));
191: print "\n";
192: result
193: end;
194:
195: 11. Profiling
196:
197: See the file doc/profiling for instructions on using the built-in
198: profiling facilities.
199:
200: 12. Basic ML environment
201:
202: Look at the files src/boot/perv.sig and src/boot/system.sig
203: for signatures that specify what is available in the basic environment.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.