Objects in Pearl Lisp

By Stephan E. Miner, Menlo Park, CA

Introduction

Coral Software recently released Pearl Lisp, a subset of Common Lisp for about $100. Pearl Lisp is based on Coral’s Allegro Common Lisp which has been discussed in an earlier issue of MacTutor (see Paul Snively’s article in the March 1988 issue.) Although Allegro received very good reviews, its list price of about $600 made it impractical for most first-time Lisp programmers. Pearl Lisp offers an affordable introduction to Lisp programming on the Macintosh.

Although a complete review of Pearl Lisp is not the purpose of this article, a brief overview might be helpful. Some features of Common Lisp (such as packages, structures, hash tables and multiple values) are not supported. However, most of the list, control, and mathematical functions of Common Lisp are available. Lexical scoping and closures are also implemented. The development environment is very much like Allegro’s and includes an EMACS-like editor known as FRED (FRED Resembles EMACS Deliberately.) The reference manual is well-written, with cross references to Steele’s Common LISP: the Language and several popular textbooks. In addition to the subset of Common Lisp functions, Pearl Lisp includes a native object-oriented programming system, called Object Lisp, which is the topic of this article.

As a demonstration of Object Lisp, the sample program simulates a solar system. Objects are used to implement the planets as well as the Macintosh windows and menus. Each planet orbits around a gravitational center at some radius with a certain period. At any point in time, the planet has some X and Y coordinates relative to the center of the solar system. The simulation is displayed in various windows with each window offering the view from a particular planet. For example, a heliocentric view has the Sun appearing fixed at the center of the window. In contrast, a geocentric view keeps the Earth at the center of display with some of the other planets showing retrograde motion. In both cases, the same planets are used and they maintain the same relative motions. It is the window objects which implements the different points of view.

Object Lisp

Before describing the sample program in detail, a brief introduction to the basic concepts of Object Lisp will be presented. As in other object-oriented programming systems, an object encapsulates both data and functions. An object’s data is contained in internal variables, known as instance variables. (Instance variables are often called slots in other systems.) An object can also have specialized object functions that allow access to the object’s internal variables as if the internal variables were local to the function. (Object functions are often called methods in other object-oriented systems.)

Inheritance is another key concept in most object-oriented systems. In Object Lisp, objects are defined in terms of other objects. An object inherits the instance variables and object functions of its parents. (Object Lisp supports multiple inheritance, but the details are not discussed in this article.) An object can replace, specialize, or combine the characteristics of its parents by shadowing the appropriate object functions. A parent’s object function foo is also accessible by calling usual-foo, even when the parent’s object function is shadowed.

The special form ask is used to access the environment of an object. For example, suppose that OBJECT is bound to some object. The form (ASK OBJECT VAR) will return the object’s internal value for VAR. The form (ASK OBJECT (FUNC ‘ARG)) will return the result of calling the object function FUNC with the argument ‘ARG.

Conceptually, global variables and functions belong to the root object nil. Thus, (ASK NIL (GLOBAL-FUNC ‘ARG)) is equivalent to (GLOBAL-FUNC ‘ARG). This also implies that global variables and functions are accessible by all objects through inheritance from the root object. The root object also implements several useful object functions. The have object function is used to create instance variables. For example, (ASK OBJECT (HAVE ‘VAR ‘VAL)) will create an instance variable VAR with an initial value VAL for the object OBJECT. The self object function simply returns the current object.

Classes

Most object-oriented systems make a distinction between a class and an instance. A class defines a type of object with a description of its internal data and the associated procedures (or methods) for operating on that data. An instance, on the other hand, is a specific object with internal values which hold its state. Object Lisp does not enforce this strict distinction, but it does support a convention that implements classes as types of objects.

Class objects can be created with the macro defobject which defines the name of the class and the parents from which it inherits. Nil is used as the root object class.

An instance of a class is created by the function oneof which takes the parent class as the first argument, followed by a list of keyword-value pairs for initializing the instance. The initialization is actually executed by the exist object function defined for the class. We will see how the exist object function works in our sample program.

The Solar Program

The sample program can be divided into three major sections. The first part implements the planet class. Window objects are implemented by the second part. The final section provides menus for controlling the execution of the program.

The *planet* class is quite simple. It is defined using defobject and inherits only from the root class object, nil.

The exist object function for *planet* needs more explanation. Exist will be called automatically by the system when the oneof function is used to create a new instance of*planet*. The init-list argument will be a list of the keyword-value pairs given to oneof. The main purpose of the exist object function is to initialize the instance variables. The getf function is used to access the value associated with the indicated keyword. A default value can also be specified in case the keyword is not found. For example, if the period of a planet is not specified in the init-list, the default value of 25 is used.

