Scheme Does Windows!

By Anne Hartheimer, President

Programming a Text Editor in MacScheme+Toolsmith™

The purpose of this article is to give an example of an application written in MacScheme+Toolsmith™. The application is a simple text editor, similar to the text editor written in Pascal that appears elsewhere in this issue of MacTutor. This editor is incomplete in many ways. It does not support the Clipboard, for example, nor does it check to make sure that the edited text does not exceed the limits of a single text edit record. It does, however, convey a sense of what it is like to program using MacScheme+Toolsmith. The code for this editor is a pre-release version of an example included with MacScheme+Toolsmith. A screen shot of the program is shown in figure 1. The program loads and saves files (which the Pascal version in this issue doesn't), and includes a find and change function.

Figure 1: Our Lisp version Text Editor

About MacScheme, MacScheme+Toolsmith

MacScheme™ is a Lisp system from Semantic Microsystems that runs on 512K and larger Macintoshes and includes an editor, incremental byte code compiler, debugger, and tracer. MacScheme implements the Scheme dialect of Lisp, a dialect known for its simplicity, regularity, and power. Aside from simple quickdraw graphics routines, however, the only way to access the Toolbox from MacScheme was by using machine code. This was one of the motivations behind a new product called MacScheme+Toolsmith.

MacScheme+Toolsmith lets you program the Macintosh Toolbox interactively in Lisp. It provides Lisp access to the complete set of Toolbox traps and high level routines for creating window and menu objects. (You can bring up a text edit window with a single line of code, interactively.) Source code for the object-oriented window and menu routines is included so you can modify them if you want. MacScheme+Toolsmith supports multitasking and provides an interrupt system for handling events.

MacScheme+Toolsmith is being released in December 1986. To use the high level window and menu routines, 1 M RAM is needed. You can use the rest of MacScheme+Toolsmith with only 512K.

The Text Editor Program

Scheme programs consist of definitions mixed with expressions. These definitions and expressions are executed in order, just as if they were typed interactively. The first expression that appears in the editor program sets some variables that tell the compiler not to include documentation for source code and arguments. The second expression loads a number of files from the MacScheme+Toolsmith disks containing definitions of procedures and data used by the program.

Figure 2: The Scheme Trap Docs

Figure 2 shows the files in the "Chapters" folder which correspond to chapters in Inside Macintosh. Thus "chap20.data" contains the type declarations for the standard file package described in chapter 20 of Inside Macintosh, while "v2.chap4.traps" contains the low level file manager traps described in chapter 4 of volume II of Inside Macintosh. By this neat packaging trick, you can easily find the Scheme definition for trap calls as you study the toolbox documentation in Inside Macintosh.

The files in the "Examples" folder shown in figure 3 are examples included with MacScheme+Toolsmith. The file "fs.sch" contains high level file system calls analogous to the Pascal calls documented in Inside Macintosh, and the file "files.sch" contains even higher level calls for prompting for, reading, and writing entire files. The file "fonts.sch" defines some general purpose procedures for setting fonts in a window. This file is reproduced in this article to show you some low level Toolbox hacking. The file "search.sch" defines a procedure for creating a Search menu that is used in this text editor. It's about five pages long, and we thought we could safely omit it from this article.

Figure 3: Our Editor Files

Scheme Syntax

The syntax for a MacScheme procedure definition is

 (define (<procedure-name> <arg1>...)
    <procedure-body>)

where <arg1>... means zero or more arguments. Most of the procedures defined in this program take no arguments.

Referring to the sample code below, the procedure main will be called to begin the application. The call to begin-application tells the MacScheme user interface to stop handling events. All future events will cause the currently executing program to be interrupted while the event is handled by an interrupt handler. Interrupt handlers are easy to install and are fairly easy to write because they are written in Scheme, but none had to be written for this application because the standard interrupt handlers provided by MacScheme+Toolsmith were sufficient.

(define (main)
  (begin-application)
  (hidewindow 
   ((lookup-window-object (frontwindow)) 
    'windowptr))
  (pushmenubar)
  (init-search)
  (setup-menus)
  (begin-tasking)
  (start-task idle-loop)
  (start-task relaxation-loop)
  (kill-current-task))

The "main" part of our Editor!

The calls to hidewindow and pushmenubar get rid of the MacScheme transcript window and the MacScheme menus so the program can replace them with its own menus. The current menu information is actually pushed onto a stack and could be recalled by calling popmenubar. The call to init-search allows the search module to open the resource file containing its dialogs. The call to begin-tasking tells MacScheme to generate periodic interrupts whether or not an event has occurred. This allows the task scheduler to operate. The program then starts up two concurrent tasks, which will run until the user selects Quit from the File menu. From this point on the program is driven entirely by interrupts while the two tasks run in the background, so the initial task can be killed.

The only thing that the idle-loop task does is to call TEIdle to blink the insertion point in the front window. The relaxation-loop does even less. In fact, the program would run just fine without the relaxation-loop task. Its only purpose is to improve performance. How can an extra task improve performance? The answer has to do with the automatic recovery of storage through garbage collection. The idle-loop task allocates a little bit of Scheme storage every time it calls TEIdle. If it were the only task running, it would amount to a tight loop generating garbage. Adding a concurrent task makes it call TEIdle less often, so it generates less garbage and the garbage collector runs less frequently.

Our Menu Bar

The application creates five menus: an apple menu, a File menu, an Edit menu, a Font menu, and a Search menu. Each menu is set up by a separate procedure.

Menu objects are created by the make-menu procedure, which also installs the menu in the current menu bar. The argument to make-menu is a Scheme string giving the name of the menu. The most important operation on the menu object returned by make-menu is the 'append operation, which adds an item to the menu. The 'append operation requires two arguments: the name of the item and an action to be performed whenever the item is chosen. In setup-file-menu, for example, (filemenu 'append "Quit" exit) adds a Quit item to the File menu and causes the exit procedure to be called whenever the item is chosen.

The 'append operation can also take an optional third argument: a predicate that determines whether the item should be enabled or disabled. Many of the menu items in this application, for example, should be enabled only if the front window was created by the application. If this optional argument is omitted, the item will always be enabled.

Lambda expressions deserve some mention here because they are more general in Scheme than in most other dialects of Lisp, and few other languages have anything to resemble them. In the expression

 (filemenu 
   'append
  "New"
   (lambda () 
      (make-document "Untitled" #f)))

the lambda expression evaluates to a procedure of no arguments whose body is (make-document "Untitled" #f). The () is the argument list, and the word "lambda" is a syntactic marker analogous to "function" in Pascal. When "New" is selected in the file menu, this procedure will be executed, creating a new untitled document window. This example shows how "object oriented" Lisp is, and in fact, it makes a very good introduction to object oriented programming.

One difference between lambda expressions and function declarations in Pascal is that the lambda expression evaluates to an anonymous procedure, while Pascal function declarations always name the procedure. Another difference is that there are no arbitrary restrictions on what can be done with the procedure returned by a lambda expression, while in Pascal procedures cannot be returned as the result of a procedure call.

The 'addresources operation on menu objects adds all resources of a given type to the menu. Its arguments are similar to those for the 'append operation, but the first argument is a resource type instead of an item name and its second argument is parameterized by an item number. That is, the second argument is a procedure that will be called once for each resource of the given type. It will be passed the menu item number for a resource and must return an action procedure for that menu item.

Most of the application's behavior is distributed among the action procedures for the various menu items. Some calls to low-level Toolbox traps can be seen in the action procedures, while other calls are hidden inside higher level procedures like stdgetfile, read-file, set-font, and set-fontsize. Calling Toolbox traps directly from MacScheme+Toolsmith is a lot like calling them from C, and in some ways it is even more difficult in MacScheme+Toolsmith than it is in C because C's natural data structures are closer to those used by the Toolbox. The advantages of MacScheme+Toolsmith lie elsewhere.

One advantage is that the interrupt system and multi-tasking makes it easier to separate an application into independent modules. As one trivial example, blinking the insertion point has nothing to do with handling events. Another advantage is that Scheme is a very good language for building generally useful abstractions like window objects, and MacScheme+Toolsmith includes source code for several of the most useful abstractions.

The main abstraction that was developed specially for this application was the notion of a document object. Document objects correspond to windows created by the application and are very similar to window objects, but they must also keep track of the name and vrefnum of the file associated with the window. This suggests that document objects should inherit the behavior of window objects and should be usable in place of window objects, just as a WindowPtr can be used in place of a GrafPtr by the Toolbox traps. It also suggests that a document object should have as its state variables a window object, a name, and a vrefnum. It seems convenient also to have document objects respond to save and save-as messages.

The make-document procedure creates a document object. It was written in the same style as the make-menu and make-window procedures that are supplied in both source and object form as part of MacScheme+Toolsmith. As can be seen from the code, a document object is just an ordinary Scheme procedure that dispatches on its argument using a case expression. If the operation takes no arguments, as in the 'window, 'name, 'save, and 'save-as operations, then it is performed immediately. If the operation takes arguments, as in the 'set-name operation, then it returns a procedure that can be called with those arguments to perform the operation. The (if args (apply (self op) args) ...) nonsense preceding the case expression is simply to make it possible to write things like (document 'set-name "Henry") instead of ((document 'set-name) "Henry").

Since many of the menu actions operate on the front window, it must be possible to find a document object beginning with the WindowPtr returned by the FrontWindow trap. This is the reason for the table of document objects and the lookup-document-object procedure.

The garbage collector cannot reclaim the space occupied by a document object so long as it appears in that table, so document objects must be removed from the table when they are closed. This is easy to accomplish when a window is closed using the Close item in the File menu, but is not so easy to do when the user simply clicks in the goaway box of the window. The problem is that the standard MacScheme+Toolsmith interrupt handler for mousedown events sends the close message directly to the window object, bypassing the document object. We could have rewritten the interrupt handler or added another interrupt handler that deals only with mousedown events in goaway boxes, but we instead changed the definition of lookup-window-object, which is called by the standard mousedown event handler, to return a document object instead of a window object whenever the window object is associated with a document. This may be the most subtle thing in the program.

The application as written does not give the user a chance to save windows as they are being closed. This would be a nice feature to add to the 'save operation on documents. There are several ways to tell whether the document has been changed since it was opened, of which the simplest is to compare the window's contents with the contents of the file from which it came.

The value of **task-timeslice** determines the interval between task switches. It sets a limit to the rate at which the insertion point will blink.

When a menu item is chosen the associated action procedure executes uninterruptibly. Ordinary tasks, however, can be interrupted at any time. This creates a potential problem. What would happen if, after the idle-loop task had fetched the text handle for the front window but before it could pass it to TEIdle, the user closed the window by clicking in the goaway box? The system would crash, that's what. The solution is to prohibit interrupts between the time that the text handle is fetched and the call to TEIdle. The call-without-interrupts routine takes a procedure of no arguments and calls it uninterruptibly.

The surrender-timeslice procedure blocks the current task until its next turn comes around. Once TEIdle has been called, there's no point to calling it again a few microseconds later.

Whenever MacScheme starts up it calls scheme-top-level with no arguments. Normally scheme-top-level is the standard read/eval/print loop, but for this application we changed it to call main.

Building Stand-Alone Programs

Link-application is a simple linker that dumps a MacScheme+Toolsmith heap image after stripping unused procedures and data. The heap image dumped by the linker is like a Smalltalk image file or snapshot. It can be launched by double-clicking provided the MacScheme+Toolsmith byte code interpreter is also present. An Application Builder is planned that will bind heap images together with a stripped down version of the byte code interpreter into a single application file, enabling standard Macintosh applications to be constructed using MacScheme+Toolsmith.

; This code was written by
; Semantic Microsystems, Inc.
; which has placed it in the
; public domain.

; Pre-release version of the file
; "texteditor.sch" from
; MacScheme+Toolsmith™

; A simple editing application.

(begin (set! include-source-code? #f)
       (set! include-lambda-list? #f))

(begin (load ":Chapters:chap20.data")
       (load ":Chapters:chap20.traps")
       (load ":Chapters:v2.chap4.data")
       (load ":Chapters:v2.chap4.traps")
       (load ":Chapters:chap7.traps")
       (load ":Examples:fs.sch")
       (load ":Examples:files.sch")
       (load ":Examples:fonts.sch")
       (load ":Examples:search.sch")
       (load ":Examples:linker.sch"))

(define (main)
  (begin-application)
  (hidewindow 
   ((lookup-window-object (frontwindow)) 
    'windowptr))
  (pushmenubar)
  (init-search)
  (setup-menus)
  (begin-tasking)
  (start-task idle-loop)
  (start-task relaxation-loop)
  (kill-current-task))

(define (setup-menus)
  (setup-apple-menu)
  (setup-file-menu)
  (setup-edit-menu)
  (setup-font-menu)
  (setup-search-menu))

(define (setup-apple-menu)
  (let ((applemenu 
         (make-menu 
          (list->string (list applmark)))))
    (applemenu 
     'addresources
     (make%restype "DRVR")
     (lambda (n)
       (lambda ()
         (let ((temp (newptr 256)))
           (getitem 
            (applemenu 'menuhandle) 
            n 
            temp)
           (opendeskacc temp)
           (disposptr temp)))))))

(define (setup-file-menu)
  (let ((filemenu (make-menu "File")))
    (filemenu 
     'append
     "New"
     (lambda () 
       (make-document "Untitled" #f)))
    (filemenu 
     'append
     "Open..."
     (lambda ()
       (let ((info
              (stdgetfile 60 60 "TEXT")))
         (let ((flag (car info))
               (name (cadr info))
               (vrefnum (caddr info)))
           (if flag
               (let
                 ((d (make-document
                      name
                      vrefnum))
                  (contents (read-file
                             name
                             vrefnum)))
                 (if contents
                     ((d 'editor 
                         'set-textstring)
                      (->string contents))
                     )))))))
    (filemenu 'append
              "Close"
              (lambda ()
                ((lookup-document-object
                  (FrontWindow))
                 'close))
              front-window-is-ours?)
    (filemenu 'append
              "Save"
              (lambda ()
                ((lookup-document-object
                  (FrontWindow))
                 'save))
              front-window-is-ours?)
    (filemenu 'append
              "Save as..."
              (lambda ()
                ((lookup-document-object
                  (FrontWindow))
                 'save-as))
              front-window-is-ours?)
    (filemenu 'append "Quit" exit)))

(define (setup-edit-menu)
  (let ((editmenu (make-menu "Edit")))
    (editmenu 'append
              "Undo/Z"
              (lambda () (systemedit 0))
              ; enable only if the 
              ; front window is not ours
              (lambda ()
                (not 
                 (front-window-is-ours?)
                 )))
    (editmenu 'append
              "-"
              (lambda () #t)
              ;always disable
              (lambda () #f))
    (editmenu 'append
              "Cut/X"
              (lambda ()
                (systemedit 2)
                ((lookup-window-object 
                  (frontwindow)) 
                 'editor 
                 'cut)))
    (editmenu 'append
              "Copy/C"
              (lambda ()
                (systemedit 3)
                ((lookup-window-object
                  (frontwindow)) 
                 'editor 
                 'copy)))
    (editmenu 'append
              "Paste/V"
              (lambda ()
                (systemedit 4)
                ((lookup-window-object 
                  (frontwindow)) 
                 'editor 
                 'paste)))
    (editmenu 'append
              "Clear"
              (lambda ()
                (systemedit 5)
                ((lookup-window-object 
                  (frontwindow)) 
                 'editor 
                 'clear)))))

(define (setup-font-menu)
  (let ((fontmenu (make-menu "Font")))
    (fontmenu 
     'addresources
     (make%restype "FONT")
     (lambda (n)
       (lambda ()
         (let ((temp1 (newptr 256))
               (temp2 (newptr 2)))
           (getitem (fontmenu 'menuhandle) 
                    n 
                    temp1)
           (getfnum temp1 temp2)
           (set-font (lookup-window-object 
                      (frontwindow))
                     (peek.word temp2))
           (disposptr temp1)
           (disposptr temp2)))))
    (fontmenu 'append
              "-"
              (lambda () #t)
              (lambda () #f))
    (for-each 
     (lambda (size)
       (fontmenu 'append
                 (number->string size)
                 (lambda ()
                   (set-fontsize
                    (lookup-window-object 
                     (frontwindow))
                    size))
                 front-window-is-ours?))
     '(9 10 12 14 18 24))))

(define (setup-search-menu) 
  (make-search-menu))
; Document objects.
; A document object inherits all the 
; behavior of a window object
; but it has additional behavior when
; sent one of the following messages:
;    window
;    name
;    set-name
;    vrefnum
;    set-vrefnum
;    save
;    save-as
;    close
(define (make-document name vrefnum)
  (letrec 
    ((window (make-window 
              'text
              'title name
              'bounds 10 40 500 330))
     (self
      (lambda (op . args)
        (if args
            (apply (self op) args)
            (case op
              ((window) window)
              ((name) name)
              ((set-name)
               (lambda (newname)
                 (set! name newname)
                 (let 
                   ((temp 
                     (make%string name)))
                   (SetWTitle 
                    (window 'windowptr) 
                    temp)
                   (disposptr temp))
                 name))
              ((vrefnum) vrefnum)
              ((set-vrefnum)
               (lambda (n) 
                 (set! vrefnum n) vrefnum))
              ((save)
               (if vrefnum
                   (write-file 
                    name
                    vrefnum
                    (window 'editor 
                            'textstring)
                    "EDIT"
                    "TEXT")
                   (self 'save-as)))
              ((save-as)
               (let ((info 
                      (stdputfile 60 
                                  60 
                                  name)))
                 (if (car info)
                     (begin
                      (self 'set-name 
                            (cadr info))
                      (self 'set-vrefnum 
                            (caddr info))
                      (self 'save)))))
              ((close)
               (set! documents
                     (remove 
                      (assq window 
                            documents) 
                      documents))
               (if (not (window 'closed?))
                   (window 'close)))
              (else (window op)))))))
    (set! documents 
          (cons (list window self) 
                documents))
    self))

; The global variable documents is
; an association list with elements of the form 
; (<window-object> <document-object>).
; There is an entry for each window
; created by this application.

(define documents '())
; Given a Toolbox windowptr such as is 
; returned by FrontWindow,
; lookup-document-object returns the 
; document object associated with
; it or #f if it's not ours.
;
; This code also redefines 
; lookup-window-object so that it will 
; return a document object instead of a
; window object for those windows
; that have been created by this 
; application. That allows documents 
; to intercept a close message sent 
; to a window.

(define lookup-document-object)
(let ((old-lookup-window-object 
       lookup-window-object))
  (set! 
   lookup-document-object
   (lambda (windowptr)
     (let ((entry 
            (assq 
             (old-lookup-window-object 
              windowptr)
             documents)))
       (if entry
           (cadr entry)
           #f))))
  (set! lookup-window-object
        (lambda (windowptr)
          (or (lookup-document-object 
               windowptr)
              (old-lookup-window-object 
               windowptr))))
  #t)

(define (front-window-is-ours?)
  (lookup-document-object (frontwindow)))

; Concurrent tasks.

(define **task-timeslice** 500)

; This procedure soaks up idle time 
; with occasional calls to TEIdle.

(define (idle-loop)
  (call-without-interrupts
   (lambda ()
     (let ((texth ((lookup-window-object 
                    (FrontWindow))
                   'editor
                   'texthandle)))
       (if texth (teidle texth)))))
  (surrender-timeslice)
  (idle-loop))

; Running this procedure as a concurrent 
; task improves interactive performance 
; because
;  (1) this procedure creates no garbage 
;      whatsoever (so running it as a
;      task makes garbage collections
;      occur less frequently);
;  (2) all pending interrupts are
;      accepted each time through the
;      loop (because the time procedure
;      enables interrupts).

(define (relaxation-loop)
  (time)
  (relaxation-loop))
; The scheme-top-level procedure is
; called when MacScheme starts up.

(define (scheme-top-level)
  ; exit if an error causes a reset
  (set! scheme-top-level exit)
  (main)
  (exit))
(link-application)