═══ 1. What is SML for PM? ═══ This package contains two programs for using the functional language Standard ML. ═══ 1.1. Programs, copyright and other stuff ═══ All programs are based on the Edinburgh Implementation of Standard ML (v4.1.02). sml.exe is therefore (c) by Edinburgh University. The OS/2 2.0 port of sml.exe and all other programs are written by Felix von Normann The programs may be copied und used for free (for personal usage). Since the programs are free, there are no warranties for any damages caused directly or indirectly by them. All software is supplied AS IS. This is a very early program version, so there are probably a lot of bugs. If there is somebody interested in a 2nd version, please let me know bugs and errors. I will try to fix them in the next release. All comments are very welcome. The author can be reached at: normann@peschl.fmi.uni-passau.de; Felix von Normann, Innstrasse 82, D-94036 Passau ═══ 1.2. programs contained in this package ═══ 1. readme - You should already have read this 2. sml.exe - the OS/2 2.0 port of Edinburgh SML version 4.1.02 3. smlpm.exe - A PM-Shell for SML. (needs sml.exe) 4. sml.exp - An import file necessary for sml.exe (all versions) 5. smlref.inf - A small SML reference in german (use view.exe) 6. sml.inf - This document 7. qref.txt - Used for online help 8. *.ml - some samples 9. (The DOS-port is not discussed in this manual) ═══ 1.3. SML - 2 versions ═══ 1. sml.exe - the OS/2 2.0 port of Edinburgh SML version 4.1.02 This program is almost left in it's original version (except changing the float div 0.0 and garbage collection). This Program can be used either via stdin/stdout or by piping a file into it. It is intended to be used for large projects and small experiments. sml.exe is necessary for smlpm.exe 2. smlpm.exe - A PM-Shell for SML. This program provides a real PM-Interface for SML including an editor. This program is intended to be used for small and medium programs, experiments and testing. Since it uses the graphics mode it is slower than than sml.exe but I hope it is easier to use. ═══ 2. Quick Start ═══ You can simply start the programs by: sml.exe: sml (This starts sml.exe with a minimal heap and a default import file "sml.exp"). smlpm: smlpm (This starts the PM-program which works interactive). You can type in the functions on the last line only. ═══ 3. User's Guide ═══ ═══ 3.1. sml.exe ═══ This section describes the usages of sml.exe ═══ 3.1.1. Getting started ═══ The syntax is: sml [-a] [-h size] [-q] [impFile] -a means to use ANSI-sequences. SML output and user input are displayed in different colors. -h specifies the size of heap used for Standard ML. -q starts ML in quiet mode An import file can be given != sml.exp. Example: sml -a -h 4000 smlexp.exp starts sml in ANSI-mode, with a heap of almost 4MB. SML uses smlexp.exp as the import file. ═══ 3.1.2. Small expressions ═══ It is easy to type in small expressions. The last one can be recalled by pressing F3. ═══ 3.1.3. Editing ═══ For larger functions the ML-commandline is not comfortable enough. There are three possibilities to make the work easier: 1. For OS/2 windowed shells you can use the OS/2's cut and paste features. 2. You can use your favorite text editor. Save the file and type use file.ml. use (string->unit) is a standard function of ML. SML loads the file and evaluates the expressions. 3. Put a small editor (must be VIO) (e.g. t.exe, supplied by IBM) into the PATH. Load edit.ml by typing use edit.ml This file defines 2 functions: edit (string->unit) invokes the texteditor, run (string->(unit*unit)) invokes first the editor and then loads the program. If your editor is not t.exe you simply have to change edit.ml ═══ 3.2. smlpm.exe ═══ This section describes the features of smlpm ═══ 3.2.1. Getting started ═══ smlpm does not need any parameter. All settings are changed interactive. ═══ 3.2.2. If you need help ═══ There are 3 help textes available: 1. Help/Infos... or view sml.inf displays this text about how to use smlpm. 2. Help/Reference... or view smlref.inf shows a small reference af the languages. 3. Help/Quick reference opens a window with a small help text (qref.txt). In Addition there is a context help. Press F2 near or on a keyword (e.g. abstype). Immediately a help screen will pop up. ═══ 3.2.3. Typing small expressions ═══ If you just want to type in a small expression, it is the best to type it in directly in the main window. To avoid problems it is allowed to type in only in the last line. Move the cursor to the bottom and type in: val x=5; As soon as you press Enter, ML answeres your input. You can recall the last line by typing F3. ═══ 3.2.4. Using the main window. ═══ The main window is intended to be used for small functions and experiments. See the chapter about small functions. To avoid problems all lines except the last one are read-only. To type text always move to the last line You can import a file by choosing File/Import. This simulates typing use ... The Edit menu works exactly like e.exe. You can cut and paste text from the window. If you want to change the font select Options/Change font Since smlpm actually loads sml.exe to eval your expressions you can give the path and name of sml.exe and the import file in the options menu. You can also change the heap size whichs defaults to 4000 KB. It is possible to save the ML dialog by selecting File/save transcript. You can restart sml.exe (the child process of smlpm.exe) by choosing File/ReStart. This is important if you change options or if sml.exe stopped its job. All options are saved. So they are available the next time the program is started. Be careful to leave the program via File/Quit. ═══ 3.2.5. Using the editor ═══ For larger functions you can start as many editors as you want by selecting Tools/Editor. Type in the whole funtion(s). That can be several lines. By pressing Alt-V (or selecting eval) all text is copied into the main window and sent to sml.exe. By pressing Alt-U (or selecting use) all text is saved in a temporary file and loaded by the use-funtion You can make full use of all edit capabilities include undo, cut, paste, ... When all functions are working save the file by selecting file/save(as). The default name is noname.ml. The actual name is displayed on the title bar. Be careful with menu option clear. The text is cleared without explicitly asking for permission. By closing the main window ALL editor windows are closed without saving. ═══ 3.2.6. Keyboard shortcuts and syntax expansion ═══ Keyboard shortcuts: Alt-V: Evaluate expression (edit window) Alt-U: Evaluate expression using temporary file Alt-B: abstype Alt-D: datatype Alt-A: andalso Alt-C: case Alt-X: exception Alt-H: handle Alt-I: if Alt-L: local Alt-N: nonfix Alt-O: orelse Alt-R: raise Alt-T: then Alt-V: val (main window) Alt-w: while Alt--: => Syntax expansion: Ctrl-a: abstype Ctrl-d: datatype Ctrl-c: case of Ctrl-i: if then else Ctrl-l: local Ctrl-v: let This is specific to the german keyboard layout! These keyboard macros are available in both, main and aditor windows. ═══ 4. Technical information ═══ This chapter describes some technical information ═══ 4.1. Why OS/2 2.0? ═══ OS/2 2.0 is a modern operation system. It allows SML to use 32 Bit and Flat memory. Because I did not want change the SML sources more than necessary sml.exe is started as a child process. stdin and stdout are piped into smlpm.exe. The operating system must offer a lot of functions for IPC. I believe this is an impossible task with Windows. SML needs a lot of processor time. This makes it necessary to divide the work into several tasks. With smlpm.exe there are at least 4 threads running. Because of the usage of multithreading sml does not slow down the system dramatically. Another reason for using OS/2 2.0 was its clear and easy to use API. In fact, programming OS/2-PM is easier than programming windows. ═══ 4.2. Why not Windows? ═══ Porting SML to 16-Bit Windows is almost impossible. There must be made a lot of changes in the original source files which I tried to avoid. Of course it allmost impossible but not really impossible to port SML for windows. It's a question af tools and I already had a windows 3.1 version (but I did not like it because I cannot use my german keyboard). But because Win16 is sometimes annoying and all other time frustrating I do not want to spend any more time on it. Windows lacks the features of multithreading, interprocess communication, it has a bad API and even worst memory management. ═══ 4.3. Why not NT? ═══ When this program was written NT was still beta. It has inherited some problems from Windows (e.g. API). It does use a lot of resources (I do not want to give away 10 MB of my RAM for the OS). ═══ 4.4. Implementation ═══ sml.exe was written in C (about 6000 LOC), pmsml.exe was written in C++ (about 1500 LOC short), but it is not programmed truely object-oriented. I did not use any class-library, so it is written in low-level OS/2. In this release smlpm starts sml.exe as a child process. It redirects the stdout into its own window an sends all keystrokes to sml.exe. Of course this way is unusual and can cause problems. The reason why I decided to work like this is that I did not want to change the Edinburgh source code. That has has a number of advantages: no additional bugs to sml.exe, easy to upgrade fam.exe, easy to port to a different language, separate GUI-code and language code, and some other. Since OS/2 is a true multitasking operating system, this solution should work stable. The main window uses an special kind of MLE (multi-line-entry field) that is "inherited" from a normal MLE. MLE are not intended to be used interactive so some problems my arise because of this. Why use a MLE? Because they are a ready-to-use editor. The alternative would be to write the own epm. This would take months. In addition, writing an editor for a complex GUI like PM (or even Windows) is not an easy task. I bet the first release of an editor would be very buggy. So why not reuse well-tested code? I hope this solution will not cause many problems. A MLE should be use with less then 16K, but I tried it with large files - without difficulties. ═══ 5. trouble shooting ═══ This section describes some common problems ═══ 5.1. There is nothing happen! ═══ Ensure that sml.exe is in the path, or change the option-settings ═══ 5.2. SML is starting, but nothing happens! ═══ Ensure that sml.exp is in the path, or change the option-settings ═══ 5.3. I cannot type in anything ═══ The main window accepts input only if the cursor is in the last line. Scroll down to the last line. ═══ 5.4. The window is blinking (flickering)! ═══ Thats not my fault. e.exe behaves the same way. Try to make the window as small as possible. ═══ 5.5. The editor is slow. ═══ There is much overhead when doing graphics. Try to minimize the overhead by making the window as small as possible. ═══ 5.6. SML quits work. ═══ Simply choose menu "File/ReStart". All definitions must be typed in from the beginning. ═══ 5.7. General problems. Wrong output. ═══ The sml-interpreter is started as a child process. It is very difficult to decides for smlpm.exe that sml.exe has done all work and is ready to accept more input. I used semaphores to do this but I know there are still a lot of problems left. If eval is not functioning the correct way try to select the use option. I know there are a lot of bugs left and I work on them.