In order to simplify the creation of new planets, the :center keyword is used to specify the orbital center of the new planet. When calculating coordinates, however, it is more natural to proceed from the center out to the satellites. The center is asked to add the new planet to the its list of satellites using the add-satellite object function.

The update-system object function calculates the new X and Y coordinates for the planet given the time and the coordinates of the planet’s orbital center. The planet then recursively asks its satellites to run update-system. Thus, a single update-system call to the sun of a solar system will be propagated through all the planets in the system.

The other class that the program defines is the *solar-window*. This class is a specialized version of the *window* class which is provided by Coral as an interface to the Macintosh window system. This is a good example of how one can easily extend a previously defined class. In this case, the new exist first calls usual-exist to handle the normal initialization of the window. The init-list-default function returns an init-list with the additional defaults. *Solar-window* also has a couple of its own instance variables. The center instance variable determines the gravitational center of the solar system (normally the *sun*.) The view instance variable controls the viewpoint of the display. For example, a geocentric view is given by setting the view to *earth*.

The center-origin object function resets the origin of the window to the center of view. This simplifies the display of the solar system. The window-zoom-event-handler and set-window-size object functions are also extended to recenter the origin.

The inheritedwindow-show object function displays the window on the screen. This indirectly calls the window-draw-contents object function. The sample program does not worry too much about animation flicker so it simply erases the entire window and then redraws everything. The usual-window-draw-contents takes care of redrawing the grow box.

The draw-system object function does most of the work. Its structure is similar to update-system in that it draws one planet and then recursively draws the satellites of that planet. In this case, however, the x-off and y-off arguments are offsets that are added to the absolute coordinates for the planet to determine the planet’s window coordinates. Each view assigns offsets so that the view planet remains centered in the window. The rlet macro lets a Lisp program create Pascal record structures, such as those used by the Macintosh ROM routines. Here, a rectangle is initialized based on the size of the planet and its window coordinates. The Quickdraw routines, fill-oval and frame-oval, are used to draw the planet. When rlet exits, the temporary record is disposed automatically.

The erase-window object function also accesses a Pascal record structure. In this case, it uses the rref macro to return the window’s portrect. The instance variable, wptr, is defined by the *window* class and holds a Macintosh window pointer. Rref allows the Lisp program to access the fields of the record using a Pascal-style notation. The window is erased by calling the Quickdraw function erase-rect.

The final section of the sample program involves the menu system. Once again, the menus and menu items are predefined classes of objects. A menu-item-action function is associated with each menu item. This function is called when the user selects the item.

The ubiquitous main event loop is implemented by the Pearl Lisp event system and its interface to the Macintosh operating system. It is important to note that the event system will interrupt the normal Lisp read-eval-print loop in order to run event handlers. Menus and dialogs can take advantage of this behavior by using the eval-enqueue function. Eval-enqueue queues the given form in the Lisp system’s read-eval-print loop for execution after the event handler exits. This allows the user to interact freely with the program while it is executing. The programmer is also freed from writing his own main event loop since the object system will call the appropriate handlers as needed.

In the sample program, the first three menu items create three different views of the solar system. Each item calls the new-solar function to create a new solar window with the appropriate view planet. The window title includes a number for easy reference. The program has no limit on the number of windows that it can display.

The *run-item* uses eval-enqueue to enqueue a call to the run-loop function. Run-loop maintains the checkmarks on the menu items and runs the simulations. On each pass through the loop, the global variable*time* is incremented, and the *sun* is asked to update-system for the new time. (This updates the locations of all the planets in the solar system.) Then each window is asked to redraw itself to reflect the new positions of the planets. The (ownp ‘wptr) test makes sure that the window still exists and protects against the user having closed the window while the loop was executing. Run-loop exits when the *stop-flag* is set or the window list is empty.

The *stop-item* action immediately sets the *stop-flag* during the execution of the handler. This action will interrupt the execution of the run-loop function which will later exit as soon as it rechecks the flag. The *exit-item* is similar but also enqueues a call to exit-solar which will execute after the run-loop function terminates. The exit-solar function then quits the demonstration by gathering a list of all *solar-window* objects and asking each of them to close-window (which is inherited from *window*.) Close-window also takes care of disposing of the window structure.

Conclusion

This article has presented an introduction to object-oriented programming in Pearl Lisp. The sample program demonstrates how the object system simplifies programming with windows and menus in Lisp. Without any extra work, the program also runs in the background under MultiFinder. The included screen shot shows how the program conveniently integrates with the Pearl Lisp environment.

;;; Sample program for "Objects in Pearl Lisp"
;;; by Stephen E. Miner
;;; Written in Pearl Lisp 1.01
;;; File:  Solar.lisp
;;; Version: 1.0

;;; NOTE:  The "object-variable" declarations prevent the ;;;compiler 
from issuing warnings about free variables.

;;; Set up environment
(eval-when (eval load compile)
  (require 'quickdraw))
(eval-when (eval compile)
  (require 'records))

;;; Global variables
(defvar *solar-num* 0 "Global counter for numbering windows.")
(defvar *time* 0 "Global variable holding the time that is     displayed.")
(defvar *stop-flag* t "Non-nil if simulation should stop.")

;;; The planet class
(defobject *planet* nil)

(defobfun (exist *planet*) (init-list)
  "Initializes an instance of the *planet* class according to INIT-LIST. 
 Useful init keywords are :period, :size, :pattern, :radius and :center. 
 The return value is undefined."
  (have 'period (getf init-list :period 25))
  (have 'size (getf init-list :size 3))
  (have 'pattern (getf init-list :pattern *black-pattern*))
  (have 'x 0)
  (have 'y 0)
  (have 'satellites nil)
  (let ((center (getf init-list :center))
           (me (self))) ;(self) returns object being defined
      (have 'radius (getf init-list :radius (if center 25 0)))
      (when center
         (ask center (add-satellite me)))))

(defobfun (add-satellite *planet*) (sat)
  "Add SAT to the planet's list of satellites and return the new list."
  (declare (object-variable satellites))
  (setq satellites (cons sat satellites)))
 
(defobfun (update-system *planet*) (time cx cy)
  "Update the x and y coordinates of the planet according to the TIME 
and the offsets CX and CY which should be the x and y coordinates of 
the center of the planet's orbit.  Then recursively send the update-system 
message to the satellites of the planet using the new x and y coordinates 
as the offsets.  The return value is undefined." 
  (declare (object-variable period radius x y satellites))
  (let* ((theta (* 2 pi (/ time period)))
             (new-x (+ cx (round (* radius (cos theta)))))
             (new-y (+ cy (round (* radius (sin theta))))))
      (setq x new-x y new-y)
      (dolist (sat satellites)
          (ask sat (update-system time new-x new-y)))))

;;; The planet objects (the numbers are not accurate, but they 
;;; produce a reasonable display.)
(defparameter *sun* (oneof *planet* :center nil :size 11 
                           :pattern *light-gray-pattern*))
  
(defparameter *mercury* (oneof *planet* :radius 20 :center     *sun* 
:period 12  :size 3 :pattern  *dark-gray-pattern*))

(defparameter *venus* (oneof *planet* :radius 35 :center       *sun* 
:period 32 :size 5 :pattern *dark-gray-pattern*))

(defparameter *earth* (oneof *planet* :radius 60 :center *sun* 
 :period 52 :size 6 :pattern *gray-pattern*))

(defparameter *moon* (oneof *planet* :radius 10 :center  *earth* :period 
4  :size 2))

(defparameter *mars* (oneof *planet* :radius 85 :center *sun*  :period 
90 :size 5 :pattern *dark-gray-pattern*))

;;; The solar window class
(defobject *solar-window* *window*)

(defobfun (exist *solar-window*) (init-list)
  "Initializes an instance of the *solar-window* according to the INIT-LIST. 
 Useful keywords are :center which specifies the gravitational center 
of the displayed system and :view which specifies the planet that controls 
the viewpoint of the display.  The return value is undefined."
  (declare (object-variable center))
  (usual-exist (init-list-default init-list 
                                  :window-title "Solar System"
                                  :window-size #@(250 250)
                                  :window-show nil))
  ;;don't show window until the window is fully initialized
  (have 'center (getf init-list :center))
  (have 'view (getf init-list :view center))
  (center-origin)
  (window-show))

;;; The event system will automatically ask windows to handle 
;;; certain events.  Specialized object functions for handling 
;;; these events are defined below.
(defobfun (window-draw-contents *solar-window*) ()
  "Specialized version of window-draw-contents called by the event system 
whenever part of the window needs to be redrawn.  The return value is 
undefined."
  (declare (object-variable center view x y))
  (erase-window)
  (usual-window-draw-contents)
  (draw-system center (- (ask view x)) (- (ask view y))))

(defobfun (window-zoom-event-handler *solar-window*) (message)
  "Specialized version of window-zoom-event-handler which is called by 
the operating system when the user clicks in the zoom box.  The MESSAGE 
is passed on to the usual-window-zoom-event-handler.  This version also 
recenters the origin.  The return value is undefined."
  (usual-window-zoom-event-handler message)
  (center-origin))

(defobfun (set-window-size *solar-window*) (h &optional v)
  "Specialized version of set-window-size.  Sets the size of the window 
according to horizontal and vertical dimensions, H and V.  H and V are 
either two integers or H is taken as a point if V is nil.  Also recenters 
the origin and redraws the window.  Returns the window's new size as 
a point."
  (prog1
    (usual-set-window-size h v)
    (center-origin)
    (window-draw-contents)))

(defobfun (center-origin *solar-window*) ()
  "Adjust the origin to the center of the window.  Returns the window's 
new upper lefthand corner as a point."
  (let ((pt (window-size)))
    (set-origin (floor (point-h pt) -2)
                (floor (point-v pt) -2))))

(defobfun (draw-system *solar-window*) (planet x-off y-off)
  "Draw the PLANET and its satellites in the window after adding X-OFF 
and Y-OFF to the planet's x and y coordinates.  The return value is undefined."
  (declare (object-variable x y size pattern satellites))
  (let ((x0 (+ (ask planet x) x-off))
        (y0 (+ (ask planet y) y-off))
        (size (ask planet size)))
    ;;allocate a temporary rectangle for graphics calls
    (rlet ((rec :rect :top (- x0 size) :left (- y0 size)
                :bottom (+ x0 size) :right (+ y0 size)))
      (fill-oval (ask planet pattern) rec)
      (frame-oval rec)))
  ;;draw the satellites
  (dolist (sat (ask planet satellites))
    (draw-system sat x-off y-off)))

(defobfun (erase-window *solar-window*) ()
  "Erase the contents of the window.  The return value is undefined."
  ;;rref access the Macintosh record and in this case returns 
  ;; the window's portrect.  See the Pearl Lisp documentation 
  ;; for more information about records.
  (declare (object-variable wptr))
  (erase-rect (rref wptr window.portrect)))

;;; Menu action functions
(defun new-solar (view-planet title)
  "Create a new solar window with VIEW-PLANET determining the point of 
view and the TITLE string used as base for the window title.  The global 
*solar-num* is incremented and appended to the window title to ease identification. 
 Returns the new window object."
  (setq *solar-num* (+ *solar-num* 1))
  (oneof *solar-window* :window-title 
         (format nil "~A ~A" title *solar-num*)
         :center *sun*
         :view view-planet))

(defun exit-solar ()
  "Close all the solar windows and deinstall the menu.  The return value 
is undefined."
  (dolist (w (windows *solar-window*)) 
    (ask w (window-close)))
  (ask *solar-menu* (menu-deinstall)))

(defun run-loop ()
  "Run the simulation until the global *stop-flag* is true.  This function 
also manages the solar menu."
  (setq *stop-flag* nil)
  (ask *stop-item* (set-menu-item-check-mark nil))
  (ask *run-item* (set-menu-item-check-mark t))
  (loop
    (let ((wlist (windows *solar-window*))) 
           ;;list of all *solar-window*'s
      (when (or *stop-flag* (null wlist))   
       ;;check for end of simulation
        (ask *run-item* (set-menu-item-check-mark nil))
        (ask *stop-item* (set-menu-item-check-mark t))
        (return))
      (setq *time* (+ 1 *time*))
      (ask *sun* (update-system *time* 0 0)) 
      ;;updates all the x and y coords
      (dolist (w wlist)
        (ask w (when (ownp 'wptr)   ;protect against close-box
            (window-draw-contents)))))))   ;redraw the window

;;; The menu items
(defparameter *new-helio-item* 
  (oneof *menu-item* :menu-item-title "New Helio"
         :menu-item-action '(new-solar *sun* "Heliocentric")))

(defparameter *new-geo-item* 
  (oneof *menu-item* :menu-item-title "New Geo"
         :menu-item-action '(new-solar *earth* "Geocentric")))

(defparameter *new-luna-item* 
  (oneof *menu-item* :menu-item-title "New Luna"
         :menu-item-action '(new-solar *moon* "Lunacentric")))

(defparameter *run-item* 
  (oneof *menu-item* :menu-item-title "Run"
         :menu-item-action '(when *stop-flag* 
                             (eval-enqueue '(run-loop)))))
                    
(defparameter *stop-item* 
  (oneof *menu-item* :menu-item-title "Stop"
         :menu-item-action '(setq *stop-flag* t)))

(defparameter *exit-item* 
  (oneof *menu-item* :menu-item-title "Exit"
         :menu-item-action 
         '(progn
            (setq *stop-flag* t)
            (eval-enqueue '(exit-solar)))))
;;The eval-enqueue makes sure that we wait for the run-loop to 
;; finish before we exit.

(defparameter *solar-menu* 
  (oneof *menu* :menu-title "Solar"
         :menu-items (list *new-helio-item*
                           *new-geo-item*      
                           *new-luna-item*
                           (oneof *menu-item* :menu-item-title "-":disabled 
t)
                           *run-item*
                           *stop-item*
                           *exit-item*)))

;;; Install the menu
(ask *run-item* (set-menu-item-check-mark (not *stop-flag*)))
(ask *stop-item* (set-menu-item-check-mark *stop-flag*))
(ask *solar-menu* (menu-install))